How to write one

Free sample

The inclusion test, the five things worth including, what to leave out, and how to keep it true.

memory/HOW-TO-WRITE-ONE.md · 4.2 KB

memory/HOW-TO-WRITE-ONE.md

# How to write a memory file that earns its context

The templates in this directory are starting points. This is the reasoning
behind them, so you can adapt rather than copy.

## The inclusion test

> Could the agent work this out by reading three files?

**Yes → leave it out.** It will read the three files. A directory listing
is the classic waste: it is derivable, it goes stale in a week, and it
costs you attention on every single turn.

**No → write it down.** Anything that lives in someone's head, in a Slack
thread, or in a decision made two years ago is exactly what belongs here.

## The five things worth including

### 1. What the system is — two sentences, operational

Not the README pitch. What matters when changing it.

    Payments service. Go 1.23, Postgres, deployed on Fly.
    Money is involved: never guess at a rounding rule — ask.

The second sentence sets a stopping condition. That is worth more than a
page of architecture description.

### 2. The commands that verify work

The highest-value lines in most memory files.

    - `make check` must pass. Runs vet, lint and the race detector.
    - `make test-integration` needs Docker; slow, run once at the end.
    - Single test: `go test ./internal/ledger -run TestName -v`

Without these the agent invents a command, gets an error, and spends three
turns discovering your build system. With them it self-corrects before
showing you anything.

### 3. Invariants not visible in the code

This is the part that prevents expensive failures.

    - internal/ledger is double-entry. Every write needs a matching
      counter-entry in the same transaction.
    - db/migrations is append-only. Never edit one that has shipped.
    - pkg/generated is regenerated from proto. Editing it is always wrong.

Each is a rule someone learned the hard way. None can be inferred.

### 4. A procedure, numbered

Agents follow numbered steps well.

    1. Read the failing test before you read the source.
    2. Change one thing, run `make check`, then continue.
    3. If a change touches internal/ledger or db/migrations, stop and
       summarise the plan before writing code.

Step 3 is a **gate**. Gates cost one sentence and stop the class of change
you most regret.

### 5. Explicit prohibitions

Negative instructions work better here than anywhere else because they are
unambiguous.

    ## Do not
    - Do not add dependencies without asking.
    - Do not "fix" a flaky test by adding a retry.
    - Do not reformat files you were not asked to change.

That last line saves more review time than anything else on the list.

## What to leave out

| Don't include | Why |
|---|---|
| Directory tree | Derivable, goes stale weekly |
| Style the linter enforces | Point at the command instead |
| Aspirational rules | If the code violates it, the agent must reconcile — and will pick wrong |
| Long prose | Competes with your actual code for attention |
| Model instructions ("be careful", "think step by step") | Does nothing measurable; costs tokens |

## Length

Aim for **60–120 lines**. Past 200 you are writing an essay the agent reads
instead of your source.

If it is growing, that is a signal to split: keep the root file about the
repo as a whole, and put subsystem-specific rules in a nested memory file
inside that subsystem's directory (most tools support this).

## Keeping it true

A memory file that is wrong is worse than none, because the agent trusts it
over the code.

- Treat it like a test: when the thing it describes changes, it changes in
  the same commit.
- Add a line to your PR template: *does this change make anything in the
  memory file untrue?*
- Once a quarter, ask the agent: *read CLAUDE.md, then verify each claim
  against the codebase. List anything that is no longer true.*

## Starting from an unfamiliar repo

Do not write it yourself on day one. Ask the agent to draft it, then correct
the draft. It gets the mechanical parts right (build commands, entry points,
test layout) and the invariants wrong — which tells you exactly which lines
deserve your attention.

Correcting a wrong draft: twenty minutes. Writing from scratch: an
afternoon, and you will still miss things.

The exact drafting prompt is in `../commands/` — see `bootstrap.md`.

That was one of 28 files

The rest of The Agent Operating Kit is written the same way. $39 once, yours permanently, 14-day refund.

# How to write a memory file that earns its context The templates in this directory are starting points. This is the reasoning behind them, so you can adapt rather than copy. ## The inclusion test > Could the agent work this out by reading three files? **Yes → leave it out.** It will read the three files. A directory listing is the classic waste: it is derivable, it goes stale in a week, and it costs you attention on every single turn. **No → write it down.** Anything that lives in someone's head, in a Slack thread, or in a decision made two years ago is exactly what belongs here. ## The five things worth including ### 1. What the system is — two sentences, operational Not the README pitch. What matters when changing it. Payments service. Go 1.23, Postgres, deployed on Fly. Money is involved: never guess at a rounding rule — ask. The second sentence sets a stopping condition. That is worth more than a page of architecture description. ### 2. The commands that verify work The highest-value lines in most memory files. - `make check` must pass. Runs vet, lint and the race detector. - `make test-integration` needs Docker; slow, run once at the end. - Single test: `go test ./internal/ledger -run TestName -v` Without these the agent invents a command, gets an error, and spends three turns discovering your build system. With them it self-corrects before showing you anything. ### 3. Invariants not visible in the code This is the part that prevents expensive failures. - internal/ledger is double-entry. Every write needs a matching counter-entry in the same transaction. - db/migrations is append-only. Never edit one that has shipped. - pkg/generated is regenerated from proto. Editing it is always wrong. Each is a rule someone learned the hard way. None can be inferred. ### 4. A procedure, numbered Agents follow numbered steps well. 1. Read the failing test before you read the source. 2. Change one thing, run `make check`, then continue. 3. If a change touches internal/ledger or db/migrations, stop and summarise the plan before writing code. Step 3 is a **gate**. Gates cost one sentence and stop the class of change you most regret. ### 5. Explicit prohibitions Negative instructions work better here than anywhere else because they are unambiguous. ## Do not - Do not add dependencies without asking. - Do not "fix" a flaky test by adding a retry. - Do not reformat files you were not asked to change. That last line saves more review time than anything else on the list. ## What to leave out | Don't include | Why | |---|---| | Directory tree | Derivable, goes stale weekly | | Style the linter enforces | Point at the command instead | | Aspirational rules | If the code violates it, the agent must reconcile — and will pick wrong | | Long prose | Competes with your actual code for attention | | Model instructions ("be careful", "think step by step") | Does nothing measurable; costs tokens | ## Length Aim for **60–120 lines**. Past 200 you are writing an essay the agent reads instead of your source. If it is growing, that is a signal to split: keep the root file about the repo as a whole, and put subsystem-specific rules in a nested memory file inside that subsystem's directory (most tools support this). ## Keeping it true A memory file that is wrong is worse than none, because the agent trusts it over the code. - Treat it like a test: when the thing it describes changes, it changes in the same commit. - Add a line to your PR template: *does this change make anything in the memory file untrue?* - Once a quarter, ask the agent: *read CLAUDE.md, then verify each claim against the codebase. List anything that is no longer true.* ## Starting from an unfamiliar repo Do not write it yourself on day one. Ask the agent to draft it, then correct the draft. It gets the mechanical parts right (build commands, entry points, test layout) and the invariants wrong — which tells you exactly which lines deserve your attention. Correcting a wrong draft: twenty minutes. Writing from scratch: an afternoon, and you will still miss things. The exact drafting prompt is in `../commands/` — see `bootstrap.md`.