upfront-design

前期设计

路由与持久化

设计文档包含请求/状态 frontmatter 和 # Design: 标题。 新请求 → 设计；草稿 → 首个缺失章节；已批准 → 检查下一个 未完成的里程碑；其他状态 → BLOCKED。命名修订阶段仅在用户授权后才会移除 后续章节。

解析此技能的绝对锚点。将新设计文档存储在 <anchor>/designs/<basename>-<slug>-<YYYY-MM-DD-HHmmss>.md，放在仓库之外。 <basename> 是第一个仓库的根目录名称。 路径存在后，在推进前，通过同级临时文件和原子重命名持久化已批准阶段及台账。 记录 request | size | design | phase | approvals | ADR offers | terminal。 在 AWAITING_USER 状态下，将台账保存在 <design>.ledger；其他终态则移除台账。

小型工作意味着仅涉及一个模块、不更改契约/数据/公开签名，且结果可用一句话描述。无需文件或台账，直接返回 DIRECT 和该句描述。 否则，查找 ADR 目录（docs/adr/、adr/、doc/adr/、docs/decisions/）； 未找到时不提示。使用 references/design.md 创建文档。 当路由、规模、路径/frontmatter 和相关 ADR 均已确定时，即为完成。

设计阶段

每个阶段结束后暂停并进入 AWAITING_USER；在开始下一阶段前写入已批准的内容。从首个缺失或明确要求修订的阶段继续。

1. 产品： 明确具体痛点、可衡量的成功标准、一句话加粗解决方案；对于面向用户的工作，提供用户给出的样稿，或草拟文本线框图/状态表；以及交付段落。将所有待确认问题汇总成一轮编号提问，并为每个问题推荐一个答案。内容经批准并持久化后即为完成。
2. 系统： 加粗描述架构形态并引用模式；说明新增/变更层的职责、来源和带有成本理由的约束，以及按阶段划分的执行顺序。指出 ADR 冲突，不得覆盖 ADR。内容经批准并持久化后即为完成。
3. 程序： 说明变更边界的契约、约束、实际签名、用法和职责，不写函数体。引用模式或假设；比较两种不确定的布局，选择一种并说明另一种为何未被采用。 对于多个边界、分发变更或不明确的异步顺序， 使用 references/design.md 中的 Wiring 视图。 当每项成功标准都映射到符号/结果，且批准已持久化后，即为完成。
4. 切片： 在预重构之后，从一个端到端的精简契约/检查开始。每个里程碑对应一个便于审查的纵向 PR；列出符号、预期成功结果和相关失败情况、断言/手动验证、仓库顺序，以及一个未勾选项。只有用户可以推迟/跳过；宽泛重构应先扩展再收敛。所有符号均已分配，且已批准的里程碑已持久化后，即为完成。
5. 最终定稿： 设置为已批准。仅当决策难以撤销、缺乏上下文时出人意料，且是从真实备选方案中选出时，才提出 ADR。批准后使用 references/decisions.md。当文档的五个章节都已存在，且每项 ADR 提议均已记录或拒绝时，以 DESIGNED 状态完成。报告设计/ADR 路径、同级审查及里程碑检查流程。

检查

对于已批准的设计，按照 references/check.md 检查第一个未完成、未推迟且未跳过的里程碑。展示准确命令，并在运行前获得批准。只有提供结果证明且符号匹配时才勾选，不得仅凭命令成功退出。未完成的手动检查项或含糊不清的旧版结果都必须暂停处理。绝不编辑产品文件来让检查通过。勾选了检查项或所有检查均已完成时，以 CHECKED 状态完成；否则为 AWAITING_USER。

终态：DIRECT（路由器空操作成功）、AWAITING_USER、DESIGNED、CHECKED、BLOCKED。通过草稿状态和命名阶段进行修订。