Feature Doc Design

特性设计文档

前置：使用本 Skill 前，先按 using-nucleus 完成 Nucleus 入口识别（Claude Code 会话由插件 SessionStart hook 自动注入该纪律）。

核心原则

特性设计先服务产品能力表达，再服务实现计划；设计未被人工评审接受前，不得进入计划、代码或测试。

<HARD-GATE>
未读取当前特性输入、需求设计 / 特性拆解证据和目标 `docs/features/**` 结构，或设计未获得人工评审事实时，不得写实施计划、源码、测试或正式交付证据。

请求人工设计评审前，必须先按 _shared/references/subagent-precheck-protocol.md 执行 subagentPreReview 子代理预审；未取得“材料可提交人工审查”结论时，不得请求人工接受设计。 </HARD-GATE>

什么时候使用

使用本 Skill：特性开发中本 Skill 是每个特性的第一个领域步骤，把当前特性收口为产品仓库里可评审的特性文档和邻近设计文档；必须用当前产品既有 docs/features/** 结构和邻近设计约定作为目标形态，让设计成为可评审 Git diff。

不要使用本 Skill：自创临时特性设计格式或把实现计划混入特性设计产物；写需求设计、源码、测试、提交、推送、PR、发布或缺陷状态变更；在设计获人工评审接受前生成实施计划、源码、测试或正式交付证据。

Checklist

启动本 Skill 后，必须先为每一项创建宿主 todo/task，并按顺序逐项推进、逐项更新状态；Codex 使用计划 / 任务工具，Claude Code 使用 TodoWrite 或等价宿主 todo。.nucleus/runs/**、summary.md、result.json、候选文件和 review report 只能记录事实，不能替代宿主任务、预审或人工设计评审事实。

1. 读取 context 和当前特性输入 完成证据：已读 .nucleus/context/<workflowRunId>.json，并确认恰好一个已存在的 primary docs/features/**/feature.md，或一个 schema 合法、带 candidateFeaturePath 的 mapping candidate。 STOP：primary 特性歧义、缺输入、受保护写入、legacy 路径、路径逃逸或 schema 失败时 FAILED_BLOCKED；缺当前特性输入时 ALERT_AND_BLOCK。

2. 读取目标产品既有 docs/features/** 结构和邻近设计约定 完成证据：当前特性的目标放置路径与邻近设计文档约定记录。 STOP：缺目标 docs/features/** 放置证据时 ALERT_AND_BLOCK，不得自创临时特性设计格式。

3. 读取需求设计 / 特性拆解证据 完成证据：相关需求设计与 requirement-decomposition 拆解证据引用。 STOP：特性开发调用时缺需求设计或特性拆解输入时 ALERT_AND_BLOCK。

4. 创建宿主特性设计任务包 完成证据：覆盖本 Checklist 各项的宿主 todo/task。 STOP：未建宿主任务包时，不得写 docs/features/** 或调度预审。

5. 写可评审特性文档到 docs/features/** 完成证据：已读取 _shared/references/design-visualization-discipline.md，按当前特性输入判断是否需要 Mermaid 图示；复杂设计使用合适图示说明业务流、数据流、状态、实体关系或跨系统时序，简单设计明确不需要图示；只读 candidateFeaturePath 时创建目标 feature.md 和同叶子设计文档；写出可评审 docs/features 变更后状态为待评审。 STOP：任何请求在设计评审前生成实施计划或代码时 ALERT_AND_BLOCK；不得把 feature design 和 implementation plan 写进同一候选产物。

6. 按共享协议执行人审前预审 完成证据：独立 reviewer 子代理 subagentPreReview 输出“材料可提交人工审查”，blocking / important 已整改复核。 STOP：按 _shared/references/subagent-precheck-protocol.md 执行预审；未取得材料可提交人工审查结论前不得请求人工评审。

7. 请求人工设计评审 完成证据：人工评审或明确 PMS 评审事实接受设计。 STOP：向人请求设计评审前必须已有 subagentPreReview 且材料可提交人工审查；按 _shared/references/interaction-format.md 的确认型格式呈现；评审接受前不得写实施计划、源码、测试或正式交付证据。

8. 写 result package 完成证据：写出可评审 docs/features 变更后返回 NEEDS_HUMAN_REVIEW。 STOP：.ac manifest / summary / result 只记录过程事实，不得代替人工设计评审事实。

产物与证据边界

可评审产品文档只写到 docs/features/**；过程证据、gate、manifest、blocker、result 只写到 .nucleus/runs/<workflowRunId>/。本 Skill 不写 docs/requirement/**、源码、测试、提交、推送、PR、发布或缺陷状态变更。写出可评审变更时返回 NEEDS_HUMAN_REVIEW；primary 特性歧义、缺输入、受保护写入、legacy 路径、路径逃逸或 schema 失败时返回 FAILED_BLOCKED。

禁止

• 用临时文档格式替代当前产品 docs/features/** 既有结构。
• 把 feature design 和 implementation plan 写在同一个候选产物里。
• 用 .ac manifest、summary 或 result 代替人工设计评审事实。
• 为了补齐格式堆砌 Mermaid 图，或在复杂设计中缺少能帮助审查业务流、数据流、状态、实体关系或跨系统时序的图示说明。

红旗

• 未读 context、当前特性输入或目标 docs/features/** 结构就写设计。
• 设计未获人工评审接受，就生成实施计划、源码或测试。
• 把实现计划混入特性设计产物，或自创临时设计格式。
• 跳过子代理预审直接请求人工评审；或把 review report、manifest、summary.md、result.json 写成人工已接受。
• Mermaid 图示没有明确审查问题和实现 / 测试 / 风险约束，或图示与正文事实不一致。

Runtime 边界

python3 skills/feature-doc-design/scripts/feature_doc_design.py design \
  --repo-root <target-repo> \
  --context <target-repo>/.nucleus/context/<workflowRunId>.json

runtime 只引用打包 Skill 资产和 skills/_shared/nucleus_runtime/，不引用 root harness/ 或 root scripts/。脚本失败、依赖缺失或 context 不满足时必须阻塞并记录原因，不得手工模拟正常产物。