Docs Aren't an Artifact (anymore)

Docs used to be the thing you did after the fun part. Ship the feature, get the dopamine, promise yourself you’ll write it up, then never write it up. Everybody knows this. Everybody does it. We all agreed to pretend otherwise during code review.

Then I started letting an agent do a bunch of my implementation work, and something weird happened. My docs got better. Not because I got more disciplined. I did not get more disciplined. I just found out that documentation had suddenly become load-bearing.

Here’s the setup. Every project I run has a ./docs folder. Specs, project notes, decisions I made and the ones I rejected and why. When a feature ships, the doc gets revised to reflect what actually got built (which is never what I planned) and moves to ./docs/shipped-features. That’s it. That’s the whole system. It fits on an index card.

The thing that changed is that a machine now reads those files on every single task.

For twenty five years, documentation rotted because only humans read it, and humans skip it. There was no immediate cost to a stale doc. It just sat there quietly being wrong until some poor soul six months later trusted it and lost an afternoon. But when an agent is reading your spec to write your code, a stale doc is not a future problem. It is a right now problem, and it will confidently produce four hundred lines of exactly the wrong thing. You feel that cost immediately. Turns out I am extremely motivated by immediate costs.

A few things fell out of this that I did not see coming.

The spec is the prompt. I never re-explain a project. The design doc already has the constraints, the decisions, and the roads not taken. Point the agent at it, and it knows what I know. The doc pays for itself twice, once for me and once for the model.

If you can’t write the issue, the spec isn’t done. My chain is docs, then GitHub issues, then Claude Code implements against the actual codebase. The issue is the unit of work an agent can finish. Trying to write one is a really unforgiving test of whether you actually thought the thing through. Half my “finished” specs have failed that test and gone back for another round, which was annoying and also correct.

The shipped-features folder is the sleeper hit. Revising the doc to match reality forces me to look at the gap between what I planned and what I built, and that gap is the entire lesson. What I ended up with is an architecture decision log that built itself instead of being some quarterly chore I resent. Six months from now when I ask why Granite handles tenants that way, the answer is sitting right there with a date on it.

So the punchline. Everyone keeps saying AI is going to kill documentation. In my projects it did the exact opposite. Docs went from the thing I owed my future self to the most valuable files in the repo, because they are the interface between what I know and what the machine can do with it.

Write the spec. Ship the feature. Fix the spec. Move the spec.

You were going to do it anyway. Now you have a reason.