CLAUDE.md patterns that actually change model behavior

Updated August 2026 · ~7 min read

In a hurry? Use the free CLAUDE.md generator — answer a few questions, get a copy-paste file built from the patterns below. No signup.

Most CLAUDE.md files are documentation cosplaying as configuration. They describe the project's history, list every directory, and explain what a service does — and then people wonder why the agent still runs the full test suite on a one-line change.

A CLAUDE.md is not a README. It is a system prompt that gets prepended to every single turn. That means two things: (1) every line costs context on every request, and (2) only lines that change a decision earn their place. Here are the five patterns that reliably change behavior, and the anti-patterns that don't.

1. Commands, not descriptions

The single highest-leverage section. The model's default is to run the broadest thing it can find. Give it the narrow thing, explicitly, with the exact invocation:

## Commands
- Test one file: `pytest path/to/test_x.py -q`   (prefer over full suite)
- Typecheck:     `npm run typecheck`
- Full check before you claim done: `npm run lint && npm run typecheck && npm test`

Anti-pattern: "We use pytest for testing." That's a fact, not an instruction. It changes nothing.

2. Negative constraints beat positive style essays

Three paragraphs on your architectural philosophy get compressed into vibes. A hard prohibition survives:

## Rules
- Never edit `db/migrations/` — generate a new migration instead.
- Never add a dependency without asking.
- No new files in `src/utils/`; put helpers next to their caller.

Prohibitions are cheap to state, unambiguous to check, and they cover the failure modes that actually cost you review time.

3. Resolve ambiguity in advance

Every agent hits forks where it either stops and asks or guesses. Decide once, in the file, which one you want:

- When a task is ambiguous, implement the smallest correct version and note your
  assumptions at the top of your summary instead of asking.

Teams often want the opposite ("stop and ask before schema changes"). Either is fine — what's expensive is leaving it undecided so behavior swings turn to turn.

4. Encode your definition of done

"Done" is the most-abused word in agent work. Pin it:

## Definition of done
1. Change compiles and the targeted tests pass (paste the command output).
2. No unrelated files touched — `git diff --stat` reviewed.
3. If you skipped anything in scope, say so explicitly in the summary.

Point 3 matters more than it looks. Without it you get confident completion reports on partial work — the single most costly failure mode in agent-assisted development.

5. One file per repo shape

A monorepo, a solo prototype, and a published library want structurally different files. A monorepo needs package-boundary routing rules ("changes to packages/api require regenerating the client"). A library needs public-API and semver constraints ("changing a signature in src/index.ts is a breaking change — flag it"). A solo prototype needs almost nothing except commands and a speed preference. Copying a team template into a solo repo just burns tokens on rules nobody enforces.

The anti-patterns, in order of how much they cost

• Directory tree dumps. The agent can read the filesystem. This is pure context tax on every turn.
• Onboarding prose. "This service was extracted from the monolith in 2023…" — history changes no decision.
• Aspirational rules nobody follows. If the codebase violates the rule in 50 places, the model pattern-matches the code, not your file, and you've taught it your instructions are optional.
• Duplicating what tooling enforces. If your formatter runs on commit, don't spend 20 lines on formatting preferences.

Practical test for any line you're about to add: can I name the specific wrong action this prevents? If not, cut it. A tight 40-line CLAUDE.md consistently outperforms a 300-line one.

Related

Free .mcp.json generator — tick the MCP servers you want, get a valid config, plus the four things that actually break a server connection.

Claude Code hooks: 5 recipes that catch bad agent edits before they land — the enforcement half of this article. A CLAUDE.md rule is a request; a hook is a guarantee. Working scripts for lint-on-edit, protected paths, a bash deny-list, an audit log, and a typecheck gate on Stop.

Claude Code subagents: when a subagent actually beats one long session — the decision rule for delegating (spawn when a task reads far more than it concludes), how to write an agent definition whose description stops mis-dispatch, parallel fan-out by dimension, and the five cases where a subagent is strictly worse than doing it yourself.

Claude Code permissions builder — free tool plus the rules behind it: build a .claude/settings.json allow/deny/ask list that stops the constant approval prompts, why prefix matching isn't a security boundary, and why npm run lint && npm test still prompts you.

Free CLAUDE.md generator — an interactive version of this article: fill in your stack, commands, layout, dead directories and guardrails, and it assembles the file. Runs in your browser, nothing uploaded.

FAQ

Does this work with Claude Code in the terminal, IDE, and web?

Yes — CLAUDE.md, .claude/agents/, and settings.json hooks are read the same way across the CLI, the IDE extensions, and the desktop/web app.

Is this just prompts I could write myself?

Yes, and the article above gives you the method for free — genuinely, that's the point of publishing it. The pack saves you the hours of iterating on wording and the hook JSON that's easy to get subtly wrong.