CLAUDE.md configuration

CLAUDE.md is the cheapest way to change how every agent works: a file every agent session reads before it does anything. Treat it like code, because at scale it behaves like code. A wrong rule in it is applied in every session by every engineer.

The first decision: what belongs here versus in a tool. If a linter, type checker, or hook can enforce a rule, put it there. CLAUDE.md is for what tools can't check: architecture, conventions, where things live, what never to touch.

File locations

Example CLAUDE.md structure

# Project: MyApp

## Tech Stack
- Framework: Next.js with App Router
- Database: PostgreSQL with Prisma ORM
- Auth: NextAuth.js with JWT
- Styling: Tailwind CSS

## ALWAYS
- Follow existing patterns in src/services/
- Write tests for new behavior
- Use environment variables for configuration
- Follow REST conventions for API routes

## NEVER
- Commit directly to main
- Store secrets in code
- Create new utility files without checking existing ones
- Edit migrations that have already run

## Commands
- `bun dev` - Start development server
- `bun test` - Run tests
- `bun lint` - Lint and format
- `bun db:migrate` - Run Prisma migrations

## Architecture Notes
- Services in src/services/ own business logic
- API routes are thin wrappers around services
- All database access goes through src/lib/db.ts

Notice what's missing: "use TypeScript strict mode", "no any", "prefer const". Those belong in tsconfig.json and lint rules, where they're enforced instead of requested.

CLAUDE.local.md (personal, gitignored)

# Local Overrides

## My Preferences
- Keep responses concise
- Show diff after edits

## Local Paths
- Test database: postgresql://localhost:5432/myapp_test
- Local API: http://localhost:3000/api

Running it as a team:

• Review it like code. Changes go through PRs. Put it under CODEOWNERS
• Standardize a base. An org-wide base plus per-repo additions makes agents behave the same across teams
• Prune it. Every line costs tokens in every session. If a rule hasn't mattered in a quarter, delete it
• Feed it from incidents. When a postmortem finds a class of mistake, add the rule that prevents it

Reference: https://www.anthropic.com/engineering/claude-code-best-practices