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）

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（形成闭环）               │
    └───────────────────────────────────────────────┘