A prompting convention for working with coding agents over many sessions.
The trick, in a paragraph #
Ask the agent to keep a design-and-work log, and make it append-only: numbered dated sections, never edited, later ones superseding earlier ones by citation. Require every section to end with a list of what was not done. Then state that convention in the file the agent loads on every session.
What you get is a document that keeps its own refutations. When a belief turns out to be wrong, the wrong belief stays on the page and a new section says so by number — so a fresh session with no context can't reintroduce the mistake as an improvement, which is exactly what it would otherwise do whenever the refuted design is the more principled-looking one. The mechanism underneath is economic: append-only drops the cost of a correction from "find and rewrite everything that depended on this" to "write one new subsection," and lowering the price of admitting error is what raises the rate of it. The mandatory "Not done" list attacks the other characteristic failure — the optimistic completion report with the awkward 20% quietly dropped.
How it was found #
By accident, and the accident is instructive.
The opening message of the project this came from asked for something much smaller: it handed the agent a plan document, described as the file I am going to tell you to use, and said append your questions and answers to it. Two things in that sentence did the work, and only one was on purpose. "Append" became the operating verb for that whole file rather than for one task. And framing the document as the user's — a spec authored by someone else and handed over — made it read as not-mine-to-edit. That posture is what yields append-and-cite instead of quiet rewriting.
The same message also asked do you have any questions?, which produced a tagged list of open decisions plus a subsection of "smaller things I'll decide unless told otherwise" — the direct ancestor of every later "Not done" list.
The convention itself appeared in a section nobody asked for. Early on, a factual claim in the plan turned out to be wrong. The obvious move is to edit the sentence. Instead the agent appended a section titled "corrections to the body above," cited the wrong section by number, and left the false sentence standing. That step — from append the answers to append corrections too, and let earlier text stay wrong — is the entire convention, and it happened only because "append" was already the default verb for the file.
What the accident did not produce is the steady rhythm that made it valuable: one numbered dated section per unit of work, each ending in a mandatory "Not done" list. That stabilized later, over dozens of sessions and about sixty sections. So the wording below states it outright rather than hoping it emerges again — which is the point of the next section.
Copy this #
Two blocks. The first is what you say when you open the project; the second is what you paste into the file the agent loads every session. Both are needed — the first starts the convention, the second is what keeps it alive across sessions. The rest of this document is why.
1 — Say this at the start of the project (replace DESIGN.md with whatever you want the log
called; keep the file framed as yours, handed to the agent, not as its own scratchpad):
Keep a design-and-work log at DESIGN.md. Write the plan first, in numbered sections.
After that, the log is append-only: every unit of work appends a new numbered, dated section, and you
never edit an earlier one. When you find that something earlier is wrong, do not fix it in place —
append a section that names the section by number, states what you believed, what the evidence
actually showed, and what changed. Earlier sections are allowed to stay wrong; the rule is that
higher-numbered sections win.
Every section ends with an explicit "Not done" list: what you deliberately skipped, what you deferred
and why, and what's still unverified. Be specific enough that I could pick any item up without asking
you a question.
Attach evidence to claims. If something passed, say what ran and what the numbers were. If it's an
assumption you couldn't check, say so in those words rather than writing it as a fact.
2 — Put this in CLAUDE.md / AGENTS.md once the log has a few sections:
`DESIGN.md` is the project's memory: §1–§N are the original plan, later sections are dated work
entries. **The convention is append-only — later sections supersede earlier ones rather than editing
them**, so earlier sections may contain claims that later ones refuted. When something looks
contradictory, the higher-numbered section wins. New work appends a numbered, dated section with
evidence and an explicit "Not done" list. Consult it before non-trivial work.
Optional third block, in the same CLAUDE.md — a second append-only log at a coarser grain,
greppable with git log -S:
Commit messages follow the same shape: a terse subject, then prose explaining what the evidence
actually showed.
Two rules for yourself, both easy to get wrong:
- Never ask for the log to be cleaned up, condensed, or made consistent. A planning section that still says something false, with a later section pointing at it, is the artifact working.
- Never let the always-loaded file become a log, or the log become a summary. Opposite policies: one is appended and never edited, the other is edited in place and always current.
That's the whole thing. What follows is why each part is load-bearing, what it costs, and where the wording came from. Nothing below depends on the originating project's domain.
1. What the convention is #
Five rules:
- One numbered, dated section per unit of work. Numbers are plain sequential integers, not semantic. Nobody has to decide where a section goes — new work goes at the end, always.
- Append; never edit an earlier section. When a later finding contradicts an earlier one, the earlier text stays wrong and the later section says so, by number.
- Every section ends with an explicit "Not done" / "Still open" list.
- Corrections get their own titled subsection that names what they overturn. Headings that read
like
§7.4 WAS WRONG: <the claim>or§24.3's evidence was wrong, and §28.4 explains why. The heading itself is the correction; you can find every reversal by scanning the table of contents. - Claims carry their evidence — what ran, what the numbers were, where an expected value came from. An assumption you could not check is written as an assumption, in those words.
The document should state the rule about itself. That is the part that makes it self-enforcing: a section that says "following this document's own convention, later sections supersede rather than edit — §28.4 did this to §24.3 — here is that list as it now stands."
The strongest version of this is a log that knowingly contains a false sentence and knows it, and says where:
§2.4 and §7.2 still contain the refuted sentence. They are the planning chapters and this document's convention is that later sections supersede rather than edit — but §2.4's list of three is now a list of two.
That bullet is the convention working, not failing.
2. Why it's worth the trouble #
It preserves refutations, and refutations are what agents keep re-deriving
An edited document says: "the API returns an empty list, not null." The appended one says: we designed for null in §2.4, built on it, tested it, and §60 reversed it against the vendor's own reference implementation — and here is the one test that failed, which existed only to assert the refuted claim.
The second version is worth far more whenever the refuted design is the more principled-looking one. A fresh session reading only the corrected text has nothing stopping it from reintroducing the mistake as an improvement. The record of the failed belief is the guardrail; editing deletes exactly that.
There is a second-order payoff. Once failed beliefs stay on the page, you can start naming patterns across them — "these two components being wrong in the same direction produces agreement and no signal", observed three times now. That pattern is only nameable because the earlier occurrences were still there to count.
It makes self-correction cheap, which is why it happens at all
This is the real mechanism, and it's easy to miss.
If correcting yourself means finding and rewriting every earlier claim that depended on the mistake, the cost of a correction is high and unbounded — so an agent quietly avoids correcting itself, or softens the correction into an edit that reads as if the error never happened. Append-only drops that cost to "write one new subsection." Lowering the price of admitting error is what raises the error-admission rate. The corrections in a mature log exist because they were cheap to write.
"Not done" lists defeat the worst failure mode
The characteristic way an agent fails is not a wrong answer — it's an optimistic completion report with the awkward 20% silently dropped. A required "Not done" list at the end of every unit converts that from a thing that happens invisibly into a thing that must be written down.
And they compound. A later section can revisit an earlier section's eight open items as a status table — itself a new section rather than an edit.
It's a handoff artifact, not a status page
Sessions end and context is lost. Append-only produces a document whose intended reader is someone with zero prior context, in a form where the reasoning survives, not just the conclusion.
Git history technically holds the same information. But a diff shows what changed, not why the old
belief was held — and nobody, human or agent, reads git log -p on a several-thousand-line file to
find out.
Numbering is what makes "later wins" resolvable
§7.4, §24.3, §59.5 are addresses. Without stable numbers, "later sections supersede" is
unusable advice — you can't tell what supersedes what. With them, the log becomes a citation graph
and contradictions have a deterministic tiebreak: higher number wins.
3. The cost, and the second document that pays it #
Be honest about the tradeoff. The log gets long, and it contains sentences that are false. Someone reading it front-to-back, in order, gets a wrong answer.
The fix is not to relax the convention. It's a second document — CLAUDE.md, AGENTS.md, or
whatever your agent loads automatically — with the opposite policy: short, edited in place, always
current, never a log. Its job is to state the convention, name the tiebreak rule, and carry the
handful of facts a fresh session needs before it can read anything else.
The pattern is two documents with opposite policies. Append-only log for reasoning and evidence; edited-in-place index for current truth and the rules of the road.
Projects that try to run one document under both policies get either a log nobody can act on, or a summary that has quietly deleted its own history. Both failure modes are common; neither is obvious until months in.
4. What to say on the next project #
4.1 Where this came from
See How it was found at the top: the convention was not designed, and the part most worth copying — framing the log as the user's file, with "append" as the operating verb — was luck. What the accident did not produce, and what the wording below therefore states outright, is the rhythm of one numbered dated section per unit of work with a mandatory "Not done" list.
4.2 The opening instruction
Keep a design-and-work log at
DESIGN.md. Write the plan first, in numbered sections.After that, the log is append-only: every unit of work appends a new numbered, dated section, and you never edit an earlier one. When you find that something earlier is wrong, do not fix it in place — append a section that names the section by number, states what you believed, what the evidence actually showed, and what changed. Earlier sections are allowed to stay wrong; the rule is that higher-numbered sections win.
Every section ends with an explicit "Not done" list: what you deliberately skipped, what you deferred and why, and what's still unverified. Be specific enough that I could pick any item up without asking you a question.
Attach evidence to claims. If something passed, say what ran and what the numbers were. If it's an assumption you couldn't check, say so in those words rather than writing it as a fact.
4.3 The line in CLAUDE.md / AGENTS.md
Add this once the log has a few sections. This is the load-bearing half — the convention only holds because every session is told about it before it reads anything else.
DESIGN.mdis the project's memory: §1–§N are the original plan, later sections are dated work entries. The convention is append-only — later sections supersede earlier ones rather than editing them, so earlier sections may contain claims that later ones refuted. When something looks contradictory, the higher-numbered section wins. New work appends a numbered, dated section with evidence and an explicit "Not done" list. Consult it before non-trivial work.
4.4 Optional, and it earns its place
Commit messages follow the same shape: a terse subject, then prose explaining what the evidence actually showed.
That gives you a second append-only log at a different granularity, greppable with git log -S.
Subjects that name a finding — "root-cause the last 35 divergences: the reference is the wrong
party" — are searchable in a way fix: update handler is not.
5. When to use it, and how it fails #
Nothing about the convention depends on a particular language or domain. What it depends on is: work spread over many sessions, decisions that are expensive to re-derive, and a real possibility of being wrong in ways only discovered later. That describes almost any non-trivial project.
It is worth the most where being wrong is likely and the wrongness surfaces late — porting, reverse-engineering, protocol work, performance tuning, migrations, anything with an unreliable oracle. It's worth the least on short, well-specified work where nothing gets refuted.
Three failure modes to watch for:
- Sections without numbers. Then supersession is unresolvable and the convention silently becomes "read all of it, hope."
- No pointer in the always-loaded file. The log stops being read, then stops being written. State the convention where the agent will see it every session, not only inside the log.
- "Not done" degrading into "future work." The list is only useful when it's specific and slightly embarrassing. Vague lists are the same silent scope-narrowing wearing a hat.
One more thing that is easy to get backwards: never ask for the log to be cleaned up, condensed, or made consistent. The apparent mess — a planning chapter that still says something false, with a later section pointing at it — is not decay. It's the artifact doing its job.