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
CLAUDE.local.md sits alongside CLAUDE.md in your repo, loads exactly the same way at session start, and never gets committed. Add it to .gitignore. It's a private layer — your preferences, your patterns, the feedback that keeps showing up in your reviews.
Most people don't know it exists. The ones who use it well treat it as something specific: a rule file built from their own mistakes.
Your reviewers are giving you free training data
Every PR you open generates feedback. Some of it is new — a problem you haven't seen before, a convention you didn't know. But a lot of it isn't. The same comments show up again. Auth-failure test missing. Wrong return type. Spec not updated. You know the list.
That recurring feedback is the most valuable input you're not using.
The discipline is simple: the moment a reviewer leaves a comment you've seen before, add it to CLAUDE.local.md. Not a vague note — the specific rule Claude needs to follow. By the next PR, Claude already knows.
A real example of what this looks like after a few months:
# From PR feedback
- New consumers need a DLQ and alarms in the same PR — never separate
- Use `Optional<T>` over null returns
- Tests for new endpoints must include the auth-failure case
- Prefer named tuples over plain dicts for return types with 3+ fields
- Update the OpenAPI spec when adding or changing an endpoint
# My own habits to correct
- Stop using `console.log` — use the project logger
- Don't leave TODO comments without a ticket reference
- Run `make lint` before opening a PR, not after
Loaded every session, Claude applies these rules without being asked. The nitpick comments on your PRs drop. The ones that remain are actually new.
Two sections, kept separate
Keep CLAUDE.local.md in two clearly separated sections: feedback from reviewers and habits you're correcting yourself. Mixing them makes the file harder to prune later.
The first section is external signal — what your team is catching. The second is internal signal — what you already know you do wrong but still slip on under pressure. Both matter. They have different half-lives.
Prune it
After a few weeks, go through the file. Anything that's become automatic — anything you'd catch yourself before Claude would — remove it. The file should represent what's still learning, not what's already muscle memory.
A bloated CLAUDE.local.md has the same problem as a bloated CLAUDE.md: the rules that matter compete with the ones that don't anymore. Keep it lean. The entries that survive pruning are the ones with real weight.
What this looks like at the team level
Each engineer on your team has their own CLAUDE.local.md. Or they don't — and they're leaving recurring feedback unaddressed, session after session.
As an EM, you won't read anyone's private file. But you can make the practice visible. In 1:1s, when you're talking through PR feedback, ask whether they've added recurring comments to their local config. Most engineers haven't thought of it. The ones who start doing it get cleaner reviews within a few weeks — not because they suddenly got better, but because they stopped making the same mistakes twice.
The pattern is the same one that makes CLAUDE.md valuable at the team level: mistakes become rules, rules prevent recurrence, the system improves faster than the person alone would. CLAUDE.local.md does the same thing at the individual level. Private, specific, compounding.
The relationship between the two files
CLAUDE.md is for the team. CLAUDE.local.md is for you. They load together, and Claude merges them into a single working context. The project rules apply to everyone. Your personal rules apply to you on top of that.
The split matters. If a rule is genuinely about the codebase, it belongs in CLAUDE.md and everyone benefits. If it's about your specific habits or your specific feedback patterns, it belongs in CLAUDE.local.md — where it doesn't add noise for engineers who don't share your blind spots.
Next: Skills — how to take the conventions and gotchas in your CLAUDE.md and package them into something reusable that a whole team can invoke.