核心 GUIDE
Generation 之前先 Specification
当 Intended Behavior 与 Acceptance Evidence 在生成代码前已经定义，AI-assisted Implementation 才真正可控。
核心心智模型
Specification 是 Generation 外围的 Executable Boundary：它描述 Problem、Constraint、Non-goal、Affected Interface 与 Observable Acceptance Criteria，让生成结果有清晰 Target，也让 Review 有独立 Evidence。
为什么重要
Coding Agent 很擅长用“看起来合理”的 Implementation Choice 填补 Ambiguity。如果 Task 过于模糊，成功-looking Code 可能解决错误问题、扩大 Scope，或者引入没人要求的 Architecture。强 Spec 能减少 Rework，因为它既给 Agent 目标，也给 Reviewer 一套独立于 Agent 自述完成的验收依据。
01
把 Intent 转成 Observable Contract
Generation 之前先写 Desired User / System Behavior、相关 Repository Constraint、允许变化的 Interface、Explicit Non-goal 与 Acceptance Check。每个重要 Requirement 都绑定至少一种 Evidence，例如 Test、Type Check、Migration Verification 或 Manual Review Criterion。涉及多文件、多 Boundary 的改动，应先让 Agent 基于这些 Constraint 形成 Plan，再开始 Edit。
02
例子：给 Media Downloader 增加 Sorting
不要只告诉 Agent“改进 Filtering”，而是明确 Sortable Field、Default Order、Pagination Behavior、Backward Compatibility 与必须通过的 Test。Agent 可以自主选择 Implementation Detail，但不能悄悄把 Feature 重写成新的 Search System，也不能影响无关 Download Behavior。
常见失败模式
- 从一句模糊 Feature Description 直接开始 Generation，代码出现后才补 Requirement。
- Acceptance Criteria 只是换一种说法写“works correctly”。
- 让 Generated Implementation 反过来定义原始 Requirement。
工程启发
- 用 Non-goal 阻止看起来很吸引人的 Scope Expansion。
- 每个 Consequential Requirement 至少绑定一个 Observable Acceptance Check。
- Change 跨越多个 File、Boundary 或 Migration 时先要求 Plan。
关键结论
- 01Specification 在 Ambiguity 变成 Code 之前先降低它。
- 02Acceptance Evidence 应独立于 Model Confidence。
- 03好 Spec 约束 Outcome，但给 Implementation 保留选择空间。
来自 Knowledge Graph 的相关知识点
这些关系直接来自 canonical graph，不维护第二套 Guide 分类体系。