Method · Agent tooling
The single artifact that let one AI agent build and keep shipping a full iOS app — a compiled, code-is-ground-truth document that keeps it oriented across a large, constantly-moving codebase.
The problem
Ask a coding agent to change one screen in a hundred-file app and it faces a quiet, expensive problem: it doesn’t know where it is. What is this app? Which of these files are load-bearing? What was already decided, and why? Was that bug fixed last week or is it still open?
Left to its own devices, it re-derives all of that from scratch, every session — grepping around, reading files, inferring architecture from fragments. That’s slow, it burns tokens on rediscovery instead of work, and it’s unreliable: the agent guesses, contradicts a decision made a week ago, or “fixes” something that was deliberate. The bigger and older the codebase, the worse the drift. Documentation is supposed to solve this — but hand-written docs rot into confident fiction the moment the code moves past them.
The model
The fix came from somewhere unexpected — autonomous robots. In a research lab at UIUC I worked with dead reckoning: how a robot holds its course with no constant external signal, by tracking its position from a known origin and heading and correcting against periodic fixes.
Agentic coding is the same navigation problem. Give the agent a known position and a heading (a tight spec for the task at hand), and let it dead-reckon through the work — course-correcting at real checkpoints (tests, verification) rather than being steered keystroke by keystroke. The heading changes with every task. The known position is the constant — and it needs to be a single, trustworthy thing the agent reads before it does anything.
The known position is one compiled document: the “State of the App.”
Read at the start of every session. It is the origin fix from which the next mile of work is dead-reckoned.
The artifact
Not a wiki and not a README. A compiled snapshot of the whole system — nine sections, each answering a question an agent would otherwise waste a session re-answering:
Above the sections sits machine-readable frontmatter — the load-bearing metadata that turns a document into an instrument:
The one rule that makes it trustworthy
A document only works as a “known position” if the agent can trust it. Hand-maintained docs fail that test — they drift the instant someone forgets to update them. So this one is never written by hand. It is compiled from the code by a command, and recompiled — not patched — when things change. When the page and the code disagree, the code wins, every time, and the page is regenerated to match.
Drift silently. Age into fiction. The reader can’t tell fresh from stale. Trust erodes, so nobody reads them — and the agent re-derives anyway.
Stamped with the commit it reflects, so drift is measurable: any session can diff the code against compiled-commit and know exactly how far things have moved. Regenerated, not maintained — it can’t rot into a lie.
There is exactly one hand-written exception — a small “Human notes” block, preserved verbatim across every recompile, for the handful of things a human knows that the code can’t confess. Everything else is a function of the source.
Compiling it
Refreshing the known position is a single instruction — /state-of-app — that scans the real sources (the app, the shared package, the database migrations, the test suites, the specs, the dated decision log) and regenerates the page from them. It runs in three modes:
compiled-commit and rewrite only the sections that actually changed, plus the counts and the “read this first” banner. Cheap enough to run after any meaningful merge.It counts things directly rather than trusting prose — migrations, interface methods, tests — cites evidence as file:line, and is deliberately honest in the provenance section about what it did and didn’t verify this pass. A snapshot that lies about its own freshness is worse than none.
Why it works
With a known position loaded, every session begins already located. Tokens go to the work, not to rediscovery — which is most of why the build ran on aggressive prompt caching at roughly 98% cache reads: the same trustworthy context, re-read cheaply, session after session. Decisions don’t get re-argued, because they’re written down with their reasons. Drift is visible instead of surprising. The load-bearing pieces are fenced off by the guardrails, so the agent refines freely where it’s safe and asks before touching what isn’t.
And because the position is known rather than watched, the human isn’t in the loop keystroke by keystroke. Hand off the map and a heading; let it dead-reckon; check the fixes at the checkpoints that matter. That is what turns one person into something that moves like a team.
Lineage
The “known position” is a small idea with good ancestry. It leans directly on Andrej Karpathy’s LLM Wiki — the pattern of an LLM that incrementally builds and maintains a persistent, structured wiki rather than re-deriving everything from raw sources on every query. The State of the App is that idea aimed at a codebase.
And it was built with two open tools in the same lineage: claude-obsidian by AgriciDaniel — a self-organizing Claude + Obsidian second brain that files any source into one connected knowledge graph — and obsidian-second-brain by eugeniughelbur — the vault structure that holds the specs, the decisions, and the compiled snapshot itself.
“The document isn’t documentation. It’s a navigation instrument — a known origin, so the next mile can be dead-reckoned with confidence.”