为高质量 AI 编程而生
V3.0.5 · MIT License · Python 3.10+
AI 编程不只是"写代码"，而是"写出正确的代码" — 当工程实践遇见 AI 辅助开发。
STDD V3.0 是一套 Spec 先行 + TDD 执行 的 AI 辅助研发流程系统。4 个有序阶段 + 3 道强制确认门 + 14 类失败模式检查 + 跨项目知识图谱 + Agent 行为验证 + 智能 Guard + 自学习经验库，将模糊需求转化为高质量交付。支持 10 门语言，适配 8 大 AI 编程平台。
STDD (Spec+Test Driven Development) 是一套 AI 辅助的研发流程方法论与工具系统。它的核心思想是：先定义行为（Spec），再编写测试（Test），最后实现代码 — 通过 4 个有序阶段（V3.0.5：SLICE/BUILD/VERIFY 合一）和 3 道强制用户确认门，确保 AI 生成的每一行代码都有据可查、有测可验。
| 原则 | 说明 |
|---|---|
| Spec 先行 | 先定义行为（GIVEN/WHEN/THEN 格式），再写代码，杜绝需求歧义 |
| TDD 执行 | RED → GREEN → REFACTOR，按垂直切片推进，每个切片可独立验证 |
| 设计调整可追溯 | 实现中对设计的任何偏离必须记录到 design-adjustments.md，Gate 3 统一审核 |
| 用户确认驱动 | 3 道强制确认门（需求→设计→质量），关键节点不可跳过 |
Gate 1 ── Phase 1 结束 ── 用户确认 proposal.md（范围、边界、成功标准）
Gate 2 ── Phase 2 结束 ── 用户确认 design.md + specs + test-plan.md（最关键的分水岭）
Gate 3 ── Phase 3 结束 ── 用户确认 test-report.md + design-adjustments.md（质量终审）
Gate 2 之后可选择全自动长程模式：一次性预授权后，Phase 3（BUILD）连续自动执行，仅 Gate 3 等待确认。也可选择普通交互模式，每阶段按需暂停。
| 场景 | 为什么适用 |
|---|---|
| 金融 / 医疗 IT 团队 | 需要高可靠性、强合规性、全链路追溯的高风险领域。内置风控规则校验、审计日志、精度约束 |
| AI 编程实践者 | 经常遇到"AI 跑偏"问题？STDD 的 11 类失败模式检查系统性堵住 AI 常见错误 |
| 技术团队 Leader | 想引入 AI 辅助研发，需要保证代码质量和可追溯性。3 道确认门让你掌控关键决策 |
| 开源项目维护者 | 接受 AI 贡献代码，但担心不可追溯、质量不可控。Spec 先行确保贡献符合预期 |
- 需求歧义 → Spec 先行：GIVEN/WHEN/THEN 格式将模糊需求转化为可验证的行为规格
- AI 跑偏 → 12 类失败检查：系统性检测幻觉行为、范围蔓延、级联错误、指令衰减等 AI 特有问题
- 质量不可控 → TDD 执行：先写测试再写代码，测试通过才是完成
- 过程黑箱 → 双向追溯：Scenario → TC-ID → 测试函数 → 源码，完整映射链可查询
- 设计偏离 → 强制记录：任何设计偏离自动记录，Gate 3 统一审核，绝不静默
| 阶段 | 触发方式 | 产出物 | 确认门 |
|---|---|---|---|
| P1: UNDERSTAND | /stdd-understand <需求> |
proposal.md | Gate 1 · 强制用户确认 |
| P2: SPEC | /stdd-spec |
design.md + specs/*.md + test-plan.md | Gate 2 · 强制用户确认（最关键） |
| P3: BUILD ⭐V3.0.5 | 自动执行 | slices.md + tasks.md + TDD 实现 + test-report.md | Gate 3 · 强制用户确认 |
| P4: DELIVER | /stdd-continue |
archive + merge specs + git tag | 无 |
Phase 1: UNDERSTAND — 需求理解 将模糊需求转化为清晰、可验证的变更提案（proposal.md）。包含 Why / What Changes / Capabilities / Impact / Success Criteria。确认前不生成文件。
Phase 2: SPEC — 规格设计 ⭐ 最关键阶段 将 proposal 转化为精确的技术规格和测试方案。产出技术设计（design.md）、行为规格（specs/*.md，GIVEN/WHEN/THEN 格式）、测试方案（test-plan.md，含 TC-ID 映射与覆盖矩阵）。Gate 2 确认后锁定设计基线。
Phase 3: BUILD — 切片规划 + TDD 实现 + 质量验证（V3.0.5：SLICE/BUILD/VERIFY 三阶段合一） 切片规划：将测试方案拆分为可独立实现的垂直切片（1 个 spec Scenario → 1+ 测试 → 1 个实现单元），按依赖拓扑排序、P0 优先。然后逐切片执行 RED → GREEN → REFACTOR 循环（先写测试、再最小实现、最后重构），设计偏离自动记录到 pending-adjustments.md。最后全量质量验证：全量测试 + 覆盖率诊断 + Diff 审查 + 12 类失败模式检查，汇总设计调整到 design-adjustments.md，生成 test-report.md。
Phase 4: DELIVER — 交付 归档变更到 archive/ → 合并 specs 到 specs/ → 自动上传经验到社区 → Git commit + tag。
| 能力 | 说明 |
|---|---|
| Spec 先行 | GIVEN/WHEN/THEN 格式定义行为，THEN 中 SHALL 标记强制行为，杜绝需求歧义 |
| 3 道强制确认门 | 需求→设计→质量三处不可跳过。Gate 2 是分水岭，之后可选全自动长程模式 |
| 长程无人值守 | Gate 2 后一次性预授权，Phase 3 (BUILD) 全自动连续执行，90%+ 操作无需人工干预 |
| 自学习经验库 ⭐V2.5 | 5 状态生命周期（发现→验证→沉淀→共享→合并/退休），AI 从历史失败中持续学习 |
| 社区经验池 ⭐V2.5 | GitHub Releases CDN + Gitee 镜像 + Issues 投票，全球 STDD 用户共享经验 |
| 多 Agent 并行 ⭐V2.5 | 并行切片自动派发到多个 subagent，主 agent 协调等待并 merge 结果 |
| 跨 Session 恢复 ⭐V2.5 | Agent 重启 session 后 1 轮内恢复上下文，长程任务不丢失进度 |
| CI 检查增强 ⭐V2.5 | 新增 scope 范围验证 + coverage 阈值检查 + contracts 契约一致性 3 项 CI 检查 |
| 双向可追溯 | Scenario → TC-ID → 测试函数 → 源码，stdd trace 命令一键追溯完整映射链 |
| 14 类故障检查 | 幻觉行为、范围蔓延、级联错误、上下文丢失、工具误用、运行时偏差、管线断链、内容质量偏差、指令衰减、覆盖真空、契约断层、锚定缺失、Agent CP 失败、跨系统不一致 |
| 跨项目知识图谱 ⭐V3.0 | knowledge-graph.yaml 跨项目失败模式提炼 + stdd knowledge merge/query/predict/fix 四命令 |
| Agent 行为验证 ⭐V3.0 | stdd agent verify CP 检查点逐条验证 + Phase 3 (Build) 代码验证与 Agent 验证双管线并行 |
| Bootcamp 训练营 ⭐V3.0.4 | AI 新兵训练营：5关实战演练 + 自动评分 + 肌肉记忆 |
| 智能 Guard ⭐V3.0 | 分级提醒模式：小改放过 / 中改建议 / 大改拦截引导 STDD 流程 |
| 覆盖差异分析 | stdd diff 输出 spec 与测试之间的覆盖缺口对比表 |
| 设计调整追溯 | 设计偏离自动记录到 design-adjustments.md，Gate 3 统一审核 |
| 25 命令 CLI 工具 | init / install / new / validate / status / archive / trace / diff / rollback / abort / experience / ci / gate / state / curate / proposal / canon / index / agent / hooks / structure / skill / fix / guard / knowledge |
| 内置 Review 审查 | V2.1 起内置代码审查能力，AI 实现后自动 Review，确保质量一致性 |
| # | 模式 | 检测内容 | 引入版本 |
|---|---|---|---|
| (a) | 幻觉行为 | 编造的文件路径、环境变量、函数名、库 API | V1.0 |
| (b) | 范围蔓延 | 超出计划文件的改动 | V1.0 |
| (c) | 级联错误 | 异常被静默吞掉、空数组 fallback 掩盖问题 | V1.0 |
| (d) | 上下文丢失 | 与 proposal/design/spec 决策矛盾 | V1.0 |
| (e) | 工具误用 | 错误的工具选择或参数 | V1.0 |
| (f) | 运行时行为偏差 | 静态结构正确但动态行为异常 | V1.1 |
| (g) | 管线断链 | 多步转换链路缺失步骤或隐式假定 | V1.1 |
| (h) | 内容质量偏差 | 数据不一致、长度越界、引用缺失 | V1.1 |
| (i) | 指令衰减 | Prompt 明确写了但 AI 未充分执行 | V1.1 |
| (j) | 覆盖真空 | 某 capability 零自动化测试覆盖 | V1.2 |
| (k) | 契约断层 | 跨 capability API 字段名/header 不一致 | V1.2 |
| (l) | 锚定缺失 | 关键变更缺少参考实现或接口锚定 | V2.7 |
| (m) | Agent CP 失败 | Agent 操作序列检查点断言未通过 | V3.0 |
| (n) | 跨系统不一致 | 多系统间运行时数据值不一致 | V3.0 |
在 AI 编程平台中直接说：
"安装 https://github.com/leonai42/stdd 到全局skill"
"/STDD 初始化 当前项目"
"/stdd 开发 我们需要为 API 增加速率限制功能"
AI 会自动处理安装、初始化、升级、以及完整的 6 Phase 流程。你只需要在三个 Gate 确认即可。
点击展开 CLI 命令
git clone https://github.com/leonai42/stdd.git /path/to/stdd-project
cd /path/to/your-project
python /path/to/stdd-project/bin/stdd init
python /path/to/stdd-project/bin/stdd install claude-code
/stdd-understand 我们需要为 API 增加速率限制功能
/stdd-spec
/stdd-continue| 命令 | 说明 | 引入版本 |
|---|---|---|
stdd init |
初始化 STDD 目录结构 | V1.0 |
stdd install <platform> |
安装 skills 到目标 AI 平台 | V1.0 |
stdd new <name> |
创建新 change 目录骨架 | V2.0 |
stdd validate [name] |
验证 change 结构完整性 + spec 格式 + TC-ID 唯一性 | V2.0 |
stdd status [name] |
查看变更当前阶段与状态 | V2.0 |
stdd archive <name> |
归档已完成变更并合并 specs | V2.0 |
stdd trace <tc-id> |
追溯 spec↔test↔code 双向映射链 | V2.0 |
stdd diff [name] |
显示 spec↔test 覆盖差异表 | V2.0 |
stdd rollback <name> |
从 archive 恢复已归档变更 | V2.0 |
stdd abort <name> |
放弃变更并归档 | V2.0 |
stdd experience <sub> |
经验库管理（list/add/stats/export/pull/verify/deposit/retire/extract/review/share/search） | V2.4 |
stdd extract-proposal |
从 proposal.md 提取结构化数据（JSON/YAML） | V2.4 |
stdd dependency-graph |
构建 spec 依赖图 + 环检测 + 拓扑排序 | V2.4 |
stdd ci <sub> |
CI 检查（7 项：结构/格式/scope/coverage/contracts/diff/经验） | V2.5 |
stdd gate approve <change> --gate <N> |
文件 token 方式确认 Gate | V2.5 |
stdd state <change> |
读写 change 状态（resume_context/active_slice 等） | V2.5 |
stdd curate <sub> |
社区经验池维护工具（pull/deduplicate/review/pack） | V2.5 |
stdd proposal <sub> |
Canonical proposal.yaml 管理（init/validate/show） | V2.7 |
stdd canon <sub> |
双轨制文档管理（init/generate/verify） | V2.7 |
stdd index <sub> |
项目索引管理（update/show/trace） | V2.7 |
stdd agent <sub> |
Agent 行为验证 | V2.7 |
stdd hooks <sub> |
生命周期 Hooks 管理（install/status） | V2.7 |
stdd structure <sub> |
代码结构摘要管理（delta/merge） | V2.7 |
stdd skill <sub> |
Skill 管理（create） | V2.7 |
stdd fix <sub> |
多级自动修复 | V2.8 |
stdd guard <sub> |
项目级智能门禁 | V2.9.3 |
stdd phase <sub> |
变更阶段管理（advance/check） | V2.9.4 |
stdd work <sub> |
关联工作记录 | V2.9.4 |
stdd knowledge <sub> |
跨项目知识图谱（merge/query/predict/fix） | V3.0 |
--dry-run |
全局选项：预览操作但不修改文件系统 | V2.0 |
--verbose / -v |
分级日志输出 | V2.0 |
| 平台 | 安装方式 | 调用方式 |
|---|---|---|
| Claude Code | stdd install claude-code |
/stdd-xxx 斜杠命令 |
| OpenAI Codex | stdd install codex |
/stdd-xxx 斜杠命令 |
| Cursor | stdd install cursor |
项目规则自动加载 |
| GitHub Copilot | stdd install copilot |
.github/copilot-instructions.md |
| Aider | stdd install aider |
.aider.conf.yml |
| WorkBuddy | stdd install workbuddy |
关键词匹配触发 |
| Trae | stdd install trae |
/stdd-xxx 斜杠命令 |
| OpenCode | stdd install opencode |
/stdd-xxx 斜杠命令 |
对于 Windsurf 等无自动安装支持的平台，可将
STDD.md手动复制为.windsurfrules。
Phase 4 开始前自动加载对应语言的开发规范。V2.9.6 已覆盖 10 门语言：
| 语言 | 测试框架 | Lint 工具 | 引入版本 |
|---|---|---|---|
| Python | pytest | ruff | V1.0 |
| Java | JUnit 5 + Mockito | Checkstyle | V2.3 |
| Go | testing + testify | golangci-lint | V2.3 |
| Rust | cargo test | clippy + rustfmt | V2.3 |
| TypeScript | Jest | ESLint + Prettier | V2.3 |
| JavaScript | Jest / Vitest | ESLint + Prettier | V2.9.6 |
| C / C++ | GTest / Catch2 | clang-tidy / clang-format | V2.9.6 |
| Kotlin | JUnit5 + MockK | ktlint / detekt | V2.9.6 |
| Swift | XCTest | SwiftLint | V2.9.6 |
| Dart / Flutter | flutter test | dart analyze | V2.9.6 |
STDD 项目仓库 你的项目（安装后）
├── .stdd/ ├── .stdd/
│ ├── skills/ # 6 阶段 Skill │ ├── skills/templates/standards/
│ ├── skills/_shared/ # DRY 共享片段 │ ├── config.d/ # 模块化配置
│ ├── templates/ # 9 文档模板 │ └── platforms/ # 多平台适配
│ ├── standards/ # 10 语言规范 ├── specs/ # 主规范
│ ├── config.d/ # 模块化配置 ├── changes/ # 活跃变更
│ └── platforms/ # 8 平台适配 ├── archive/ # 已完成
├── stdd/cli/ # CLI 模块 ├── STDD.md
├── bin/stdd # CLI 入口 └── AGENTS.md
├── tests/ # STDD 自身测试
├── STDD.md # 通用流程指引
├── DESIGN.md # 系统设计文档
├── DEPLOY.md # 部署与使用指南
├── EXTENDING.md # 扩展开发指南
├── TROUBLESHOOTING.md # 故障排除指南
├── CHANGELOG.md # 变更日志
├── CONTRIBUTING.md # 参与贡献指南
└── README.md
基于 STDD V1.2 流程，5 天从 0 到可发布产品。
| 指标 | 数据 |
|---|---|
| 代码行数 | 27,826 行（不含 node_modules） |
| 测试通过率 | 100%（326 个可执行用例） |
| AI 自动化率 | 90%+（Phase 3 长程模式） |
| 规格文件 | 41 份 spec.md，319+ 个 Scenarios |
| 测试密度 | 每 2.4 行业务代码对应 1 行测试代码 |
| 人效比 | 1,400 行/人时 |
基于 STDD 方法论的中短线趋势策略系统，已迭代至 V4.2 稳定版。19,500+ 行测试代码，多层评分决策体系 + 多级风控防护。完整的 changes/ + specs/ 目录，每次策略迭代走完整四阶段流程。
1 小时以内，完整 STDD 四阶段流程，271 行核心交付件，29 TC 100% 通过率。证明 STDD 不只适用于中大型项目 — 小型任务同样能从中获益，质量不因规模而妥协。
| 版本 | 日期 | 核心变更 |
|---|---|---|
| V3.0.5 | 2026-08-17 | 6→4 Phase 合并落地（SLICE+BUILD+VERIFY → BUILD）+ phase_constants 单一常量 + 旧数据容错 + 版本统一 3.0.5 |
| V3.0.4 | 2026-07-09 | V3.0 瘦身计划（6→4 Phase）+ Batch Pipeline 规划 + 目录迁移回归修复 |
| V3.0.3 | 2026-07-09 | STDD Bootcamp 训练营：5 关实战 + 自动评分 + 经验沉淀 |
| V3.0.2 | 2026-07-02 | 目录收敛至 .stdd/ + Phase 前置检查 + Gate 3 确认 |
| V3.0.1 | 2026-07-01 | Guard 完善 + 新项目冷启动修复 + Zombie change 检测 |
| V3.0.0 | 2026-07-02 | 跨项目知识图谱 + Agent 行为验证 + 智能 Guard + 14 类失败模式 |
| V2.9.6 | 2026-07-01 | Codex 平台适配 + 10 语言规范 + DELIVER 经验自动上传 |
| V2.9 | 2026-06-05 | 三档执行模式（轻量/标准/全面）+ Canonical YAML 双轨制 + Phase Context + 上下文预算检查 |
| V2.8 | 2026-06-03 | 多级自动修复（fix）+ 代码结构摘要（structure）+ Skill 管理 + 工程效能优化 |
| V2.7 | 2026-06-03 | 结构化基础：Canonical YAML + 锚定体系 L1-L4 + 双轨验证 + OpenCode 平台 + 第 12 类失败模式 (l) |
| V2.5 | 2026-05-21 | 经验生命周期闭环 + 社区经验池 + 多 Agent 适配 + 跨 Session 恢复 + CI 检查增强 |
| V2.4 | 2026-05-20 | AI 辅助增强：自学习经验库 + Spec 自动补全 + 智能切片推荐 + CI/CD 集成 |
| V2.3 | 2026-05-18 | 基础配套完善：5 语言规范 + 6 平台扩展 + 配置模块化 + Skill 标准化 |
| V2.2 | 2026-05-15 | 流程体验优化：Gate 交互信息完善 + 长程模式可靠性提升 |
| V2.1 | 2026-05-14 | 方法论增强：全面修复 80 项评审问题 + 内置 Review 能力 |
| V2.0 | 2026-05-13 | 架构升级：CLI 模块化拆分 + 11 命令 + pytest 测试框架 |
| V1.x | 2026-05 | 基础建设：6 阶段流程 → 长程模式 → 11 类失败模式 → E2E + 覆盖率 |
详见 CHANGELOG.md
| 文档 | 内容 |
|---|---|
| STDD.md | 通用流程指引，可作为项目规则加载到无 Skill 系统的 AI 平台 |
| DESIGN.md | 完整系统设计：架构、状态机、跨平台设计、用户交互协议 |
| DEPLOY.md | 部署与使用指南：安装方式、配置说明、平台适配、FAQ |
| EXTENDING.md | 扩展开发指南：新增平台/语言规范/失败模式/CLI 命令 |
| TROUBLESHOOTING.md | 故障排除：常见问题与解决方案 |
| CHANGELOG.md | 完整版本变更日志 |
| CONTRIBUTING.md | 参与贡献指南 |
我们欢迎社区贡献！无论是报告 Bug、提出功能建议、新增语言规范或平台适配，请查看 CONTRIBUTING.md 了解详细流程。
Copyright (c) 2026 杭州大道一以科技有限公司
Spec 先行，TDD 执行，质量不靠运气，靠系统。