---
name: project-sdd-planning
description: |
  在 PRD 基础上产出 Solution Design Document（SDD），采用 MVCP 四件套（Model/View/Controller/Process）形成
  可执行的实施边界与约束合同。
tags:
  - planning
  - sdd
  - mvcp
  - architecture
  - code-agent
version: 1.2.0
metadata:
  hermes:
    tags: [planning, sdd, mvcp, code-agent, architecture]
---

# SKILL：project-sdd-planning

## 一、先说结论：你说的 SDD 我同意

SDD（Solution Design Document）在本技能里定义为：

- **基于 BRD 与已评审 PRD 的“可执行设计合同”**；
- 它不是“灵感稿”，而是能直接驱动实现与测试的约束集；
- 交付物默认以 **MVCP（Model/View/Controller/Process）** 四块来组织。

你的理解与本技能完全一致：

1. M（Model）：数据结构/状态/约束；
2. V（View）：界面/交互/字段校验与权限可见性；
3. C（Controller）：接口、操作流、幂等与错误码；
4. P（Process）：流程状态机、定时/异步、补偿与回滚。

## 二、要追溯的外部方法论（在线参考）

在编写本技能时借鉴了三类成熟方法论：

- **arc42**：将文档按目标、上下文、结构、运行视图、部署等拆解，强调约束和运行时语义。
  - 参考：`https://r.jina.ai/http://arc42.org/overview/`
- **C4**：用上下文/容器/组件层次统一架构视图，帮助边界定义与依赖可读性。
  - 参考：`https://r.jina.ai/http://c4model.com/`
- **UML/REST/API 设计实践**：用于结构图（语义图）和资源接口约束表达。
  - 参考：`https://r.jina.ai/http://www.uml.org/what-is-uml.htm`（建模思路）
  - 参考：`https://r.jina.ai/http://restfulapi.net/resource-naming/`（资源接口约定）

> 注：网络访问在当前环境有波动，以上地址采用镜像可读源，若失效请手工替换为团队内部知识库同义来源。

## 三、SDD 目标与触发条件

### 适用场景
- PRD 已通过对齐且可执行；
- 需要把“产品要求”转为“工程约束”；
- 下游出现“每个开发者理解不一致/接口先后定义不一致/测试边界不清”的频发问题；
- 需要自动化拆分 Development Unit。

### 不适用场景
- 仅做战略、市场文档输出，不含实施细节；
- 研发能力未稳定，需求仍在频繁试错（此时先 PRD/实验设计）。

## 四、输入清单（必须齐备）

1. PRD 主干（至少包含功能/流程/界面）；
2. 领域对象列表（实体名、术语表）；
3. 现有系统边界：已有服务、数据库、权限系统、队列、对象存储、第三方 SDK；
4. 非功能目标（P95 延迟、可用性、合规）；
5. 既有数据迁移和发布约束；
6. 关键验收目标（业务指标 + 风险边界）。

## 五、产出物（强制）

每份 SDD 必须同时输出以下 4 类核心章节（文件化建议）：

1. `01-M-模型设计.md`
2. `02-V-界面与交互.md`
3. `03-C-控制与接口.md`
4. `04-P-流程与状态流转.md`

并附带 2 类执行文件：

5. `05-实施约束与依赖.md`
6. `06-验收与测试锚点.md`

其中 5/6 是为 Code Agent 提供“可执行边界”；没有这两项则不进入代码开发。

## 六、MVCP 产出模板（最小字段，禁止空口号）

### 6.1 M：模型（Model）——数据库 + 业务状态定义

每个实体必须写：

- 实体名（中文名/英文名）；
- 目的（为何必须存在）；
- 字段列表（类型、约束、默认值、是否可空、是否唯一/索引）；
- 生命周期与状态集合（若有）；
- 关联关系（1-N、N-N、聚合边界）；
- 并发与幂等策略（唯一键、乐观锁、事务边界）；
- 迁移与回滚约束（上线顺序、兼容性）。

最低输出格式（建议）：

- `entity`: `users`
- `pk`: `id`
- `fields`:
  - `id` bigint pk
  - `tenant_id` bigint not null fk
  - `name` varchar(50) not null
- `indexes`: [tenant_id, user_name]
- `unique`: [tenant_id + external_id]
- `state_machine`: [DRAFT, ACTIVE, FROZEN, DELETED]
- `rules`: [同 tenant 下同名用户禁止]

### 6.2 V：视图（View）——界面、组件、字段和可见性

每个界面必须写：

- 页面 ID 与路由；
- 权限矩阵（角色 × 字段可见性）；
- 输入项（字段名、类型、校验、必填、错误信息）；
- 提交流程（提交前校验、确认态、成功/失败反馈）；
- 异常态（空态、错误态、无权限态）；
- 交互事件对 C/P 的映射。

输出要求：

- “前端字段集合”必须在 C 和 M 中有明确对应关系；
- 所有按钮事件必须映射到唯一 Controller 动作；
- 每个视图必须标注“无可执行变化时可回归条件”。

### 6.3 C：控制（Controller）——接口与操作

每个接口必须写：

- `operation_id`；
- `method + path`；
- `auth`：会话/签名/角色；
- `input_contract`（示例：类型、必填、范围、正则）；
- `output_contract`（成功/失败字段）；
- `errors`（可重试/不可重试）；
- `idempotent`；
- `transaction`；
- `side_effects`；
- `audit_trace`（trace_id、actor、business_id）；
- `owner_team`。

### 6.4 P：流程（Process）——状态机与异步

每个流程必须写：

- 初始态、终态；
- 状态转移与触发器；
- 条件守卫（guard）与失败回退；
- 并发控制（串行/乐观锁/队列）
- 超时、重试、重试上限、补偿策略；
- 人工干预点（工单/客服）。

输出要求：

- 每条转移都能追溯到一个 controller/action 或 scheduler/事件；
- 每个异常路径必须有错误码 + 对应界面反馈。

## 七、Code Agents 自动化执行规范（核心）

目标：让 Code Agent 直接接收一份“可执行约束包”开始开发。

### 7.1 约束包最小格式（建议交付，供工具解析）

必须从 SDD 生成 `sdd-mvcp-contract.json`，字段示意：

- `meta`: `project, version, owner, effective_date`
- `assumptions`: 待验证假设
- `facts`: 已确认事实
- `model_contract`: 实体数组（含字段和索引）
- `view_contract`: 页面数组（含字段、权限、事件）
- `controller_contract`: 接口数组（含入参、出参、错误码）
- `process_contract`: 流程数组（含状态机）
- `non_goals`: 不做列表
- `risks`: 风险项
- `acceptance_matrix`: 需求→模型/视图/控制/流程的映射矩阵

Code Agent 开发前必须先完成：

1. 逐项核对 `non_goals`；
2. 对齐每个 `controller_contract` 与 `model/view/process` 的依赖；
3. 将 `acceptance_matrix` 转成开发 Unit；
4. 任何缺字段、无 owner、无错误码字段都不得进入 coding。

### 7.2 Code Agent 单任务输入模板

每个 Development Unit 的约束输入只包含：

- 相关实体（M）；
- 相关页面（V）；
- 相关接口（C）；
- 相关状态流（P）；
- 验收标准列表（最小 3 条：happy path、边界、异常）。

### 7.3 代码约束映射到测试

对每个 C / P 条目必须至少有一条自动化验证：

- 接口合约测试（入参/出参、错误码）；
- 数据约束测试（唯一约束、外键约束、事务一致性）；
- 流程测试（状态转移与幂等）；
- 视图端到端核验（按钮→接口→结果态）。

## 八、反模式门禁（未通过则退回）

以下项出现之一即阻断交付：

1. M、V、C、P 有一部分缺失；
2. 有“空目标”条目（不写字段/接口/状态只写大段描述）；
3. C 侧无法映射到 M 或 V；
4. P 侧转移缺少失败态或超时态；
5. 无 “验收矩阵”与“非目标列表”；
6. 无迁移/回滚条件。

## 九、分解与交付映射（SDD→Unit）

默认拆分规则：

- M 大改动可单独形成数据迁移/模型实现 Unit；
- V 与 C 一起形成“前后端联动 Unit”；
- P 单独形成“流程与调度 Unit”；
- 每个 Unit 都有 `depends_on` 和 `deliverable_contract`。

## 十、验收标准（可观察）

SDD 达成条件：

1. 四块内容齐备且互相引用无缺口；
2. 所有实体/接口/流程都有唯一 ID；
3. `acceptance_matrix` 覆盖 PRD 全量需求；
4. 每个接口至少包含成功 + 典型失败 + 并发失败场景；
5. 每个流程至少有超时/重试/回滚条件；
6. Code Agent 约束包可被下游消费（不依赖自然语言推断）；
7. 若本任务的验收依赖另一任务/流程已经产出的真实数据（而非本任务自己创建的数据），Benchmark 必须点名一个真实存在的具体对象作为验收锚点，不能只描述“机制应该正确”（真实教训 2026-08-06：Skill 内容迁移与详情页展示分属两个任务，谁都没被要求验证“真实迁移的内容能否被真实查到”，这条数据链路因此从未被真正接通过）。

## 十一、质量门禁（给自审与下一轮）

- 事实/决策/假设分离：
  - 已有事实：来自 BRD/PRD/仓库/历史问题。
  - 设计决策：基于约束与代价权衡。
  - 假设：必须标注 owner + 验证计划。 
- 任何假设不得进入“代码不可选条件”；若未在验证后确认，保留为阻塞。 
- 仅在约束包完整后，才输出 Development Unit；否则回退到 PRD 对齐。

---

## 十二、生成器模板版本（推荐默认流程）

为避免“手工重复填充”，新增生成器模板版本，支持在 PRD 落库后批量生成 SDD 骨架：

- 目标输入：PRD 目录、项目名、版本、owner。
- 输出产物：`01~06` 章节骨架 + `00-SDD-生成记录.md` + `sdd-mvcp-contract.json` + （默认）`sdd_exec_graph_manifest.json` + `sdd-graph.mmd` + `sdd-graph.runbook.json` + `unit_matrix.json` + `handoff_bundle.md`。
  - 启用 `--disable-graph` 时，不输出执行图相关产物（manifest/mmd/runbook/unit_matrix/handoff）。

### 12.1 一键生成（半自动）

```bash
python3 scripts/sdd_mvcp_generator.py \
  --project-name "<project_name>" \
  --version "v1.0.0" \
  --owner "<owner>" \
  --prd-root "/path/to/PRD" \
  --out "./SDD" \
  [--requirements-json "/path/to/requirements.json"] \
  [--manifest "/path/to/manifest.json"] \
  [--agent-pool "agent-1,agent-2,agent-3"] \
  [--graph-parallel-threshold 3] \
  [--graph-loop-round 2] \
  [--disable-graph]
```

生成器默认行为（1 条）：

1. 自动生成骨架：`00~06` + `sdd-mvcp-contract.json`。
2. 默认自动构建执行图（可通过 `--disable-graph` 关闭）；默认产物：
   - `sdd_exec_graph_manifest.json`
   - `sdd-graph.mmd`
   - `sdd-graph.runbook.json`
3. 并行策略：默认优先依据 **PRD 文本语义规则 + 规模阈值**（而非单一规模阈值）；显式传入 `--manifest` 时，规则不参与。
4. 回灌策略：`q_gate` 的失败触发 `max_loop_round` 回灌（默认 2 轮）。

### 12.2 PRD 文本语义推导 manifest 默认规则

> 规则用于“无显式 manifest”时，作为 `build_workflow_manifest` 的默认输入；显式 manifest 一律顶层覆盖。

规则输入源（只读）：`prd-root` 下的 `.md/.markdown/.txt` 文本。规则命中集合为 `derived_rules` 写入 manifest meta，用于追溯。

默认推导规则：

- `enable_mv_parallel`（并行）：
  - 条件1：`requirements_count >= graph_parallel_threshold`；
  - 条件2：未触发高风险阻断关键字。
- `strict_contract_mode`（高风险阻断）：命中文本中的任一词时，默认收紧并行，
  - `支付、财务、对账、扣费、结算、退款、税、风控、权限、审计、合规、资金、并发`
  - 在该模式下：
    - `M`/`V` 并行标记下降为 `False`
    - `C` 依赖 `P`（`c_depends_on_process=True`）
    - `P` 额外依赖 `V`（`p_depends_on_view=True`）
- `flow_boundary`（流程边界提示）：命中 `审批/审核/异步/回调/超时/重试/补偿/状态机/队列/任务/通知/消息/人工干预` 时，提升 `P` 与 `V` 先后约束。
- `scope_hint`（范围提示）：命中 `页面/视图/表单/界面/功能/场景/接口/流程` 会记录到 `matched_keywords`，用于审计，不直接强改结构。

回退策略：当 PRD 文本不可读取或特征不充分时，回退到原 `requirements_count` + 阈值行为；`requirements_count` 仍由文件内编号或默认位次占位。

### 12.3 自动化可观测（推荐）

- 运行后立即检查标准输出是否有：`sdd_skeleton_written=ok`。
- 如带图：确认 `sdd-graph.runbook.json` 可解析，且 `outcome.total_nodes` 与 `outcome.total_waves` 及 `waves` 长度一致。
- 关键字段存在性：
  - `manifest.meta.requirements_count`
  - `manifest.loop_rules`
  - `runbook.source_manifest`
  - `runbook.sdd_dir`
  - `runbook.outcome.require_parallel`
- 若执行图子进程失败，主生成器会退出并报 `执行图生成失败`（不产出半成品）——避免主 Agent 接收不完整图。

### 12.3.1 一键自检命令（推荐）

从 `project-sdd-planning` 目录运行，支持一条命令覆盖“生成 → 校验 → 回归”：

- `py_compile`：校验 `sdd_mvcp_generator.py`、`sdd_exec_graph.py`
- 4 个生成场景重放：
  1) 默认图
  2) `--disable-graph`
  3) 外部 manifest（`constraints=null`）
  4) 外部 manifest（`constraints=非法类型`）
- 每个场景统一做：
  - `sdd-mvcp-contract.json` 四块非空
  - `unit_matrix.json` / `handoff_bundle.md`
  - `sdd-graph.runbook.json`（含 `manifest_meta`、`constraints`）
  - schema 与 trace 校验

```bash
# 可按需覆盖
export PRD_ROOT="/tmp/sdd_100_a"
export PROJECT_NAME="DemoProj"
export VERSION="v1.0.0"
export OWNER="ops"

bash scripts/sdd_selfcheck.sh ./SDD/selfcheck
```

检查某个既有输出目录（仅验收，不重放）：

```bash
bash scripts/sdd_selfcheck.sh check ./SDD/selfcheck/default_graph
```

### 12.4 生成后补齐规则

1. 使用 `references/sdd_mvcp_contract_schema.json` 验证 json 可解析；
2. 用 `templates/sdd-mvcp-checklist.md` 逐项补齐；
3. 将 `requirements` 映射到 `acceptance_matrix`，覆盖 PRD 全量条目；
4. 缺失 owner / non-goals / 错误码 / timeout / error_state 的条目不得进入 coding。


## 十三、SDD 写作的执行图（Graph/Loop/Harness）

为了让主 Agent 在多子任务场景下可控分工，默认采用以下执行图。

本版本新增：
- 若执行 `sdd_mvcp_generator.py`，会自动基于 PRD 规模生成 `sdd_exec_graph_manifest.json`，并落盘输出 `sdd-graph.mmd` + `sdd-graph.runbook.json`。
- 这样主 Agent 在启动后就能直接从 `runbook` 取 `waves` 作为子 Agent 派发输入。

### 13.1 阶段与依赖

- `P0-输入与边界`：读取 PRD/BRD、事实清单、非目标清单（**串行起点**）
- `M-模型`：建立模型实体与约束
- `V-视图`：建立页面、字段、校验、权限
- `C-控制`：建立接口与错误码
- `P-流程`：建立流程图与异常链路
- `S-约束聚合`：汇总为 `sdd-mvcp-contract.json`
- `Q-质量门禁`：反模式门禁 + 关键核验
- `U-拆分`：映射为 Development Unit 并产出分工

#### 推荐依赖关系

```mermaid
graph TD
  A[P0 输入与边界] --> M[M-模型]
  A --> V[V-视图]
  M --> C[C-控制]
  V --> C
  M --> P[P-流程]
  C --> S[并行汇聚]
  V --> S
  P --> S
  S --> Q[Q-质量门禁]
  Q --> U[U-拆分与发布]
```

说明：`M` 与 `V` 默认可并行（在同一约束前提下）；
`C` 建议等待 M 与 V 完成后开始；`P` 建议等待 M 完成后开始，且可与 `C` 平行。
### 13.2 并行执行分配（示例）

```json
{
  "wave_1": ["agent-1: P0 输入与边界"],
  "wave_2": ["agent-2: M-模型", "agent-3: V-视图"],
  "wave_3": ["agent-2: C-控制", "agent-4: P-流程"],
  "wave_4": ["agent-5: S-约束聚合/验收映射"],
  "wave_5": ["agent-1: Q-质量门禁与 U-拆分"]
}
```

### 13.3 自我修正 Loop（可回灌重跑）

- 当 `Q-质量门禁` 任意项失败：
  - 只回灌最小影响的上游阶段（如缺字段回到 M，接口错误码回到 C）；
  - 记录 loop 轮次与失败原因。
- 回灌后只启动受影响子图，不强制重跑完整链路。

### 13.4 Harness 约束（子 Agent 交接）

每个 Agent 的交付必须包含：
1. 输入与边界（引用文件/任务 ID）；
2. 输出产物路径；
3. 本阶段验收断言（至少一条可观察结果）；
4. 异常与阻塞项（如发生，必须在下一波带回）。

建议交付对象：
- `wave_<N>` 的 markdown 交付包；
- `sdd-graph.mmd`（流程图）；
- `sdd-graph.runbook.json`（下一波 plan）。

### 13.5 生成器可视化（默认自动，或手工重算）

默认执行 `sdd_mvcp_generator.py` 时，自动产出并写入 `sdd_exec_graph_manifest.json`、`sdd-graph.mmd`、`sdd-graph.runbook.json`。

runbook 结构最少包含：

- `source_manifest`: manifest 文件路径
- `sdd_dir`: 运行时 SDD 根目录
- `manifest_meta`: 完整 manifest 元信息（包含 `derived_rules`）
- `waves`: 分波列表（每波包含 agent + node_id）
- `edges`: 依赖边
- `loop_rules`: 质量门禁触发回灌规则
- `outcome`: `total_nodes/total_waves/require_parallel`

若需重算（例如 manifest 被改动后），可用下列脚本：

```bash
python3 scripts/sdd_exec_graph.py \
  --sdd-dir /path/to/SDD \
  --manifest /path/to/manifest.json \
  --out-dir ./SDD
```

## 十四、可选产物（建议）

- `templates/sdd-mvcp-checklist.md`：执行清单；
- `templates/sdd_mvcp_contract_sample.json`：可直接改填的 `sdd-mvcp-contract.json` 示例；
- `templates/sdd_mvcp_generator_prompt.md`：生成器执行清单（模板版）；
- `templates/sdd_mvcp_generator_input.yaml`：生成器输入清单；
- `templates/sdd_exec_graph_manifest.json`：子任务执行图的输入清单；
- `scripts/sdd_mvcp_generator.py`：生成器脚本；
- `scripts/sdd_exec_graph.py`：执行图生成与分波脚本；
- `references/sdd_mvcp_contract_schema.json`：Code Agent 约束 JSON Schema；
- `references/sdd_code_agent_checklist.md`：代码约束输入标准。