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. - From 2026-08-18-autoresearch-effective-all-day-bot-loops: SitePoint's 13-day recipe keeps architectural rules and do-not-touch zones in a committed
CLAUDE.mdand feeds tasks to isolated CLI sessions. Cursor Cloud Agent best-practices put the same class of conventions inagents.md+ skills for a "smart but low-context" developer. DEV Community is explicit that hotstate.mdmust stay under 4 KB because it is injected every iteration; historical journal and learned facts go in cold files the agent reads on demand. That split maps onto this page:CLAUDE.md/agents.mdis cold / durable memory; the next queue row (or a tinystate.md/TODO.md) is hot state. OpenClaw'sHEARTBEAT.mdis the always-on analogue and must stay short because every token is loaded every cycle. - From 2026-08-23-session-cursor-paper-grok-app-builder-workflow: repo
AGENTS.mdis always applied and instructs consulting Grok skills; “it does not inject the skill bodies.” Instruction file ≠ available-skills list. See agent-skill-discovery. - From 2026-08-27-best-agent-harnesses-for-programming: the filename standard is now contested at lab/CEO level — OpenAI documents AGENTS.md as the instruction chain; Anthropic still ships CLAUDE.md as native; Tobi (primary, 25 Aug 2026) vs Thariq (primary: Claude.md stays default; AGENTS.md support “working on it,” not fetched as shipped). That fight lives on agents-md-vs-claude-md. This page stays the process claim (living team file, update cadence). Do not collapse the two.
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.
- Keep hot state tiny. For an unattended loop, do not dump the day's journal into the file that is injected every wake (unattended-all-day-agent-loop).
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.
- CLAUDE.md vs AGENTS.md as a standard. Process can survive either filename. Cross-tool default is unresolved as of 25 Aug 2026. See agents-md-vs-claude-md.
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.
Sources
- 2026-04-21-boris-claude-techniques
- 2026-08-18-autoresearch-effective-all-day-bot-loops
- 2026-08-23-session-cursor-paper-grok-app-builder-workflow
- 2026-08-27-best-agent-harnesses-for-programming — AGENTS.md vs CLAUDE.md standard fight (see agents-md-vs-claude-md)