Keeping docs current with Claude Code and tests
How this repo keeps its docs true with Claude Code and tests: one owner per fact, a test that fails on drift, a Stop hook reminder and a pull request check.
I built this site with AI coding agents, Claude Code sessions working in parallel, under my direction and review. That changes what documentation is for. A human team keeps context in people's heads. An agent session keeps it only until the session ends, a usage limit cuts it off, or a better model replaces it. When the context is gone, the repository is all that is left.
So on 28 Sep 2026 I asked for everything to be written down, so that a future session, or a better model, could refine or rebuild the whole project without starting from zero. Writing docs is easy; keeping them true is not. So the rule became: documentation is part of done, and a test enforces it.
One fact, one owner
Every doc in the repository has one job. The status page owns the current phase, what is next, what is blocked and what was removed on purpose. The architecture doc owns the map of files, routes and data flow. The decision log owns the decision records, newest last. The content rules own what may be published, and the journey owns the story.
A change-to-doc table in the contributing guide says which doc each kind of change must update: a new route updates the architecture map, a choice that is hard to reverse gets a new decision record, and a removal goes into the status page's delete-zone, so nobody rebuilds it by accident. Two more rules keep the set small. One fact has one owner, so other docs link to it instead of copying it. And history is append-only: a stale decision is corrected with a dated note, never silently rewritten.
Every doc lives in docs/. The only Markdown at the root is the README, plus a one-line loader in .claude/ that makes Claude Code read the contributing guide when a session starts there.
A test that fails when the docs drift
scripts/docs-governance.test.ts runs with the unit tests on every commit. Its 15 checks fail the build when:
| Area | Fails when |
|---|---|
| Set | a core doc is missing, or the reading order names a missing file |
| Links | a relative link points at a missing file |
| Index | a doc is missing from the docs index |
| Location | Markdown lives outside docs/ other than the README, or the loader stops pointing at the guide |
| Paths | a backticked repository path does not exist, or a path recorded as removed is back |
| Scripts | an npm run name does not exist, or the README's scripts table differs from package.json |
| Status | the status page lacks a section, or was last reviewed before the newest decision |
| Decisions | records are out of sequence or undated, or a doc cites one that does not exist |
| Design | the documented world colours or stop order differ from the prototype |
The history docs, the decision log and the journey among them, are exempt from the path and script checks, because they are records: they are allowed to name files that no longer exist. And the status rule means a new decision record cannot land without the status page being reviewed that day or later.
The check has been wrong, too. A CI run on GitHub once failed only on it: the docs named git-ignored paths, like the private notes folder and build output, that exist on my machine but never in a CI checkout. The fix taught the test which paths are local only. A rule that blocks the build has to be right about what it blocks.
A reminder at the moment an agent stops
Tests catch drift at the end; an agent is better served by a nudge when it thinks it is done. A Stop hook in .claude/settings.json runs scripts/docs-reminder.mjs whenever a Claude Code session is about to stop. If code changed in the working tree and no doc did, it blocks the stop once with a reminder that points at the change-to-doc table. It also fires when docs did change but the newest changed code file is newer than the newest changed doc, so an early doc edit cannot hide later code edits.
It is careful not to nag. It hashes the set of changed code paths and keeps the hash in the git directory, so the same set is never flagged twice. If no doc is affected, the agent says so in one line and stops. And if the hook itself fails, it exits quietly, because a check that traps a session is worse than no check.
The same check on every pull request
The hook only runs inside Claude Code, so pull requests get the same rule in CI. The step "Docs updated with code" diffs the branch against its base and fails, listing the paths, when code changed and no doc did. A missing base or a git error exits with its own code, so the step never passes silently. When a change really affects no doc, the pull request says so in its description and carries a no-docs label.
Numbers that cannot go stale
The same idea covers the numbers on the site. This site's own page prints how many decision records and end-to-end tests it has, and a test counts each from its source: the headings in the decision log, the tests Playwright lists. Generated data works the same way: tests fail when the agent's corpus or the prototype's data file differs from what its generator builds. A printed number matches the thing it counts, or the build is red. This section's posts are held the same way: a test pins every number they print, so if the governance test gains a check, this post fails until it says so. How I keep a public AI agent cheap and safe fails the same way if a limit changes.
What it costs
It is not free. Every change touches a doc, which is slower in the moment. Tools that only read a root AGENTS.md get no rules automatically, so the README points them at the guide. A session started in a parent directory may skip the repository's settings, and the hook with them, so sessions start in the repository itself.
What it buys is a repository that explains itself. There are now more than seventy decision records, each with a date and a reason, and a status page reviewed at least as recently as the newest of them. When a session ends on a usage limit, the next one starts from the docs instead of from memory, and the tests tell it at once if anything it reads has gone stale.
How this site is built and tested, end to end, is in the denniskhor.com case study.
Open to senior AI and software engineering roles: on site or hybrid in Sydney, or remote for Australian and US teams. Read my CV, or paste a job description into Ask about fit for a verdict with cited evidence.