Multi-Developer CLAUDE.md

A single-developer CLAUDE.md is a personal tool. A multi-developer CLAUDE.md is a shared contract. The transition from one to the other is where most teams struggle, because the instincts that make a personal CLAUDE.md effective — specificity, personal shortcuts, idiosyncratic trigger phrases — are exactly the instincts that make a shared CLAUDE.md contentious.

The core tension is ownership. When one developer writes the CLAUDE.md, it reflects their mental model, their priorities, their coding style. When five developers share it, whose mental model wins? The answer cannot be "everyone adds their preferences" because that path leads to a 600-line file where half the rules contradict the other half.

The solution is to separate shared rules from personal rules using the CLAUDE.md hierarchy. The project-level CLAUDE.md (committed to the repository) contains only team-agreed rules: build commands, architecture descriptions, hard constraints, and naming conventions that the team has explicitly decided on. Personal preferences — formatting shortcuts, trigger phrases, model preferences — live in ~/.claude/CLAUDE.md, which is per-developer and never committed.

This separation requires discipline. When a developer discovers a useful rule, the question is not "should I add this to CLAUDE.md?" The question is "would every developer on this team agree this should be a rule?" If yes, it goes in the project file. If no, it goes in the personal file. If maybe, it goes in a PR and the team decides.