yugef3h SOP Design — Spec + Harness 双支柱开发流程
Overview
将 AI 辅助开发工程化为两个支柱：Spec（文档先行，定义"做什么"） 和 Harness（质量保障，验证"做对了没"）。核心理念：让 AI 自己写 spec、自己拆 task、自己写代码，Harness 自动化验收——人只做 review 和方向引导。
技术栈： React 前端 + Python/Go 后端
🚨 五大风险警告
以下风险必须在每个生成的 spec 文档中引用并评估等级。忽视任何一项都将导致项目失控。
| # | 风险 | 根因 | 应对 |
|---|---|---|---|
| 🔴 1 | AGENTS.md 过大 = 无规则 | 规则越多，AI 越容易跑偏，等同于没有规则 | 三次原则写入 + 大小监控（>200 行必须压缩）+ 按需加载。见 references/claude-setup.md |
| 🔴 2 | 先代码后文档 = 浪费时间 | 直接让 AI 写代码，功能可能对但架构全错，无法维护 | Spec→Plan→Task→Code 绝对顺序，写入 AGENTS 强制执行。违反时 Harness 拒绝通过 |
| 🟡 3 | AI 写测试需分层对待 | AI 生成的单元/集成测试已足够可靠，但 E2E 测试仍不稳定 | 分层策略：静态分析 + 单测默认开启，集成测试关键行为开启，E2E 默认关闭。见 references/testing-trophy.md |
| 🟡 4 | 巨型 Task → 难以 review | Task 太粗，一次生成太多代码，review 困难，改错成本高 | 每个 Task 应在 50-150 行代码量，一个 Task 一次 Conventional Commit |
| 🟡 5 | 功能都对/架构全错 | AI 生成的代码能跑，但不符合架构设计，维护成本飙升 | Harness 审查必须核对 spec 一致性（不只是功能正确）；定期触发架构重构 |
核心铁律（写入 AGENTS.md）
1. 文档先行：Spec → Plan → Task → Code，不可逆。任何代码生成前必须先有对应 spec。
2. 三次原则：同一问题/模式出现 ≥3 次，才写入 AGENTS.md。杜绝一次教训就上规则。
3. 测试分层：静态分析始终开启，单元测试默认开启，集成测试关键行为开启，E2E 默认关闭。
4. 即改即提：一个 Task 完成 → 一个 Conventional Commit。不要把对的改错了。
5. 不写自然语言：生成代码时只输出代码，不在代码中夹杂解释性自然语言。
模块路由
先判断用户意图，再加载对应 reference：
| 用户说什么 | 激活模块 | 加载文件 |
|---|---|---|
| "新项目""没有 CLAUDE.md""/init""初始化" | 项目初始化 | references/claude-setup.md |
| "新功能""写个 spec""需求文档""技术方案" | Spec 支柱 | references/spec-pillar.md + references/bdd-gherkin.md |
| "审查""测试""重构""AGENTS 太大了""加个规则" | Harness 支柱 | references/harness-pillar.md + references/testing-trophy.md |
| "提交""commit""task 拆完了" | 交付节奏 | references/conventional-commits.md |
| 不确定 | 先问：要写 spec 定义"做什么"，还是用 Harness 验证"做对了没"？ | — |
双支柱总览
用户需求
│
├── Spec 支柱（文档先行）──────────────────────┐
│ Requirements Spec ──▶ Design Spec │
│ (BDD/Gherkin) (C4/架构图) │
│ │ │ │
│ └──────┬──────────────┘ │
│ ▼ │
│ Implementation Spec │
│ (Task 拆解 + 依赖 + Checklist) │
│ │ │
│ ▼ │
│ AI 生成代码 │
│ │ │
└───────────────┼───────────────────────────────┘
▼
┌── Harness 支柱（质量保障）────────────────────┐
│ │
│ TDD ──▶ Code Review ──▶ Refactor │
│ (分层) (Spec一致性) (人工引导) │
│ │
│ AGENTS.md 维护（三次原则 + 压缩） │
│ │
│ 反馈 ──▶ 更新 Spec（形成闭环） │
└───────────────────────────────────────────────┘
快速参考
Spec 支柱核心
| 层级 | 内容 | 格式 | 谁写 |
|---|---|---|---|
| Requirements Spec | 用户故事、验收标准、业务逻辑、约束 | BDD/Gherkin (Given-When-Then) | AI 生成 + 人 review |
| Design Spec | 技术架构、组件边界、数据流、集成模式 | C4 模型 + 文字描述 | AI 生成 + 人 review |
| Implementation Spec | Task 拆解、依赖关系、实施计划、测试方案 | Task 清单 + Checklist | AI 生成 + 人 review |
Harness 支柱核心
| 模块 | 做什么 | 频率 | 谁主导 |
|---|---|---|---|
| TDD | Red（失败测试）→ Green（最小实现）→ Refactor | 每次写代码（按分层策略） | AI 执行 |
| Code Review | 检查代码与 spec 一致性、架构合理性 | 每个 Task 完成后 | AI 执行 + 人抽查 |
| Refactor | 不改功能，优化代码质量和架构 | 定期 / 发现坏味道时 | 人引导方向，AI 执行 |
| AGENTS.md | 提炼规范、控制大小、按需加载 | 同一问题 ≥3 次时 | AI 提议 + 人确认 |
文件索引
| 文件 | 内容 | 何时读 |
|---|---|---|
references/claude-setup.md |
/init 初始化、四层优先级、200 行硬上限、正向指令、渐进式披露 | 新项目启动 / AGENTS.md 维护前必读 |
references/spec-pillar.md |
Spec 三层规范详细写法、Task 拆解标准 | 写 spec 前必读 |
references/harness-pillar.md |
TDD 流程、审查清单、重构流程、AGENTS.md 维护 | 做质量保障前必读 |
references/bdd-gherkin.md |
Given-When-Then 验收标准写法、示例 | 写 Requirements Spec 前读 |
references/conventional-commits.md |
提交格式规范、Task 粒度标准 | 开始交付前读 |
references/testing-trophy.md |
前端测试分层（Trophy）+ 后端测试分层（Pyramid）+ 分层策略 | 写测试前必读 |
工作流：新项目启动
0. 初始化 CLAUDE.md（没有就 /init，20 行起步）
检查四层优先级，确认规则不冲突
详见 references/claude-setup.md
│
▼
1. 讨论需求（先不写代码，把细节说清楚）
│
▼
2. AI 生成 Requirements Spec → docs/specs/xxx-requirements.md
人 review，对齐目标（这步错了后面全错）
│
▼
3. AI 生成 Design Spec → docs/specs/xxx-design.md
人 review 架构方向
│
▼
4. AI 拆解 Task → docs/specs/xxx-tasks.md
每个 Task：状态、依赖、Checklist、对应 spec 段落
人 review Task 粒度和依赖关系
│
▼
5. 逐个 Task 实现（一个 Task = 一个 Conventional Commit）
Harness 在每个 Task 后自动审查 spec 一致性
│
▼
6. 有问题 → 回到步骤 2 更新 spec，循环
常见错误
| 错误 | 正确做法 |
|---|---|
| 跟 AI 说"帮我做个 XX"直接生成代码 | 先讨论需求，输出 spec，review 后再写代码 |
| spec 讨论不对就进入开发 | spec 写完后自己审查一遍，和审查需求文档一样 |
| 越改越多，把对的改错了 | 改对了就提交，一个 Task 一次提交 |
| AGENTS.md 什么都往里塞 | 三次原则，≥3 次才写入。>200 行必须压缩。见 claude-setup.md |
| 用否定式指令约束 AI | 正向指令："数据变更走 Service 层" 而非 "不要直接改数据库" |
| 所有测试默认关闭 | 分层策略：静态分析 + 单测默认开，E2E 默认关。见 testing-trophy.md |
| Task 太大 | 50-150 行代码量，拆到无法再拆为止 |