What's Left When the Code Becomes the Source of Truth

I recently wrote that AI can explain your code, so we should stop documenting the obvious. The argument: AI handles the how, so human documentation should focus on the why — the intent and reasoning that code can’t express.

That was theory. This is the experiment.

A few hours. That’s how long the whole thing took. Write 786 lines of documentation. Build a working prototype with Claude. Delete 656 lines — 83% of them — because they’d done their job. By dinner, the app worked and the planning documents had mostly disappeared.

When you’re pair-programming with an AI, the feedback loop shrinks from days to minutes. Design specs become working code before you’ve finished writing them. And once they do, why keep the blueprint when you’re standing in the building?

The app now runs on 130 lines of remaining docs and a codebase that serves as its own specification. Which raises an uncomfortable question — one that Part 2 will test. That codebase is hours old. The developer’s context is still warm. What happens when you hand it to a different AI, cold, and ask: can you pick this up?

The Documentation Phase

Claude and I built this together, and the documentation evolved as we went.

PRINCIPLES.md came first — five design principles including “micro-sessions win” and “recall over capture.” Before Claude could help build anything, it needed to understand what we were building and why. The principles gave us a common language.

Then came the tokens. DESIGN_TOKENS.md defined colour scales, spacing units, typography — everything visual, captured in prose before any CSS existed. Why markdown? Because I was still deciding these things. A markdown file is easy to revise, easy to discuss with an AI partner, easy to read alongside wireframes. It was the right home for tokens at that moment.

The wireframes came next. Using a text-based notation:

[H] Good to see you[C] Progress card[B] Start a session

It let Claude and me iterate on screen layouts without getting tangled in HTML syntax too early.

Building With an AI Partner

The documentation became a shared workspace. I’d draft MICRO_COPY.md with phrases like “Nearly there — one more minute.” Claude would implement them. Then I’d notice the phrasing felt off in context, we’d discuss it, and the doc would update. The documentation wasn’t a one-way transmission. It was a conversation that happened to leave artefacts.

The feedback loop was tight. Draft a spec section. Build working code together. Notice something wrong. Refine the spec — or realise the implementation had revealed something better. Claude pushed back. I pushed back. We iterated.

The Truth Migrated

Somewhere around hour four, I noticed the tokens had moved house.

DESIGN_TOKENS.md originally specified a colour palette in markdown: primaries, neutrals, semantic mappings. But now those values lived in CSS custom properties — --colour-brand-primary: #2e5e4e, --space-4: 16px — at the top of styles.css. The markdown wasn’t wrong, exactly. It just wasn’t the source of truth anymore. The truth had migrated.

The same pattern everywhere. WIREFRAMES.md described screens in bracket notation, but the actual HTML was the wireframe now — and a better one. SCREEN_FLOW.md mapped navigation paths, but the JavaScript showed the real flow. MICRO_COPY.md captured button labels, but those labels lived in the DOM.

Information migrates to where it’s most useful. Tokens belong in CSS once CSS exists. Screen flows belong in code once the code embodies them.

So we cleaned up. Nine files. 656 lines. The git commit message read: “Code is now the source of truth.”

What Survived (and Why)

Three files remained: PRINCIPLES.md (61 lines), NOTE_SCHEMA.md (44 lines), ACCESSIBILITY.md (329 lines). About 17% of the original corpus.

The pattern: these files encode intent and constraints that cannot be derived from the code. PRINCIPLES.md tells you that sessions cap at 10 minutes because “micro-sessions win.” The code shows MAX_SESSION_MINUTES = 10. One explains the why; the other merely demonstrates the what. A future developer could change that constant to 30 and never understand they’d violated the core philosophy.

NOTE_SCHEMA.md survives because it describes what data means, not just how it’s structured. ACCESSIBILITY.md survives because accessibility requirements are contractual. Delete that file and the code still runs. But you’ve lost the specification of what “working” actually means.

Back to the Idea

So does the experiment support the theory? The original argument was: AI can explain the how, so document the why.

What migrated to code was all how — screen flows, component specs, design tokens, micro-copy. Things an AI can now read directly from the source. What survived was all why — design principles, data meaning, accessibility contracts. Things that require human judgement to create and interpret.

The lesson isn’t “delete your documentation.” It’s that documentation has a job, and that job changes. Early on, it captures decisions while you’re still making them. Later, much of it migrates to better homes. What remains is the irreducible core: intent and constraints that code can’t express.

Should you try this? If you’re building something small and well-scoped with AI, yes — write documentation for the conversation, not for posterity. But this approach has limits. It works when the build is fast enough that context stays fresh. Whether it works when someone else picks up the codebase cold — that’s a different question entirely.

How This Felt

Outlining the principles — even hastily — forced me to articulate who this was for and what the app should feel like. That clarity paid off throughout the build. And defining tokens upfront meant I controlled the starting point; the AI had space to evolve things within those constraints. Constraints as creative partnership.

But I miss the pixel pushing — the tactile satisfaction of moulding an interface with my hands. Words in, interface out. No clay on my fingers. I don’t know if that’s a loss worth grieving or a habit worth breaking.

Next: The Handover

Part 1 tested whether documentation can evolve and migrate during a build. But the original thesis makes a bolder claim: that documenting the why is enough for others to pick up your work.

Time to test that.

I’m going to hand this codebase — the working prototype, the three surviving documents — to a different AI. Not Claude. Something that wasn’t there for any of the conversations, hasn’t seen the scaffolding, doesn’t know the history. A cold start.

The question: is 130 lines of documentation enough? Can a stranger understand not just what the code does, but why? Can they extend it meaningfully, or will they drift off-course the moment they try? I genuinely don’t know. This isn’t a demonstration; it’s a test.

It might hold. It might not. Either way, we’ll learn something.

If you want to explore the codebase yourself, it’s on GitHub.

Read part 2 from the AI’s perspective.