Claude Code for Engineering Teams: 1. The Setup That Compounds · 2. CLAUDE.md: Write It Like the Creator Does · 3. CLAUDE.local.md: Your Private Layer
Most engineers open .claude/, see CLAUDE.md, and figure that's the whole thing. It isn't. The directory is a layered configuration system, and getting it right is the difference between Claude Code that improves every week and Claude Code that gives you the same mediocre output forever.
This is the first article in a series on Claude Code for engineering teams. Not for individual developers — for the people responsible for how a team uses it.
Two scopes, one mental model
Everything in Claude Code's configuration lives at one of two scopes.
Project scope lives in .claude/ inside your repo. It gets committed to git. Your whole team shares it. When someone clones the repo, they inherit whatever you've put here — your conventions, your gotchas, your accumulated knowledge about what Claude gets wrong in this specific codebase.
Global scope lives in ~/.claude/ on your machine. It applies across every project you work in. This is personal. Your preferences, your working style, the feedback you keep getting in code reviews.
The mental model that makes this stick: project files describe the project, global files describe you.
As an engineering manager, your job is to own the project scope. That's team infrastructure. Treat it that way.
What's actually in the directory
Here's the full layout — most of which people never touch:
my-repo/
├── .claude/
│ ├── settings.json # permissions, hooks, model defaults
│ ├── agents/ # subagent definitions
│ │ └── pr-review.md
│ ├── skills/ # reusable slash commands with bundled context
│ │ └── api-conventions/
│ │ └── SKILL.md
│ └── rules/ # path-gated instructions
│ └── migrations.md # only loads when working in db/migrations/
├── CLAUDE.md # committed, team-shared
├── CLAUDE.local.md # gitignored, personal
└── .mcp.json # team-shared MCP servers
A few things worth understanding properly:
CLAUDE.md cascades in a monorepo. If you have a root/CLAUDE.md and a root/services/billing/CLAUDE.md, both load when Claude is working in the billing service. This means you can have global team conventions at the root and service-specific detail closer to the code. Use it.
rules/*.md is path-gated. Guidance specific to your database migrations folder doesn't belong in the root CLAUDE.md where it loads for every session. It belongs in .claude/rules/migrations.md with a glob that activates it only when Claude is touching that path. Keep the root file short. Put detail where it's relevant.
Skills over commands. You can create slash commands two ways: a simple markdown file in .claude/commands/, or a full skill folder in .claude/skills/<name>/. Skills support bundled files, tool restrictions, and subagent overrides. New work belongs in skills.
.mcp.json is team infrastructure. MCP servers listed here are shared across the team. GitHub, Linear, Sentry — the tools your engineers are already in every day. If you're setting up the .claude directory and you're not thinking about .mcp.json, you're leaving half the value on the table.
What the EM owns
Most of this directory will evolve from the bottom up — engineers add skills, update the rules files, catch new gotchas in CLAUDE.md. That's the right model. But someone has to set the foundation.
As the EM, you own three things:
The initial structure. Create the directory, stub out the key files, decide the folder conventions. This takes a few hours the first time. After that, the team maintains it.
The CLAUDE.md discipline. The single highest-leverage habit in the entire Claude Code workflow is this: when Claude does something wrong, update CLAUDE.md so it doesn't happen again. Boris Cherny, who built Claude Code, calls Claude "eerily good at writing rules for itself from its own failures." Make this a team norm. Any engineer who hits a recurring mistake adds a rule. The file becomes a curated list of everything Claude gets wrong in your specific codebase.
What gets committed. Your CLAUDE.md, skills, agents, rules, and .mcp.json are all committed to git. They're as much a part of the codebase as your test configuration or your CI scripts. Review them. Keep them clean. When someone joins the team and clones the repo, they inherit everything your team has learned about working with Claude in this codebase. That's the compound interest.
The number that matters
A new engineer cloning your repo should be productive with Claude Code within minutes — not because Claude is magic, but because your team has spent months encoding its conventions, gotchas, and tooling into a directory structure that hands all of that over automatically.
That's the setup. Next: what goes inside CLAUDE.md, and how to write it the way the people who built the tool actually write it.