夜雨聆风🧩 5 个 Sub-Agent + 3 个 Skill，跑通了需求-设计-编码-验收-归档全链路。
⚙️ 不是演示玩具，是真能干活的生产力工具。
✍️ Harry📅 2026.06
为什么做这个
团队里每个人写代码的习惯不一样，有人先写测试有人直接梭哈，有人写设计文档有人靠口头沟通。代码 review 也是看心情，有时间就多看看，没时间就"LGTM"三个字母完事。
我想解决的问题很明确：能不能把软件研发流程标准化、自动化，让每个环节都有明确的质量门禁和决策证据，同时又不增加额外负担？
答案就是这套基于 Claude Code Sub-Agent + Skill 的研发工作流编排系统。前前后后改了十几版，自己审了自己四轮，现在趋于稳定了。
整体架构：门、约、环、证
软件工程流程管理，最核心的是四件事：
- 门（Gate）
——每个阶段有客观的准入/准出条件，不是凭感觉 - 约（Contract）
——阶段间的输入输出是明确的，上游不猜下游要什么 - 环（Loop）
——失败可以回退重来，有明确的回环路径和次数上限 - 证（Evidence）
——每个决策留下审计记录，出问题能追溯
这套系统的骨架就建立在四个字上。
五个 Sub-Agent 串成一条管道，每个都是独立 AI，加载自己的系统提示词，互不干扰。
管道五节点
① req-writer — 业务需求
业务分析师角色。输入用户模糊诉求，输出结构化需求文档。产出 ./docs/{feature}/requirement.md，包含需求概述、业务背景、用户故事、业务规则、异常场景、验收标准（Given/When/Then）。强制要求：§8 决策记录表。每个决策必须带选项、选择、依据三列，禁止无依据论断。
② prd-writer — PRD 产品方案
产品方案专家角色。输入业务需求文档，输出 OpenSpec 格式的 proposal.md。两个关键约束："只产出 proposal.md，不写 design/specs/plan"，以及 "Capabilities 列表直接决定下游 specs/ 拆分粒度"。
③ trd-writer — 技术设计
技术需求分析师角色。产出设计文档链：design.md (ADR格式，至少2个选项对比)、specs/{capability}.md (反向标注Capability)、plan.md (Superpowers Plan格式，TDD驱动，禁止TBD)。巧妙之处：若上游无 proposal.md，会自动补齐最小 proposal，让用户可以直接开干。
④ tdd-coder — 编码
工程师角色，按 TDD RGB 三阶段编码：
- Red
→ 先写测试，确认全部失败 → code-review - Blue
→ 设计确认，输出差异决策表 → code-review - Green
→ 最小实现，全部通过后重构 → code-review 集成验证 → 全量测试 + 覆盖率 ≥ 80% + 无 TODO/FIXME
每个阶段都有 code-review 闸门，最多2次迭代，超限自动阻断并输出"人工介入"标记。
⑤ e2e-validator — 验收
QA 架构师角色，名字叫赵敏。以业务规则为唯一依据，证据驱动验收。每条判定有完整证据链：规则原文 → 实现分析（文件:行号）→ 行为推断 → 差异判定。禁止"看起来没问题"。
三个支撑 Skill
🔎 code-review
六维度审查：正确性→架构→整洁→安全→性能→测试。内置硬标准（方法≤30行，类≤300行，禁止模糊命名）。
📄 doc-reviewer
文档审查五维审计：正确性、合理性、完整性、一致性、可验证性。杜绝不可测描述。
🔄 双审底线
“一次性给出所有问题，不要多次交互”。一轮审完一次改完，最多两轮。
决策链路：不是拍脑袋
很多人以为编排器就是"Agent A 跑完跑 Agent B"，其实没那么简单。真实执行链路有五道判断：
- ① 需求是否明确？
三问 checklist（一句话说清？核心输入输出？主要异常场景？）全Yes放行，否则让用户选择。 - ② trd-writer 必经
——不管复杂度高低，TRD 必须产出。 - ③ 审核闸门
——三道条件决定是否强制人工审核。 - ④ 验收判定 — 根因分类
：编码问题回退 tdd-coder，设计问题回退 trd-writer，需求问题回退节点①。自动升级机制防止反复。 - ⑤ 需求变更 — 三级响应
：轻量改文档，中度回退到受影响阶段，重度回到节点①。
审核闸门表
| 强制 Path A | |
消费者自检：把把关权还给买单的人
编排器不做中间 check，下游 Agent 启动时自己校验输入。
tdd-coder 启动 → 自检 design.md API/Contracts 有没有方法签名？
→ 缺？回退 trd-writer 补充
→ 全？继续 Red 阶段
e2e-validator 启动 → 自检代码能不能编译？测试全量通过？
→ 不通过？回退 tdd-coder
→ 全过？继续验收消费者最知道要什么。把检查权交给买单的人。
audit-trail：全链路审计追踪
每次跑完工作流，产出一份 audit-trail.md，记录七个节点的完整决策证据：需求确认、TRD产出、审核闸门、TDD编码、E2E验收、验收判定、归档确认。最后附度量汇总表，出问题回头翻 audit-trail 比翻聊天记录快一百倍。
🧾 度量示例：需求明确度、TRD review 迭代次数、tdd-coder 总迭代、e2e 回退次数、全链路 tool_uses 总数。
文件体系：三层分离
研发期:
./docs/{feature}/ ← 业务层: requirement, e2e-report, audit-trail
docs/superpowers/plans/{f}.md ← Superpowers 层: plan
openspec/changes/{feature}/ ← OpenSpec 层: proposal, design, specs
归档后:
./docs/archive/{date}/{feature}/ ← 业务+Superpowers+audit-trail+SUMMARY
openspec/changes/archive/{date}-{feature}/ ← OpenSpec: proposal, design, specs质量保障：全流程 13 阶段检查清单
比写代码本身更长的，是检查清单。全流程 13 个阶段，每个阶段 3-7 项检查，每项有“怎么查+通过标准+不通过处理”。👤 标记 9 处需要用户参与，其余全部自动校验。每个 reviewer 迭代上限 2 次，回退升级上限 2 次，异常自动阻断。
四条核心设计原则
- TRD 必经。
简单功能跳过的是人工审核，不是设计。 - 消费者自检。
编排器不做中间裁判，下游校验输入质量。 - 决策留证。
每个 AskUserQuestion 自动记录到 audit-trail，不增加负担。 - 失败可回退。
按根因分类回退，同问题反复出现自动升级根因。
跑一条看看
用减法功能验证了完整流程：
/software-workflow "减法"
→ ① 三问全 Yes
→ ② trd-writer (doc-reviewer ×3: 2个严重问题 + 修复)
→ ③ 审核闸门 (🟢低风险, ≤10任务, 用户选跳过 → Path B)
→ ④ tdd-coder (RGB, 16/16 测试通过)
→ ⑤ e2e-validator (6/6 业务规则 ✅, 1个🟡建议)
→ ⑥ 验收判定 (全部 ✅ → 归档)
→ ⑦ 归档 (三层 + audit-trail.md)全程 5 次 Agent 调用，128 次工具操作，0 次回退。audit-trail 完整记录。
这套东西适合谁
适合个人开发者和小团队，尤其是对代码质量有要求、希望流程标准化、但不想搞太重流程的人。不适合大厂多团队协作场景（无权限管理、多环境、发布审批）。
后续方向
三个已做但持续优化的：增量迭代闭环、风险驱动决策、决策证据透明化。三个未来想做的：Agent 间共享记忆、流程度量自动优化、多语言/CICD 集成。
从需求到归档，每一步都有门、有约、有环、有证。
代码会过时，决策证据不会。这就是 audit-trail 的意义。
