Most CLAUDE.md guidance is written for solo developers working on one project at a time. Agency work is different: you have a portfolio of client projects, each with its own conventions, and the same engineer might touch six of them in a week. The CLAUDE.md strategy that works for a solo dev fails at agency scale. This is the working approach we have settled on at Seahawk Media after 18 months of iteration across 200+ active client repositories.
If you are running an agency that uses Claude Code daily and finding that engineers are getting wildly different output across projects, this post is the structural fix.
Why solo-dev CLAUDE.md advice breaks at agency scale
The standard CLAUDE.md advice is: write it once, optimise it for your project, keep it under 500 lines. That works when you have one project. When you have 50 client repositories, three problems emerge. The same engineer cannot remember which conventions apply to which client. New engineers onboarding to a project face fifty different CLAUDE.md files. The CLAUDE.md content drifts as engineers update one project and forget the others.
Solving this at agency scale requires a layered approach: agency-wide standards in one place, client-specific overrides in another, and per-engagement context in a third. The layers stack rather than duplicate.
The three-layer CLAUDE.md model
Layer 1: agency-wide standards
A single CLAUDE.md template lives in a private GitHub repository at our agency. It covers: code style across the languages we ship, our forbidden patterns, our testing conventions, our security standards, our British-spelling editorial rule, our deployment defaults. This file is roughly 400 lines and changes a few times per year.
Every new client project starts by symlinking or copying this file. Changes to the agency-wide file get pulled into projects on a quarterly review cadence. Engineers can rely on these conventions being identical regardless of which project they open.
Layer 2: client-specific CLAUDE.md
Each client repository has its own CLAUDE.md that imports the agency-wide one and adds client specifics: their stack, their hosting, their plugins, their team conventions, their editorial voice, their forbidden plugins. This file is typically 100 to 200 lines and changes when the client engagement changes shape.
We use a simple include directive at the top: "## Agency standards" with a link to the agency-wide file, then "## Client-specific" with the overrides. Claude reads both because they are both in the project tree.
Layer 3: per-engagement notes
Specific time-bound context: the current sprint goal, the active discovery findings, the recent decisions log, the open questions list. Lives in CLAUDE_NOTES.md or similar, updated weekly during the engagement, archived at engagement close.
This is where most agencies fail at CLAUDE.md hygiene. The first two layers stay tidy; the third drifts and becomes stale. We solve this with a Friday-afternoon review cadence: each engineer reviews their active CLAUDE_NOTES.md and either updates or archives it.
The forbidden-pattern list that compounds
The single highest-leverage element of our agency-wide CLAUDE.md is the forbidden-pattern list. Twenty entries, refreshed quarterly. Examples from the current list:
Never use eval() in any language we ship.
Never use query_posts() in WordPress (use WP_Query instead).
Never use any in TypeScript without an explicit "// suppressed: <reason>" comment.
Never use document.write() in any context.
Never commit secrets to git, ever, regardless of branch.
Never use em-dashes in any client-facing copy (operator standard for AI-detection avoidance).
Never disable RLS on Supabase tables to fix a bug.
Never push directly to main (always PR).
Never create a new file when an existing one can be edited.
The list compounds because every time an engineer breaks one of these rules, we add the rule. Claude reads the forbidden-pattern list every session and refuses to generate code that violates them. The class of bugs we used to ship to staging is gone.
What to keep out of CLAUDE.md
Five things we explicitly do not put in agency CLAUDE.md files:
Project status updates. They go stale; they belong in Linear or Notion.
Long architectural rationale. Belongs in design docs; CLAUDE.md should reference them, not duplicate them.
Client-side secrets, credentials, or anything sensitive. Even private CLAUDE.md files are too leakable.
Personal preferences of individual engineers. The standards have to be agency-wide; engineer-specific preferences belong in their own .claude/settings.json.
Marketing copy or sales language. The CLAUDE.md is engineering context; it should read like a senior engineer wrote it for other engineers.
How CLAUDE.md changes the hiring equation
A senior engineer who can ship across our client portfolio without re-learning each project on every visit is dramatically more valuable than one who cannot. The three-layer CLAUDE.md system is what makes that possible. Onboarding time for new engineers dropped from roughly 2 weeks of project-specific ramp to 3 days because the conventions are codified rather than tribal.
Same engineer, more output, less onboarding tax, less context-switch overhead. The hiring loop shipped fewer junior engineers and more senior ones once we had this system in place because junior engineers were no longer needed to absorb the project-specific context that had previously been the only way conventions transferred.
Bottom line
Agency-scale CLAUDE.md is a layered system: agency-wide standards as the base, client-specific overrides as the middle, per-engagement notes as the top. The forbidden-pattern list is the highest-leverage section. Avoid stale content in the per-engagement layer with a Friday-review cadence.
Implement the three-layer model and your engineers stop shipping inconsistent output across the portfolio. Skip it and you are paying for AI assistance that produces different work depending on which project the engineer happened to open last.