write-spec

编写规格

将大型功能拆解成一系列小型契约。每个阶梯都应便于人理解、可由 Agent 测试，并且在整个功能完成之前就能发挥作用。

第一原则

1. 先刨根问底，再做规划。 每次只问一个问题，直到弄清楚预期结果、非目标、评审范围、必须遵守的契约、缺失的素材，以及第一个有用的可运行检查点。每个问题都给出建议答案，方便用户接受、拒绝或修改。检查代码仓库，不要询问代码已经能回答的问题。访谈结束时，询问计划是否必须保留向后兼容性或包含数据迁移——默认是两者都不需要：直接切换，不做兼容垫片、不搭建迁移框架，也不安排部署顺序。只有用户明确选择加入时，才将这些内容纳入计划。

2. 沿 API 接缝切分。 尽可能让每个切片都像一个小型库：有明确命名的模块边界、带类型的输入和输出、确定性的测试夹具，以及在接缝处进行的测试。如果一个切片需要启动三个互不相关的系统才能检查，就应进一步明确接缝。

3. 研究未知之处。 如果功能依赖陌生领域、高保真视觉目标、具名参考、基准测试、外部代码仓库、库，或“人们通常如何实现这个？”之类的问题，在最终确定切片前，先进行有针对性的在线研究。优先参考一手资料：官方文档、源代码仓库、论文、案例研究、演讲和已发布的示例。如果存在参考实现，就在移植或近似实现之前，加入一个复现探索阶段。

4. 让进展清晰可见。 对于视觉或交互类工作，每个切片都应产出可供体验的内容：路由、测试夹具页面、测试框架、CLI 探测工具，或人类可以运行、检查、截图并提出意见的 HTML 可视化。测试用于证明契约；演示用于展现审美和意图。

5. 优化反馈循环。 拆分切片，让下一个有用的问题能够快速得到解答。优先采用可运行的小型界面、支持热重载的测试框架、示例测试夹具和独立工作台，而不是要求整个功能都完成后才能获得反馈的计划。对于素材密集型工作，规划一个素材应用／工作台，让人类和美术人员可以添加样本、上传替代素材、实时预览，并快速查看验证失败。

6. 遵循代码仓库的自然结构。 如果代码仓库是 monorepo，就规划应用和包，不要强行把所有内容都塞进当前应用。为每个可测试界面提供一等路由或命令；如果一个小型专用应用更清晰，就不要把新行为堆在不透明的查询参数后面。

7. 不要因缺少输入而停滞。 如果缺少美术素材、数据、凭据或外部素材，就规划生成占位内容，并明确替换契约。功能应借助占位内容继续推进，同时提供单独的交接流程，准确说明之后需要人类或外部合作方提供什么。

8. 并行起草，再综合取舍。 对于包含多个切片的功能，不要相信单次起草就能找到正确的拆分方式。分派几份独立草案，再合并出一份最佳计划（参见工作流）。观点分歧是有价值的——因此要从两个维度设计差异：给每份草案指定不同的侧重点（即它要优化的视角）；如果有不止一个模型系列可用，就混合使用不同的模型。盲审且侧重点不同的草案，能揭示单份计划容易遗漏的切片、接缝和风险；如果它们独立得出相同结论，就说明拆分方式可靠。

9. 递归揭开迷雾。 第一版切片图只是初步侦察，并不代表已经摸清所有情况。起草后，要把每个高风险切片都当作独立功能来检查。如果其中隐藏着多个变量、未知的外部实践、未经验证的架构，或“实现时再说”的问题，就继续拆分该部分并重复此过程，直到每个后续切片都只有一个问题、一个接缝、一个评审界面和一个明确结论。

10. 每个切片只关注一个视觉变量。 如果视觉切片要求一次就匹配最终主视觉图，就会失败。应按评判对象拆分：密度、轮廓、颜色、纹理、光照、雾、水体位置、水体材质、标签可读性、动画节奏。每个切片都针对该变量单独提供裁剪图／蒙版和评判结果。只有在各变量都有自己的证据之后，才应在合成／集成阶段进行整帧对比。

工作流

1. 访谈： 持续提问，直到你能清楚地说出各个切片，不再含糊其辞。当剩余未知项可以安全地通过第一个切片来发现时，就停止提问。
2. 研究： 如果功能涉及参考对象、库、技术、标准、视觉目标或性能模式，在起草之前先检查代码仓库，并研究陌生的外部实践。将发现的来源、代码仓库、文章或论文链接记录到规格说明中，并将任何范例转化为复现试验，再开始移植切片。 如果先前的实验已经确定了认可的方案，请在起草替代方案之前应用下文的从研究到实现。
3. 并行起草： 对于包含多个切片的功能，至少安排 三个独立子 Agent 起草完整计划——每个子 Agent 都使用全新的上下文；如果需要运行或构建来验证，就为各自分配一个 Git worktree，否则让它们直接返回计划。三个只是最低数量，不是固定数量：根据功能复杂度扩充团队，问题支持的每种真正不同的方案或视角都应增加一名起草者。给每个人相同的访谈简报，且不提供其他内容（绝不能提供其他人的草稿），但要为每个人指定不同的偏向，让他们的分歧有章可循，而非偶然产生。基准三人组：
   • A — 最少切片偏向： 采用仍能交付的最短阶梯；积极合并切片，并质疑每一个步骤。
   • B — 风险优先偏向： 优先处理最令人担忧的未知因素；安排切片顺序，使计划在假设错误时能尽早失败。
   • C — 边界质量偏向： 优化每个边界处的 API 边界、所有权和可测试性，即使这意味着增加切片。 根据功能需求替换或添加视角（例如资产管线偏向、性能偏向、迁移安全偏向），但要保持各视角彼此正交——通过添加新视角来扩充视角池，绝不要重复运行同一个视角。 还要混合模型系列：如果当前要求使用 codex 起草，至少用 claude 起草一份——反之亦然——这样视角池才能平衡不同模型的盲点，而不只是不同提示词的盲点。系列指供应商（claude 与 codex），而非等级：每份草案都使用最先进的模型；绝不要通过降级到同一系列中较弱的等级来实现多样化。每位起草者都要侦察真实代码和测试（实测事实、失败的做法、范围防火墙、可搜索的文件/测试名称），然后提出切片图、包/应用边界、依赖关系、API 接缝、可运行交付物、验证关卡和人工评审检查点。只有在问题确实只有一个切片时，才跳过并行发散。
4. **综合：**阅读每份草案并亲自制定规范计划——不要钦定其中一份。采用最好的切片方式，汇总各份草案单独发现的接缝、风险和防火墙；如果草案意见不一，就选择论据更充分的方案，并记录真正的备选方案供人工决定。草案独立达成一致之处就是可靠依据；意见分歧之处则最值得深入思考。只要功能具有任何视觉界面，就要将 screenshot-critique 设为 README 中的固定验证关卡，让每个视觉切片都继承此要求：规范必须要求实现 Agent 在接受任何视觉截图前，将无偏的 screenshot-critique 作为最后一项检查。只要某个切片有可供截图对比的对象——它所改变的先前视觉效果，或为该功能添加的参考/灵感图片——规范还必须将 compare-screenshots 指定为评判候选图与目标图的关卡：它能提供 screenshot-critique 的单图观察所不具备的遥测信息和「哪种方案较不差」的判断。
5. 递归排查模糊点：逐个审查规范图中的切片。对于存在隐藏变量、宽泛动词（“让它更逼真”“匹配参考图”“添加后端”）、缺少研究，或包含多个视觉变量/API 接缝的切片，将同样的切片逻辑应用于该切片，将其视为子功能。持续重复，直到下一个实现切片都能根据一个聚焦的产物予以接受或拒绝。将延后的变量记录为后续切片，而非当前切片中的文字说明。退出标准是决策预算：当实现 Agent 继承的是决策而非自行做出决策时，切片才算完整定义——每一项尚未明确的自由度，要么在切片文件中注明已委派，要么就需要再审查一轮。
6. **落实计划：**当功能包含多个切片或需要素材/可视化内容时，创建 specs/<feature>/。
7. **对计划进行重构清理：**对已落实的规范运行 refactor-clean——计划也是架构的一部分，必须描述代码库在当下重新设计时应有的形态，而非将功能强行附加到旧形态上。明确指出每个应有唯一所有者的概念（投影、环境、数据契约、渲染器阶段、状态机、测试判定标准），并确认没有任何切片引入平行抽象、重复概念，或必须由后续切片删除的兼容层。若某个切片确实需要过渡性脚手架，必须将其明确为短期接缝，注明移除条件和负责移除的切片——一旦其使用方迁移完成，就立即合并清除，默认不得保留到最后。将最终得到的单一所有者不变量和最终形态（“如同当下设计，而非事后拼凑”）写入 README，让每个实现阶段都能继承这些要求。
8. **回溯记录审查：**对话终会结束，规范会保留下来。在宣布计划完成前，检查完整对话及所有较早的规划材料（映射、访谈笔记、草案），找出只存在于其中的内容——带有理由的决策、说明淘汰原因的备选方案、中途的范围变更、用户提供的约束，以及决定了某事的随口备注。每项内容要么写入所属规范文件，要么有意舍弃；范围变更必须传达到所有提及该范围的位置，而不只是最终落笔的位置。然后重新阅读规范所取代的每份仍保留的计划前材料（映射的启动提示、待解决问题列表或提议计划），并在已被取代的部分标注指向计划的链接——不能让过时指示误导新的 Agent。完成标准是：每项对话决策都能在规范中找到，且没有任何仍保留的材料与执行阶梯相矛盾。
9. **逐个切片构建：**在依赖每个切片前，确保该切片有可运行的产物和验证结果。每个产物都要足够小，以便快速迭代。README 中的“下一位 Agent 提示词”应写成未来 Agent 阅读并遵循的交接文本。
10. **根据实际情况重新切片：**如果实现遇到阻碍，导致切片开始改变无关变量，或决策记录表因单个切片不断填满，就停止扩大补丁范围。先更新规范：将切片拆分为更小的契约，明确冻结的输入，将额外的视觉变量移至后续切片，并重写“下一位 Agent 提示词”，使工作从第一个新切片继续。重新切片是进展，不是失败。

从研究到实现

通过不可变标识冻结已验收 spike 的可运行代码、依赖项、配置、输入、提示词/技能和证据。检查它的实际行为；选项名称和摘要并不能证明其行为。

在规范中映射 已验证行为 → 证据 → 负责的切片 → 一致性门槛。向每位起草者提供这份契约和发现结果的局限。将用户要求的差异与未经测试的提案区分开；清理工作不得悄然重新设计胜出方案。

规划一次尽早进行的生产入口点对比，将其与冻结的参考版本使用匹配输入和受控响应进行比较。检查计算出的请求、决策和完整输出；明确允许的差异。每条保留项都必须有负责人和检查项。在耗费大量资源进行确认前运行一致性检查，并保留原有质量门槛。

计划文件夹

仅当问题规模较小且只涉及一个切片时，才使用 specs/<feature>.md。大型功能应放在以下结构中：

• specs/<feature>/README.md — 目标、背景、切片关系图、审查映射、契约、防火墙、已知未知项，以及一个“下一位 Agent 提示词”部分，其中包含当前状态、下一步接手点、全局 TODO 检查清单和交接说明。
• specs/<feature>/slices/<NN>-<name>.md — 每个文件包含一个可独立验证的切片。
• specs/<feature>/visualizations/*.html — 路线图图表、原型、测试框架样板、生成的报告、联系表或其他可供人工审查的制品。
• specs/<feature>/assets/ — 评估工作所需的参考图片、测试样例、采集内容和其他输入。

对于视觉工作，将功能专属的视觉证据保存在规范文件夹中：灵感图片、参考截图、归档基线、对比联系表、生成的候选截图和评审制品。如果这些文件最初位于规范文件夹之外，应在其成为该功能的审查依据时将其复制到规范文件夹中。产品快照文件夹仍可保存其测试框架所管理的当前回归基线，但不要只依赖这些可变输出或外部路径来记录该功能的评判依据。

切片文件约定

每个切片文件都要回答：

• 这个切片解锁了什么约定？
• API 接缝是什么：模块、函数/类型、数据形状、所有权？
• 人可以运行或看到什么？
• 用哪些测试、场景、截图、探测或性能门槛来验证？
• 如果切片会生成任何视觉图像（截图、GIF、联系表或屏幕渲染），切片文件必须指示实现 Agent 在接受切片前，将 screenshot-critique 作为最后一项检查来运行——这是回归门槛和实现者自己的检查无法提供的、未经预先引导的第二意见。必须将其写成切片中的明确验证步骤，而不是一笔带过。
• 如果切片的图像有比较目标——它要改变的既有视觉效果，或为该功能添加的参考/灵感图片——切片文件还必须指示 Agent 使用 compare-screenshots 来评判候选图像与目标：结合遥测信息给出更不偏离目标的判断，而不是检查图像是否与参考图一致。这也必须写成明确步骤。
• 对于带有参考图片的视觉切片，说明切片变量和用于评判它的裁剪/遮罩。还要列出明确不在范围内的可见问题。例如，草地密度切片只比较画面下三分之一的覆盖范围和渐变；悬崖形状、悬崖纹理、水、天空和雾属于后续切片。悬崖轮廓切片只比较山脊轮廓和深度层；岩石纹理和薄雾属于后续切片。
• 哪些决策交由实现者决定？明确列出有意留白的自由度（内部结构、命名、可逆的外观调整）。其他所有事项都必须在切片中确定：任何未列出的、需要实现者自行发明的决策，都是规格缺口，应记录到 choices ledger（audit-choices）中，而不是交由实现者自行决定。
• 哪些内容必须保持通过？
• 人的哪些反馈会改变这个切片？
• 如果切片设有人为审核检查点，切片文件必须将其表述为非阻塞：指示实现 Agent 使用 preview-shots 向用户打开图像，留出一段较短的回复时间（约 5 分钟）；如果用户没有回复，则依据证据作出决定，在规格中记录决定和理由，关闭已打开的图像（preview-shots 会清理 Preview，避免隔夜运行时窗口越积越多），然后继续。实现绝不能因等待批准而停滞；检查点是调整可逆决策的机会，而非阻止构建的关卡。

README 交接提示词

每份包含多个切片的规格 README 都需要在靠前位置设有“Next Agent Prompt”。请使用第二人称撰写，内容应是未来 Agent 恢复此功能工作时要阅读的提示词。README 不能只描述这是当前有效的交接状态；该章节本身必须直接告诉下一位 Agent 接下来该做什么。内容应包括：

• 当前状态和最后更新日期。
• 确切的下一步接手位置。
• 当前阻塞项或警告。
• 全局 TODO 清单，每一项都指向所属切片。
• 直接指示下一位 Agent 在结束本轮工作前更新此章节。

这样一来，新接手的 Agent 只需打开 README，就知道接下来该做什么，无须阅读聊天记录。

完成

只要新接手的 Agent 无需对话记录就能从切片 1 开始，且人无需逆向梳理大段文字就能审核路线图，功能计划就算完成。

所有切片都交付后，close-spec 会将计划归档到 specs/done/，并将其从构建阶梯改写为可长期保留的决策依据记录。