how to make AI agents follow your CLAUDE.md project conventions

Most teams using Claude Code know to write a CLAUDE.md. You add your architecture decisions, the libraries that are off-limits, the naming conventions you actually enforce, the patterns you've banned after they caused problems. When you open a Claude Code session in your project directory, the CLI reads it. The agent starts aware of your rules.

When you run parallel agents — or when an orchestrator launches a new agent for each stage of a task — that awareness doesn't transfer. Each agent launch is a fresh context. If the agent's prompt doesn't include your CLAUDE.md content, the agent doesn't know your rules exist. It will introduce the ORM patterns you banned, add console.log to production paths, organize files in whatever structure feels natural to the model. You catch it in review, revert it, re-brief, and run again.

This is the recurring overhead of multi-agent workflows that nobody names directly: the cost isn't just tokens and time, it's re-establishing your project's conventions for every agent invocation.

why agents don't automatically read CLAUDE.md

The Claude Code CLI loads CLAUDE.md (and its variants — CLAUDE.local.md, .claude/CLAUDE.md) when it starts in your project directory. That's a single-session, single-process load. When an orchestration layer launches a new agent subprocess — to run in parallel, to handle a specific stage, to perform a review — it's a new process, new context. The file is on disk, but the new agent's prompt doesn't include its contents unless something explicitly puts it there.

For teams running a single Claude Code session, this is invisible. For teams using parallel agents or structured pipelines, it becomes a persistent source of convention drift. The design agent and the implementation agent both pass through your codebase, but they don't share the accumulated knowledge of the session — and they don't share the rules unless those rules were explicitly loaded for each of them.

what teams do manually

There are three common approaches, all with tradeoffs:

Copy rules into each task prompt — the most direct approach. You paste the rules you care about into the task description or the agent's system prompt. Works for a few rules, breaks down when the list grows, and requires a per-invocation decision about which rules apply.

Build a prompt loader — write a script that reads your CLAUDE.md and prepends it to every agent's context. Reliable, but it's infrastructure to build and maintain. If your conventions file is long, you're spending tokens on every agent launch to transmit content that's only partially relevant to that stage.

Stage-specific rules files — maintain separate files (REVIEW_RULES.md, ARCHITECTURE_GUIDE.md) and load only the relevant one per agent. More precise, but adds organizational overhead and creates the risk that rules diverge across files over time.

All three work. None of them eliminate the manual wiring, and none of them scale cleanly to a team where multiple people are running agents against the same codebase.

what belongs in a project-quality CLAUDE.md

A CLAUDE.md that actually improves multi-agent output is not a README summary. It's a rules file — the conventions that change agent behavior versus the model operating with no project context:

• Architecture decisions — choices already made that shouldn't be re-evaluated per task. "We use PostgreSQL everywhere, no SQLite." "All background jobs use the queue abstraction in lib/queue, not direct Redis calls."
• Prohibited patterns — things the model reaches for by default that you've ruled out. "No inline SQL — use the query builder in lib/db." "No any types in TypeScript." "No console.log in production paths."
• Naming and file organization — conventions that produce coherent output across parallel agents. "Service files go in src/services/, not src/lib/." "Test files live adjacent to the files they test."
• Library preferences — which packages to use and which to avoid. "Date handling uses date-fns, not moment." "Validation uses zod schemas, not custom validators."
• Review criteria — what your review stage checks beyond general correctness. "All database writes must be idempotent." "Error messages must not expose internal stack traces."

Keep it tight. A CLAUDE.md that's 3,000 words of general philosophy provides less value than 400 words of specific, actionable rules. The agent reads the whole file; the precision of the rules is what actually changes behavior.

extraction: getting conventions into every agent

The extraction approach shifts where the work happens. Instead of manually wiring your CLAUDE.md into each agent invocation, the orchestration layer reads the file once and injects the relevant content into every agent prompt it launches — scope agents, design agents, architecture agents, implementation agents, review agents.

This changes the maintenance model. You write the rule once. When you update your CLAUDE.md, the next agent invocation gets the updated rules. There's no sync step, no risk of a stale copy of the rules living in one agent's prompt but not another's.

Extraction also enables consistency at scale. When five parallel implementation agents all start with the same project conventions, their output is measurably more coherent than when each agent got a different subset of the rules, or none at all. The context problem in parallel agents applies to conventions the same way it applies to design decisions: consistency requires the shared context to actually be shared, across every agent, every time.

how defract handles CLAUDE.md extraction

defract reads your CLAUDE.md and all its variants from your project directory through a Settings → Extraction step. The extracted conventions are folded into every agent prompt across the lifecycle — from scope through to review. You configure it once per project; every agent defract launches for that project then operates with your full convention set, without per-task prompt wiring.

If you're already running Claude Code on a project with a CLAUDE.md, the extraction step is the most direct way to bring those conventions into a structured multi-stage pipeline. The rules you wrote to govern your Claude Code sessions become the rules every stage agent follows — without re-stating them per task, and without building and maintaining an extraction layer of your own.