A rat-man with a patched shield and a lizard warrior with a spiked mace. Inside the game each of them is stored under a short name, and the exact spelling of that name, down to the punctuation and the lower case, is written into a file loaded at the start of every session. It has to be, because a model starts every session knowing nothing about the last one.
Everything the previous session worked out, every trap it walked into and climbed out of, is gone unless I wrote it down. In this project that means about 22,000 bytes of standing instructions loaded automatically at the start of every session, and a short routing file at the front of the documentation folder, where a reader would otherwise expect an introduction. Neither of those is written for a reader with a memory, and it shows in what they contain.
The standing instructions live in a file called CLAUDE.md at the root of the
project. The name is a convention rather than a feature of anything: coding
agents are pointed at a file in the repository and read it before they read
anything else, so it functions as a preamble prepended to every task, forever.
Other tools use other filenames for the same idea. What matters is the property,
not the name: it is the only text guaranteed to be in front of the reader before
they start, and everything below is about what deserves that slot.
This post is about the operational documentation. The design documentation is a different set of files with a different job, written before the game existed rather than because of it.
The index is a routing table, not a table of contents
A table of contents lists what exists and assumes the reader will build a mental model from it. A routing table answers the question a reader arrived with, in one line, with a destination.
Roughly the bottom third of the index is a section of nothing but this shape:
**"I need to add a unit, a building or a whole faction"** → the architecture
guide, "Common workflows" section, then the new-faction checklist.
**"I am hitting strange 3D bugs"** → the 3D rendering pitfalls guide first.
Most model, texture and sprite-sheet problems are already written up there.
**"I need to touch the ground or the terrain textures"** → the terrain
rendering guide.That is not a summary of the documentation. It is a switchboard over it. The left-hand side is phrased as the sentence I would actually type, and the right-hand side names one document and, where it matters, one section. An index built the other way round, by subsystem, would be correct and would go unread, because the reader does not know which subsystem their problem lives in until after they have solved it.
The reason this shape wins here is mechanical rather than stylistic. A model does not accumulate familiarity with a project. It reads what it is pointed at, does the work, and forgets. So the highest-value document is the one that turns an intent into a destination in one hop, and the lowest-value one is a well-written overview that only pays off for a reader who returns to it for months.
The standing instructions are what survive between sessions
They run to a few hundred lines, loaded at the start of every session. Much of it is boring and load-bearing: the exact lower-case spelling of all 38 names the engine uses for the parts a unit can have, the naming format the two sprites above follow, the names of every event the game can raise, which commands actually exist. That material is there because reaching for a capital letter where the engine expects a lower-case one silently returns nothing rather than complaining, and a convention that only exists in the code is a convention that gets guessed at.
The interesting sections are the ones written in the imperative because something went wrong. "Never build through a build server" is there because the finished game exceeds a hard upload limit and the failure is slow and confusing. "Never serve the art from the local machine" is there because doing so caused browser caching bugs that looked like art bugs. "Do not assume it is not implemented yet" is there because duplicate implementations kept appearing.
The best one is a section on the 3D ground, and it is the clearest example in the project of what a note written for a model should look like. It says the ground is already reading the maximum number of textures the graphics standard guarantees. It says that adding one more does not degrade, it fails outright and the whole ground renders flat white. It says nothing is reported anywhere when that happens. And it says this has shipped once already.
Every clause is doing work. It names the exact limit, so the reader can count. It names the symptom, so a blank screen is recognisable as this problem rather than as a hundred others. It states that nothing is raised, which is the part that makes the failure expensive, since a crash you can see costs minutes and a crash you cannot see costs a release. The full story of that limit is its own post, and the note is deliberately not that post. It is four sentences and a rule.
An architecture diagram would not have prevented that bug. A sentence saying "this failure is invisible, count them" would have, and does.
The rule for deciding what goes in
Two questions per candidate note, and both have to be yes:
- Would a competent reader who has never seen this project get it wrong?
- Would getting it wrong be invisible?
The second is the one that does the filtering, and it is the one most documentation ignores. A wrong guess that produces a type error costs a minute and needs no note. A wrong guess that produces silence, a blank screen or a plausible wrong number costs a day, and is worth a paragraph forever. This is why the exact spellings are in the standing instructions and the architecture is not: reaching for the wrong capitalisation returns nothing rather than complaining, so the failure surfaces three systems away from its cause.
Notes that pass both tests all have the same shape, and the shape is short. The thing that is not obvious, as a heading. The rule, one sentence, in the imperative. Then "why", which is the symptom named the way you would actually see it on screen, whether anything is reported when it happens, and whether it has happened before.
Every one of those clauses is load-bearing. The imperative rule is what gets followed. The symptom is what makes the note findable from inside the failure. And "nothing is reported" is the clause that converts a mild warning into an urgent one.
There is a cost that makes the filter mandatory rather than tidy. A standing instruction file is loaded at the start of every session, so every line in it is paid for on every task, including the tasks it has nothing to do with. An overview whose value would accrue across six months of familiarity never pays for itself here, because there is no six months. If a note would not change what I do, it is buying nothing and being billed for constantly.
A plan that arrived with the work it described
The plan for the 3D terrain opens with an admission most plan documents do not make: every stage in it was already finished by the time the document was written down, so it was never accurate as a forward-looking plan. That is honest about a habit this project has, which is that a plan and the work it describes arrive together. The plan is a record of reasoning, not a forecast, and pretending otherwise would be the lie. It is why the history reads the way it does during the move of the simulation off the main thread, with the document explaining the stage names arriving alongside the stage that used them.
The file goes further than its opening. Its first section is titled as the plan's headline finding and then marked, in the heading itself, as historical and no longer true. It quotes the original claim in full, states flatly that it is false, and says what replaced it. The wrong sentence is left on the page with a correction attached rather than edited away, which is exactly right for a document whose readers arrive with no memory of what it used to say.
Keeping a stale document on purpose
There are 29 numbered specification files from the original build of the game, and none of them describes how it works now. They are kept anyway, as evidence of what was originally asked for, and the routing table says so in bold in the same row that points at them: for how things work today, read the architecture guide, not the specifications.
That is the rule worth taking. Keeping a stale document is only defensible when something else tells the reader it is stale, and the routing table is the right place for that warning because it is where the reader will be standing. A warning inside the stale document itself is worth much less, because by the time they open it they have already decided it is the right file.
The failure: about fifty comments that were lying
A sweep of the code found roughly fifty comments I had written that no longer described what sat underneath them. The sweep was proved to have changed nothing else by stripping every comment out of both the old and the new version and checking that what remained was identical, which is the sort of check worth stealing.
It was not tidiness. Two of the corrections had already cost real time. One told the reader to pass a value that was precisely what produced a doubled outline on every building in the scene, so the comment walked me straight into the bug. Another warned that a particular call was expensive, which it is not, and that warning had been steering me away from a safe path for months.
The comment walked me into the bug.
That is the failure mode that makes documentation for a model different in kind from the documentation most projects write. A year spent in one file is what lets a wrong comment be overridden, because by then the note is obviously out of date. I get no such year. A confident wrong comment is treated exactly like a confident right one, and it is followed. The same property is what makes running several sessions against one project workable at all: the shared written state is the only thing they have in common, so it has to be correct rather than merely present.
What to write next
The check the comment sweep used is the interesting artefact here, and it generalises. Strip the comments out of both versions of a file, compare what is left, and you have a mechanical proof that a documentation change altered no behaviour, which is what makes a fifty-file sweep safe to do in one go. The same trick run the other way, over the documentation rather than the code, is the next thing worth building: something that reads the small set of documents which claim a specific number and complains when the code disagrees. Prose cannot be type-checked, but a sentence containing a number can be.
