宜博 / lemongraph

SKILL.md 17.6 KB

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 类执行文件：

  1. 05-实施约束与依赖.md
  2. 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 一键生成（半自动）

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 校验
# 可按需覆盖
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 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 并产出分工

推荐依赖关系

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 并行执行分配（示例）

{
  "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 被改动后），可用下列脚本：

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：代码约束输入标准。