design-feature

设计功能

产品定义——在任何工程规划开始之前，将想法或功能请求转化为一套详尽、可检查的验收标准。仅限文档——不写代码，不建分支。

回合约定

每回合结束前，加载并验证规范的回合约定（11 个框）。设计专属的收尾框（产品部分、能力/角色矩阵、预期检查、更新）仅见于INTERVIEW.md。缺少参考文档 → 停止。

适用场景

• 有一个粗略想法，尚无 issue，也没有 SPEC：design-feature "<idea>"。
• 已有功能 slug，但其 SPEC 尚未标记为 designed： design-feature <NN-slug>。
• 修改已完成设计的功能定义： design-feature <NN-slug> "<change>"（指令模式），或直接运行 design-feature <NN-slug> 进入审查模式（参见交互与更新）。
• 当 plan-feature 检测到功能尚未设计，或 review-spec 返回 NEEDS-DESIGN 判定并将产品选择交还给用户时，会重定向到此处。

步骤 0 — 了解项目（始终首先执行）

按照 Agent 指南的工作流约定和文档地图，然后阅读此技能所需的内容：docs/features/_TEMPLATE/SPEC.md（两部分布局和 ## Design status 标记）、路线图（docs/features/ROADMAP.md）、能力清单（docs/CAPABILITIES.md——Integration 收尾流程所依据的基础；如果项目没有该文件，则在步骤 5 中根据架构文档和代码库整理临时清单，并提出按照模板创建该文件），以及——如果此 slug 已有文件夹——完整阅读其中现有的 SPEC.md 和 decisions.md（更新绝不盲目开始）。只需浏览与该想法相关领域的架构和领域文档，了解项目中的实际实体和角色，以便完成能力梳理；深入工程研究属于工程部分的工作，不在此处进行。

使用内部的 evidence-grounding 能力，按照顺序执行各阶段并进行就绪预检：清单 → 证据 → 草稿 → 精简 → 就绪。其结果（READY-FOR-REVIEW | NEEDS-EVIDENCE | NEEDS-DESIGN | NEEDS-REPLAN）是撰写门槛，而非批准：只有 review-spec 才能批准产品部分。

研究门槛（强制，失败时默认拒绝）

在输出 Product 部分之前，先在证据阶段（有序流程的第 2 步）通过研究门槛：

• 获取该领域的资料 — 获取该能力领域的至少两个外部来源（通过 fetch/WebFetch/浏览器）：了解该领域如何定义和实现这项能力。仅凭仓库证据不足以为设计提供依据；此门槛旨在消除仅依据仓库现有认知进行设计的偏差。每个获取的来源都要成为一条证据记录（URL 和访问日期）。
• 覆盖完整定义 — 证据记录必须说明该能力是什么，以及不是什么，并说明用户对它的预期——可接受和不可接受的输入、边界、语义，而不能只描述项目当前对它的理解。
• 分解每项明确提出的预期 — 在确定 Product 部分之前，将用户明确提出的每项预期展开为它隐含的案例分解：有效值和无效值及其限制、交互状态、降级模式、后端验证／过滤／解析、其他用户路径。典型案例：“电话号码输入”不是一个字段，而是一整组案例向量（一行需求隐藏了前缀／后缀、长度、拒绝非文本输入、焦点、无 JS／有 JS 时的行为、后端过滤／验证／解析等情形）。
• 失败时默认拒绝 — 离线，或获取的资料未能回答实质性问题时，返回 NEEDS-EVIDENCE，并注明负责人和下一项要获取的资料：绝不猜测，绝不编造引用。
• 先研究，再编码 — 在测试创建之前，先根据权威文档核实测试将编码的平台语义（这是 verification-contract 不可变测试契约的预防部分）。

渐进式加载——先确认状态，再了解产品详情

参考资料的允许列表仅限下方链接中的路径。绝不编造或读取其他 references/ 路径；DEFER 列中的裸文件名与这些链接位于同一目录。

**未完成原始想法访谈时必须立即停止：**只加载 references/INTERVIEW.md，不加载其他参考资料。提出其中规定的下一个问题，返回 NEEDS_INPUT，并结束本轮。所有必填访谈项解决之前，禁止加载 WRITE_AND_UPSERT.md；之后由该资源负责结束记录和编写。

当前条件	现在加载	现在延后／跳过
仅有现存 slug，没有指令	按交互规则加载访谈；报告状态并停止	WRITE_AND_UPSERT.md、UPSERT_EXAMPLE.md、REPAIR.md、PORTABILITY.md
全新想法，且有任一必填访谈项尚未解决	仅加载访谈；只提出下一个问题，然后停止	WRITE_AND_UPSERT.md、UPSERT_EXAMPLE.md、REPAIR.md、PORTABILITY.md
全新想法，所有必填访谈项均已解决	加载访谈，然后加载结束、编写和更新	除非结构不明确，否则跳过 UPSERT_EXAMPLE.md；跳过 REPAIR.md、PORTABILITY.md
现存 slug 加指令	访谈，然后结束／编写／更新	除非结构不明确，否则跳过更新示例；跳过 REPAIR.md、PORTABILITY.md
现存 slug 的 progress.md 标有 SPEC-REVIEW-FAIL 或 NEEDS-DESIGN	加载访谈，然后加载评审修复	UPSERT_EXAMPLE.md、PORTABILITY.md
缺少某个具名平台原语	加载上方选定行中的内容，再加载可移植性	仅跳过无关行

访谈项尚未解决时，不要加载编写／更新资料。支持某个平台原语，不代表仅仅因为当前任务未使用它，该原语就不存在。

所有资源都只需从本文跳转一次即可访问。结束记录、角色矩阵、预期计数、固定状态块和 Spec-lint 均为规范性要求。缺少必需资源或必填项尚未解决时，返回 NEEDS_INPUT；绝不猜测。

护栏

• 无审核权限。 此技能负责编写和修复 Product 部分；绝不批准该部分。## Design status: designed 和就绪状态行 READY-FOR-REVIEW 都不是审核结论：审核结论由 review-spec 作出，且审核时所处的上下文并未写入这些字节。绝不要写入或“同步”PreExecutionReviewReceipt——审核者会自行持久化该记录。
• 每次写入都轮换修订版本。 每次写入 Product 部分都必须使用新的 artifactRevisionId，即使是恢复到先前发布的字节也一样；交接时也必须附带该 ID。跳过轮换会让过期的 PASS 重新生效。
• 仅限文档——不写代码、不建分支（这些属于 execute-phase），不编写工程内容（架构、设计、阶段、测试——属于 plan-feature 的 Engineering 部分；即使答案看似显而易见，也不要预先填入）。
• 如果 Capability closure 行为空、跳过了清单中的子系统、角色矩阵不完整，或 Expectation sweep 行尚未解决，绝不要标记 ## Design status: designed——跳过任何一行都会悄然抹去此技能的全部意义。
• Expectation sweep 枚举的是领域惯例，不是新增范围：每项预期只能归类为范围内、范围外或延期——绝不能在用户确认前悄然扩大功能范围。
• 不进行市场或竞争研究——上文规定的强制研究关卡是此技能唯一的外部研究；不进行全局 skill/MCP 发现扫描（这是 product-audit 的工作）；不使用 --update 标志——upsert 始终是默认行为，而非可选项。
• 不要单独创建 DESIGN.md——始终使用一份 SPEC，分为两个部分。
• 组合层级。 此技能属于规划类（判断工作——应使用最强模型／最高推理力度运行）。只有在运行层级不低于此技能时，plan-feature-from-issue 才允许在同一轮中组合此技能来处理内容单薄的问题；否则必须交接（运行 /design-feature <slug>），而不是降低其能力。
• 其他情况遵循项目的 Workflow conventions（docs-language）。

规范化仓库状态

从 docs/workflow/REPOSITORY_STATE.md 中读取冻结的事实和决策。缺失的事实可以检查；发生冲突时则构成待解决的矛盾。文档和推断都不是实现证据。

架构不变量

在定义能力之前，查找文档映射中声明的可选项目不变量文档（通常为 docs/architecture/ARCHITECTURAL_INVARIANTS.md）。如果不存在，在 SPEC 中记录 n/a: no project invariants declared 并继续。对于每条适用规则，引用其 ID 和仓库证据，并将提案归类为 preserves、violates、introduces 或 changes。只有 preserves 才能继续进行能力闭合。违反规则、新增规则或更改规则都会中止设计，等待项目声明的权威方作出明确的架构决策；绝不能通过 SPEC、实现计划或测试追溯性地为其授权。存在 NRS 时，先读取其中冻结的事实；仓库仍是权威依据，发生冲突时应交由解决流程处理。

可移植性

在受支持的平台上，不要读取 portability。只有检测到某个具名交互原语不可用后，才读取该文件。访谈、闭合、upsert 和固定输出契约保持不变。

与其他技能的关系

• review-spec 是本技能移交的关卡：设计完成的部分会先接受独立评审，然后 plan-feature 才能使用。没有当前的评审回执，plan-feature 就会拒绝继续，因此在此处移交——而不是移交给 plan-feature——才能确保流程严谨。
• 当功能的产品部分未标记为 designed 或没有当前评审时，plan-feature 会重定向到此处（没有绕过标志）；review-spec 通过后，plan-feature 会填写工程部分并搭建相关工件。
• 对于信息不足的问题，plan-feature-from-issue 可以在本轮中组合使用本技能（仅限 ≥ tier——参见 护栏），也可以直接移交给本技能。它会止步于产品部分和 review-spec——不再在同一轮中继续进行工程规划。
• evidence-grounding 负责本技能使用的检查流程和就绪状态术语；它也不会给出评审结论。
• triage-issue 的 promote-to-feature 结论会转交给 plan-feature；如果提升的问题仍未设计，plan-feature 会重定向到此处。
• execute-phase 从不调用本技能——它只执行已完成规划的 SPEC 中的工程部分。

完成条件

• SPEC 的产品部分已填写完毕，且每一行能力闭环都已解决（填写界面或明确标记为 n/a）。

• ## Design status 准确反映结果（仅当闭环完成时才标记为 designed）。

• 路线图中已有对应条目（如果这是全新功能，则以 idea 创建），且其状态与结果一致——当状态为 designed 时标记为 defined；若为 NEEDS_INPUT，则保持为 idea。

• 已运行就绪预检，并返回 READY-FOR-REVIEW；否则，本轮以其确切的阻塞结果结束。

• 移交内容注明当前的 artifactRevisionId。

• 已打印收尾的 → Next: 区块：

  → Next: /review-spec <slug> — product half designed and readiness-clean; it needs an
      independent review before any engineering planning
    · more to design → re-run /design-feature <slug> "<instruction>" (upsert, destroys nothing,
      rotates the artifact revision)
    · recurring gap in this project's capability closure → /product-audit (a systemic pattern,
      not a one-off design fix)
  

  若以 NEEDS_INPUT 结束，则使用：

  → Next: answer the pending question, then re-run /design-feature <slug>
    · unsure how to scope it → propose the smallest version and confirm
  

  若就绪状态返回 NEEDS-EVIDENCE 或 NEEDS-REPLAN，则使用：

  → Next: /design-feature <slug> "<the missing evidence>" — readiness returned
      NEEDS-EVIDENCE for <rows>; do not invoke /review-spec on an artifact that is
      not readiness-clean
    · the gap is engineering, not product → it belongs to plan-feature's evidence, not here