Repo instruction files
AGENTS.md, CLAUDE.md, Cursor rules. Standing instructions a person writes in the repo, loaded into the agent's context at the start of every session.
Verdict
Necessary for conventions every session must follow, but they hold rules, not history; pair them with something that remembers.
Best for
Every repo with agents in it: build commands, conventions and the things no agent should ever do.
Poor fit
Anything that changes during a run: decisions, progress, who is doing what.
Scores
| Criterion | Score | Why |
|---|---|---|
| Survival across sessions | Strong | In git, so every checkout and sandbox has them. |
| Cross-tool reach | Partial | AGENTS.md reaches many agents; tool-specific files (CLAUDE.md, Cursor rules) reach one. Check each agent's docs for which it reads. |
| Multi-agent sharing | Weak | Changes reach other agents only after they are committed and pulled. |
| Retention of reasons | Weak | Rules, not the conversations behind them. |
| Scale | Weak | Must fit in every session's context, so they cannot grow with the project. |
| Openness | Strong | Plain files you own. |
Strengths
- Committed, reviewed and versioned like code.
- AGENTS.md is read by many agents; CLAUDE.md and Cursor rules serve their own tools.
- Cheap and predictable: the same text every session.
Limits
- Written by people, so they are only as current as the last person who edited them.
- Loaded whole into every session, so they must stay short; they cannot hold a project's history.
- They record the rule, rarely the incident that made it a rule.
How it fails
- A rule that was true in March is still loaded in November, and the agent follows it.
- Two instruction files (AGENTS.md and CLAUDE.md) drift apart and agents behave differently in the same repo.
Cost
Free: files in your repo, read into every session's context.