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). · GitHub

/" data-turbo-transient="true" />

Skip to content

-->

Search Gists

Search Gists

Sign in

Sign up

You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

{{ message }}

Instantly share code, notes, and snippets.

sourdecor/PROMPT_DESIGN_APPEND.md

Created<br>July 29, 2026 18:53

Show Gist options

Download ZIP

Star

(0)

You must be signed in to star a gist

Fork

(0)

You must be signed in to fork a gist

Embed

Select an option

Embed<br>Embed this gist in your website.

Share<br>Copy sharable link for this gist.

Clone via HTTPS<br>Clone using the web URL.

No results found

Learn more about clone URLs

Clone this repository at &lt;script src=&quot;https://gist.github.com/sourdecor/78b2ff9016f3f597934150a3501427ff.js&quot;&gt;&lt;/script&gt;

" readonly="readonly" data-autoselect="true" data-target="primer-text-field.inputElement " aria-describedby="validation-266eb83b-c613-45b9-88bd-20823977e043" class="form-control FormControl-monospace FormControl-input FormControl-small rounded-left-0 rounded-right-0 border-right-0" type="text" name="gist-share-url-sized-down" />

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

Embed

Select an option

Embed<br>Embed this gist in your website.

Share<br>Copy sharable link for this gist.

Clone via HTTPS<br>Clone using the web URL.

No results found

Learn more about clone URLs

Clone this repository at &lt;script src=&quot;https://gist.github.com/sourdecor/78b2ff9016f3f597934150a3501427ff.js&quot;&gt;&lt;/script&gt;

" readonly="readonly" data-autoselect="true" data-target="primer-text-field.inputElement " aria-describedby="validation-c13c3bdd-a585-4601-9bea-ca2d096d12e7" class="form-control FormControl-monospace FormControl-input FormControl-small rounded-left-0 rounded-right-0 border-right-0" type="text" name="gist-share-url-original" />

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

Raw

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<br>edited, later ones superseding earlier ones by citation. Require every section to end with a list of<br>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<br>wording to open a project with.

This is distilled from a project where the convention ran for dozens of sessions and about sixty<br>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<br>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<br>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<br>like §7.4 WAS WRONG: or §24.3's evidence was wrong, and §28.4 explains why. The<br>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<br>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<br>section that says "following this document's own convention, later sections supersede rather than<br>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<br>says where:

§2.4 and §7.2 still contain the refuted sentence. They are the planning chapters and this<br>document's convention is that later sections supersede rather than edit — but §2.4's list of three<br>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<br>designed for null in §2.4, built on it, tested...