CLAUDE.md Examples for Python, TypeScript, React, and Go

A generic CLAUDE.md is better than nothing. A stack-specific one is dramatically better.

When Claude Code reads your CLAUDE.md, it adapts every suggestion, every test, every refactor to match your actual project — your conventions, your toolchain, your team's preferences. A Python FastAPI project and a React SPA have completely different needs. Writing one generic file for both means Claude is guessing at half the context it needs.

This post gives you real, copy-paste CLAUDE.md starting points for the four most common stacks we see teams using: Python, TypeScript (Node), React, and Go. Each one is opinionated. Adjust to match your actual setup.

What goes in every CLAUDE.md

Before you look at the stack-specific examples, understand what the core sections do. Every good CLAUDE.md has five parts:

1. Project overview — one paragraph. What does this codebase do? Who uses it?
2. Architecture — directory structure, key modules, where things live
3. Coding standards — style, naming, patterns you enforce in PR review
4. Test & build commands — exactly how to run tests, lint, and build
5. What NOT to do — anti-patterns, deprecated approaches, things Claude should avoid

Optional but high-value: current focus / active work. Update this section when you start a new feature or sprint. Claude will prioritize relevant context.

---

Python (FastAPI / Django)

Python projects vary wildly by framework. This template targets FastAPI + async patterns, which is the most common setup we see for new API projects in 2026. Adjust the "Architecture" section for Django, Flask, or scripts-heavy repos.

# Project Overview

This is a FastAPI REST API for [your product].
Primary users: [internal tools / mobile app / third-party integrations].
Language: Python 3.12. Async throughout.

## Architecture

app/
  api/          # Route handlers (one file per resource)
  core/         # Config, database, security, dependencies
  models/       # SQLAlchemy ORM models
  schemas/      # Pydantic request/response schemas
  services/     # Business logic (imported by routes, not DB-aware)
  tests/        # Mirrors app/ structure

Keep business logic in services/. Routes should be thin.
Never put SQL queries directly in route handlers.

## Coding Standards

- Type hints on every function signature (input and return)
- Use Pydantic v2 models for all API I/O
- Async everywhere: async def for all route handlers and service methods
- Dependency injection via FastAPI Depends() — not global state
- Error handling: raise HTTPException with structured detail dicts
- Logging: use structlog, not print() or standard logging
- No bare except: clauses — catch specific exception types

## Test & Build Commands

pytest -v                          # Run all tests
pytest tests/api/ -v               # API tests only
pytest --cov=app --cov-report=term # Coverage
ruff check .                       # Lint
ruff format .                      # Format
uvicorn app.main:app --reload      # Local dev server

Target: >85% test coverage. Never merge code that drops coverage.

## What NOT To Do

- Do NOT use synchronous DB calls inside async functions
- Do NOT import from app.main in other modules (circular imports)
- Do NOT store secrets in code — use environment variables via pydantic-settings
- Do NOT use dict() to create responses — use Pydantic schema instances
- Do NOT write SQL strings manually — use SQLAlchemy ORM

## Current Focus

# Update this section when starting new work:
# Working on: [feature name]
# Key files: [list files being changed]
# Constraints: [any special rules for this sprint]

---

TypeScript / Node.js

This template targets a TypeScript Node.js backend — Express, Fastify, or a similar framework. If you're using tRPC or NestJS, adjust the routing and DI sections accordingly.

# Project Overview

TypeScript Node.js backend for [product].
Runtime: Node 22+. Framework: Express / Fastify.
Strict TypeScript — tsconfig.strict: true.

## Architecture

src/
  routes/       # Express routers (thin — delegate to controllers)
  controllers/  # Request parsing, response shaping
  services/     # Business logic, external API calls
  models/       # Prisma schema + generated types
  middleware/   # Auth, error handling, logging
  lib/          # Shared utilities, clients, config
  types/        # Custom type declarations
tests/          # Jest test files (mirrors src/)

## Coding Standards

- TypeScript strict mode. No any. Suppress nothing.
- Use zod for all runtime validation (request bodies, env vars, API responses)
- Named exports preferred over default exports
- Async/await everywhere — no raw Promises or callbacks
- Error handling: typed error classes in src/lib/errors.ts
- Imports: use path aliases (@/services/user, not ../../../services/user)
- No console.log in production code — use the logger from src/lib/logger

## Test & Build Commands

npm test              # Jest (all tests)
npm run test:watch    # Jest watch mode
npm run lint          # ESLint
npm run typecheck     # tsc --noEmit
npm run build         # Compile to dist/
npm run dev           # ts-node-dev with hot reload

## What NOT To Do

- Do NOT use require() — ES modules only
- Do NOT bypass Zod validation for external data
- Do NOT use Date for business logic — use dayjs or date-fns
- Do NOT mutate function arguments
- Do NOT access process.env directly — use src/lib/config.ts

## Current Focus

// [feature or area being worked on]
// [files in scope]
// [any temporary constraints]

---

React (with TypeScript)

Frontend React projects need different CLAUDE.md content than backend. The focus shifts to component architecture, state management, and UI conventions. This template assumes Vite + React + TypeScript — adjust for Next.js or Remix as needed.

# Project Overview

React frontend for [product]. 
Vite + React 19 + TypeScript strict. Deployed to [Vercel / Cloudflare / S3].
Design system: custom components in src/components/ui/ — do not use external UI libraries.

## Architecture

src/
  app/           # Routes (React Router v7 or file-based routing)
  components/
    ui/          # Primitive, reusable UI (Button, Input, Modal)
    features/    # Feature-specific components (UserProfile, OrderCard)
  hooks/         # Custom React hooks (useFetch, useLocalStorage)
  stores/        # Zustand stores (one per domain)
  services/      # API client functions (no fetch() outside here)
  types/         # Shared TypeScript types
  lib/           # Utils, formatters, constants

## Coding Standards

- Functional components only — no class components
- Co-locate styles: ComponentName.module.css next to ComponentName.tsx
- Props: define explicit TypeScript interface per component — no inline type literals
- State: local useState first. Lift to Zustand only when needed in >2 components
- Never fetch data inside components — use custom hooks or React Query
- Keys in lists: use stable IDs, never array index
- useEffect: comment explaining why it exists and what triggers it

## Test & Build Commands

npm test                # Vitest (unit)
npm run test:e2e        # Playwright (end-to-end)
npm run lint            # ESLint + TypeScript
npm run build           # Vite production build
npm run preview         # Preview production build locally

## Component Conventions

- Default export for page components (src/app/)
- Named exports for everything else
- Event handlers: handleVerbNoun (e.g., handleFormSubmit)
- Boolean props: isLoading, hasError, canEdit
- Do NOT forward internal state through >2 component layers — lift to store

## What NOT To Do

- Do NOT use any or cast to unknown to silence TypeScript
- Do NOT call fetch() or axios() directly in components
- Do NOT use inline styles — use CSS modules or Tailwind
- Do NOT add external UI component libraries without team discussion
- Do NOT store derived state — compute it from source state

## Current Focus

// [current feature / page being built]
// [components being modified]
// [any design tokens or patterns to use]

---

Go

Go projects tend to be opinionated about structure already, but CLAUDE.md still helps enforce team-specific patterns — especially around error handling, package layout, and which external packages are approved.

# Project Overview

Go service for [product]. Go 1.22+.
HTTP API using [net/http stdlib / Chi / Gin].
Database: PostgreSQL via pgx/v5.

## Architecture

cmd/
  server/       # main.go — entry point only, minimal logic
internal/
  api/          # HTTP handlers, middleware, routing
  domain/       # Business logic and domain types (no external deps)
  store/        # Database access (interfaces + implementations)
  service/      # Orchestrates domain + store
  config/       # Config loading (env vars only)
pkg/            # Shared code that could be extracted to separate modules
migrations/     # SQL migration files

## Coding Standards

- All errors must be handled — no _ for error returns
- Wrap errors with context: fmt.Errorf("service.CreateUser: %w", err)
- No panic() except in main() for unrecoverable init errors
- Context must be the first parameter in every function that does I/O
- Interfaces defined at point of use (in the package that depends on them)
- Structs exported; fields exported only when needed outside the package
- Table-driven tests for all non-trivial functions

## Test & Build Commands

go test ./...              # All tests
go test -race ./...        # Race condition check
go test -cover ./...       # Coverage
golangci-lint run          # Lint
go build ./cmd/server      # Build
go vet ./...               # Vet

## What NOT To Do

- Do NOT use init() — explicit initialization only
- Do NOT use global variables for shared state — pass dependencies explicitly
- Do NOT use ORM libraries — raw SQL with pgx
- Do NOT use interface{} or any unless genuinely needed
- Do NOT shadow err in nested scopes (causes silent failures)
- Do NOT use goroutines without clear ownership of cancellation

## Current Focus

// [current feature]
// [packages in scope]
// [any constraints for this sprint]

---

What to customize for your team

These templates are starting points. The sections you must customize before your first commit:

1. Architecture diagram — update the directory tree to match your actual repo. Wrong directories are worse than no directories.
2. Test commands — paste in your actual commands. If you use a Makefile, put the make targets here.
3. External packages — add a "Approved dependencies" list and a "Do NOT add" list. Claude will otherwise use whatever it knows, which may conflict with what's already in your lockfile.
4. Current Focus — update this whenever you start a new feature. This is the highest-leverage section for day-to-day work.

One pattern that pays off quickly: create role-specific CLAUDE.md files. A backend engineer, a frontend engineer, and a DevOps engineer all have different context needs. Rather than one massive file, you can have:

• CLAUDE.md — project-wide, always loaded
• frontend/CLAUDE.md — frontend-specific conventions
• infra/CLAUDE.md — infrastructure and deployment context

Claude Code reads the CLAUDE.md closest to your current working directory, plus any parent-directory CLAUDE.md files up to your project root. Use this hierarchy to your advantage.

Further reading

• CLAUDE.md Best Practices: The Complete Guide (2026)
• How to Roll Out Claude Code to an Engineering Team
• Claude Code Guide: Everything Your Team Needs to Know