Claude Code
CLAUDE.md that the team actually follows
CLAUDE.md is repo policy for Claude Code, not a novel. Here is what we put in it so agentic coding stays inside your conventions after we leave.
June 15, 2026/2 min read/Claude Certified Engineers
CLAUDE.md is the file Claude Code treats as standing policy for a repository. It is useful when it states commands, layout, and refusals the agent can follow on the next pull request. It is noise when it restates the company handbook.
We write this file on Certification Enablement and on every embed, using your repo as the training ground, not a toy.
What belongs
- How to install, test, lint, and typecheck. Exact commands.
- Where new code goes. Paths, not philosophy.
- Secrets and data you must never commit or paste.
- How to run the eval suite if this repo has one.
- Hard no's: generated folders, golden files, production credentials.
What does not
- History of the company.
- Duplicate of CONTRIBUTING.md copied twice.
- "Be helpful and write clean code."
If a rule cannot be checked by a command or a path, it probably belongs in human review, not in CLAUDE.md. "Write accessible UI" is a reviewer comment. npm run lint is an agent instruction.
Treat the file as code
Open PRs against CLAUDE.md. When someone adds a new eval command, the file changes in the same diff. When the package manager changes, the install block changes. A file that only the enablement week touched will be wrong by month two, and Claude Code will still obey the stale commands until a human notices the red CI.
We put a one-line "if this file disagrees with package.json, trust package.json and fix this file" near the top. Agents follow local instructions hard. Give them an escape hatch that points at the repo of record.
Pair it with conventions, then leave
Pair CLAUDE.md with repo conventions. The file points at the conventions. The conventions live in the same PRs humans already review. The first useful PR should already have this file, even if the change is a test, not an agent.
When we leave, your engineers keep the file current because it is small enough to hate when it is wrong. That is the enablement product. A 20-page CLAUDE.md is a document you will pay us to rewrite next quarter.
Questions
- What is CLAUDE.md?
- A markdown file in the repository that Claude Code reads as standing instructions for that codebase. Commands, conventions, and hard no's. Not a second README for humans only.
- How long should CLAUDE.md be?
- Short enough that a change to CI still gets a matching edit. If it cannot be reviewed in one sitting, it will rot and Claude Code will ignore the stale parts in practice.
- Does CLAUDE.md replace human code review?
- No. It reduces the number of times the agent repeats the same mistake. A second certified reviewer still reads the PR.