I like CLAUDE.md. I also think people are asking it to do a job it cannot do.
CLAUDE.md, AGENTS.md, and .cursor/rules are where you put the rules you want an agent to follow: how to run tests, which folders are sensitive, what style the team uses, and when to ask before deploying. That is written context. It belongs in git.
But a coding agent also learns things while it works.
It discovers that a particular test is flaky under one flag. It learns why an apparently odd abstraction exists. It finds the deployment step that is not in the runbook yet. Those are not stable enough to hard-code into an instruction file, and they are too useful to lose when the session ends.
That is the distinction I use:
- Instructions are what your team writes down before the work.
- Memory is what your connected agents learn during the work.
The practical move is not to replace instruction files. Keep them. Add a small memory protocol beside them:
Top comments (1)
One rule I would add at the promotion boundary: memory entries are hypotheses, instructions are ratified. A "this test is flaky under FLAG_X" note discovered mid-session has a confidence and a timestamp; six weeks later the flake may be fixed and the note is now misinformation with the authority of memory. So the write path matters less than the read path: when the agent consumes a memory entry, it should re-verify cheap claims before acting on them (run the one test, check the flag still exists) rather than trusting the note. And promotion from memory to CLAUDE.md should go through the same review as code: a human reads the entry, decides it is stable and team-relevant, and lands it in a commit. The anti-pattern is letting the agent append to the instruction file directly, which quietly merges the two categories you just separated.