# [Project] 10. My Vibe Coding Best Practices: From One Sentence to Code
If you know me, you know I've been focused on how to make AI better at maintaining requirements and developing features. This workflow is the best practice that crystallized out of my latest round of practice.
Over the past two years I've written a lot with AI, from one-line scripts to entire systems. After stepping on enough landmines, I settled on a path I actually trust: **don't let AI write code directly — first have it "translate" the requirement into a tens-of-thousands-of-words design document, read it yourself, pass blind review, then touch code**. It sounds roundabout, but it's actually much faster.
First, about the term "vibe code": it's the popular recent practice of writing code by conversing with AI in natural language — you give a one-line requirement, AI writes the code for you. This workflow is essentially a form of vibe coding, except it goes a few steps further than "one sentence for a thousand lines of code" — it makes AI understand first, then act. If you're not familiar with vibe coding, just read this as "letting AI write code".
This article breaks the whole workflow down. I won't teach you how to chant prompts like spells — that's tactics. I'll explain why throwing a one-line requirement straight at AI always collapses, why you have to take the long way around and write a document first, and how humans should interact with AI at each step. The only "tactics" I cover is the model selection in the final coding section — that's the exception, because it directly determines success or failure, so I set it aside for a dedicated section later.
A directly usable version of this workflow is an AI skill recommended by goody-hao, in the [pi-desktop skills directory](https://github.com/GOODDAYDAY/pi-desktop/tree/main/src/plugins/system/goody-hao/skills). A note first: this paragraph just points to a ready-made artifact; if you only want the methodology, you can skip it entirely without affecting anything below. Three names, briefly: an AI skill is a packaged instruction set you can feed directly to an AI tool so it runs the workflow automatically; goody-hao is an AI assistant that maintains these skills; pi-desktop is the desktop tool project that hosts them. In that directory, `write-design-doc` is the methodology of this article itself, and `arch-to-code` is its companion flow extending to "architecture doc → complete code". Drop the files into the skills directory your local AI tool expects (each tool differs; follow its instructions) and you can trigger it. What follows is the full design rationale behind this skill.
Here's a full flow diagram up front; every section below follows it. Every term in the diagram (title, summary, blind review) gets expanded in the body — for now, just get the big picture.
**Figure 1 — Full flow: one-line requirement to code, where every level is a human-AI alignment checkpoint**
You might ask: with thirty thousand words in between, is this still vibe coding? Yes. The essence of vibe coding isn't "write less, ship fast" — it's humans driving AI with natural language. My path front-loads the alignment time that needs to be spent: slow at the beginning, no rework later. I'll do that math below.
## Why One-Line Requirements Straight to Code Always Collapse
Let's replay the most common train wreck. You tell AI "write me a ticket system", it spews out a thousand lines of code — pages exist, database tables created, APIs wired up. You open it up — it's not what you wanted. Missing state transitions, an unwanted notification nobody asked for, field names that don't match your team's conventions. Then you start the "prompt loop": wrong here, fix it; wrong there, fix it again. By round ten, AI starts breaking things it fixed correctly earlier. You get frustrated, it apologizes, then rewrites the whole thing and loses features that worked in the first version.
That's the classic vibe coding death spiral, and almost everyone has been through it. Where's the problem?
It's not that AI is dumb. It's that **your input is too thin, and AI's output is too thick**. Between one sentence and a thousand lines of code sit tens of thousands of decisions you never voiced: how state transitions, who has permissions, where data lives, what happens on errors, what the UI looks like. The "ticket system" in your head is a complete picture full of defaults; what you said out loud is five words. AI can only guess — guessing wrong is the norm, guessing right is luck.
**Figure 2 — One sentence to code: information gets compressed, then guessed open. Divergence is inevitable on this chain**
Here's a key insight: **the understanding gap (diff) between you and AI is unavoidable**. No matter how good the prompt or how full the context, as long as there's a "compress-guess" step, the diff exists. So the question isn't "how to eliminate the diff" — it's **how to expose the diff in a cheap place**.
Code is the most expensive place. If you only discover the misunderstanding after the code is written, it means rewrite from scratch, rework, re-running tests. Fixing a diff at the code layer costs hours to days per occurrence. The text layer is far cheaper — a misunderstood paragraph in a document is fixed by changing a few words, costing seconds.
**Figure 3 — Diff exposed at the text layer vs. exploding at the code layer: two orders of magnitude in cost**
So my conclusion is: to be good at vibe coding, you first learn to "not write code". Push everything that needs alignment up front, and resolve it at the text layer.
## Vibe Coding Succeeds or Fails on Understanding Alignment
To put it plainly: AI writing code isn't "executing instructions" — it's "understanding the requirement, then translating it into code itself". Translation presupposes understanding, and understanding inevitably distorts — because your intent is a picture that isn't fully made explicit, and AI can only reconstruct it from your limited expression.
That sounds philosophical, but it has one very practical corollary, which I call the **diff law**:
> The difference between the solution in your head and the solution AI reconstructs necessarily exists — it's never absent, only late. What you need to do is catch it when it's cheap, not wait until it becomes an expensive bug.
How do you catch it? Make AI **restate its understanding to you at every level**, and you compare and correct level by level. That's the whole meaning of the chain "one-line requirement → title → summary → complete document" — it's not ceremony, it's a row of **alignment checkpoints**, each forcing AI to lay its current understanding out for you, while you check carefully at each level and correct deviations immediately.
**Figure 4 — The essence of progressive expansion: every level is a "AI restates → human checks → human expands" loop**
"Correct + expand" in the diagram means the two things humans do in each loop: **correct** is fixing the parts AI got wrong in this level's output; **expand** is adding new ideas you didn't say before on top of it — both happen in the same pass, and AI continues expanding with your corrections and additions. It corresponds to the most common thing you do when writing docs: fixing what AI got wrong and adding what you just thought of.
Here's a counterintuitive but important point: **check for diffs at every level — but they guard against different kinds of errors**. Early diffs check direction — the gap at the one-line/title level, where even after correction AI might drift a bit again, but it blocks catastrophic "entire direction wrong" failures at the cost of thirty seconds per fix. Late diffs check details — at the full-document level, AI has made every decision explicit, each of your corrections lands concretely and won't drift, but the cost is higher. So neither end can be skipped: the early ones are cheap and block big errors; the late ones are precise and catch details. Alignment debt incurred early gets repaid at tenfold interest later.
## The Full Flow: Six Steps, Each a Checkpoint
The whole chain is: one-line requirement → title → summary → 10k-word complete document → blind review → code. Here's a diagram of each step's output and checkpoint; the sections below break each one down.
**Figure 5 — Six-step overview: the first five steps align at the text layer, leaving only translation at the code layer**
See it? The outputs of the first five steps are all "things humans read"; only the last step is "something machines run". When the design phase is done, the solution no longer needs "thinking" — every decision is in the document, and writing code is just translating it. This echoes one sentence: **a design document is an argument for humans to read, not a form to fill for a system**.
Why must you expand progressively instead of having AI write thirty thousand words in one go? Three reasons. (A note: this is about "why not write it all at once", not that every step must be followed mechanically; in practice, producing titles and summaries can be merged or skipped per project, see 4.1 and 9.3 — but only after the direction is confirmed.)
1. **Avoid self-directed detail dumping**: if you have AI write a long document in one shot, it will invent piles of details in places where you haven't fixed the direction, and those details become the cost of later rework. Progressive expansion guarantees each step builds on ground you already confirmed in the previous step.
2. **Train your sensitivity to diff**: starting from one sentence, comparing carefully at every level, you gradually develop a feel — where AI misunderstood, where it's gliding past, where it's making decisions for you. This feel can never be trained by writing a long text in one go.
3. **Respect human reading speed**: human reading and digestion speed is limited. Handed thirty thousand words at once, you'll most likely not finish reading, or forget the beginning by the end — you simply don't have the mental capacity to align with AI on every decision. But handed piece by piece, you have time to read each piece through, think it over, and confirm — which itself constitutes the process of you gradually sorting out the requirement. By the section the document has reached, your understanding of the requirement has reached that layer; step by step, the requirement becomes fully thought through. **This isn't AI helping you — it's you using AI's output to figure out your own requirement.**
## Nail Down "What Problem Are We Solving"
Many people jump straight to writing the document and skip the first three steps as fluff. But the most valuable alignment happens precisely in these three steps — because the document is still empty, you haven't been led astray by "existing text", and your intent is at its cleanest.
### One-Line Requirement: Start with Intent, Not Instructions
The very first sentence — don't write imperative phrasing like "build me an XX system". First think: **why** do you want this? What problem does it solve? Who uses it?
This isn't mystification. Because what AI can infer from "why" is far more than from "what". "Build a ticket system" and "let support stop tracking tickets in Excel" are two different sentences — the latter lets AI fill in a large number of reasonable design decisions itself; the former leaves AI guessing blind.
I usually add three more things: background (how it's done now, where it hurts), goal (what counts as done after it's built), and boundaries (what's explicitly out of scope). Together these usually amount to about a hundred characters. For example, a recent requirement of mine started like this:
> The team currently tracks tickets in Excel, one copy per support agent, merging is all manual, and tickets get lost regularly. (Background) I want an internal ticket system: agents can create tickets, transition status, add follow-up notes, and managers can see statistics. (Goal) V1 has no permission system — everyone sees everything; no notifications — manual notification for now. (Boundary)
That's only about a hundred characters, but it fully conveys "why, what, and where V1 stops". Based on it, AI can infer: there should be a ticket object with status fields, a list and detail page, a note timeline, and a simple statistics view. The default decisions AI infers are exactly the objects you'll verify one by one next.
That said, the above is the ideal form; in practice I'm more casual. I usually chat with AI about the feature itself first — have it load relevant domain context (background, similar projects, relevant conventions), then discuss my own ideas until both sides understand each other. By then I often don't need to walk through those three steps formally — I go straight from the one-line requirement to "make a title". Every step on this chain is a checkpoint, but exactly where you linger and where you skip is flexible per project — don't be bound by the process. What's preserved is only the spirit of "align at every level". Note the distinction: what can be skipped is the order and trade-off of producing "title, summary" — but **the "careful checking" action after each level's output can never be skipped** — that's the lifeline of this chain (re-emphasized in 9.3).
Let me clarify what "skipping output forms" means, to avoid misleading: it doesn't mean you skip checking and run straight to writing the document; it means the two levels "title" and "summary" **can be merged or drop their standalone outputs** — for example, if while chatting the direction is already confirmed, you directly ask it to write the document section by section, without separately producing "title" and "summary" intermediate files. But even when merged, you still carefully check each section AI produces and correct any diff you see. What's skipped is "one extra intermediate file", not "the act of checking".
### Title: Force AI to Restate Your Intent
After the first step, have AI **propose a title** based on your description.
A title is a one-sentence summary; it naturally forces AI to compress "what it thinks you want" into a single judgment. One look at the title tells you whether it misunderstood — if off, correct immediately at zero cost; if on, the direction is right and you can proceed confidently.
Bonus: the title also reveals **whether AI picked up on what matters to you**. Did it reflect the point you care about most in the title? For example, if what you want is "no lost tickets, no broken transitions" and it gives a safe title like "ticket collaboration platform", that shows it didn't grasp your real concern — and this deviation is worth correcting on the spot, just like a misunderstanding.
Don't underestimate this step. It's the first real alignment point, and because it's small, you almost never skip the checking out of laziness. The habit of "carefully looking at every level" is built right here.
In practice, when I get a title I do one thing: translate it back to the requirement in my head and see if the two ends match. If AI's title is "internal ticket collaboration platform", I expect it understood "collaboration platform" with emphasis on multi-person collaboration; if what I actually want is "ticket recording and follow-up", those are not the same thing — I correct on the spot rather than settle and move on.
### Summary: Distill the Core Mechanism
Once the title is confirmed, have AI write a summary — a few hundred words explaining the system's most core mechanism.
The value of this step: **it forces you to answer "which part is the heart of this system"**. Many requirements you claim to want, but you've never seriously thought about what the true core mechanism is. If AI's summary misses the point, you see it at a glance, and you're forced to answer "so what should the core be" — and this forced thinking process itself eliminates the most expensive kind of diff: **you haven't even figured out what you want**.
Back to the ticket example. If AI's summary emphasizes "how nice the statistics dashboard looks" while your true core is "status transitions never break, no lost tickets", that's a directional diff — it wants to go left, you want to go right. Correcting at this step is one sentence; correcting after the whole document is written means throwing the whole document away.
**Figure 6 — First three steps: each output is tiny, but each is a gate for eliminating directional diffs**
### Check Diff at Every Step: Don't Tolerate Vague Steps
The shared discipline of these three steps is one rule: **every time AI produces a level, check it carefully, fix any diff, don't move on**. Sounds like common sense, but 90% of people fail right here — the title is wrong, and they think "keep writing, deal with it later", and the whole document ends up on a crooked foundation, with full rework at the end.
This isn't inefficiency; it's time-saving. A correction up front costs thirty seconds; rework later costs three hours.
## The 30k-Word Complete Document — Length Forces Specificity
The first three steps nail down the direction; now comes the main event: have AI expand the whole solution into a complete design document that can be followed directly to write code.
To be honest, the title and summary work above is just the appetizer. The real core of this workflow is the very long design document produced in this step — it's the carrier of all prior alignment and the only basis for writing code later. All the earlier steps, at bottom, exist to **keep the frame from being crooked**: if the direction isn't nailed down first, this core document is wrong no matter how long. With the direction right, this long document has meaning.
### Length Isn't the Goal; Specificity Is
Why must it be on the scale of thirty thousand words? Because **only at this length does AI have no room for vagueness**.
AI's laziness resembles a human's: given a short length limit, it writes every decision ambiguously, because "leaving the specifics for the reader to fill in" isn't wrong in a short document. But when the length is pushed to the ten-thousand-word scale, every topic must be expanded thoroughly and vagueness has nowhere to hide — it must draw the state machine, define every field, write every failure path. **Length isn't the goal; length is the means: use volume to force specificity.**
This process is equally cruel and equally fair to humans. Every vague spot AI exposes in a long document is a place in your head where "I thought I understood, but I hadn't thought it through". Reading paragraph by paragraph, you're forced to fill them in — and this is the biggest value of the document phase: **it turns the mush in your head into solid decisions in the document**.
### Block-Style Prose: How Long Text Stays Readable and Scannable
The easiest way a 30k-word document fails is being unreadable. AI's default output is "short-phrase outlines + flat sections" — all fragmented bullets, reads like a slide deck, extremely low information density, and people give up checking before five thousand words. Giving up checking means falling back to the "AI writes it and AI reads it" path, and all the diffs leak through again.
My approach is to have AI write in **block-style prose**: each paragraph is a complete argument block, with list shells separating boundaries, but inside each block are complete sentences and complete arguments, not fragment phrases. Titles provide the map, paragraphs provide the footing — readers can scan, but wherever they land they capture complete information. The article you're reading right now is written this way.
One more rule: **name section titles by their content** ("Why progressive expansion is necessary", not "Section 3"). Readers know what a section covers by its title and can jump wherever they want.
My typical instruction is:
> Please write this solution as a complete design document, organized by topic, each section around one decision. Split subsections as much as possible; better to split finely than pile everything into one section. Write arguments in complete sentences in the body, don't use fragment short words as bullets; define every key concept clearly — don't make me fill in the blanks.
Behind these sentences is blood and tears: fragmented bullets make you unable to read on, flat sections drown the key points, and without demanding "define clearly" it defaults to assuming you can fill in the gaps.
### Diff Convergence in Section-by-Section Expansion
Don't have AI spit out the whole 30k-word document at once. Have it **expand section by section**, one topic per section; after each section, you read it, correct the diffs, then move to the next.
This is the same rhythm as the first three steps, just at a larger scale: the first three are "sentence-level alignment", this is "section-level alignment". Section-by-section expansion has one extra benefit — AI writes each section on top of "upper text you've already confirmed", so its deviation shrinks progressively. You might correct a lot in the first few sections, but it gets smoother and smoother — that's diff convergence.
**Figure 7 — Section-by-section expansion: every section is a "AI drafts → human checks → diff to zero" loop, getting smoother over time**
The four kinds of diffs I most often correct during section review, for you to match against:
- **Misunderstanding**: the section says something different from what you want — fix it directly, have AI rewrite the section.
- **Self-directed decisions**: AI made a decision you never mentioned — first ask yourself "is this decision right"; keep it if right, correct it if not.
- **Vague gliding**: halfway through the section you find it circling and not saying anything clear — send it back to expand thoroughly.
- **Scope creep**: the section quietly includes features outside the boundary — cut them, back to within the boundary.
### When Is the Document Ready to Start Coding
This is a frequently asked question. My criterion is simple: **when no sentence in the document still requires you to fill in details in your head, you can start coding**.
A more operational formulation: read it through once; if every decision has an explicit definition in the document — what states exist, what the data looks like, what happens on errors, why this option was chosen — without you needing to mentally add anything, the document is ready. If while reading you find yourself mentally adding "there should also be…" and the document doesn't have it, it's not done — keep going.
Another practical signal: you find yourself starting to "think AI is being verbose". Verbosity means it packed in details thoroughly, and you approve of all of them — which is actually good news: it means the diff is essentially zero and everything left is stuff you already confirmed.
## Blind Review — the Quality Gate
The document is done and reads smoothly to you. This is the most dangerous moment — because your head carries context, and you think "this paragraph obviously means X", but someone who wasn't involved might understand nothing. **You can't read your own document on behalf of a reader**. This step is about bringing in a reader who's "never seen the world" to find every place you thought you made clear but didn't.
### What Is Blind Review
Blind review is: find someone **completely uninvolved in this project** (or a fresh AI session), feed them only the current version of the document, have them read from zero, and see whether they can understand it and find the information they want.
The core is four words: **zero context**. No background, no conversation history, no "you told me earlier". Because that's exactly how readers receive your document — they only have the document, not you.
In practice, "start a fresh AI session" means opening a brand-new conversation in your AI tool (a new chat window that doesn't inherit the current conversation), pasting the entire current document in, and attaching the one question you want to ask — that's it, nothing else. (If the document is too long for one message, section 6.3 has concrete handling.) After opening that session, don't go back to the writing conversation and keep asking it — then it has context and is no longer a "zero-context reader".
### Why Blind Review Is Mandatory
Because writers always overestimate how clearly they've written. Psychology calls this the "curse of knowledge": once you know something, you can't imagine how hard it is for someone who doesn't. When you read your own document, you automatically fill in every gap — but readers don't.
I've been burned by this. There was a document I thought was logically airtight; during blind review I had AI play "a reader who's never heard of this project" reading paragraph by paragraph, and it reported seven or eight questions like "I can't understand what this paragraph is saying" and "are these three concepts the same thing?". Every one was a place I'd skipped past as obvious but a reader would get stuck on.
### How to Do It
Blind review runs on two tracks in parallel.
**Question track**:
1. First predict 5–8 "questions a new reader trying to use this document would most likely ask" — e.g., "how exactly does this state transition?", "what happens on failure?", "why not use the off-the-shelf XX?".
2. For each question, start a brand-new AI session (not the current one!), feed it only the document + this one question, and ask: "Where in the document can the answer to this question be found? Or nowhere?"
3. In practice, "only the document + one question" means pasting the whole document into the first message of the new session, right before the question. If the document is too long to paste in one message, paste it in chunks into the same message (keep typing, don't open a new message to let it "receive"), or first let it "receive the complete document, please answer…" — the key is that this session has no background other than the document and your question. Ask after feeding, end after asking; don't follow up down the rabbit hole, and don't bring any history.
**Sweep track**:
1. Start another fresh AI session, have it sweep the entire document, and specifically report three things — where it's vague, where it assumes the reader already knows some knowledge, and where sections contradict each other.
2. The instruction I commonly use for this track is: "You are a reader who has never seen this document. Read the whole text; answer only three questions: ①Which parts read as vague or get readers stuck? ②What does it assume the reader already knows? ③Are there contradictions between different sections? List them one by one with locations." — readers can copy this verbatim.
I want to emphasize one point here, which is also one of the most important roles of blind review: **internal error correction — pulling out contradictions inside the document itself**. Long documents are written in several sections; by the time you write section 6, you've long forgotten what section 2 said — so it's extremely easy to get "this section says state A, that section says state B" or "here it says return null, there it says throw an exception". You won't find these yourself, because you read with the filter "I know it's like this"; but a zero-context reader has no such filter and immediately sees the two sections don't match. This is what blind review catches — it doesn't just check whether readers can understand, it checks whether the document stands on its own.
It's normal for the two tracks to hit the same gap; just deduplicate. Then aggregate all gaps into a list, go back to the document and patch each one, re-run blind review after patching, until the sweep report is empty and every question can locate its answer in the document.
**Figure 8 — Blind review is a loop: expose gaps, patch the document, re-test until clean**
One technical detail worth mentioning: **every question must use a brand-new AI session**, never reuse the current session, and never reuse a previous round's session. Because reuse gives it context, and it's no longer a "zero-context reader" — then blind review becomes grading yourself, which is worse than not testing, because it manufactures the illusion of "I've verified this".
### Convergence Criterion
When does blind review pass? Look at two observable facts: the sweep track reports "no vagueness, no assumptions, no contradictions", and every question on the question track can locate an answering passage in the document.
Note the criterion is "**can it be located**", not "does AI think the answer is correct". Design questions have no standard answer; the only thing that can be judged is "does the document provide the basis". This is a sober boundary: blind review isn't responsible for evaluating whether your solution is good; it only tells you whether readers can understand your solution.
Run at most three rounds of blind review. If it's still not clean after three, list the remaining gaps and let you decide whether to patch or accept — don't grind forever.
## Write Code — Translate the Document into Implementation
Only after the document passes blind review do you write code. The coding step is comparatively "simple" — because every decision is in the document, AI's job shifts from "understanding the requirement" to "translating as written", and translation has an order of magnitude lower error rate than understanding.
### With a Complete Document, Code Is Just Translation
What I want to emphasize about this step is precisely not how to write, but **don't rush**. Many people get excited at this step, delete the document, and start a fresh session from zero — which throws away all the hard-won diff alignment and returns to "one-line requirement coding".
The right way: feed the entire document as context to the coding session and have it implement section by section. The document already specifies the state machine, data structures, interfaces, and failure paths; AI just turns them into code. You can require it to "state which document section a feature comes from before implementing it" — so when it tries to cut corners and glide past, you notice immediately.
My typical requirement for the coding session:
> The following document is the only source of truth. Implement by section; before implementing each feature, tell me which document section it corresponds to. If you find anything unclear in the document during implementation, don't decide on your own — list it and ask first.
This requirement chokes off AI's "self-directed decisions" in advance: once it starts adding things not in the document, either it proactively reports, or it gets caught when "stating the source".
In practice I've also tried a more convenient approach: pull up a **dynamic workflow** in Claude Code to do the implementation, rather than relying on a single session to translate it all at once. (Claude Code is a command-line AI coding tool; a dynamic workflow is one of its execution modes — splitting a large task into multiple steps run sequentially and automatically, each step with its own context.) A dynamic workflow splits "code per the document" into a long-horizon task — broken down by the document's sections into steps, each with clear inputs/outputs, self-checking before the next step, with context handoff and state tracking along the way. In practice this is far more reliable than a single session spitting it all out: a large implementation won't be crushed by one session's context limit, each section's completion can be tracked separately, and the probability of missing things drops a tier. If your tool supports dynamic workflows, prefer this path for the implementation phase.
### Model Experience: k3 Is Complete; glm5.2 and Below Drop Items
Here's an experience I bought with real money, worth calling out separately. Two model code names first, used below: k3 is the high-tier model I use daily (top tier in capability, on par with the strongest few on the market), and glm5.2 is a common mid-tier model that's good enough — what follows is the difference between these two classes of models at the "document → code" step. Match your own model: if capability is top tier you're in the k3 class; if mid-tier, the glm5.2 class.
The document phase doesn't demand much model capability — writing documents and blind review are fine on mid-tier models. But **the step from document to code has a steep jump in completeness requirements**. What I measured in practice:
- **k3-tier (high-tier) models implement what the document defines fairly completely** — full state coverage, failure paths handled, fields aligned.
- **glm5.2 and below drop things — and the dropping has nothing to do with how you write the prompt; no matter how you write it, things get dropped**. It's not disobedience; its "completeness capability" is simply insufficient: some branches and edge cases written in the document get lost during implementation, one or two at a time, and it doesn't know it.
**Figure 9 — The completeness requirement at the document phase vs. the code phase: not the same magnitude**
The practical implication is direct: **if the document is detailed and you only have a mid-tier model, for the code implementation either upgrade the model or do strict item-by-item verification** — go through every decision in the document and tick it off against the code. Don't expect a prompt tweak to make glm5.2 complete; it can't, and this isn't something prompts can fix.
### Why Things Get Dropped: Model Differences in Completeness
Why do some models drop things? It's not that they "get dumber" — it's that **the ability to maintain completeness over a long context is an independent capability dimension**. "Long context" here means the amount of information AI can "hold in its head" at once — the longer the document and the more decisions, the harder it is for the model to "remember all constraints and implement all of them" while generating code. High-tier models have ample headroom in this dimension; low-tier models "overflow" — beyond their retention range, they start quietly discarding things they consider "unimportant", and they won't tell you.
So the document phase's value shows up here once more: **the more detailed the document and the more explicit each decision, the cheaper a model's "dropping" is at the code phase** — because you can spot what was dropped against the document immediately. Conversely, if the document is thin, you can't even notice the dropping, and it becomes a bug after release.
## The Document Is Alive: AI Continuously Maintains the Requirements Document
After this workflow completes — document delivered, code written — is that the end of it? I initially thought so. But in practice I found an unexpected payoff: **these documents aren't dead; AI keeps updating them as the project evolves**. (A note: I've been calling it a "design document" until now; from this section on I call it a "requirements document" — it's the same document. In the design phase it's a design proposal; after the code phase it becomes the factual source of truth for this requirement.)
High-capability AI automatically writes new decisions back into the document during later development — a field gets added, it patches the data-structure section; a state transition changes, it updates the state-machine section. It even goes beyond "faithful recording": when you propose a change in code that contradicts the document, it first points out "this conflicts with section X of the document", reminding you to decide whether to change the code or the document. That is, in effect, already doing **requirements document maintenance** — which is normally the easiest thing in a project to let rot, and the chore nobody wants to do.
Why can it do this? Because the document is detailed enough and well-structured enough that AI can read it and maintain it. A 30k-word document isn't a burden to AI — it's a "world model" AI can read and understand; it knows what the requirement looks like and can update it with confidence. Conversely, if the document is only a thousand words and vague, AI has nothing to grip when maintaining it, so it naturally won't touch it.
This loops back into the workflow itself: **the document is worth writing carefully not just for pre-code alignment, but to become the project's only trustworthy, continuously maintained (by AI) source of requirements**. If the requirements document doesn't rot, code and requirements won't drift apart.
## Boundaries and Common Problems
This workflow is very useful, but it's not universal. Let's cover when not to use it, and the most common pitfalls.
### When Not to Use This Workflow
- **When the scope is too small**: fixing a bug, adding a small feature, or writing a one-off script doesn't justify the full workflow — a document longer than the code is pure waste. My rough line: if it can be said in one session and written in half an hour, don't write a document; if it spans days, dozens of files, and involves state, you must.
- **When you're not sure of the requirement yourself**: don't rush to write a document either. The input to this workflow is "you at least have a rough direction"; if you don't even have a direction, prototype first, talk first — don't force the document workflow onto it.
### Thirty Thousand Words Isn't for Every Project
Length should follow complexity. A small tool's document might be a few thousand words; a complete system's document needs the ten-thousand-word scale. Don't pad for padding's sake — **length is a means to force specificity, not a goal**. The pass criterion for a document is always "every decision is explicit", not "reached a certain word count". So "thirty thousand words" in the title refers to a magnitude — projects that need a document typically balloon toward ten thousand words once expanded; it's not that you must count your way to thirty thousand to be done.
### Common Pitfalls
- **Skipping checks**: as said in 4.1, producing titles and summaries can be flexibly skipped per project; but the "careful checking after each level's output" action, once skipped, loses everything. Many people think titles and summaries are too small and skip the checking, only to have directional diffs surface at the document phase with a pile of rework.
- **Blind review as a formality**: using the current session to "grade yourself", or letting the same session both write and review. That's worse than not testing — it gives you the illusion of "I've verified this".
- **Rushing to code**: excited when the document is done, starting a fresh session from zero, throwing away all the diff-clearing results. Remember: the code phase must feed the document in as context.
- **Forcing a low-tier model through the code phase**: the document is detailed but the code phase is forced through glm5.2, then you keep tweaking prompts to stop it dropping things — it can't. Either switch models or verify item by item; pick one.
## QA: The Questions Readers Most Likely Ask
**Q: How long does this workflow take? Isn't it slower than writing code directly?**
It depends on the project. Small projects are indeed not worth it (as said, don't write documents for things that can be written in half an hour). But for medium and larger projects, the extra time spent writing the document up front is fully recovered in the code phase — because there's no rework. Writing a complete, shippable document typically takes a day or two; but one "misunderstood, throw it all away" rework often takes more than a day or two. The math goes in that direction.
**Q: Will the document and code drift apart over time?**
If the code phase feeds the document in as context, drift is small; if you start a fresh session from zero, drift is large. So the key action is: **the coding session must carry the document**. The document is the spec for the code; every question in the code phase should go back to the document for answers.
**Q: Will AI make up things I didn't say when writing the document?**
Yes, and that's a feature, not a bug. For the parts you left out, AI fills in default decisions — and that's exactly where you most easily find diffs during checking. Every "AI self-directed decision" you see while reading paragraph by paragraph is a reminder that "you haven't thought this through yourself yet". Fixing it is far more efficient than leaving it blank for you to fill in later.
**Q: Does blind review have to use AI? Can a real person read it?**
A real person is better, but expensive and slow. My approach is AI blind review as primary (fast, repeatable, zero context every round), with a real human doing one extra round on critical documents. The value of AI blind review is precisely that it can be re-run infinitely, truly zero-context every time — something a real person can't do.
**Q: Is thirty thousand words mandatory? I've never written such a long document; what if I can't?**
Thirty thousand words is a result, not a requirement. First demand AI "expand every topic thoroughly, no vagueness allowed", and what it writes naturally gets long. You don't need to know how to write long text yourself — your job is to read it, correct it, and force it to explain clearly. The longer the document, the more specific it usually is, and the closer it is to "ready to write code".
**Q: Is the document fixed after it's written? What if requirements change later?**
If requirements change during coding, change the document first, then the code — never the reverse. The document is the only trustworthy source of requirements, and code always follows the document. The first step of any requirement change is always updating the document, so code and document stay aligned and you never get "ghost features that exist in code but not in the document". And as section 8 says, high-capability AI proactively maintains the document for you — it executes the "document first, code second" discipline for you.