如何给编码代理一份可执行的规格说明

编码代理在成功条件可观察时更可靠。Microsoft介绍的spec-driven development把living specification作为真相来源，并让它与代码和测试同步更新。

1. 先写结果

从用户和可观察行为开始。

Goal: A signed-in learner can resume the lesson they started most recently.

User-visible behavior:
- The dashboard shows the most recently started lesson.
- Selecting it opens the lesson at the next incomplete step.
- A learner with no progress sees the existing “Start learning” action.

2. 写验收标准

包括正常路径、空状态、无效输入、权限和失败行为。

Acceptance criteria:
- A learner sees only their own progress.
- Missing progress does not cause a request or render error.
- A completed lesson points to the next lesson, or to the completion state.
- The existing dashboard remains unchanged for signed-out visitors.
- Automated tests cover the resume, empty, and unauthorized cases.

3. 先调查再计划

让代理找到相关路由、组件、数据访问和测试，再给出计划与不确定性。检查是否保留现有契约。

4. 让规格可执行

把它放在团队真正维护的版本控制文档或issue中，并把每条标准连接到测试或人工检查。

5. 保留人工审核

Sources: Microsoft on spec-driven development, Build with agents in VS Code, and VS Code trust and safety.

6. 随现实更新

规格不是一次性prompt。当测试或产品决定改变时同步更新，并在每条标准都有证据后再宣布完成。