CLAUDE.md as team knowledge base
CLAUDE.md as team knowledge base
One-line summary: A single plain-text CLAUDE.md file per repo, checked in and edited multiple times a week by everyone on the team, serves as the agent's institutional memory — and its maintenance is treated as core engineering work.
The insight
The agent's long-horizon context is not the model; it's the repo-level instructions file. Teams that treat CLAUDE.md as a living doc — updated every time the agent does something wrong, every time a code-review lesson repeats — compound the agent's effectiveness over time. Teams that set-and-forget it hit a ceiling.
The format is intentionally boring: plain text, no schema. The discipline is in the update cadence, not the structure.
Evidence
- From 2026-04-21-boris-claude-techniques (Boris Cherny):
- "Our team shares a single CLAUDE.md for the Claude Code repo. We check it in to git, the whole team contributes multiple times a week. Anytime we see Claude do something incorrectly, we add it to the .md. So Claude knows not to do it next time."
- "Other teams maintain their own CLAUDE.md's. It is each team's job to keep theirs up to date."
- "The CLAUDE.md is just a text file. So there's no special format — people ask this all the time. Is there some special format that it has to be in? No, it's just a text file. So you can put whatever you want in it."
- "Make sure that you invest in your CLAUDE.md — that's super, super important."
- Reply commenter @MGMurray1 reports a variant: 7 master files instead of 1, each serving a different slice of institutional knowledge — e.g.,
SOUL.mdfor voice and judgment,AGENTS.mdfor agent behaviors. Suggests the single-file convention is not a hard requirement.
How Boris connects it to code review
Boris treats CLAUDE.md maintenance as the successor to an older practice of his:
"Back when I was at Meta … every code review that I did, I would keep a spreadsheet of all the issues that came up. And whenever the same kind of issue came up again, I would just tally up on the spreadsheet. And whenever something hit like five or ten tallies, I would write a lint rule … So I don't have to comment about it again." "This is the equivalent nowadays. It's tag
@claudeand you have it update your CLAUDE.md, which is your team's knowledge base."
He explicitly credits this framing as his version of Dan Shipper's "compound engineering" — automating what you'd otherwise comment on twice. (Boris notes two bugs in his original tweet: the idea is "compound engineering," not "compounding engineering," and the GitHub handle is @claude, not @.claude.)
Design implications
- Make CLAUDE.md edits a normal PR artifact, not a rare event. Boris's team contributes multiple times per week.
- Code review becomes a CLAUDE.md feeder. The feedback loop is: see Claude err → file a line in CLAUDE.md → agent doesn't err that way again.
- The
@claudeGitHub Action closes the loop — installed via Claude Code's/install-github-action, it lets reviewers drop a CLAUDE.md update directly from a PR comment, with Claude pushing the change back to the branch. - Don't over-engineer the format. Schemas and structure come later (or never); update frequency is the leading indicator of health.
Contradictions / tensions
- One file vs. many. Boris says one file per repo; @MGMurray1's team uses seven. Neither source quantifies when the split is worth it. Hypothesis: at small scale, one file; at enterprise scale with multiple specialized agent personas, multiple files give better separation of concerns.
Open questions
- How does CLAUDE.md quality decay as it grows? At what size do agents start paying diminishing attention to later entries?
- Is the right update cadence "every time Claude errs" (Boris) or "every time the same kind of issue repeats" (his older tally-then-rule pattern)? The former is noisier; the latter is slower to react.