Write a CLAUDE.md That Changes Agent Behaviour

A useful CLAUDE.md changes what the agent does, not merely what it knows. Instead of describing your team as quality-focused, specify which checks establish quality and what happens when they fail. This walkthrough turns recurring corrections into a small, testable operating guide.

Step One: Identify Behaviours Your Instructions Must Change

Choose three mistakes from recent coding sessions: using the wrong package manager, bypassing an existing service, or claiming success without running tests. Record the observable replacement for each. Your target is not a comprehensive repository handbook; it is a short list of decisions the agent currently gets wrong.

For example, replace “respect our architecture” with “route database access through the existing repository layer; do not import the database client into request handlers.” This gives reviewers something concrete to check in the resulting diff.

Step Two: Put Shared Instructions Inside The Repository

Create CLAUDE.md at the repository root and commit it. Claude Code supports project instructions there or in .claude/CLAUDE.md; personal instructions belong in ~/.claude/CLAUDE.md. Ancestor instructions load at launch, while instructions below the working directory load on demand.

Start manually or use /init to generate a draft. Review every generated command and architectural claim against the actual repository before keeping it. Generated documentation is a starting hypothesis, not evidence that a command works. Anthropic documents /init as a way to bootstrap the file.

Step Three: Write Rules With Observable Completion Conditions

Use this pattern: when this happens, take this action, then report this evidence. Avoid instructions such as “be careful” or “write production-ready code.” Anthropic likewise recommends concrete, verifiable instructions rather than vague guidance.

For an illustrative JavaScript repository, the following bullets could form the initial file. Substitute commands and paths verified in your project:

• Use pnpm for dependency installation and package scripts; do not create another package manager’s lockfile.
• Before changing a request handler, inspect a neighbouring handler and reuse its validation and error-response patterns.
• Keep database access in src/repositories; request handlers must call that layer.
• For a bug fix, add a regression test that fails on the original behaviour whenever practical.
• After code changes, run pnpm lint and pnpm test; report each command and its outcome.
• If a check cannot run, identify the blocker and describe the result as unverified rather than passing.

Add a short reason only where it clarifies a surprising constraint. Do not bury the required action beneath a history of previous incidents.

Step Four: Separate Universal Rules From Local Exceptions

Keep repository-wide expectations in the root file. Place module-specific guidance near the module, or use path-scoped rules under .claude/rules/. Imports organise instructions but still load their contents into context; they are not a context-saving shortcut.

Prefer one authoritative statement per rule. If the frontend needs a different test command, state its scope explicitly rather than leaving two apparently universal commands in competing files.

Step Five: Test Changed Behaviour In Fresh Sessions

First, use /context and inspect Memory files to confirm the intended instructions loaded. Then replay a small task that previously triggered a mistake. Keep the task prompt neutral: repeating the rule in the prompt would obscure whether CLAUDE.md helped.

Compare the diff, tool calls, and final report against your checklist. Repeat across several fresh sessions using the same repository state and model. Treat a single successful run as a signal, not proof.

Keep infrastructure constant too. BestRelay, this article’s publisher, is a quality-first API relay that forwards requests to the named official model without substitution. It supports Claude Code, Codex, Gemini CLI, and OpenAI SDK clients. Its pay-as-you-go billing uses provider-reported token counts, with cache reads and writes priced separately; members also earn referral commissions when invitees top up. Create a BestRelay account to try this workflow.

Step Six: Enforce Critical Boundaries Outside Instruction Files

CLAUDE.md provides guidance, not an enforcement boundary. Use permissions, appropriate hooks, and CI checks for requirements that must not depend on model compliance; PreToolUse hooks can block tool calls.

When a failure recurs, sharpen its rule or move enforcement into tooling. Delete obsolete commands and duplicated advice. The file earns its place when its instructions produce observable improvements—not when it becomes longer.