Claude Code in a Team Setting - The Conventions Nobody Writes Down

One engineer using Claude Code is a productivity story. Ten engineers using Claude Code on the same repo, with no shared conventions, is a coordination problem that looks a lot like the early days of untyped JavaScript on a big team. Everyone is fast individually. Collectively you get inconsistent code, a CLAUDE.md that three people edit in three directions, and a PR queue full of 800-line diffs that the author skimmed and nobody else wants to read.

I have watched this play out on two teams now. The tools did not get worse when we scaled from one user to ten. The missing piece was the set of conventions nobody thinks to write down because when you work alone they live in your head. This post is those conventions.

The Naive Rollout and Where It Breaks

The naive rollout is: buy seats, tell everyone to install Claude Code, point them at the repo. Each engineer figures out their own workflow. This works great for about two weeks, then four things break in a predictable order.

1. The CLAUDE.md becomes a battleground. One person adds “prefer functional components.” Another adds “use classes for stateful logic.” A third pastes in 200 lines of API docs because Claude kept guessing wrong. The file grows to 400 lines, contradicts itself, and now every session loads a bloated, self-conflicting context on the first token.

2. Prompt drift. Alice prompts Claude to “refactor this for readability” and gets small, safe diffs. Bob prompts “make this production-ready” and gets Claude rewriting error handling, adding retries, and touching files he never mentioned. Same tool, wildly different output, because the prompting style is personal and invisible to everyone else.

3. AI PRs nobody wants to review. The volume goes up. A reviewer used to seeing a 120-line PR from a human now sees a 700-line PR that “works” and passes tests, but was clearly generated in one shot. The author cannot answer “why did you do it this way” because they did not make the decisions. Review slows to a crawl, or worse, becomes rubber-stamping.

4. Silent divergence in tooling. Half the team is on the latest model with hooks configured. Half is on defaults. Nobody knows who is running what, so “it worked on my machine” now includes the AI’s behavior, not just the runtime.

None of these are model problems. They are process gaps. Let us fix them one at a time.

Convention 1: The CLAUDE.md Is Code, With an Owner

The single biggest fix is to stop treating CLAUDE.md as a scratchpad and start treating it as source code with the same rules as any other file.

CLAUDE.md conflict, before:
  everyone edits, no review, grows unbounded, contradicts itself

CLAUDE.md as code, after:
  root CLAUDE.md         -> project facts, reviewed in PRs, owned
  .claude/rules/*.md     -> path-scoped rules, reviewed by area owners
  ~/.claude/CLAUDE.md    -> personal, never committed, per-engineer

The rules that keep this sane:

• The root CLAUDE.md is reviewed in PRs like any other file. A change to it needs an approval. This alone kills 80% of the drift, because “prefer functional components” now has to survive a reviewer asking “is this a team decision or your preference?”
• It has a named owner. One person (usually a tech lead) is responsible for it staying tight. When it crosses 60 lines, they audit it. Ownership prevents the tragedy-of-the-commons growth.
• Personal preferences go in ~/.claude/CLAUDE.md, never the repo. Your commit message style, your verbosity preference, your favorite variable naming - all of that is user-level config and stays out of everyone else’s context.
• Team-specific but area-specific rules go in .claude/rules/ with globs. The backend team’s rules only load when Claude touches backend files. This keeps the shared root file small and lets area owners maintain their own conventions without a merge war.

Here is the split in practice:

The test for whether something belongs in the shared CLAUDE.md: if a human violated it, would it fail review? If yes, it is a rule. If it is a preference, it is personal config.

Convention 2: Name the Prompt Modes So Everyone Uses the Same Ones

Prompt drift is invisible because prompts are private. The fix is to make a small, shared vocabulary of intent that the team actually agrees on. You do not need a prompt library. You need three or four named modes and a shared understanding of what each one means for scope.

## Team prompt modes (in CLAUDE.md)

- "tight edit": change only what I point at. No refactors, no new files,
  no touching adjacent code. Smallest diff that works.
- "refactor": improve structure in the files I named. May reorganize,
  may not change behavior. Tests must still pass unchanged.
- "feature": implement the described feature end to end. May add files.
  Must include tests. Explain the plan before writing code.
- "spike": throw-away exploration. Optimize for speed, not quality.
  This will not be merged as-is.

Once these are written down, “tight edit this validation bug” means the same thing to Alice’s Claude and Bob’s Claude. The output converges because the intent is shared, not personal. This is the cheapest high-leverage convention on the list, and it takes ten lines.

The deeper win: these modes map cleanly to review expectations. A “tight edit” PR that touches eight files is a bug in the process, and the reviewer can say so without it being a judgment call.

Convention 3: The Author Owns the Diff, Not the Model

This is the cultural convention and the hardest to enforce, because it is about accountability, not tooling.

The rule: the engineer who opens the PR is fully accountable for every line, exactly as if they typed it by hand. “Claude wrote it” is never an explanation in review. If you cannot explain why a line exists, it does not go in the PR.

In practice this changes the workflow before the PR is even opened. The author’s job is to be the first, most ruthless reviewer of the AI’s output:

Bad AI-assisted workflow:
  prompt -> accept -> tests pass -> open PR -> "please review"

Good AI-assisted workflow:
  prompt -> read every line -> reject/reprompt the parts you cannot defend
        -> shrink the diff -> understand it fully -> open PR with real context

The concrete behaviors that make this stick:

• Small PRs, still. AI does not change the reason small PRs are reviewable. If Claude produced a 700-line diff, the author’s job is to break it into three PRs a human can actually reason about, or to cut it down. Volume is not velocity.
• The PR description explains decisions, not activity. “Added retry logic with exponential backoff because the payment API returns 503s under load” is a decision. “Refactored the service layer” is activity. Reviewers need the first.
• No unexplained scope. If the diff touches a file the ticket did not mention, the description says why. AI loves to helpfully fix adjacent things. Sometimes that is good. It always needs to be surfaced.

Convention 4: Make the AI’s Footprint Visible in Review

Reviewers review differently when they know how a change was produced. Not because AI code is worse, but because it fails in different places. Human code tends to have logic bugs in the parts the author found hard. AI code tends to be plausible everywhere and subtly wrong in the parts that needed context the model did not have - your specific auth model, your rate limits, that one legacy quirk.

A lightweight convention: a PR template checkbox and a focus hint.

## PR template addition

- [ ] AI-assisted (Claude Code)
- [ ] I have read and can defend every line
- [ ] Diff is scoped to the described change

If AI-assisted, where should the reviewer look hardest?
> e.g. "the token refresh logic - Claude did not have full context on our
>       session model, I verified it manually but double-check line 40-70"

This does two things. It tells the reviewer where the model was most likely to be confidently wrong, and it forces the author to have already thought about that. The checkbox that says “I can defend every line” is doing real work - it is a public commitment, and people edit their behavior when they have to check it.

Putting It Together: The Team Workflow

Here is the end-to-end flow with all four conventions in place.

                    +---------------------------+
                    |   Shared repo config      |
                    |  CLAUDE.md (owned, PR'd)   |
                    |  .claude/rules/*.md        |
                    |  named prompt modes        |
                    +-------------+-------------+
                                  |
                loads on every session for every engineer
                                  |
   Alice: ~/.claude/CLAUDE.md     v      Bob: ~/.claude/CLAUDE.md
   (personal prefs)   +-----------+-----------+  (personal prefs)
                      |     Claude Code       |
                      |  session per engineer |
                      +-----------+-----------+
                                  |
                    author reads every line, shrinks diff,
                    understands it, uses a named mode
                                  |
                                  v
                      +-----------------------+
                      |  PR: small, scoped,    |
                      |  decisions explained,  |
                      |  AI footprint flagged  |
                      +-----------+-----------+
                                  |
                                  v
                      reviewer focuses on flagged
                      context-dependent areas

The shared config drives convergence. The personal config absorbs individual preference without leaking it. The author is the first reviewer. The human reviewer knows where to look. Nothing here requires a new tool. It requires four agreements.

A Concrete CLAUDE.md for a Team

To make it concrete, here is a root CLAUDE.md structured for a ten-person team. Note what is in it and, more importantly, what is not.

# Project: Acme Platform (team conventions)

## Commands
- `pnpm dev` / `pnpm build` / `pnpm test` / `pnpm lint`
- `pnpm test -- --grep "auth"` for scoped tests

## Stack (do not substitute)
- Next.js App Router (NOT Pages Router)
- Drizzle ORM + PostgreSQL (NOT Prisma - we migrated off it)
- vitest (NOT jest)

## Hard rules (violating these fails review)
- All DB access goes through src/server/db/queries/
- API responses use the Result type from src/lib/result
- Named exports only, no barrel files

## Prompt modes (team vocabulary)
- tight edit / refactor / feature / spike (see wiki for definitions)

## Scope discipline
- Do not touch files outside the described change without saying why
- Prefer the smallest diff that satisfies the request
- For "feature" mode, state the plan before writing code

That is roughly 25 lines. It is small on purpose. Area-specific detail lives in .claude/rules/. The negative instructions (“NOT Prisma”, “NOT jest”) matter more than usual on a team, because without them each engineer’s Claude drifts toward its training-data defaults in a different direction, and you get a codebase that fights itself.

What This Does Not Solve

Being honest about the limits.

• It does not stop a determined engineer from rubber-stamping. Conventions are social. If the team culture rewards volume over understanding, the “I can defend every line” checkbox becomes a lie people click through. The conventions work when leadership actually enforces small, understood PRs.
• It does not make review free. AI raises the volume of code. Even with perfect scoping, reviewers have more to look at. Teams that succeed here often pair the conventions with stricter PR size limits than they had before AI, not the same ones.
• It does not fix a bad CLAUDE.md owner. Ownership concentrates the risk. A tech lead who lets the file rot or who encodes their personal taste as team rules is worse than no owner. The role needs someone with judgment about the line between rule and preference.
• Path-scoped rules add maintenance. .claude/rules/ files can go stale like any config. They need to be in the same review path as the code they describe, or they drift out of sync silently.

What to Actually Do

If you are rolling Claude Code out to a team this quarter, do these four things in order and skip everything else until they stick:

1. Make CLAUDE.md a reviewed file with one owner. This is 90% of the value. Do it first.
2. Write down three or four named prompt modes and put them in the CLAUDE.md. Ten lines, huge convergence.
3. Adopt the rule that the PR author owns every line. Enforce it by asking “why is this here” in review until people internalize it.
4. Add two checkboxes and a focus hint to the PR template. Cheap, and it changes how reviewers spend attention.

The teams that struggle with Claude Code at scale are not the ones with the wrong model or the wrong config. They are the ones that treated a team tool like a personal one and let ten private workflows diverge in ten directions. The conventions above are boring on purpose. Boring conventions, written down and actually followed, are what turn ten fast individuals into one fast team.