{"slug": "lightweight-zero-dependency-prompt-that-prevents-ai-agents-from-losing-context", "title": "Lightweight, zero-dependency prompt that prevents AI agents from losing context", "summary": "A developer has discovered a lightweight, zero-dependency prompting convention that prevents AI coding agents from losing context across sessions. The technique uses an append-only design log where numbered, dated sections are never edited, and later sections supersede earlier ones by citation. The mandatory 'Not done' list at the end of each section further prevents optimistic completion reports.", "body_md": "# The append-only design log\n\n**A prompting convention for working with coding agents over many sessions.**\n\n---\n\n## The trick, in a paragraph\n\nAsk the agent to keep a design-and-work log, and make it **append-only**: numbered dated sections,\nnever edited, later ones superseding earlier ones by citation. Require every section to end with a\nlist of what was *not* done. Then state that convention in the file the agent loads on every session.\n\nWhat you get is a document that keeps its own refutations. When a belief turns out to be wrong, the\nwrong belief stays on the page and a new section says so by number — so a fresh session with no\ncontext can't reintroduce the mistake as an improvement, which is exactly what it would otherwise do\nwhenever the refuted design is the more principled-looking one. The mechanism underneath is\neconomic: append-only drops the cost of a correction from \"find and rewrite everything that depended\non this\" to \"write one new subsection,\" and lowering the price of admitting error is what raises the\nrate of it. The mandatory \"Not done\" list attacks the other characteristic failure — the optimistic\ncompletion report with the awkward 20% quietly dropped.\n\n## How it was found\n\nBy accident, and the accident is instructive.\n\nThe opening message of the project this came from asked for something much smaller: it handed the\nagent a plan document, described as *the file I am going to tell you to use*, and said **append your\nquestions and answers to it**. Two things in that sentence did the work, and only one was on purpose.\n\"Append\" became the operating verb for that whole file rather than for one task. And framing the\ndocument as the user's — a spec authored by someone else and handed over — made it read as\nnot-mine-to-edit. That posture is what yields append-and-cite instead of quiet rewriting.\n\nThe same message also asked *do you have any questions?*, which produced a tagged list of open\ndecisions plus a subsection of \"smaller things I'll decide unless told otherwise\" — the direct\nancestor of every later \"Not done\" list.\n\nThe convention itself appeared in a section nobody asked for. Early on, a factual claim in the plan\nturned out to be wrong. The obvious move is to edit the sentence. Instead the agent appended a\nsection titled \"corrections to the body above,\" cited the wrong section by number, and left the false\nsentence standing. That step — from *append the answers* to *append corrections too, and let earlier\ntext stay wrong* — is the entire convention, and it happened only because \"append\" was already the\ndefault verb for the file.\n\nWhat the accident did *not* produce is the steady rhythm that made it valuable: one numbered dated\nsection per unit of work, each ending in a mandatory \"Not done\" list. That stabilized later, over\ndozens of sessions and about sixty sections. So the wording below states it outright rather than\nhoping it emerges again — which is the point of the next section.\n\n## Copy this\n\nTwo blocks. The first is what you say when you open the project; the second is what you paste into\nthe file the agent loads every session. Both are needed — the first starts the convention, the second\nis what keeps it alive across sessions. The rest of this document is why.\n\n**1 — Say this at the start of the project** (replace `DESIGN.md` with whatever you want the log\ncalled; keep the file framed as *yours*, handed to the agent, not as its own scratchpad):\n\n```\nKeep a design-and-work log at DESIGN.md. Write the plan first, in numbered sections.\n\nAfter that, the log is append-only: every unit of work appends a new numbered, dated section, and you\nnever edit an earlier one. When you find that something earlier is wrong, do not fix it in place —\nappend a section that names the section by number, states what you believed, what the evidence\nactually showed, and what changed. Earlier sections are allowed to stay wrong; the rule is that\nhigher-numbered sections win.\n\nEvery section ends with an explicit \"Not done\" list: what you deliberately skipped, what you deferred\nand why, and what's still unverified. Be specific enough that I could pick any item up without asking\nyou a question.\n\nAttach evidence to claims. If something passed, say what ran and what the numbers were. If it's an\nassumption you couldn't check, say so in those words rather than writing it as a fact.\n```\n\n**2 — Put this in `CLAUDE.md` / `AGENTS.md`** once the log has a few sections:\n\n```markdown\n`DESIGN.md` is the project's memory: §1–§N are the original plan, later sections are dated work\nentries. **The convention is append-only — later sections supersede earlier ones rather than editing\nthem**, so earlier sections may contain claims that later ones refuted. When something looks\ncontradictory, the higher-numbered section wins. New work appends a numbered, dated section with\nevidence and an explicit \"Not done\" list. Consult it before non-trivial work.\n```\n\nOptional third block, in the same `CLAUDE.md` — a second append-only log at a coarser grain,\ngreppable with `git log -S`:\n\n```markdown\nCommit messages follow the same shape: a terse subject, then prose explaining what the evidence\nactually showed.\n```\n\nTwo rules for yourself, both easy to get wrong:\n\n- **Never ask for the log to be cleaned up, condensed, or made consistent.** A planning section that\n  still says something false, with a later section pointing at it, is the artifact working.\n- **Never let the always-loaded file become a log, or the log become a summary.** Opposite policies:\n  one is appended and never edited, the other is edited in place and always current.\n\n---\n\nThat's the whole thing. What follows is why each part is load-bearing, what it costs, and where the\nwording came from. Nothing below depends on the originating project's domain.\n\n---\n\n## 1. What the convention is\n\nFive rules:\n\n1. **One numbered, dated section per unit of work.** Numbers are plain sequential integers, not\n   semantic. Nobody has to decide *where* a section goes — new work goes at the end, always.\n2. **Append; never edit an earlier section.** When a later finding contradicts an earlier one, the\n   earlier text stays wrong and the later section says so, by number.\n3. **Every section ends with an explicit \"Not done\" / \"Still open\" list.**\n4. **Corrections get their own titled subsection that names what they overturn.** Headings that read\n   like `§7.4 WAS WRONG: <the claim>` or `§24.3's evidence was wrong, and §28.4 explains why`. The\n   heading itself is the correction; you can find every reversal by scanning the table of contents.\n5. **Claims carry their evidence** — what ran, what the numbers were, where an expected value came\n   from. An assumption you could not check is written as an assumption, in those words.\n\nThe document should state the rule about itself. That is the part that makes it self-enforcing: a\nsection that says \"following this document's own convention, later sections supersede rather than\nedit — §28.4 did this to §24.3 — here is that list as it now stands.\"\n\nThe strongest version of this is a log that knowingly contains a false sentence *and knows it, and\nsays where*:\n\n> **§2.4 and §7.2 still contain the refuted sentence.** They are the planning chapters and this\n> document's convention is that later sections supersede rather than edit — but §2.4's list of three\n> is now a list of two.\n\nThat bullet is the convention working, not failing.\n\n---\n\n## 2. Why it's worth the trouble\n\n### It preserves refutations, and refutations are what agents keep re-deriving\n\nAn edited document says: \"the API returns an empty list, not null.\" The appended one says: we\ndesigned for null in §2.4, built on it, tested it, and §60 reversed it against the vendor's own\nreference implementation — and here is the one test that failed, which existed only to assert the\nrefuted claim.\n\nThe second version is worth far more whenever the refuted design is the *more principled-looking*\none. A fresh session reading only the corrected text has nothing stopping it from reintroducing the\nmistake as an improvement. The record of the failed belief is the guardrail; editing deletes exactly\nthat.\n\nThere is a second-order payoff. Once failed beliefs stay on the page, you can start naming *patterns*\nacross them — \"these two components being wrong in the same direction produces agreement and no\nsignal\", observed three times now. That pattern is only nameable because the earlier occurrences\nwere still there to count.\n\n### It makes self-correction cheap, which is why it happens at all\n\nThis is the real mechanism, and it's easy to miss.\n\nIf correcting yourself means finding and rewriting every earlier claim that depended on the mistake,\nthe cost of a correction is high and unbounded — so an agent quietly avoids correcting itself, or\nsoftens the correction into an edit that reads as if the error never happened. Append-only drops\nthat cost to \"write one new subsection.\" **Lowering the price of admitting error is what raises the\nerror-admission rate.** The corrections in a mature log exist because they were cheap to write.\n\n### \"Not done\" lists defeat the worst failure mode\n\nThe characteristic way an agent fails is not a wrong answer — it's an optimistic completion report\nwith the awkward 20% silently dropped. A required \"Not done\" list at the end of every unit converts\nthat from a thing that happens invisibly into a thing that must be written down.\n\nAnd they compound. A later section can revisit an earlier section's eight open items as a status\ntable — itself a new section rather than an edit.\n\n### It's a handoff artifact, not a status page\n\nSessions end and context is lost. Append-only produces a document whose intended reader is someone\nwith zero prior context, in a form where the *reasoning* survives, not just the conclusion.\n\nGit history technically holds the same information. But a diff shows what changed, not why the old\nbelief was held — and nobody, human or agent, reads `git log -p` on a several-thousand-line file to\nfind out.\n\n### Numbering is what makes \"later wins\" resolvable\n\n`§7.4`, `§24.3`, `§59.5` are addresses. Without stable numbers, \"later sections supersede\" is\nunusable advice — you can't tell what supersedes what. With them, the log becomes a citation graph\nand contradictions have a deterministic tiebreak: higher number wins.\n\n---\n\n## 3. The cost, and the second document that pays it\n\nBe honest about the tradeoff. The log gets long, and it contains sentences that are false. Someone\nreading it front-to-back, in order, gets a wrong answer.\n\nThe fix is **not** to relax the convention. It's a second document — `CLAUDE.md`, `AGENTS.md`, or\nwhatever your agent loads automatically — with the *opposite* policy: short, edited in place, always\ncurrent, never a log. Its job is to state the convention, name the tiebreak rule, and carry the\nhandful of facts a fresh session needs before it can read anything else.\n\n**The pattern is two documents with opposite policies.** Append-only log for reasoning and evidence;\nedited-in-place index for current truth and the rules of the road.\n\nProjects that try to run one document under both policies get either a log nobody can act on, or a\nsummary that has quietly deleted its own history. Both failure modes are common; neither is obvious\nuntil months in.\n\n---\n\n## 4. What to say on the next project\n\n### 4.1 Where this came from\n\nSee **How it was found** at the top: the convention was not designed, and the part most worth copying\n— framing the log as the user's file, with \"append\" as the operating verb — was luck. What the\naccident did not produce, and what the wording below therefore states outright, is the rhythm of one\nnumbered dated section per unit of work with a mandatory \"Not done\" list.\n\n### 4.2 The opening instruction\n\n> Keep a design-and-work log at `DESIGN.md`. Write the plan first, in numbered sections.\n>\n> After that, the log is **append-only**: every unit of work appends a new numbered, dated section,\n> and you never edit an earlier one. When you find that something earlier is wrong, do not fix it in\n> place — append a section that names the section by number, states what you believed, what the\n> evidence actually showed, and what changed. Earlier sections are allowed to stay wrong; the rule is\n> that higher-numbered sections win.\n>\n> Every section ends with an explicit **\"Not done\"** list: what you deliberately skipped, what you\n> deferred and why, and what's still unverified. Be specific enough that I could pick any item up\n> without asking you a question.\n>\n> Attach evidence to claims. If something passed, say what ran and what the numbers were. If it's an\n> assumption you couldn't check, say so in those words rather than writing it as a fact.\n\n### 4.3 The line in `CLAUDE.md` / `AGENTS.md`\n\nAdd this once the log has a few sections. This is the load-bearing half — the convention only holds\nbecause every session is told about it before it reads anything else.\n\n> `DESIGN.md` is the project's memory: §1–§N are the original plan, later sections are dated work\n> entries. **The convention is append-only — later sections supersede earlier ones rather than\n> editing them**, so earlier sections may contain claims that later ones refuted. When something\n> looks contradictory, the higher-numbered section wins. New work appends a numbered, dated section\n> with evidence and an explicit \"Not done\" list. Consult it before non-trivial work.\n\n### 4.4 Optional, and it earns its place\n\n> Commit messages follow the same shape: a terse subject, then prose explaining what the evidence\n> actually showed.\n\nThat gives you a second append-only log at a different granularity, greppable with `git log -S`.\nSubjects that name a finding — \"root-cause the last 35 divergences: the reference is the wrong\nparty\" — are searchable in a way `fix: update handler` is not.\n\n---\n\n## 5. When to use it, and how it fails\n\nNothing about the convention depends on a particular language or domain. What it depends on is: work\nspread over many sessions, decisions that are expensive to re-derive, and a real possibility of being\nwrong in ways only discovered later. That describes almost any non-trivial project.\n\nIt is worth the most where being wrong is likely and the wrongness surfaces late — porting,\nreverse-engineering, protocol work, performance tuning, migrations, anything with an unreliable\noracle. It's worth the least on short, well-specified work where nothing gets refuted.\n\nThree failure modes to watch for:\n\n- **Sections without numbers.** Then supersession is unresolvable and the convention silently becomes\n  \"read all of it, hope.\"\n- **No pointer in the always-loaded file.** The log stops being read, then stops being written. State\n  the convention where the agent will see it every session, not only inside the log.\n- **\"Not done\" degrading into \"future work.\"** The list is only useful when it's specific and\n  slightly embarrassing. Vague lists are the same silent scope-narrowing wearing a hat.\n\nOne more thing that is easy to get backwards: **never ask for the log to be cleaned up, condensed, or\nmade consistent.** The apparent mess — a planning chapter that still says something false, with a\nlater section pointing at it — is not decay. It's the artifact doing its job.\n", "url": "https://wpnews.pro/news/lightweight-zero-dependency-prompt-that-prevents-ai-agents-from-losing-context", "canonical_source": "https://gist.github.com/sourdecor/78b2ff9016f3f597934150a3501427ff", "published_at": "2026-07-29 18:57:27+00:00", "updated_at": "2026-07-29 19:22:34.300477+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "developer-tools", "large-language-models"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/lightweight-zero-dependency-prompt-that-prevents-ai-agents-from-losing-context", "markdown": "https://wpnews.pro/news/lightweight-zero-dependency-prompt-that-prevents-ai-agents-from-losing-context.md", "text": "https://wpnews.pro/news/lightweight-zero-dependency-prompt-that-prevents-ai-agents-from-losing-context.txt", "jsonld": "https://wpnews.pro/news/lightweight-zero-dependency-prompt-that-prevents-ai-agents-from-losing-context.jsonld"}}