Team Collaboration Conventions for CLAUDE.md

A CLAUDE.md written by one engineer and never revisited by the rest of the team tends to drift toward that one person’s preferences and blind spots. Treating it as genuinely shared infrastructure — with the same review discipline as any other part of the codebase — is what keeps it representing the team’s actual conventions rather than one contributor’s opinions.

Review It Like Code

<!-- A PR that changes a convention should update CLAUDE.md in the same PR -->
Title: Migrate error handling to Result<T, E> pattern

Files changed:
- src/services/*.ts        (the actual migration)
- CLAUDE.md                 (updated: "Error Handling" section now
                              documents the Result<T, E> pattern instead
                              of the old exception-based approach)

The rule of thumb: any PR that changes something CLAUDE.md documents should update CLAUDE.md in the same PR, not as an afterthought. This is the same discipline good teams already apply to README updates — the file review-list should include it explicitly.

Assign Ownership

For a file that affects every agent session on the project, it’s worth being deliberate about who has final say on changes — not because contributions should be gatekept, but because an unowned, anyone-can-edit-anything file tends to accumulate inconsistent voice and unreviewed additions over time. A common pattern: whoever owns the codebase area a section describes (the API team owns the API conventions section, the frontend team owns the frontend section) is the natural reviewer for changes to that section.

Capture Disagreements as Decisions, Not Ambiguity

<!-- Ambiguous — doesn't actually resolve anything -->
Some people prefer named exports, others prefer default exports. Use your
judgment.

<!-- Resolved — a team decision, even if not unanimous -->
Named exports only, no default exports. (Decided in #1284 — default exports
made refactoring/renaming harder to track across the codebase.)

An unresolved disagreement left in CLAUDE.md doesn’t help the agent — it just means behavior on that point stays inconsistent across sessions. Better to make an explicit decision (even a provisional one, revisitable later) than to document the disagreement itself as if that were guidance.

Onboarding New Team Members Through It

A well-maintained CLAUDE.md doubles as genuinely useful onboarding material for new human engineers, not just the agent — reading through it is often a faster way to absorb a project’s real conventions than reading scattered Slack history or asking around. Framing it this way (as documentation for humans and the agent, not agent-only config) tends to raise the quality bar teams hold it to, since nobody wants to hand a new hire a sloppy document.

Handling Cross-Team Monorepo Ownership

In monorepo setups (see Monorepo & Multi-Directory CLAUDE.md Setups), ownership naturally splits along the same lines as code ownership — each package’s CLAUDE.md reviewed by that package’s owning team, with the root file requiring broader cross-team review since it affects everyone.

<!-- CODEOWNERS-style thinking applied to CLAUDE.md -->
/CLAUDE.md                    @platform-team          # cross-cutting, needs broad review
/packages/api/CLAUDE.md       @backend-team
/packages/web/CLAUDE.md       @frontend-team

If your repository already uses a CODEOWNERS file for review routing, extending the same pattern to CLAUDE.md files is a natural, low-effort way to formalize this.

Common Mistakes

Letting CLAUDE.md changes go through without any review, unlike every other file in the repository — this is exactly how it drifts toward reflecting whoever last had time to edit it, rather than the team’s actual, agreed conventions.

Documenting a still-unresolved team disagreement as if it were settled guidance, or conversely leaving genuine open questions unstated as though they’d already been resolved — both leave the agent (and human readers) with an inaccurate picture of the team’s actual position.

Assuming one person’s mental model of the project is the whole team’s. A CLAUDE.md written solo, without any review from teammates who work in different parts of the codebase, tends to reflect only the author’s own areas of familiarity — genuinely broad review catches blind spots a single author wouldn’t think to include.

Frequently Asked Questions

Should CLAUDE.md changes require the same approval process as production code changes? Not necessarily as strict, but at minimum a review from someone other than the author — the goal is catching drift and blind spots, not adding heavyweight process to a documentation file.

How do we handle a CLAUDE.md that’s grown inconsistent because multiple people have edited it independently over time? Periodic full-file review sessions (not just incremental PR reviews) catch inconsistencies that individual small edits miss — treat it the same way you’d periodically revisit and clean up a style guide that’s accumulated contributions from many people.

What if the team can’t agree on a convention CLAUDE.md needs to document? Escalate it as you would any other unresolved technical decision (a team discussion, a documented tradeoff, a decision made by whoever has final say in that area) — the goal is landing on a stated decision, not leaving CLAUDE.md itself as the venue where the disagreement plays out.

Summary

The same discipline that keeps a codebase’s other documentation trustworthy — review, clear ownership, explicit decisions over unresolved ambiguity — is what keeps CLAUDE.md representing the team’s actual shared conventions rather than one person’s preferences frozen at whatever point they last edited it. Treat it as real, reviewed infrastructure, not an informal scratchpad.