CLAUDE.md for teams: how we turned five people's AI memories into shared rules

Every developer who works with an AI coding agent is quietly writing a rule book. Claude Code’s auto memory saves notes from your corrections as it works, your personal ~/.claude/CLAUDE.md collects the preferences you got tired of repeating, and a few personal skills grow up around the jobs you do every week. All of it is private. Auto memory is machine-local and per repo: your teammates’ agents never see it.

So five people learn the same lesson separately, each in a private file. The rules your team most needs are already written down. They’re just not written down anywhere shared.

In September, five of us ran a memory harvest: we pooled those private files and asked which rules deserved to become team rules. This is how we did it, what earned promotion, where each rule went, and what we found, including the rules we got wrong.

What a memory harvest is

A memory harvest is a team practice with three steps. Each person exports their private agent memories and personal rules. One reviewer clusters the entries across everyone’s exports. The rules that several people wrote down independently get proposed for the shared files: the project CLAUDE.md, AGENTS.md, a shared skill, or a check in CI.

It’s the maintenance step context engineering usually skips. We’ve argued before that context files need a feedback loop driven by the agents that use them. A harvest is the same loop run across people instead of sessions: it’s Stage 4 of the agent feedback lifecycle, aimed at the notes already stranded in private memory.

The tooling for this is thin. Of ten AI coding tools we looked at, only Devin ships a loop that watches a session, proposes a shared rule and waits for a human to approve it. The rest rely on files people write and commit by hand, or instruction sets an admin pushes out. None of them mines several people’s private memories for candidate team rules.

What we did

On 17 September 2026, five developers each ran an export script over their own Claude Code memories, their personal global CLAUDE.md and their personal skills. The script transmits nothing. Each person read their own bundle, deleted anything that shouldn’t travel, and only then submitted it.

The five bundles held 444 memory entries, 5 global CLAUDE.md files, 13 personal skills and 194 rows describing the skills installed in each repo. One reviewer, an AI agent working with a human, clustered the entries across all five bundles and wrote up a proposal for each cluster. On 22 September, four of us voted on two review pages. The promotions landed as ordinary pull requests in three repos: our main product repo, a games repo and our shared skills plugin.

The bundles live on a branch that never merges. Only the promotions leave, each as a separate PR against the repo it governs, reviewed like any other change.

What earns promotion: count authors, not entries

A rule earns promotion when two or more people wrote it down independently. Count distinct authors, never entries. This one rule did most of the work, and it needed three refinements before it could be trusted.

Weigh the heavy user. One bundle held 251 of the 444 entries, across 10 repos. Everyone else brought 37–68 entries across 1–4 repos. So “two authors” usually meant “our heaviest agent user plus one”, and a cluster without the heavy user was rarer and stronger evidence. We marked those clusters separately.

One person is one author. One developer exported from two machines. That’s one author. One person restating the same rule three times is emphasis. Corroboration needs a second person.

Shared sources aren’t independent. Two people’s global CLAUDE.md files were byte-identical in their first four sections, because both had adopted the same published text: Andrej Karpathy’s coding guidelines for AI agents. Both were quoting one upstream document, so it counted as a single source. Any future cluster resting only on that pair gets checked against the upstream wording first.

To classify each cluster we borrowed the four operators from ExpeL, a research method for agents that learn rules from experience: ADD a new rule, UPVOTE one the shared docs already have, DOWNVOTE one the evidence contradicts, EDIT one that’s close but wrong. Downvote and edit matter as much as add. A harvest that can only add rules makes your context files longer and never more correct.

The threshold decides what the reviewer proposes, not what the team may adopt. A second review page listed the one-author facts that looked worth sharing, and the room voted on each. They got in because people read them and agreed.

Where each rule should live

Agreeing on a rule is half the decision. The other half is its altitude: the level where it will actually be read and applied. (Our guide chapter on where a fix should land covers the ladder in full.) For harvested rules, this is the routing table we used:

The rule is	It belongs in	Why
A standing fact every session in this repo needs	The project CLAUDE.md	It loads at the start of every session
The same, for every AI tool the team uses	AGENTS.md, imported from CLAUDE.md	One file every tool can read
Only relevant to part of the codebase	A path-scoped rule in .claude/rules/	Loads only when the agent touches matching files
A procedure used across several repos	A skill in a shared plugin	Plugins carry skills, not CLAUDE.md
A procedure specific to one repo	A repo skill	Loads when the task calls for it
Reference detail too long for every session	A doc, plus a one-line pointer in CLAUDE.md	A doc nothing loads is a doc the agent never reads
Mechanically checkable	A lint rule, test or CI check	Prose warns; a check stops it
A preference about your own tools, machine or budget	Your personal CLAUDE.md or memory	It isn’t a fact about the codebase

Two rows need emphasis. First, a Claude Code plugin can ship skills, agents and hooks, but not a CLAUDE.md. Procedures cross repos in a plugin; standing rules have to be placed in each repo that needs them.

Second, only delete the private memory once the destination auto-loads. Move a rule into a doc that nothing loads and the agent simply forgets it. Where a rule went into reference docs, the private memory shrank to a pointer instead of disappearing.

What to do with contradictions

Pooled memories disagree. Resolve a contradiction by scope where you can, supersede the stale side, and leave disagreements about preference in an explicit unresolved bucket.

Check scope first. One contradiction was about how to set up dependencies in a second working copy of a repo: two people had written opposite rules. Both were true in their own repo. A later change to a shared skill had since settled it for both, and our heaviest user’s memory turned out to be the stale side, so that is the one to supersede rather than quietly delete.

Supersede, never overwrite. When a shared rule changes, add the new rule with a date and keep the old one readable, the way an architecture decision record supersedes an earlier decision. The next reviewer can see what changed and why.

Keep an unresolved bucket. The second contradiction was which AI model subagents should use. Two people wanted one top-tier model for every subagent; one picked models by task. The vote split two “discuss”, two “agree”. It stayed unresolved on purpose, because it’s about how much each person is willing to spend on their own account, not a fact of the codebase. It stays in each person’s private rules.

What the harvest found

Fifteen promotions landed from the first review page: 11 for our main product repo (two of them also applied to the games repo), three for the shared skills plugin, and one fixing the harvest’s own exporter. Seventeen more landed from the second page: one-author facts the room agreed to share, plus two clusters the first count had wrongly recorded as one-author. On the second page, one item was voted down, three were parked for more discussion or a better home, and three were agreed but need code or a skill rather than a doc line. The model question stayed open.

The most repeated cluster was about comments. Three authors, one of whom had written it down four times: comments state durable facts about the code; they never narrate the change or its history. One author noted that subagents are the usual offenders.

The broadest was about evidence. Four of the five authors had written a version of “verify before asserting; a failed search is not evidence of absence.” Reviewer claims are hypotheses, and failing to reproduce a bug doesn’t prove it can’t happen. It was the closest thing the team had to a shared house rule, and it was written down nowhere shared.

A related cluster, from two authors, was about stale git state: a local branch far behind the remote, a search run against the wrong checkout. Each of its five incidents produced a confident, false claim that reached a commit message or PR description.

Harvesting corrected wrong guidance, not just missing guidance. Three findings were DOWNVOTE or EDIT calls on guidance we already had:

• Our shared AGENTS.md told agents to run the repo-wide lint:fix when changing lint rules. Three people had separately warned against it: the repo doesn’t lint clean at baseline, so a repo-wide fix buries your diff in unrelated formatting.
• A shared skill said to fall back to the API if gh pr edit failed. It doesn’t fail: it prints a non-fatal notice, exits 0 and leaves the pull request unchanged. A fallback keyed on a failure that never happens never runs. Three authors had hit this across three repos.
• An existing warning in our agent docs called one database mistake “safe” because it errors immediately. Three people had hit it on three different tables. In one case the mistake passed review, passed CI and crashed only at runtime.

Some agreed rules belonged in a machine check. The database warning above is mechanically checkable: a test that reads the schema would end the whole class, where the doc only warns about it. “Never hand-edit the generated schema file” was agreed as true and still parked, because prose is the wrong enforcement. Two other agreed items were already written as step-by-step procedures, which makes them skills. Several items left the vote as tickets instead of documentation.

A rule can be default behavior and still need writing. Two people had independently written “never commit or push unless asked”. One put it best: “writing files is not permission to commit them.” Any agent should already behave this way. Two people wrote it down because it kept happening anyway, which is the argument for making it explicit.

The harvest found a bug in the harvest. Each bundle carried a version stamp so the review would refuse to compare bundles built by different collection rules. The stamp came from the plugin’s version, not the exporter’s. All five bundles were built by byte-identical scripts and stamped with three different versions. The safety gate could never fire on a real rules change and would fire on every unrelated plugin update. That fix was one of the fifteen.

How often to run it

The first harvest is the expensive one: months of private notes, cleared in one bounded session. After that, keep a five-minute standing check at a regular team sync: anything new that more than one person has written down?

Five failure modes to design against:

• Write-only: rules get promoted and nobody checks whether the agent’s behavior changed.
• Stale with no owner: a shared rule outlives the code it describes.
• Promoted on n=1: one person’s strong opinion becomes a team rule because they were first to write it.
• One doc holding four kinds of content: standing rules, procedures, reference and history in a single file nobody reads end to end.
• Abstracted until useless: a rule generalized so far from the incident that caused it that it no longer tells the agent what to do.

Run one by hand

You don’t need special tooling. Our export was a small script, but every step works by hand:

1. Export privately. Each person copies their auto memory folder (in Claude Code, ~/.claude/projects/<project>/memory/), their ~/.claude/CLAUDE.md and any personal skills into one folder per person.
2. Prune before sharing. Each person deletes anything that shouldn’t travel: credentials, customer details, anything about a named colleague. Nothing leaves without its owner reading it.
3. Cluster by meaning. One reviewer, human or agent, groups entries that say the same thing in different words and records who wrote each one.
4. Count distinct authors. Two or more independent authors is a candidate. Merge one person’s machines, discount shared upstream text, and note which clusters stand without your heaviest user.
5. Classify and route. Label each candidate ADD, UPVOTE, DOWNVOTE or EDIT, then give it a destination from the routing table above.
6. List contradictions separately. Resolve by scope where you can; leave the rest unresolved and say so.
7. Let the room vote. Put the proposals on one page, the one-author facts on a second, and decide together.
8. Land each promotion as its own PR against the repo it governs. Keep the raw bundles out of main.

Frequently asked questions

What is a memory harvest?

A memory harvest is a team practice for AI coding agents: each developer exports their private agent memories and personal rules, one reviewer clusters the entries across everyone’s exports, and the rules that several people wrote independently are promoted into shared files such as CLAUDE.md or AGENTS.md. It’s the team-level maintenance step of context engineering.

How many people need to agree before a rule goes into CLAUDE.md?

We use two or more independent authors. Count distinct people, not entries: one person restating a rule three times, or exporting from two machines, is still one author. Two people who copied the same published text aren’t independent either. The threshold decides what gets proposed; the team still votes on every promotion.

What belongs in a team CLAUDE.md versus personal memory?

Standing facts every session in that repo needs belong in the project CLAUDE.md, because it loads automatically. Procedures go in skills, reference detail goes in docs with a pointer, and anything a machine can check goes in a lint rule or test. Preferences about your own tools, machine or budget stay personal.

Should team rules go in CLAUDE.md or AGENTS.md?

Rules every AI tool should follow go in AGENTS.md; Claude-specific instructions stay in CLAUDE.md. Claude Code can read AGENTS.md directly or through an @AGENTS.md import, so one file can serve every tool your team uses.

What do you do when two developers’ memories contradict each other?

Check scope first: both can be true in different repos, and a later tool change may have settled it. If one side is stale, supersede it rather than overwrite it. If the disagreement is about preference rather than a fact of the codebase, leave it unresolved and keep it in each person’s private rules.

How often should a team run a memory harvest?

Run one bounded session to clear the backlog, then keep a five-minute standing check at a regular team sync for new candidates. The first harvest is the expensive one; after that the volume should be small.

Make it a team decision

In a memory harvest, the team decides which rules become shared; the reviewer only proposes. The export, the clustering and the counting can all be automated. The vote can’t, and shouldn’t be. Which rules bind everyone, which stay personal, and which disagreements stay open are calls for the people who will live with them. It’s the same point we make in the report exists, the room doesn’t: an aggregate view is only useful once the people who own the fixes decide together.

That’s a retrospective with different inputs. When our AI agents filed their own retro items, the evidence came from their sessions. This time it came from our own private notes, and the room did the same job: read the pattern, pick the altitude, give each fix an owner. If your team already has a regular retro, a memory harvest fits in as one agenda item. The full practice is in our guide to AI agent retrospectives.

Run a harvest of your own, or think our threshold is wrong? Tell us: ai-discussion@teamretro.com.