Best practices for writing CLAUDE.md project instruction files that give Claude Code effective, accurate context about your codebase, conventions, and workflows.
# CLAUDE.md Authoring Rules
## File Purpose & Placement
- Place `CLAUDE.md` at the project root for global context; add nested `CLAUDE.md` files in subdirectories for scoped context (e.g., `packages/api/CLAUDE.md`).
- Claude Code reads all CLAUDE.md files in the directory hierarchy — use nested files to reduce noise for focused tasks.
- Keep CLAUDE.md under 400 lines. Longer files dilute focus — link to docs instead of inlining everything.
## Structure
- Open with a one-paragraph project overview: what it does, primary language/stack, and key constraints.
- Use H2 sections: `## Tech Stack`, `## Project Structure`, `## Key Commands`, `## Conventions`, `## Do Not`.
- List key commands in a fenced code block — build, test, lint, dev server, deploy. Keep them copy-pasteable.
- Include the repo structure with one-line descriptions per directory/package.
## Conventions Section
- Be explicit about naming conventions: files, variables, functions, classes, database columns.
- Specify import ordering rules if your linter enforces them.
- Document the test file naming pattern and where tests live relative to source.
- Note any non-obvious patterns: e.g., "All API routes return `{ data, error }` shape", "Use Result types, never throw in business logic".
## Do Not Section
- List explicit anti-patterns with brief explanations: "Do not use `any` type — use `unknown` with type guards."
- List files/directories that should never be modified without specific instructions.
- Note sensitive areas: auth logic, payment processing, database migrations.
## Commands & Tooling
- Document custom scripts and what they do, not just how to run them.
- Specify the package manager (npm/pnpm/yarn/bun) and lockfile policy.
- Note environment variable requirements — list required vars (names only, no values) and where `.env.example` lives.
## Writing Style
- Use imperative mood: "Use X", "Avoid Y", "Always Z" — not "You should" or "It is recommended".
- Be specific and concrete. "Use `pnpm`" beats "Use the project package manager".
- Avoid ambiguity: if a rule has exceptions, document them explicitly.
- Prefer bullet lists over prose for conventions — easier to scan during generation.
## What to Include
- Code architecture decisions and the reasoning behind them.
- Non-obvious gotchas: known issues, workarounds, quirks of the stack.
- The "definition of done" for typical tasks (tests required, linting must pass, etc.).
- Links to relevant docs for external services your codebase integrates with.
## What to Exclude
- Do not include secrets, API keys, or passwords — use `${env:VAR_NAME}` references.
- Do not include content better suited for a README (marketing copy, installation for new devs).
- Do not include stale information — outdated rules are worse than missing rules.
- Do not duplicate information already enforced by linters or formatters.
## Maintenance
- Update CLAUDE.md when architecture changes, not after the fact.
- Treat CLAUDE.md as production code — review it in PRs when relevant conventions change.
- Version-control CLAUDE.md; never gitignore it.
Mindaxis