---
name: feature-doc-design
description: Use when 特性开发需要直接在产品仓库 docs/features 下写可评审的特性文档和邻近设计文档。
---

# 特性设计文档

> 前置：使用本 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 边界

```bash
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 不满足时必须阻塞并记录原因，不得手工模拟正常产物。