What goes in CLAUDE.md, AGENTS.md and team memory?
By Soumen Sarkar · October 2026
Short answer: CLAUDE.md and AGENTS.md hold the stable instructions for working in a repository: how to build and test, conventions, and how agents should behave. Team memory holds what changes every day: decisions with their reasons, work in progress, open assumptions and handoffs, searchable by every agent.
What are CLAUDE.md and AGENTS.md?
Both are instruction files checked into the repository. Claude Code reads CLAUDE.md at the start of every session. AGENTS.md is the file Codex and several other coding agents read for the same purpose. Many teams keep one of them as the real file and have the other point to it, so every agent gets the same instructions.
Because they live in the repository, they change through commits, like code. That makes them a good home for things that change slowly, and a poor home for things that change every hour.
What belongs in the instruction files?
- How to build, run and test the project.
- Conventions that apply everywhere: naming, error handling, where tests go.
- How agents should behave: look before asking, state assumptions, leave a handoff.
- Where to find everything else, including how to reach team memory.
- Rules that rarely change and apply to the whole repository.
What belongs in team memory?
- Decisions, each with its reason and the part of the code it applies to.
- Work in progress: who is changing what right now, with the goal and plan.
- Open assumptions waiting for someone to confirm or correct.
- Handoffs from sessions that stopped before they finished.
- What was tried and dropped, so nobody tries it again.
How do I tell which is which?
Ask two questions. Will it still be true next month without anyone touching it? Does it apply to the whole repository? If both answers are yes, it goes in the instruction file. If either is no, it belongs in memory, where it can be added, searched and replaced without a commit.
What does the split look like in one repository?
A team ships features behind flags. Their CLAUDE.md says:
## Feature flags
- Every new user-facing feature ships behind a flag in lib/flags.
- Remove a flag within two weeks of full rollout.
That is a stable rule for the whole repository. Meanwhile, in Flags · lib/flags, an agent decides that the checkout-v2 flag stays on for EU customers only until VAT display is finished, because prices shown without VAT break EU rules. That decision belongs in memory: it concerns one flag, it will be superseded in a few weeks, and the next agent that touches flags needs to find it today. Putting it in CLAUDE.md would mean a commit to add it, another to remove it, and an instruction file that slowly fills with expired calls.
How do the two connect?
The instruction file tells agents that memory exists and when to use it: search before deciding, record decisions as they are made. Memory does the rest. This is answer it yourself: look first, and if the answer isn't there, assume it or decide it.
With Campfyrr as team memory, Claude Code sessions don't even need to remember to look. Hooks hand each session the team's state at start and the team record for each area the first time it touches it. Other agents reach the same memory through MCP tools.
Words used here
- Team record: The team record is everything a team has written down that a person or agent can search before asking: decisions, rules, handoffs, assumptions and the reasons behind changes.
- Decision: A decision is a call made in the work, recorded with its reason at the moment it is made, so it travels to everyone who touches the same ground.
- Work in progress: Work in progress is work under way, shown with its plan, so others build on it rather than around it.
- Handoff: A handoff is what unfinished work carries for whoever continues it: what's done, what's left, the next step, and what to watch out for.
The principle behind this: Answer it yourself: Look first. If the answer isn't there, assume it or decide it.
Move as one at agent speed. Nobody waits. Add Campfyrr to Claude: it briefs every agent before it touches the code, keeps assumptions and handoffs where the team can see them, and never takes your code (what it keeps).