Lightweight, zero-dependency prompt that prevents AI agents from losing context

Instantly share code, notes, and snippets.

sourdecor/PROMPT_DESIGN_APPEND.md

Created July 29, 2026 18:53

Show Gist options

Download ZIP

Star

0 (0)

You must be signed in to star a gist

Fork

0 (0)

You must be signed in to fork a gist

No results found

Clone this repository at

Save sourdecor/78b2ff9016f3f597934150a3501427ff to your computer and use it in GitHub Desktop.

No results found

Clone this repository at

Save sourdecor/78b2ff9016f3f597934150a3501427ff to your computer and use it in GitHub Desktop.

Download ZIP

The two-document pattern for AI agents: an immutable, append-only log for reasoning and refutations (DESIGN.md), and an edited-in-place index for current rules (CLAUDE.md).

PROMPT_DESIGN_APPEND.md

The append-only design log

A prompting convention for working with coding agents over many sessions.

Ask an agent to keep a design-and-work log. 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.

That's the whole thing. What follows is why each part is load-bearing, what it costs, and the exact wording to open a project with.

This is distilled from a project where the convention ran for dozens of sessions and about sixty sections. Nothing below depends on that 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: 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.

1. 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.

1. 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.

1. What to say on the next project

4.1 Where this came from, and which part was luck

The convention was not designed. It came out of an opening message that did three things:

It handed the agent a plan document framed as the user's — "the file I am going to tell you to use" — a spec authored by someone else. That makes it read as not-mine-to-edit, which is exactly the posture that yields append-and-cite. This was probably luck. It would not reproduce if the agent wrote the document itself from scratch.

It used "append" as the verb, applied to a whole file rather than to one task: append your questions and answers to it. That set a default mode of interaction.

It asked "do you have any questions?" — which produced a tagged list of open decisions, and a subsection of "smaller things I'll decide unless told otherwise." That subsection is the direct ancestor of every later "Not done" list.

The generalization happened 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 it. Instead the agent appended a section titled "corrections to the body above," cited the wrong section by number, and left the false sentence standing. Going from append the answers to append corrections too, and let earlier text stay wrong is the whole convention — and it happened because "append" was already the operating verb for that file.

What that opening did not produce is the steady rhythm of one numbered dated section per unit of work with a mandatory "Not done" list. That stabilized later. The wording below states it outright rather than hoping it emerges again.

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.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.

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.

1. 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment