# Cs Feat Design Review

> Feature design review gate。触发：人审前审 design/checklist，或用户要求方案审查。

- Skill: `dafang/cs-feat-design-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dafang/cs-feat-design-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dafang/cs-feat-design-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dafang (https://skillmd.com/u/dafang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dafang/cs-feat-design-review

---


# cs-feat-design-review

## 启动必读

开始任何判断或动作前，先执行 CodeStable preflight：读 `.codestable/attention.md`；缺失先 `cs-onboard`；不读外部 AI 入口替代（详见 `.codestable/reference/execution-conventions.md`）。

本阶段是 feature design 交给用户人工确认前的方案审查 gate。它只读 design、checklist、相关文档和必要代码事实，只写 `{slug}-design-review.md`，不直接改 design/checklist、不替用户批准 design、不进入实现。

目标不是替用户做产品判断，而是确认这份 design 已经具备让用户有效 review 和让下游稳定执行的条件：需求边界可核对、名词层和编排层有代码事实支撑、steps 可独立验证、checks 能回到 design 证据、风险 / 基线 / 交付物 / 清洁度可被后续 implement、code review、QA 和 acceptance 消费。

> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。feature design 的具体结构以目标 `{slug}-design.md` / `{slug}-checklist.yaml` 和项目内共享口径为准。
> 报告语言：design-review 报告正文必须按 `.codestable/attention.md` 用**中文**；若草稿用了英文，落盘前先改写为中文。frontmatter / yaml 字段不翻译。

---

## 输入

进入 review 前必须读取：

- `.codestable/attention.md`
- `.codestable/features/{feature}/{slug}-design.md`
- `.codestable/features/{feature}/{slug}-checklist.yaml`
- 同目录的 `{slug}-intent.md` / `{slug}-brainstorm.md`（如果存在）
- design frontmatter 指向的 requirement 文档
- design frontmatter 指向的 roadmap 主文档和 items.yaml（如果有 `roadmap` / `roadmap_item`）
- design 第 4 节指向的 architecture 文档
- 相关 compound 沉淀：用项目搜索工具按 feature 关键词检索 decision / learning / explore / trick
- design 中引用到的关键代码位置、接口、类型、组件、命令、配置
- 独立 Task agent reviewer 输出（如果本轮已启动）

没有代码引用时不强行扫全仓库；但 design 声称复用、修改、挂载或约束某个现有模块时，必须读对应代码或文档事实核验。

---

## 启动检查

1. design 存在，frontmatter `doc_type=feature-design`，`feature` 与目录一致，`status` 通常是 `draft`；复审已 approved 设计时要确认用户确实要求重新审查。
2. checklist 存在，`feature` 与目录一致，`steps` 非空，`checks` 非空；缺 checklist 时报告 `blocked`，回 `cs-feat-design` 生成 review candidate checklist。
3. checklist 的 `steps.status` 和 `checks.status` 在人审前都应是 `pending`；已有 `done/passed` 说明阶段混乱，报告 `blocked`。
4. 从 roadmap 起头时，roadmap item 必须能在 items.yaml 中找到，design 的 `roadmap_item` 与 feature slug 对齐。
5. 如果已有 `{slug}-design-review.md`：
   - `status: passed` 且 design/checklist 未变化：提示可进入用户整体 review。
   - `status: changes-requested` / `blocked`：读取旧 findings，确认是否复审。
   - design/checklist 已变化：重新 review，并在报告里记录轮次。

---

## 独立 Task agent reviewer gate

本阶段必须优先启动独立 Task agent reviewer；当前 agent 的本地审查只能作为合并与事实核验，不能替代独立审查。只有运行时确实没有 Task agent 能力、provider 不可用且无法配置，或用户在看到降级风险后明确授权，才允许 `local-only` / `skipped-by-user`。批量 design、赶时间、主 agent 自认为风险低，都不是降级理由；需要授权降级时，先按 `.codestable/reference/approval-conventions.md` 写 `approval-report.md`，再让用户选择。

一旦本轮应该启动或已经启动独立 Task agent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 reviewer 返回前定稿 `{slug}-design-review.md`、不能给出 `passed`、不能把 design 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。

**检测由主 agent 在运行时自检自己的工具**，不靠脚本猜环境——主 agent 最清楚自己手上有哪些工具。按 Task agent 选择规则启动独立 Task agent reviewer（优先 Paseo subagent，否则当前宿主原生 Codex/Claude Task/Agent）：

1. **有 `mcp__paseo__create_agent` 工具**：必须优先用 Paseo subagent 做只读独立审查（首选：能换 provider，做到真正异构审查）。启动前先加载 / 读取 `paseo` skill 的当前说明，并遵守它的规则：读取 `~/.paseo/orchestration-preferences.json`，使用 `providers.audit`，不要硬编码 Claude 或 Codex。不要无限轮询运行中的 agent；如果 reviewer 已启动但结果未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。
2. **否则有当前宿主原生 Codex/Claude Task/Agent 工具**：用原生 Task agent 做独立上下文审查。如属同类 agent，在报告里记录降级和残余风险。
3. **两者都没有**：本地 review 只能在记录 `local-only` 且获得必要授权后定稿；没有授权时报告 `blocked`，不要伪装启动。

独立 Task agent reviewer prompt 必须只给原始材料和边界，不透露本地 review 结论：

```text
你是 CodeStable feature design 的独立方案审查 agent。只读，不修改文件，不更新 design/checklist。

请读取：
- .codestable/attention.md
- {design_path}
- {checklist_path}
- 同目录 intent / brainstorm（如有）
- 相关 roadmap / requirement / architecture / compound 文档
- design 引用到的关键代码、接口、类型、组件、命令入口

按 cs-feat-design-review 的严重度语义输出：blocking / important / nit / suggestion / learning / praise / residual-risk。
重点审查：需求边界、术语冲突、名词层现状→变化、module interface depth / seam / adapter、编排层流程、挂载点可卸载性、结构健康度、验收契约、steps 原子性、checks 来源、基线与验证命令、交付物、清洁度、roadmap 接口契约遵守情况。
每条 finding 必须有 design/checklist/doc/code 事实证据、影响、建议修复边界。
不要写 {slug}-design-review.md；只把审查结果回传给主 agent。
```

主 agent 仍是最终审查责任方：必须逐条核验独立 Task agent reviewer 的 finding，去重、定级、合并进 `{slug}-design-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。

---

## 审查流程

### 1. 范围与事实

- 用 design 第 0/1 节确认术语、需求摘要、明确不做、复杂度档位、关键决策。
- 用第 2.1 / 2.2 节确认名词层和编排层是否都有"现状 → 变化"，且现状指向真实代码 / 文档。
- 用第 2.3 节确认挂载点是否按"删掉 feature 是否消失"收紧。
- 用第 2.4 节和 checklist steps 对齐推进策略、退出信号和验证动作。
- 用第 2.5 节确认结构健康度评估覆盖文件级 + 目录级，微重构只做"只搬不改行为"。
- 用第 3/4 节确认验收契约、架构回写预判、证据类型。
- 从 roadmap 起头时，额外核对 roadmap 第 4 节接口契约是硬约束，design 没有私自绕开。

### 2. 独立审查合并

- 记录主 agent 自检结果：`paseo` / `native-agent` / `local-only`。
- 没有启动独立 Task agent reviewer 时，记录确无能力 / provider 不可用 / 用户授权降级；未满足这些条件时不得定稿 `passed`。
- 启动 Paseo subagent / 原生 Task agent 后，最终 verdict 必须等 reviewer 返回。
- reviewer 返回后逐条做本地事实核验；能用 design / checklist / 文档 / 代码证据支撑才合并。
- reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。

### 3. 方案审查

至少覆盖：

- 需求边界：用户目标、核心行为、成功标准、明确不做是否可核对。
- 术语与现状：关键术语是否与代码 / 架构 / 历史 feature 冲突；现状描述是否真实。
- 名词层：值对象、实体、接口、类型、组件 props/events 是否讲清变化。
- Module/interface 设计：interface 是否包含 caller 必须知道的 invariant / ordering / error mode；module 是否 deep；seam / adapter 是否真实需要；测试是否能通过 interface 观察行为。
- 编排层：主流程图、分支、错误语义、幂等、并发、可观测点是否能跑通。
- 挂载点：是否列了真实对外注册点，而不是内部改动文件清单。
- 结构健康度：微重构是否必要且边界安全；目录 convention 候选是否合理。
- 验收契约：正常 / 边界 / 错误路径是否覆盖，是否有证据类型。
- checklist：steps 是否独立可验证，exit_signal 是否 yes/no，checks 是否都能追溯到 design。
- 基线与验证：必跑命令、预检策略、基线红灯归因是否写清。
- 交付物与清洁度：acceptance 是否能从仓库事实核验；调试输出、TODO、死 import 等规则是否明确。

### 4. Feature Design Review Invariants 与证据分级

每轮 review 必须形成 Evidence Confidence Ledger。证据分级只描述依据来源，不计算质量分：

- `E` Embedded：design / checklist / roadmap item / 命令输出里直接可见。
- `C` Context：相关 req / arch / compound / 代码事实支撑。
- `H` Heuristic：工程经验或 reviewer 判断，缺少直接仓库证据。

核心 invariants：

- Acceptance Coverage Matrix 覆盖每个核心验收场景。
- 每个核心场景能追踪到 checklist step、证据类型和命令 / 动作。
- checklist steps 独立可验证，checks 能回到 design 来源。
- roadmap 起头的 design 没有绕开 roadmap 接口契约。
- DoD Contract 覆盖 Design / Implementation / Review / QA / Acceptance DoD、Validation Commands 和 Required Artifacts。
- Module/interface design 覆盖 depth、seam placement、dependency strategy；没有新增 / 改动 interface 时可标 not-applicable。
- checklist `dod.commands` 若存在，字段使用 `{id, command, core, failure_handling}`；design 表格只是人读投影。
- 核心检查若只有 `H` 证据，不能静默 `passed`；至少写入 residual risk，必要时列 important / blocking finding。

---

## 严重度

- `blocking`：必须先修。会导致 design 不能被用户有效 review、实现无稳定契约、roadmap 契约被绕开、steps/checks 无法执行、验收不可证伪、关键风险没有验证路径。
- `important`：应该修；若用户决定延后，必须在 design review 和用户 review 摘要中明确记录。
- `nit`：小的清晰度或一致性建议，不阻塞。
- `suggestion`：替代设计思路或补强建议，不要求本次采用。
- `learning`：知识性说明，不要求动作。
- `praise`：记录值得保留的设计做法；少量即可。
- `residual-risk`：review 无法完全消除的不确定性，需要用户 review、implementation、code review、QA 或 acceptance 重点复核。

不要把个人偏好的实现写法升级成 blocking。blocking 必须能用 design 契约、checklist、roadmap/req/arch、代码事实或可靠工程原则支撑。

---

## 报告模板

报告路径：`.codestable/features/{feature}/{slug}-design-review.md`。

```markdown
---
doc_type: feature-design-review
feature: {feature}
status: passed|changes-requested|blocked
reviewed: YYYY-MM-DD
round: 1
---

# {slug} feature design 审查报告

## 1. Scope And Inputs

- Design: {path}
- Checklist: {path}
- Intent / brainstorm: {path / none}
- Roadmap: {path / none}
- Related docs: {requirements / architecture / compound}
- Code facts checked: {paths / none}

### Independent Review

- Status: not-available|skipped-by-user|local-only|pending|completed|failed|blocked
- Detection: paseo|native-agent|local-only|skipped
- Provider / agent: {providers.audit / agent id / none}
- Raw output: {摘要 / 路径 / none}
- Merge policy: {已逐条核验 / 未启用原因 / pending 时不得定稿}
- Gate effect: {none | blocks final verdict until completed / user-approved downgrade}

## 2. Design Summary

- Goal: {摘要}
- Key contracts: {名词层 / 编排层摘要}
- Steps: {数量 + 风险热点}
- Checks: {数量 + 来源完整性}
- Baseline / validation: {摘要}

## 3. Findings

### blocking

- [ ] FDR-001 `{path#section|checklist.step|file:line}` {问题}
  - Evidence: {事实}
  - Impact: {为什么阻塞用户 review / implement}
  - Expected fix scope: {修复边界}

### important

- [ ] FDR-00N `{证据位置}` {问题}
  - Evidence: {事实}
  - Impact: {影响}

### nit

- [ ] FDR-00N `{证据位置}` {建议}

### suggestion

- [ ] FDR-00N {建议}

### learning

- {可复用设计经验或注意点}

### praise

- {值得保留的做法}

## 4. User Review Focus

- 用户需要重点拍板：{决策 / 假设 / 不做范围}
- implement 需要重点遵守：{契约 / steps / 验证}
- code review / QA / acceptance 需要重点复核：{风险 / 证据}

## 5. Evidence Confidence Ledger

| Check | Verdict | Evidence Class | Basis | Follow-up |
|---|---|---|---|---|
| Acceptance Coverage Matrix | pass|warn|fail | E|C|H | {路径 / 事实 / 判断依据} | {none / 复核点} |
| DoD Contract | pass|warn|fail | E|C|H | {依据} | {复核点} |
| Steps and checks traceability | pass|warn|fail | E|C|H | {依据} | {复核点} |
| Roadmap contract compliance | pass|warn|fail | E|C|H | {依据} | {复核点} |
| Module interface design | pass|warn|fail|n/a | E|C|H | {依据} | {复核点} |
| Validation and artifacts | pass|warn|fail | E|C|H | {依据} | {复核点} |

Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。

## 6. Residual Risk

- {风险 + 下游如何处理；没有写 none}

## 7. Verdict

- Status: passed|changes-requested|blocked
- Next: 交给用户整体 review | 回 `cs-feat-design` 修订后重跑 `cs-feat-design-review` | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑
```

没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。

---

## 退出条件

- [ ] 已读取 attention、design、checklist、相关 intent / brainstorm / roadmap / req / arch / compound。
- [ ] 已按 design 声明核验必要代码、接口、类型、组件或命令事实。
- [ ] 已确认 checklist 可解析，steps/checks 都可追溯。
- [ ] 已按 Task agent 选择规则启动独立 reviewer；若未启动，已记录确无能力 / provider 不可用 / 用户授权降级。
- [ ] 如果启动了独立 Task agent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。
- [ ] 已审查需求边界、术语、名词层、编排层、挂载点、结构健康度、验收契约、steps/checks、基线、交付物、清洁度。
- [ ] 已检查 Acceptance Coverage Matrix、Feature Design Review Invariants 和 Evidence Confidence Ledger。
- [ ] 核心检查 H-only 时没有静默 passed。
- [ ] 已写 `.codestable/features/{feature}/{slug}-design-review.md`。
- [ ] 有 blocking / 未处理 important 时指向 `cs-feat-design` 修订并重跑 review。
- [ ] 无 blocking 且 important 已处理或明确接受时，明确告诉用户下一步是 feature design 人工 review。

---

## 容易踩的坑

- 把 design review 做成文案润色，没审 steps/checks 是否能执行。
- 只读 design，不核对 checklist 来源。
- roadmap 起头时不检查接口契约，导致 feature 偷偷绕开 roadmap。
- 现状段没读代码就放过，implement 阶段才发现设计站不住。
- steps 出现"和 / 以及 / 同时"却不复查是否该拆。
- 把批量 design 或赶时间当成 local-only 降级理由。
- 启动独立 Task agent reviewer 后结果还没回来，就把本地 review 定稿为 passed。
- 外部 reviewer 的结论没经本地事实核验就照抄。
- review 报告没有落盘，导致用户 review 和后续实现没有可追溯输入。