Real-time documentation: writing while you build, not after

The standard model of project documentation is that you build a thing and then, if there's time at the end, you write down how it works and why. There's almost never time at the end. So most projects ship without documentation, and the people who later need to understand them — including the original author six months on — are reduced to reading commits.

I'm building this project with a different model: documents are written during the build, alongside the code, and they're load-bearing while the project is alive. They don't describe what the project is. They make the project possible.

There are three of these on this project. They each do different work.

CLAUDE.md — the orientation document

CLAUDE.md is the document Claude Code reads at the start of every session. Its job is to make session zero of any new conversation indistinguishable from session N. Without it, every session starts cold: the model doesn't know the project's purpose, hasn't seen the design principles, doesn't know which architectural decisions are settled. With it, the session starts warm.

Mine has:

• The site's purpose in one paragraph.
• Current state — what's shipped, what's in progress.
• Design principles I've already settled (dark mode, single accent, serif display, restrained motion).
• Tech stack and the routing.
• The references I found resonant, with a one-line note on what I want from each.
• An explicit instruction that says, in effect: don't re-litigate any of this.

The file is updated when something in it stops being true. The phrase "live document" is the right one — it's not a snapshot, it's the current state of the project's stable assumptions.

The critical word is stable. Things that change session-to-session don't go in CLAUDE.md. Goals for this conversation don't go in CLAUDE.md. Whatever I'm currently arguing with myself about doesn't go in CLAUDE.md. Once a decision is made and unlikely to flip, then it goes in.

WORKING-WITH-JONLIN.md — the collaboration manual

If CLAUDE.md is "what is this project," then WORKING-WITH-JONLIN.md is "how do you work with the human."

Mine specifies: be concise, lead with a recommendation, ask before non-trivial work, ship small reviewable PRs (30–80 lines), explain as you build because I'm learning, never run destructive git ops without an explicit ask. It's a list of preferences, each one usually stemming from a moment where I noticed I was annoyed and wrote down why.

The discipline of writing them down rather than restating them is what makes them work. If I had to give the same correction every session — please be more concise, please don't dump 400 lines of code at me, please ask before installing new dependencies — I would burn through both my patience and the model's effective context. Once the rule is in the document, the document carries the weight.

The file gets longer over time as I notice new patterns. It does not get shorter unless a rule was wrong.

BACKLOG.md — the parking lot

This one is the most underappreciated of the three. BACKLOG.md is where decisions that I've consciously deferred go, with trigger conditions for revisiting them.

Examples from mine:

• Conversation logging for /ask-ai — deferred until I have enough traffic that I'd actually learn something from logs.
• Custom domain — deferred until the rest of v1 is ready to be shown publicly.
• MDXEditor mixed-list quirk — deferred indefinitely; documented workaround.
• Tag pages, series, slug auto-generation — deferred to the post-MVP backlog with rough scope.

Each entry has the decision, why it was deferred, and what would make me revisit it. Trigger conditions, not deadlines. "Custom domain when v1 is solid enough to share publicly" is a better trigger than "custom domain by the end of the month," because it's anchored to a real signal rather than a calendar date that's going to slip.

This pattern is hard to describe and easy to feel. The difference between an entry that says "buy domain (someday)" and one that says "buy domain when v1 is shareable; current blocker is the writing index" is enormous. The second is actionable; the first is debt.

BACKLOG.md is also where I write down bugs I'm not fixing right now. The MDXEditor mixed-list bug is documented there with the workaround. Future me, hitting the same issue, will find the file before re-deriving the workaround.

How AI changes the calculus

For a solo human builder, the cost of these documents is "time spent writing instead of coding," and that's why most solo projects don't have them. With an AI pair, the calculus inverts.

Every minute I spend updating CLAUDE.md saves me five minutes of orienting the model in the next session. Every entry in WORKING-WITH-JONLIN.md is a correction I will not have to give again. Every line in BACKLOG.md is a decision I don't have to re-litigate.

The documents are amortized across sessions. The session-zero of any new conversation starts roughly where session-N of the last conversation ended, because the documents bridge the gap. This is the single biggest source of velocity in AI-paired development that nobody talks about. The talk is all about the model. The model is fine. The documents are what make the model useful.

A specific moment: a few weeks in, I started a session intending to add tags to the writing index. The conversation flowed for an hour without me having to explain the project's purpose, the database schema, or my preferences. We just did the work. Pre-document, that conversation would have started with twenty minutes of "let me catch you up" and the model still wouldn't have known the things I'd never thought to mention.

The cost is discipline, not hours

The actual hours-cost of these three files is small. Updating CLAUDE.md after a session is two minutes. Adding a BACKLOG.md entry when I defer something is one minute. Adding a WORKING-WITH-JONLIN.md rule when I notice myself making the same correction twice is two minutes.

The cost is discipline — the willingness to write the entry when the impulse is to keep coding. Most failures of this approach aren't "I forgot to do it"; they're "I knew I should and I didn't." The fix is the same as for any habit: do it for long enough that not doing it feels wrong.

What I deliberately did not document

A real document strategy includes saying no to certain documents:

• Architecture diagrams. The site is small enough that the file structure is the architecture diagram. A separate document would drift.
• API specs. The route handlers are TypeScript. The handler is the spec.
• Deployment runbook. Vercel auto-deploys. The runbook would be one sentence.
• Style guide. Tailwind config and the CSS variables in globals.css are the style guide.

Writing documents you don't need is worse than writing none. Each unread document silently rots, becomes wrong, and confuses you the next time you stumble into it. I'd rather have three well-tended documents than thirty stale ones.

The principle

Documents earn their keep by reducing future-cost more than they cost to produce. The three I keep all clear that bar — they save more time than they take, every week. Anything that doesn't is dead weight.

The pattern generalizes past AI-paired development. Even on a fully human project, a document that exists because session-N needs context from session-N-1 is worth its weight in coordination overhead. AI just makes the savings show up faster, because session-N starts with zero memory unless you give it some.