Mastering CLAUDE.md

CLAUDE.md is not a project wiki. Treat it as an operating contract for the agent: concise, actionable, and biased toward rules that prevent real mistakes.

Hierarchy

Use three layers:

• Global rules for personal preferences and machine-specific constraints.
• Repository rules for build commands, architecture boundaries, and workflow expectations.
• Directory rules for specialized areas such as docs, apps, migrations, or package internals.

The repository file should be useful even when read alone. Directory files should add local context, not restate the whole project.

What Belongs In The File

Good entries are specific:

- Use `rg` for code search.
- Run `yarn workspace handbook typecheck` after changing handbook routes or MDX source code.
- Do not edit generated `.source` files manually.
- Keep English locale content under `content/books/en`.

Weak entries are broad:

- Write clean code.
- Be careful.
- Make it scalable.

The agent cannot reliably execute vague values. Convert them into commands, constraints, or review criteria.

Imports And Modules

If the file grows, split stable sections into imported files:

@docs/agent-routing.md
@docs/testing-contract.md

Keep imports close to the work they affect. A frontend package should not need to load backend migration policy on every task.

Maintenance Rhythm

Update CLAUDE.md when a mistake repeats, when a command changes, or when a new workflow becomes standard. Do not add instructions for one-off incidents unless they reveal a durable rule.

Review Checklist

• Can a new agent understand how to build and test the repo?
• Are destructive commands explicitly restricted?
• Are generated files and ownership boundaries named?
• Are instructions short enough to stay in working context?
• Is each rule observable during review?