Solutions
What belongs in AGENTS.md, and what it cannot hold
Updated
AGENTS.md is the right home for instructions: conventions, commands, mistakes to avoid, read by most coding agents. Findings, what an agent works out mid-job and what was already tried and abandoned, belong somewhere else: they arrive after the file is written and go stale without announcing it. In Forkbench that somewhere is a Thread, where any agent can list, read and revise a note instead of growing the file.
You wrote an AGENTS.md and for a fortnight it was the best hour you had spent. The agent stopped guessing the package manager, stopped reformatting files it had no business touching, stopped proposing the approach you had already ruled out. Then it grew. Every correction became another line, it passed four hundred, and it is now read in full at the start of every session whether any of it applies to the task or not. Some of it is no longer true, and nothing tells you which parts.
The distinction is not stylistic. It is about when a thing is written and when it is needed. An instruction is stable: you know it in advance, it applies to every task, and paying for it on every session is a fair price. A finding is the opposite - produced during one job, relevant to that job and to whatever later touches the same ground, and worthless everywhere else. Put findings in AGENTS.md and you pay context for them forever; leave them out and they die when the pane closes, which is why most of them are never written down at all. In Forkbench they go to the Thread the job lives in: an agent files what it learns as a note, any agent in that Thread can list, read and revise it, and nothing is loaded until something goes looking for it.
How it works
- 1Keep AGENTS.md for what you would tell a new colleague on their first morning: the stack, the commands, the conventions, the two mistakes everybody makes.
- 2Take out anything phrased as a fact about the system rather than an instruction to follow. Those are the lines that go stale without telling you.
- 3Give the job a Thread and file those facts there instead, so they are fetched when an agent needs them rather than pre-loaded on every session.
- 4Tell your agents to write findings down as they go. An agent that is not asked to will not.
- 5Leave AGENTS.md where it is. Your agents read it, Forkbench does not touch it, and the two are not competing for the same job.
Straight about the guarantee: Forkbench does not read, write or sync AGENTS.md or CLAUDE.md. Those are your agent's files and they stay exactly as they are. Notes are a separate place agents reach through a tool call or the fb command, which is what makes them retrievable rather than pre-loaded. Notebooks are free and unlimited, version history and the cross-notebook library included.
Frequently asked
Is AGENTS.md the same as CLAUDE.md?
They do the same job for different readers. CLAUDE.md is Claude Code's own instruction file; AGENTS.md is the cross-tool convention a long list of other agents read. If you keep both, make one authoritative and have the other point at it, or you will maintain the same rules twice and they will drift.
Should I delete my CLAUDE.md?
Not unless you have stopped using Claude Code. The two coexist happily. What is worth deleting from either is the accumulated facts, which is a different edit from deleting the file.
Does Forkbench read AGENTS.md?
No. It is a terminal: your agent reads AGENTS.md exactly as it does now, because it is the same file in the same repository. Forkbench adds a second place, outside the repository, for the material that should not be loaded on every session.
Related: CLAUDE.md is too big. What do you take out?, Does Codex read CLAUDE.md?, Claude Code to Codex: what actually carries over