Spec Before Code

Ask for code directly and you'll read four hundred lines before realizing it misunderstood. Ask for a one-page spec first and the same error shows up in twenty lines in thirty seconds.

Before letting the AI write code, have it write in plain language what it intends to do: the data structures, the states on the page, how edge cases are handled, and where it's unsure. You read that page, change a few lines, then let it proceed.

This looks like an extra step, but it saves the most expensive step of all. The AI writing code costs you almost no time, but reading the code, discovering it misunderstood, then describing how to fix it—these three things all drain your attention, and they scale linearly with code volume. A spec is twenty lines; you can scan it in thirty seconds, and catching an error here costs almost nothing.

More importantly, the spec forces out the questions you haven't thought through yourself. The sentence "build a comment section" hides seven or eight decisions: threaded replies or not, editable or not, soft delete or hard delete, visible to logged-out users or not. If you don't say, the AI decides for you—and it usually picks the most common convention, which may not be the one you want.

The other patterns in "Working with AI"—three-part prompts, reference anchoring, distilling constraints—all depend on having this habit first.

The four parts of a spec

All four are essential; the last one is the most valuable.

Design considerations

• Explicitly tell it not to write code yet, or it will go ahead and finish. The model's default is to hand you something complete and runnable. Without this constraint you get a spec plus four hundred lines of code — which defeats the purpose. Put this line both at the start and the end of the prompt.
• Ask it to call out anything it's unsure about. This is the most valuable part of the whole pattern. It exposes the holes in your need, and if you don't fill them here, the model will quietly guess an answer and bury it in the code — usually only caught at test time.
• Keep the spec within one screen. Beyond one screen you stop reading carefully, and this step is wasted. A spec that's too long usually means the task is too big — split it (see "One Thing at a Time"). Twenty to thirty lines is a comfortable length.
• Keep the agreed spec in context, not just in your head. Write the finalized spec into a markdown file in the project, and bring it along every time you ask it to modify that module. Otherwise, by round three it forgets round one's conventions and you have to re-explain everything.
• Change the spec, not the code. When the output is wrong, your first move should be to add the missing line in the spec, not to say "change this here to that." The former fixes the whole class of issue you haven't even noticed yet; the latter fixes only this one spot.
• Write the spec about what and why, not how to implement. Specifying which library to use or how to split functions is over-constraining — it forces the AI to abandon what it already knows. You judge; it implements. Clear boundaries save both sides work.

Note for the AI

You can fix this line as the opening sentence every time you start a new module.

我要做：[一句话描述功能]

先不要写任何代码。先给我一份不超过 30 行的规格，包含四部分：

1. 数据：涉及哪些实体、关键字段、彼此的关系。
2. 状态：这个界面会出现哪几种样子，各自什么条件下出现。
   至少覆盖正常、空、加载中、出错。
3. 边界：你能想到的异常情况和你打算怎么处理
   （超长内容、零条数据、权限不足、并发修改、网络失败）。
4. 未定项：我没说清楚、你只能靠猜的地方，逐条列出来问我。
   不要自己替我决定。

用中文，列表形式，不要展开解释。我确认之后再动手写代码。

After confirming, the second line:

规格按以下修改后定稿：
- [你的修改 1]
- [你的修改 2]
- 未定项的答复：[逐条回答]

请把定稿的规格写入 docs/specs/[模块名].md，然后按它实现。
之后我对这个模块提的任何修改，都要先同步更新那份规格文件。

Related Patterns

Real Examples