The problem
A team of eight engineers adopts Claude Code. Within two weeks, every developer maintains their own bespoke local CLAUDE.md, nobody knows what custom commands do, and a newly onboarded engineer spends their entire first day asking "has this been tried before?" because team conventions are not written anywhere the agent can systematically read. The breakdown is not a Claude Code limitation — it is treating configuration as subjective personal preference rather than shared engineering infrastructure.
Scaling Claude Code across an engineering organization is not handing the tool to individuals and letting each person configure it in isolation. It is defining shared operational constraints once, centrally, in an architectural tier that the agent always ingests.
The core architectural concept
CLAUDE.md is hierarchical by design: it separates project scope (versioned in git, shared uniformly across the team) from user scope (local, unversioned, developer-specific). The architectural decision is not "what should we put in CLAUDE.md" — it is "what belongs in which scope." Team conventions — commit message standards, directories requiring senior review, exact commands to execute test suites — belong in project scope because every developer's session must enforce them. Personal developer preferences — desired explanation verbosity, terminal output styles — belong in user scope, because imposing individual habits across the entire team introduces operational noise.
Path-specific rules solve a problem that a single monolithic CLAUDE.md handles poorly: large codebases contain distinct subdomains with differing standards. Infrastructure and Terraform directories require far more stringent validation policies than frontend UI components. A bloated root CLAUDE.md trying to cover everything creates noise for both domains. Path-scoped rules load context dynamically only when relevant — an engineer modifying UI components never ingests Terraform infrastructure policies, and vice versa.
Custom commands and Skills represent the second scaling vector. Project-level commands (.claude/commands/) standardize recurring team procedures — "review a database migration", "generate a release changelog", "verify PR readiness" — into parameterized workflows that any team member can invoke identically without engineering prompts from scratch. This ensures procedural consistency rather than relying on individual prompt reinterpretation.
The third pillar is executing Claude Code headlessly, particularly within CI/CD pipelines. Using -p/--print with --output-format json produces structured JSON payloads that external automation tools can ingest — allowing a CI pipeline to invoke Claude Code for PR triage and programmatically gate pull requests based on the output payload. The critical architectural safeguard: automated review signals must feed into independent verification (human review or a decoupled validation pass) for high-risk flags — never letting the same agent that drafted a PR be the sole authority approving its merge.
Put it into practice
In this lesson's lab, you will build a Python configuration router: given a list of organizational engineering policies, it assigns each rule to its optimal scope (project-level, user-level, or path-scoped), and simulates parsing structured JSON outputs emitted by a headless CI review pass.