Hermes STDD 手册

Hermes STDD 手册

一句话操作

安装 https://github.com/leonai42/stdd.git

用 STDD [要做的事]

卸载 STDD

STDD 项目

STDD (Spec+Test Driven Development) 是一套 Spec 先行 + TDD 执行的 AI 辅助研发流程方法论，由 leonai42 开发，MIT 许可证。

• GitHub: leonai42/stdd
• 版本: V2.3 (2026-05-18)
• 语言: Python 3.10+ (CLI)，中英双语文档
• 核心理念: 先定义行为 (Spec)，再编写测试 (Test)，最后实现代码
• 平台: Claude Code / Cursor / Copilot / Aider / WorkBuddy / Trae / Windsurf → Hermes Agent

通过 6 个有序阶段 + 3 道强制确认门 + 11 类失败模式检查 + 双向可追溯链，将模糊需求转化为高质量交付。支持 5 门语言（Python / Java / Go / Rust / TypeScript）。

STDD 流程示意图

=== 六阶段流程 ===

需求输入
  │
  v
[P1] UNDERSTAND ------------> proposal.md
  │                               │
  │                               v
  │                         [Gate 1] 用户确认
  │                               │ 确认通过
  v                               v
[P2] SPEC  (最关键阶段)
  ├── design.md (技术设计)
  ├── specs/*.md (行为规格 GIVEN/WHEN/THEN)
  └── test-plan.md (测试方案 TC-ID 映射)
  │
  v
[Gate 2] 用户确认
  │ 确认通过
  ├── 长程模式 ─── P3-P5 全自动执行, 仅 Gate 3 暂停
  └── 交互模式 ─── P3-P5 按需暂停交互
  │
  v
[P3] SLICE ---------> tasks.md + slices.md
  每个切片: 1 Scenario → 1+ 测试 → 1 个实现单元
  │
  v
[P4] BUILD ---------> RED → GREEN → REFACTOR
  逐切片 TDD 循环:
    RED   = 写测试 → 确认 FAIL
    GREEN = 最小实现 → 确认 PASS
    REFACTOR = 重构 → 保持绿色
  设计偏离自动记录到 pending-adjustments.md
  │
  v
[P5] VERIFY --------> test-report.md + design-adjustments.md
  ├── 全量测试 + 覆盖率诊断
  ├── 11 类失败模式检查
  ├── Diff 审查
  └── 普通5轮 / 长程10轮修复
  │
  v
[Gate 3] 用户终审
  │ 确认通过
  v
[P6] DELIVER -------> archive + merge specs + git tag

11 类失败模式: 幻觉行为 / 范围蔓延 / 级联错误 / 上下文丢失 / 工具误用 / 运行时行为偏差 / 管线断链 / 内容质量偏差 / 指令衰减 / 覆盖真空 / 契约断层

STDD 目录结构

~/.stdd/
├── bin/stdd                        CLI 入口
├── .stdd/
│   ├── skills/                     6 阶段技能指令
│   │   ├── understand.md           P1 需求理解
│   │   ├── spec.md                 P2 规格设计
│   │   ├── slice.md                P3 切片规划
│   │   ├── build.md                P4 TDD 实现
│   │   ├── verify.md               P5 质量验证
│   │   └── deliver.md              P6 交付
│   ├── templates/                  9 个文档模板
│   │   ├── proposal.md             P1 需求提案
│   │   ├── design.md               P2 技术设计
│   │   ├── spec.md                 P2 行为规格
│   │   ├── test-plan.md            P2 测试方案
│   │   ├── tasks.md                P3 任务列表
│   │   ├── slices.md               P3 切片清单
│   │   ├── test-report.md          P5 质量报告
│   │   ├── design-adjustments.md   P5 设计调整汇总
│   │   └── long-range-auth.md      长程模式授权
│   ├── standards/                  5 语言开发规范
│   │   ├── python.md
│   │   ├── java.md
│   │   ├── go.md
│   │   ├── rust.md
│   │   └── typescript.md
│   ├── config.d/                   模块化配置
│   │   ├── project.yaml            项目配置
│   │   ├── gates.yaml              确认门配置
│   │   ├── long_range.yaml         长程模式配置
│   │   └── quality.yaml            质量阈值配置
│   └── platforms/                  多平台适配
├── STDD.md                         通用流程指引
├── DESIGN.md                       系统设计文档
├── DEPLOY.md                       部署与使用指南
├── EXTENDING.md                    扩展开发指南
├── TROUBLESHOOTING.md              故障排除
├── CHANGELOG.md                    变更日志
├── AGENTS.md                       AI 记忆文件
├── changes/                        (项目 init 后) 活跃变更
├── specs/                          (项目 init 后) 主规范库
└── archive/                        (项目 init 后) 归档

安装 STDD

对 Hermes 说一句：安装 https://github.com/leonai42/stdd.git

Hermes 执行的操作：

git clone --depth 1 https://github.com/leonai42/stdd.git ~/.stdd/
python3 -m pip install pyyaml pytest pytest-cov
# 自动创建 Hermes Skill: software-development/stdd

安装后状态:

• ~/.stdd/ — STDD 系统文件
• Hermes Skill — skill_view('stdd') 加载 6 阶段流程
• CLI — python3 ~/.stdd/bin/stdd init|new|status|archive|...
• 依赖 — pyyaml / pytest / pytest-cov

使用 STDD

对 Hermes 说：用 STDD [要做的事]，自动进入 P1 需求理解流程。

用法一：小任务对话开发

用户: 用STDD帮我实现一个Markdown文件生成工具

P1 需求理解: 加载 skill_view('stdd') 读取 proposal.md 模板 → 生成提案
  Gate 1 等待确认

P2 规格设计: 读取 spec.md + 设计/spec/test模板 → 设计文档 + 行为规格 + 测试方案
  Gate 2 等待确认

P3-P5: 按切片 TDD 实现 → 质量验证 (11类失败模式)
  Gate 3 等待终审

P6: 归档交付

用法二：技术调研

用户: 用STDD调研一下Hermes集成MCP的方案对比

P1: 调研提案 (范围: native-mcp vs 自定义MCP, 成功标准: 集成复杂度/功能/维护成本)
  Gate 1 确认

P2: 调研架构设计、方案对比、关键决策记录
  Gate 2 确认

P3-P5: 按维度切片 → 各维度搭建原型 → 汇总对比报告
  Gate 3 确认

P6: 文档归档

用法三：项目设计开发

用户: 用STDD开发一个行情监控服务

P1: 需求提案 (监控范围 / 告警指标 / 数据源)
P2: 架构设计 + 行为规格 + 测试方案
P3: 切片 (数据接入 → 解析 → 告警 → 存储 → 展示)
P4: 逐切片 TDD (RED→GREEN→REFACTOR)
P5: 全量测试 + 覆盖率 + 11类失败模式检查
P6: 归档, merge specs, git tag v1.0

用法四：接手旧项目重构改造

用户: 用STDD重构遗留的Flask API项目

P1: 分析代码/识别技术债/定义重构范围
  API兼容? 数据库变? 成功标准: 测试通过率/性能指标
  Gate 1 确认

P2: 新架构 design.md + 每 API 的 spec
  先为旧 API 写 characterization test 作为回归基线
  Gate 2 确认

P3-P6: 模块划片 → 每片锁定行为→重构→验证→替换
  Gate 3 审计

改进分析

STDD 原生的流程控制机制基于单 AI 对话 + 文件系统状态 + 顺序阶段推进。Hermes Agent 是多工具、多 session、可并行、有记忆的 Agent 系统，两者的范式差异决定了改进方向。

STDD 原生机制拆解

流程控制:  .stdd.yaml 状态文件驱动
           AI 读取 skill 文件 → 按指令执行 → 写产出物 → 等用户确认
           顺序推进 (P1→P2→P3→P4→P5→P6), 一次只能一个 change

阶段切换:  用户发 "/stdd-spec" 或 "/stdd-continue" 触发
           AI 读对应的 skill 文件获取指令
           或长程模式: AI 读完 Gate 2 后自主判断继续下一阶段

确认门:    3 个 Gate 由用户输入确认信号触发
           Gate 后读取下一个 skill 文件和模板

产出物:    Markdown 文件写入 changes/<name>/ 目录
           模板先行: AI 先读模板再生成文稿

质量验证:  5-10 轮迭代, 每轮 pytest + 11类检查
           3 个 Review Agent 审查代码/测试/文档

不足分析

AI 开发模式项目