rewrote my docs so Claude Code could actually use them, some notes
Spent last weekend rewriting the docs for a project so Claude Code could build against them without me hand-holding every step. Not docs for devs to read. Docs so the model can make correct decisions on its own.
What I changed:
- No tutorials or prose. Just endpoints, payload shapes, constraints, error cases. Everything in one place.
- Every doc is self-contained. No "see the auth guide." Just inline the auth details where they're needed. Models fall apart when they have to piece things together across 5 files.
- Explicit constraint blocks. Stuff like "this field must be set before calling X" or "these two ops can't run in the same transaction." If you don't spell it out the model will just guess wrong.
- Flat markdown, consistent headers. No tabs, no collapsible sections. Keep the structure boring and predictable.
Tested it on a real build — agent for a tutoring business (scheduling, payments, WhatsApp, Google Calendar). Pointed Claude Code at the docs, it built the working system in ~2 days. I mostly just reviewed PRs and tested edge cases.
Funny thing is the docs actually got shorter. Turns out most of what we write in docs is filler — transitions, analogies, "why you might want this" sections. Strip that out and you end up with something way more precise.
Downside: these docs are basically useless for a human trying to learn the system from scratch. So you kinda need two versions which sucks.
Anyone else doing this? What's worked or not worked for you?
