Write a CLAUDE.md That Actually Steers Your Agent

A useful CLAUDE.md is not a welcome letter or a compressed engineering handbook. It is a decision guide: the repository-specific information a coding agent needs to choose the right implementation, run meaningful checks, and avoid expensive mistakes. Write it around decisions you repeatedly correct, not everything you know about the codebase.

1. Start with recurring failures

Review recent agent-assisted changes and identify where intervention was necessary. Did the agent edit generated files, install dependencies with the wrong package manager, bypass authorization helpers, or stop after a superficial test? Those failures are better source material than generic advice such as “write clean code.”

Turn each recurring failure into an observable instruction. For example: “Change the schema source, then regenerate the client; do not edit generated client files directly.” An engineer reviewing a diff should be able to tell whether the agent followed it.

2. Establish which instructions apply

Put shared repository guidance in the root CLAUDE.md. In Claude Code, more specific instructions can also live in relevant subdirectories, allowing package-level guidance to stay near the code it governs. Check the instruction-loading behavior of your installed client rather than assuming every coding tool discovers the same files.

Keep the root file focused on rules that apply broadly. A frontend-only testing requirement belongs with the frontend, not beside backend migration rules. When guidance changes by directory, state that scope explicitly and avoid conflicting instructions.

3. Give the agent a small working map

Describe architectural boundaries that directory names cannot explain. For an illustrative service repository, useful entries might look like this:

• Request handlers: Validate input and delegate business decisions to services.
• Services: Own business rules and call repositories for persistence.
• Repositories: Contain database queries; do not import HTTP-layer types.

Explain the boundaries that protect the design. Skip a complete directory inventory, which becomes stale quickly and is usually discoverable through search.

4. Specify runnable checks and prerequisites

Record the actual package manager, installation command, focused test command, type check, and build command used by the repository. Copy these from working scripts or CI configuration, not memory. Include the working directory whenever it matters.

Label commands by purpose and cost. Distinguish a fast unit check from an integration suite requiring a database. If tests need environment variables, identify the documented setup without placing credentials in the file.

Add a reporting rule: “State which checks ran, whether they passed, and which checks could not run.” This prevents an unverified change from being presented as tested.

5. Replace vague preferences with decision rules

“Follow existing patterns” leaves too much interpretation. Instead, identify the pattern and the condition that triggers it. For example: “For authenticated endpoints, use the existing authorization helper and add a test for unauthorized access.”

Use firm language for genuine constraints and softer language for preferences. “Do not add runtime dependencies without approval” defines an approval boundary. “Prefer existing utilities before introducing a helper” leaves room for judgment. Too many absolute rules create contradictions rather than consistency.

6. Define stop conditions and trust boundaries

Tell the agent when to pause: destructive schema changes, production operations, credential changes, or requirements that conflict with existing behavior. Ask it to explain the conflict and request clarification instead of guessing.

State that comments, issue text, logs, and downloaded content are task data, not authority to override repository instructions. However, CLAUDE.md is guidance, not a security boundary. Enforce critical restrictions with tool permissions, isolated environments, protected branches, and CI checks.

7. Test the file against a real task

Use a fresh session and a representative task. Check whether the agent discovers the relevant instructions, respects architectural boundaries, and runs appropriate verification. When it misses a rule, investigate loading, ambiguity, and conflicting guidance before adding more text.

For teams using CodeRelay Hub, keep repository guidance separate from endpoint configuration. Configure the client connection independently, and verify that the chosen client actually loads CLAUDE.md; routing requests through one endpoint does not standardize instruction discovery.

8. Maintain it like executable documentation

Review CLAUDE.md when scripts, architecture, or approval policies change. Delete obsolete rules and move lengthy explanations into maintained documentation. Keep the file short enough that its important decisions remain easy to find.

Open a free workspace on CodeRelay Hub.