When Claude Code launched, most platform leads treated it the way they treat any new developer tool: spin up a few pilot users, collect feedback, figure out the rollout later. That approach works fine for tools that are self-contained. It doesn’t work for Claude Code.
Claude Code is a multiplier, not a standalone tool. Its quality is proportional to the context it starts with. A Claude session that begins knowing your monorepo structure, your test conventions, your deploy pipeline, and your non-obvious architectural decisions is categorically different from one that starts cold. This means rollout isn’t just “give people access” — it’s “build the substrate that makes every session good.”
This guide is for platform engineering leads who want to do that right.
The Substrate Pattern: CLAUDE.md as Org Memory
The most important thing you will do in a Claude Code rollout is write a good CLAUDE.md. Not a perfect one — a good enough one that captures the decisions your team made that aren’t obvious from the code.
Every Claude Code session reads CLAUDE.md files from the current directory up through the file tree. That means a CLAUDE.md at your repo root becomes the default context for every engineer who opens Claude Code in that repo. This is the substrate: the floor of knowledge that every session starts from.
A strong org-level CLAUDE.md covers four areas:
1. Coding conventions. Not the obvious stuff like “use TypeScript” — Claude can figure that out from your codebase. The non-obvious stuff: whether you prefer const functions or function declarations for React components, how you handle error boundaries, whether you use barrel exports or direct imports. These are the micro-decisions that accumulate into “this feels like our code” or “this doesn’t.”
2. Monorepo structure. If you’re running a monorepo (and most orgs at scale are), document the package graph. Which packages are shared utilities? Which are application packages? What are the rules about cross-package imports? A new engineer takes a week to internalize this. Claude needs it in writing.
3. Test patterns. Where do tests live relative to source files? What’s your testing pyramid — unit-heavy, integration-heavy, or balanced? What mocking patterns do you use? What test utilities are available? An LLM that doesn’t know your test patterns will write tests that technically pass but don’t fit how your team thinks about testing.
4. Deploy and operational context. What commands actually build and deploy this service? What environment variables are required? What are the gotchas — the things that always trip up new engineers the first time they try to deploy? This section saves hours of debugging during onboarding.
Writing the Substrate Document
The format matters less than the content, but a few structural choices help.
Keep it in plain Markdown with minimal hierarchy. Claude Code reads it programmatically — a flat document with clear headers is easier to parse than a deeply nested one. Use ## sections, keep each section focused, and prefer concrete examples over abstract descriptions.
Write it from the perspective of someone who just joined the team and needs to be productive by end of day. What would they need to know? What would they get wrong without being told? Those are your CLAUDE.md entries.
Treat it as a living document. The right process is: when an engineer spends more than 15 minutes debugging something that turns out to be a known pattern or convention, that thing goes in CLAUDE.md. Make it someone’s job — rotation works well — to update the document monthly.
Hook Patterns for Platform-Level Enforcement
CLAUDE.md handles context. Hooks handle enforcement. The distinction matters.
Context tells Claude what your conventions are and trusts it to follow them. Enforcement runs checks that fail loudly when conventions are violated. Platform leads who confuse these two create brittle systems — either over-relying on Claude’s judgment for things that need hard checks, or burning cycles enforcing things that Claude can reason about itself.
The hooks that belong at the platform level are the ones that protect invariants across teams:
Pre-commit linting and formatting. If your org uses ESLint, Prettier, or similar tools, run them as Claude Code hooks before any commit. This isn’t about catching what Claude writes — Claude usually passes these. It’s about ensuring that the tool never creates exceptions to the rule that every engineer follows.
Schema validation hooks. If you have shared schemas — API contracts, database schemas, configuration files — validate them before committing. A Claude session that modifies a shared schema without realizing it’s shared can cause downstream breakage that’s expensive to untangle.
Security scan hooks. Secrets detection, dependency vulnerability checks, SAST scans. These should run on every commit regardless of who (or what) wrote the code. Claude Code is disciplined about not hardcoding secrets, but “disciplined” isn’t the same as “infallible.”
Test execution hooks. Run the affected test suite before allowing Claude Code to complete a task. This is the most important hook from a platform perspective. It creates a feedback loop where Claude sees test failures immediately and can fix them in the same session, rather than those failures showing up in CI hours later.
The key insight for platform leads: hooks are the interface between Claude Code and your existing CI/CD infrastructure. Your CI pipeline already has these checks. Hooks bring them earlier in the loop — into the editor session itself — so errors surface when context is fresh.
Rollout Strategy: Open Early, Guide Well
The instinct to gate Claude Code access is understandable. Platform leads are responsible for code quality, security, and consistency. A new tool that generates code at scale is a reasonable thing to be cautious about.
But the economics of AI tooling adoption work differently from traditional tool adoption. Traditional tools are symmetric — a developer who hasn’t adopted a new IDE has roughly the same capabilities as one who has. AI coding tools are asymmetric. A developer using Claude Code well has a significant productivity advantage. A developer not using Claude Code has no advantage, but also incurs no cost.
This asymmetry changes the rollout calculus. The risk of moving too slow is real: you lose adoption before it starts. Engineers who try Claude Code in an unsupported state, hit friction, and give up are hard to re-engage. Engineers who try it with good tooling and a clear CLAUDE.md have high success rates.
The approach that works:
-
Ship a starter CLAUDE.md on day one. Even a minimal one is better than nothing. Cover the basics: monorepo structure, test patterns, deploy commands. Leave blanks for teams to fill in. Something exists to iterate on.
-
Run a 1-hour kickoff session. Not a training session — an onboarding session. Walk through the CLAUDE.md, show a few real use cases from your own workflow, answer questions. The goal is to normalize “this is how we use this tool” early, before ad-hoc patterns crystallize.
-
Set up the hooks. Pre-commit linting and test execution are the minimum viable hook set. These create guardrails without blocking exploration. Engineers feel the safety net and develop confidence in the tool.
-
Create a feedback channel. A Slack channel, a shared doc, anything. The first month of rollout generates more CLAUDE.md improvements than the next six months combined. You need a place to capture them.
-
Iterate on the substrate monthly. Assign this to someone. The CLAUDE.md is the most leveraged document in your engineering org’s Claude Code rollout — it’s worth one person’s monthly hour.
Making It Stick: The Long Game
The tools that stick in engineering orgs are the ones that become invisible. Developers don’t think “I’m using Claude Code” — they just think about the problem they’re solving. The tool is fast, reliable, and aligned with how the team works.
Getting there requires the platform team to treat Claude Code infrastructure like any other platform infrastructure: with investment, maintenance, and a feedback loop.
The CLAUDE.md substrate is not a one-time artifact. It’s a living document that should evolve as your architecture evolves, as your team grows, and as you learn what Claude gets right and what it needs help with. The platform leads who invest here early create a compounding advantage: every improvement to the substrate makes every future Claude session better for every engineer.
That’s the platform engineering mindset applied to AI tooling. Not “did we give everyone access” but “have we made access valuable.”
FAQ
What should go in a shared CLAUDE.md for a 50-person eng org?
Start with your coding conventions, then add project-specific context like your monorepo structure, test patterns, and deploy commands. The most valuable entries are the non-obvious ones — the decisions your team made that a new engineer would spend a week figuring out.
How do you prevent Claude Code from becoming inconsistent across teams?
Use a parent CLAUDE.md at the repo root with org-wide conventions, and let sub-directories add their own CLAUDE.md files for local context. Claude reads both. The parent file is the substrate — it’s what makes every Claude session start with your conventions already loaded.
Should platform leads gate Claude Code access or open it up?
Open it up early, with lightweight guardrails. The cost of moving fast is a few inconsistent patterns — the cost of gating access is losing adoption before it starts. Ship a starter CLAUDE.md, run a 1-hour kickoff session, and let teams iterate.