sop-design

# 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） ```markdown 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-pi...