Every project here starts with a document written for someone who wasn't there.
It used to be for the next developer, or for me in six months, which is the same thing. Now it's also for Claude Code, which reads it at the start of every session. Same document. Nothing about it changed when the reader did, and that told me something about what the document was for all along.
What's in it
Not the code. The code explains itself, or should. The doc explains everything the code can't.
What the product is for. One paragraph. Who uses it, what they're trying to do, what "working" means. Every technical decision below is downstream of this, and it's the thing most codebases never write down.
What it isn't. The features that were considered and rejected, and why. This is the section that saves the most time, because the rejected ideas come back. A new developer suggests them. An AI agent builds them unprompted. A client asks again. "We're not doing X because Y" ends the conversation in one line.
Where things run. Which server, which database, which third-party services, which keys live where. The map of the territory, so nobody has to rediscover that the database isn't on the same box as the app.
The decisions and why. Why Expo and not native. Why one form backend. Why this pricing model. Not just the choice; the reason, so the next person can tell when the reason no longer applies.
Things that look wrong but aren't. Every project has a few. The retry that seems redundant and isn't. The index that seems unused and isn't. Without this list, someone "cleans them up."
How to deploy. The actual commands. Boring and essential.
When it gets written
At kickoff, before the first line of code. Then it gets updated every time a decision is made, in the same commit as the decision.
Writing it first feels backwards. You're documenting something that doesn't exist. But the act of writing "what this product is for" and "what it isn't" is most of the design work, and doing it in prose before doing it in code is cheaper by an order of magnitude. The doc isn't a record of the plan. It is the plan.
Writing it last, the way most handoff docs get written, produces a worse document. By then you've forgotten why half the decisions were made, and the doc becomes a description of what the code does, which the code already provides.
Why it works for an AI
Claude Code reads this doc at the start of a session and behaves differently for it: fewer rejected features rebuilt, fewer "cleanups" of things that look wrong, more decisions consistent with the ones already made. The drift I wrote about across long projects mostly disappears when the context is written down.
That's not because the agent is special. It's because the agent is a competent developer with no memory of the project, which is exactly who the doc was always for. A new hire is that person on day one. I'm that person after four months on something else. The doc was never for the team. It was for whoever's holding the code and wasn't there when it was decided.
If you're hiring me
You get this document with your build. Written at the start, updated throughout, delivered at the end. It's the thing that makes the handoff a handoff rather than a hostage situation, and it's the reason a project I built can be picked up by someone who isn't me.
Write yours the day you'd rather be coding. That's the day it's worth the most.