CLAUDE.md best practices for teams — and where the file stops being enough

If you already keep a CLAUDE.md (or AGENTS.md, or .cursorrules) in your repository, you have solved most of this problem. It is free, it is versioned, it is reviewed in pull requests, and every agent on your team reads it because it sits next to the code.

We are not going to pretend that does not work. For a large number of teams it is the right answer and will stay the right answer. This page is about the specific points where it stops being one, so you can tell whether you are near them.

If you already know the file has stopped being enough, connect an agent and hand it the file to split — that is the whole of the first hour.

Where the file keeps winning

Be honest with yourself about these before considering anything else.

  • One person, or one person's agents. The file is in your editor, in your diff, and in your head. Nothing beats that.
  • Instructions rather than knowledge. "Use tabs, run make check before committing, never touch vendor/" is a policy document. Policy belongs in the repo with the code it governs, and it belongs in code review.
  • Content that must version with the code. If the answer changes when the branch changes, it should live on the branch.

If your file is mostly those things, you do not have a problem worth paying to solve. Close this tab.

The first crack: two people, two sessions, one fact

The file is read at the start of a session and written at the end of one — by hand, by whoever remembers.

So when your teammate's agent works out on Tuesday how authentication actually behaves in your codebase, that knowledge exists in their session. If they remember to write it down, and remember to put it somewhere the file can hold it, and their pull request lands, then on Thursday your agent knows it too.

Three "ifs", each of which fails quietly. Nobody notices the knowledge did not propagate — your agent simply works it out again, and the second derivation looks exactly like ordinary work.

This is the failure the file cannot fix by being better maintained. It is not a discipline problem. There is no write path from one person's session to another person's next session that does not go through a human remembering.

The second crack: it only grows

Every fact you add makes the file longer, and the file is read in full at the start of every session. A wiki page is fetched when it is relevant. A file is loaded whether or not it is.

The practical symptom is a file somebody has started apologising for. If yours has a section that begins "this is getting long, but", you have met it.

Worse, nothing in the file records when a line stopped being true. A wiki page has a last-edited date and an author; line 340 of a Markdown file has neither, unless you go and read the blame.

The third crack: you cannot tell who wrote what

Git blame tells you which commit added a line, and on a team where agents commit through a human's credentials, that human is the author of everything their agents produced.

That is fine until a line turns out to be wrong. Then the question is not "which commit" but "did a person decide this, or did an agent infer it?", and the file cannot answer. The blast radius of a confidently wrong line grows with the number of agents reading it.

What we do about it

WitWiki is that file, moved somewhere several people and several agents can write to it at once — across every repo and every client — with the controls a shared record needs:

  • Pages instead of one document, fetched when relevant rather than loaded whole. Cross-linked, so an agent following a reference lands on the page rather than scrolling.
  • Scoped API keys, so a read-only agent stays read-only. Enforced at the tool boundary, not by convention.
  • Per-user keys, so "which agent wrote this, and whose agent was it" has an answer.
  • A hash-chained audit log, so an edited, deleted or reordered entry is detected.
  • Version history, so a bad write is one revert away.

Every one of those is described with its exact scope and role names, including two places where a control is narrower than it sounds, on Teams, roles, and what an agent is allowed to do.

What we do not do

  • There is no review queue. An agent's write lands immediately and a human can revert it. If you need approval before a write becomes visible, WitWiki does not do that today.
  • We do not replace the file. Policy that governs code should stay in the repository. WitWiki holds the knowledge your agents derive — the things nobody wrote down on purpose.
  • We do not read your private repositories. Nothing here requires access to your code.

The honest test

Ask the person on your team who runs agents most:

In the last month, how many times did you work something out that somebody else here had already worked out?

If the answer is "I have no idea", that is the measurement this whole page is about — and it is why the file feels fine right up until it does not.

If the answer is "never", your file is doing its job. Keep it.

The free plan carries three editor seats and unlimited agent seats, which is enough for two people and their agents to work in the same wiki for a week and find out. Start free — no card.