On this page#
- How we judged them
- The shortlist
- Repository contract
- Verification
- What we rejected and why
- The one nobody talks about
- When blocked
- Choosing by repo shape
- FAQ
How we judged them#
The best CLAUDE.md practice is a small, repository-specific contract containing only durable constraints, exact verification commands, and rules the agent cannot reliably infer from code. It requires the least babysitting because it prevents expensive mistakes without prescribing every step. Everything else should live closer to the relevant code or task.
A CLAUDE.md file supplies persistent instructions to Claude Code; the exact discovery and precedence behavior belongs in the Claude Code official documentation. This ranking applies the same principles to Codex, Cursor, and similar agents, but filenames and instruction-loading rules differ between products.
We ranked each practice against four criteria:
- Correction avoided: Does it prevent a plausible, costly mistake?
- Durability: Will the instruction remain true after normal repository changes?
- Verifiability: Can the agent prove compliance with a command or observable result?
- Inference gap: Is the rule genuinely hard to discover from code, configuration, or tests?
The governing metric is babysitting: how often a competent agent still needs a human to redirect it. A rule scores poorly when it becomes stale, conflicts with the repository, or forces the agent through an obsolete workflow.
A large language model generates output from learned and supplied context; it does not acquire a durable private understanding of your repository between unrelated sessions. CLAUDE.md should therefore encode repository invariants, not attempt to turn the model into a permanent teammate through autobiography and exhaustive prose.
Use this test for every proposed line:
If this instruction disappeared, would the repository itself make the correct behavior obvious?
If yes, delete it. Duplicating visible facts creates two sources of truth, and the prose version is usually the one that rots.
Photo by mali maeder on Pexels.
The shortlist#
The lowest-maintenance choices are narrow contracts, executable checks, and instructions placed at the smallest valid scope. A monolithic “complete guide to the repository” ranks below them because completeness is fragile. The ranking is about supervision cost, not how impressive the file looks.
| Rank | Practice | Best for | When not to use | |---|---|---|---| | 1 | Durable invariants only | Any real repository with architectural or operational boundaries | When the “rule” is merely a current implementation detail | | 2 | Exact verification commands | Repositories with reliable tests, linting, type checks, or build gates | When the command is flaky, destructive, interactive, or environment-specific | | 3 | Scoped instructions near the affected code | Monorepos and repositories with different subsystem conventions | When the same rule truly applies everywhere | | 4 | Explicit forbidden actions with an approved alternative | Sensitive migrations, generated files, security boundaries, and release workflows | When the prohibition is obvious from tooling or permissions | | 5 | A short repository map based on responsibilities | Unfamiliar or irregular layouts | When directory names and package boundaries already explain the structure | | 6 | Prescribed implementation recipes | Narrow, highly standardized change types | When multiple valid designs exist or the recipe changes frequently |
The top-ranked pattern is intentionally plain:
## Repository contract
- Preserve backward compatibility for the public API.
- Do not edit generated files; change their source and regenerate them.
- Keep database migrations additive once committed.
*Photo by Jakub Zerdzicki on [Pexels](https://www.pexels.com/photo/close-up-of-programmer-typing-code-on-laptop-36496927/).*
## Verification
- Run: `<repository test command>`
- Run: `<repository lint or type-check command>`
- If either command cannot run, report the blocker and the unverified scope.Replace the placeholders with commands that already exist in the repository. Do not invent a universal command, and do not claim “all checks pass” when only a subset ran. The official Claude Code documentation should remain the authority for how the file is loaded; your repository remains the authority for what its commands mean.
Negative rules need a permitted path. “Never edit generated files” is incomplete supervision: the agent still needs to know whether to edit a schema, template, or generator. Write “Edit the schema, then run the repository’s generation command.” That converts a warning into an executable workflow.
For reusable configurations and agent-oriented utilities, PairFoundry tools provide the natural next step. Keep CLAUDE.md focused even when supporting tooling becomes more sophisticated.
What we rejected and why#
We rejected exhaustive manuals, persona prompts, copied documentation, style sermons, and task-specific plans. They look helpful but increase supervision because they compete with current code and current requests. A persistent instruction file is the wrong storage layer for information that changes with each ticket, branch, or implementation.
The giant repository handbook#
A giant handbook fails through conflict, not merely length. When instructions describe every package, command, convention, and historical decision, some portion will eventually disagree with the repository. The agent must then guess whether prose, code, or configuration is authoritative.
Link to existing canonical documentation when it is genuinely required; do not paste it into CLAUDE.md. Better still, make the relevant behavior discoverable through package scripts, tests, schemas, and local README files. The instruction file should identify the non-obvious boundary, not mirror the entire landscape.
“Always” rules for coding style#
Style belongs in formatters, linters, compiler settings, and tests whenever those mechanisms can enforce it. Telling an agent to “write clean code,” “follow best practices,” or “prefer maintainability” provides no decision procedure and no proof of compliance.
Keep only unenforced conventions with real architectural consequences. “Use the shared authorization boundary rather than checking roles in handlers” is actionable if both approaches appear valid in the code. “Write idiomatic code” is decoration.
Engineers who need the underlying workflow before adopting packaged configurations should use the free PairFoundry foundations track. The goal is to understand which constraints belong in prompts and which belong in executable repository controls.
Task plans and current priorities#
A branch-specific plan becomes dangerous as soon as the task changes. CLAUDE.md persists while issue scope, rollout order, and temporary workarounds do not. Put the acceptance criteria in the task and keep the repository contract stable.
Do not add instructions such as “finish the billing refactor first” or “temporarily skip integration tests.” If a temporary exception must exist, place it in the active task with its reason and removal condition.
Agent personas and motivational prose#
“Act as a senior engineer” does not define the repository’s invariants. Neither do requests to be careful, thoughtful, production-ready, or concise. These phrases consume attention without resolving a concrete choice.
Replace personality language with observable requirements: preserve the public contract, avoid destructive migration changes, run named checks, and report unverified behavior. That is enough direction for an agent to act and enough evidence for a reviewer to evaluate.
The broader category context is collected in The Landscape, but CLAUDE.md itself should not contain industry commentary.
Photo by Daniil Komov on Pexels.
The one nobody talks about#
The most underrated practice is specifying the failure protocol: what the agent must do when verification cannot run or instructions conflict. Success-path commands are common; explicit degraded-mode behavior is not. Without it, an agent may silently narrow validation, improvise around a missing dependency, or overstate confidence.
Add a compact protocol:
## When blocked
- Do not bypass or weaken a required check.
- State which command failed or could not run.
- Separate verified behavior from unverified behavior.
- If instructions conflict, stop before the irreversible action and identify both rules.This reduces babysitting because it defines a safe stopping point. The objective is not to prevent every failure. It is to ensure that failure remains visible, bounded, and reversible.
The distinction also protects against false completion. An agent can make a plausible edit without proving that the repository accepts it. Exact reporting forces the final handoff to distinguish “implemented” from “verified.”
The Claude Code official documentation explains product behavior, but it cannot define your repository’s acceptable fallback when a service, credential, fixture, or platform dependency is unavailable. That policy belongs to the team.
Teams wanting ready-made configurations should compare the three options on the PairFoundry packs overview, then adopt only the rules that correspond to actual repository constraints.
Choosing by repo shape#
Choose the instruction structure from the repository’s boundaries, not from a universal template. A single-service repository usually needs one compact contract; a monorepo needs layered, scoped guidance; a legacy repository needs protection around fragile seams; and a generated-code repository needs explicit source-to-output workflows.
Single service or library#
Use one root file containing public compatibility rules, verification commands, and the few architectural constraints that code does not reveal. Avoid directory tours unless the layout is genuinely misleading.
For a library, state which interfaces are public and what compatibility means operationally. Do not enumerate every exported symbol; the source already does that.
Monorepo#
Keep the root instructions universal: shared safety boundaries, cross-package validation, and rules governing dependency direction. Put subsystem-specific commands and conventions near the subsystem if the agent supports scoped instruction files.
Repeating every package rule at the root creates collisions. A frontend package should not inherit backend migration instructions merely because both live in one repository.
Legacy repository#
Prioritize containment over modernization slogans. Identify fragile integration boundaries, required characterization checks, and areas where a seemingly local change affects external behavior.
Do not instruct the agent to “clean up nearby code.” That expands scope and makes regression attribution harder. Require the smallest coherent change unless the task explicitly authorizes structural work.
Generated or schema-driven repository#
State the authoritative source, the regeneration path, and whether generated output is committed. “Do not edit generated files” alone is insufficient because it omits the correct route.
If regeneration cannot run, the failure protocol should stop the agent from hand-patching output and presenting it as complete. This is where a short CLAUDE.md earns its keep.
Related reading#
- AI code review tools — ranked by how little you have to babysit them
- Best Claude Code plugins: what each one is genuinely good at
FAQ#
How is this different from simply following the official Claude Code guidance?#
Official guidance explains how Claude Code discovers and applies instructions. Your CLAUDE.md must define repository-specific invariants, commands, and failure behavior that product documentation cannot know. Use the official documentation for mechanics and the repository for policy.
What causes the most trouble when a team shares one CLAUDE.md?#
Unowned additions and duplicated documentation cause the most trouble. Treat changes to CLAUDE.md like changes to build configuration: require a concrete failure mode, an appropriate scope, and a way to verify that the instruction is still valid.
How do we recover when CLAUDE.md sends the agent in the wrong direction?#
Stop the current task, identify the conflicting or stale rule, and verify repository behavior from canonical code, configuration, and tests. Fix or remove the instruction before continuing. Do not compensate by adding another contradictory exception.
When should we avoid CLAUDE.md entirely?#
Avoid it when the repository has no non-obvious persistent constraints or when every proposed instruction is already enforced by tooling. An empty or tiny file is better than a speculative handbook that creates a second, weaker source of truth.
Should task-specific acceptance criteria go into CLAUDE.md?#
No. Put acceptance criteria in the issue, prompt, or task plan. Promote a rule into CLAUDE.md only when it remains true across tasks and branches, applies at that file’s scope, and prevents a recurring class of repository-level error.