Skip to content

A shared rules folder is not a handoff between coding agents

One AGENTS.md can brief Codex and Claude Code alike, but it does not pass work between them. A session continues another's task only from the trail that session had to leave: a progress log, a task list with statuses, small commits. Even then it re-reads the work. It does not resume it.

The short answer. A shared rules folder tells every agent how to work. It does not tell the next agent what was done. When one agent stops halfway, another can continue only from the trail the first one had to leave: a progress log, a task list with statuses, a commit per step. Even with that trail, the new session starts cold and reads its way back in.

The claim, at its strongest

A piece of advice is going around. Put your agents on one server: Codex, Claude Code and a few server-side scripts. Give them one folder of shared documentation, rules and instructions. When one agent runs out of its usage limit, another picks up the task and carries on without a break.

Half of this holds, and that half deserves to be said first. Shared instructions really are a standard now. Codex reads AGENTS.md automatically. Claude Code reads it from v2.1.277. So one file really can brief both tools. The part that does not hold is "picks up the task without a break".

Where it breaks: rules are not state

A rules folder holds the same text before the task, during it and after it. Several things never make it into that text. Which task was half done. Which test was red. Which external call already went out.

Anthropic described this problem in an engineering post on long-running agents (26 November 2025). Their fix was a set of artifacts, not a longer set of rules: claude-progress.txt, feature_list.json and the git history. Each session starts by reading the progress file and the git log, takes one unfinished feature from the list, and ends with a commit. Even with that setup, agents left the environment broken, and the next session had to "guess at what had happened".

We take this as the strongest evidence against the no-break version of the claim. It does not come from critics of agents. It comes from the people who build one of them.

Proof: more context is not a handoff either

In February 2026 an ETH Zurich group (Gloaguen, Mündler, Müller, Raychev, Vechev) measured what repository context files do to coding agents, on SWE-bench Lite (300 tasks) and AGENTbench (138 tasks).

context file             solved tasks         cost
written by the model     -0.5% / -2%          +20% / +23%
written by developers    +4% on average       up to +19%

Be precise about what was measured. These are context files that describe the repository: its layout, its conventions, how to build and test. The study did not measure progress logs or run records, and we are not claiming it did.

Our reading is narrower than "never let an agent write a file". A model's general description of the project mostly repeats what the agent could read for itself, so it adds reading and cost without adding much. A progress log is a different kind of file. It records facts that exist nowhere else: what was finished, what failed, what already went out. That is the thing a rules folder cannot hold. Keep the rules file short and written by a person. Let the agent write the log.

The opposite myth is wrong too

The usual rebuttal says that switching agents mid-task loses all progress. That does not hold either. If the progress lives in files and in git, nothing is lost. What you lose is the session's working memory, and you pay to rebuild it. So progress is safe if it was written down. The handoff still has a seam.

What actually carries the work

Production practice for agents points the same way. Agent state goes into durable storage from the first step, not into process memory. Every action with an external side effect is made idempotent or checkpointed, so a restart does not repeat it. We also see a trend in engineering practice: instead of growing the system prompt, a harness writes intermediate output to the filesystem, keeps a running list of subtasks and isolates subagents. The working state lives in artifacts, not in rules.

Here is what that looks like in a repository. These are our sketches, not a standard.

A progress log that each session appends to before it stops:

# progress.md
2026-10-13 14:02  session: codex
  done:    F-12 invoice export, tests green, commit 3f1a9c2
  started: F-13 retry on webhook timeout
  state:   test_webhook_retry RED, cause unknown
  careful: sandbox payment sent once for order 8812 - do not resend
  next:    read logs/webhook.log before touching retry code

A task list with statuses, so the next agent picks one item instead of guessing:

[
  {"id": "F-12", "title": "invoice export",   "status": "done",        "commit": "3f1a9c2"},
  {"id": "F-13", "title": "webhook retry",    "status": "in_progress", "owner": "codex"},
  {"id": "F-14", "title": "refund endpoint",  "status": "todo"}
]

The routine every session follows, whichever tool runs it:

start:  read AGENTS.md, progress.md, git log -20, the task list
        run the test suite; if red and not yours, fix or record it first
work:   one task only
stop:   tests green or the failure written down
        commit, update the status, append to progress.md

Side effects that survive a restart without repeating:

key = f"refund:{order_id}:{attempt_id}"
if ledger.exists(key):
    return ledger.get(key)            # already done by an earlier session
result = payments.refund(order_id, idempotency_key=key)
ledger.put(key, result)               # receipt written before anything else

None of this is clever. It is discipline. A rules folder can require it ("append to progress.md before you stop"), but it cannot do it for the agent.

How we run it ourselves

Our internal task board, krilal board, is built this way. The board is a git repository. A card is a markdown file, and moving a card between columns is a commit. One model executes and another reviews. Auto mode takes work strictly one card at a time, because each working copy is cut from the current main. A card that fails or is rejected three times goes back to the queue marked "waiting for you". It is not picked up again until a person moves it. The card numbers reached 0229 by 15 September 2026, and eleven cards were merged on 14 September alone, each on its own branch after review. Whichever model picks up a card, the handoff is the history of that card.

What would change our mind

Two things would. The first is a measured run in which a fresh session continues a half-finished task from a rules folder alone, with no progress log, task list or commits, at the same solve rate and cost as a session that has them. The second is a runtime that carries in-flight execution state across vendors in a form another tool can read. We have seen neither. If you have, we will correct this post in public.

Checklist

1. One short AGENTS.md for rules, written by a person.
2. A progress log every session appends to before it stops.
3. A task list with statuses; one task per session.
4. A commit per step; leave the tests green or the failure written down.
5. Idempotency keys on every external side effect.

FAQ

Can Codex and Claude Code share one instructions file? Yes. Codex reads AGENTS.md automatically, and Claude Code reads it from v2.1.277.

Should I let the agent write its own context file about the repository? On the ETH Zurich numbers, no. Model-generated context files lowered the share of solved tasks by 0.5% and 2% and raised cost by 20% and 23%. Files written by developers raised it by 4% on average, at up to 19% more cost. That study was about files describing the repository. It says nothing either way about a progress log, which we think the agent should write.

Is progress lost when an agent hits its limit? Not if it was written down. Files and git keep the progress. What gets lost is the session's context, and the next session spends time and tokens rebuilding it.

What can a text file not reliably hand over? An action that was in flight. Whether a payment went out or an email was sent should live in a ledger with idempotency keys, not in prose.

A related case

Holt, our language-learning product, is built on the same rule: the state the next step depends on stays outside the model. In Holt, math owns the schedule and AI owns the content. The engine that decides what a learner sees next never calls a model. The case is at iloblique.com/holt.

Sources