EvanFlow：Claude Code 的 TDD 反馈循环框架

一个由 TDD 驱动的软件开发迭代反馈循环，配合 Claude Code。

16 个内聚的 skill + 2 个自定义 subagent 将一个想法从头脑风暴一路走到实现，全程有检查点保证你始终掌控。单一入口：说"let's evanflow this"，编排器就会运行整个循环。

brainstorm → plan → execute (vertical-slice TDD per task) → iterate → STOP
                    └─ sequential, or parallel coder/overseer

TDD 不是执行后的单独阶段——它是每个代码写作任务内部的纪律。Execute 是执行框架（任务跟踪、阻碍项、质量检查）；evanflow-tdd 是运行在任何生成生产代码任务内部的东西。

循环是指挥官，不是自动驾驶仪：在设计批准、计划批准和迭代后有真实的检查点。Agent 在每个 git 操作前停止，等待你的方向。没有自动提交。没有强制仪式。没有"必须调用某个 skill"的税收。

推荐路径——通过 Claude Code 的插件市场：

/plugin marketplace add evanklem/evanflow
/plugin install evanflow@evanflow

"Let's evanflow this — I want to add a small feature that does X."

evanflow-go 启动并遍历整个循环。git-guardrails hook 随插件自动激活（无需编辑 settings.json）。Skills 显示在 evanflow: 命名空间下（如 /evanflow:evanflow-go）。

查看下面的 Installation 了解两条替代路径。

什么让它成为一个反馈循环

循环围绕纪律构建，这种纪律在迭代中会复利增长，而不是单次生成。每个步骤都有一个检查点来控制下一步：

Brainstorm 澄清意图，提出 2–3 种方案并内置 grill（压力测试）→ 你批准设计

Plan 首先映射文件结构（深模块、删除测试）→ 你批准计划

Execute 逐任务运行，内部验证 → 阻碍项停止循环并浮出给你。在每个代码写作任务内，TDD 是纪律（不是执行后的单独阶段）。

TDD 是垂直切片且每循环完整的 RED → GREEN → REFACTOR：一个失败的测试 → 最小实现 → 在你刚写的测试仍然是新鲜的安全网时进行重构 → 下一个测试。重构不被延后到最后。测试通过公共接口验证行为，所以它们在重构中存活下来。

Iterate 用新眼光重读 diff，运行质量检查，对 UI 变化进行屏幕截图，并对照五个故障模式检查清单运行（幻觉动作、范围蠕变、级联错误、上下文丢失、工具滥用）。硬上限为 5 次迭代。

STOP。报告。等待你的方向。agent 永远不会自动提交，永远不会自动暂存，永远不会提议一个 PR。

对于有 3 个或以上真正独立单元的计划，循环分叉为并行的 coder/overseer 编排：每个单元一个 coder（使用带 RED 检查点的垂直切片 TDD），每个 coder 一个 overseer（只读审查 subagent，不能修改代码），加上一个在每个接触点运行命名集成测试的集成 overseer。集成测试是可执行的契约——如果两边都必须满足相同的通过测试，接口就不会漂移。

硬编码到循环中的硬规则

下面的每条规则都引用了它的来源。如果缺少引用，该规则来自在真实项目上运行循环的观点，不是研究——标记为如此。

永远不要凭空造值——文件路径、环境变量、ID、函数名、库 API。如果不确定，agent 停止并询问。来源：action-hallucination 是 DAPLab/Columbia"9 Critical Failure Patterns of Coding Agents"中的首要故障模式。

断言正确性警告——在 HumanEval 对四个 LLM 的评估中，超过 62% 的 LLM 生成的测试断言是错误的。来源："Test-Driven Development for Code Generation"(arXiv 2402.13521)，§3.2。evanflow-tdd 和 overseer 审查都明确检查实现中的单字符 bug 是否仍会让断言通过。

五个故障模式检查在 iterate + overseer review 中进行——幻觉动作、范围蠕变、级联错误、上下文丢失、工具滥用。来源：综合自上述 DAPLab 故障模式论文。

上下文漂移监视——evanflow-compact 在清晰的阶段边界和漂移症状时触发（重新询问已解决的问题、与早期决定矛盾）。来源：2025 年企业 AI 失败的近 65% 被归因于多步推理中的上下文漂移或内存丢失，而不是原始上下文耗尽——见 Alex Merced，"Context Management Strategies for OpenCode"(March 2026)。

永远不要自动提交，永远不要自动暂存——观点，不是研究。来自在真实项目上运行循环：每当 agent 决定集成时，它都集成错了。

没有 skill 税——观点。Skills 是工具，不是收费站。

默认循环（5 个 skill）

特殊用途（9 个 skill）

跨越（1 个 skill）

在 agents/ 中——通过 Agent tool 与 subagent_type: 参数调用：

hooks/block-dangerous-git.sh — PreToolUse hook，阻止破坏性 git 操作（git push、git reset --hard、git clean -f、git branch -D、git checkout .、git restore .）。随插件安装路径自动激活。

硬规则（适用于每个 skill）

永远不要自动提交，永远不要自动暂存，永远不要自动完成。每个 git 写操作都需要你在当前回合中明确要求。

永远不要凭空造值。文件路径、环境变量、ID、函数名、库 API——如果不确定，agent 停止并询问。

没有 skill 税。临时问题不需要 skill 调用。Skills 是工具，不是收费站。

没有强制的 spec/plan 路径。文件存放在你想要的地方。

声称完成前进行验证。质量检查（typecheck、lint、test）在任何"完成"报告前运行。

安装

要求

Claude Code（任何最近版本）

Bash——用于捆绑的 hook 脚本（Linux、macOS 或 Windows + WSL）

jq——由 hook 脚本用来解析 Claude 的 JSON 工具输入。通过 apt install jq、brew install jq 或你的平台的包管理器安装。如果 jq 丢失，guardrail hook 会静默失败，危险的 git 操作不会被阻止。

可选但推荐：

chromium 或 google-chrome——用于 evanflow-iterate 的 UI 变化视觉验证（chromium --headless --screenshot=...）。如果丢失会优雅地降级——skill 会标记并要求你进行视觉验证。

三条路径，按优先级顺序。所有三条都以你的 .claude/skills/ 中相同的 skill 集结束。插件路径额外自动连接 guardrail hook。

路径 1 — Claude Code 插件市场（推荐）

这是最简洁的安装。Skills、agents 和 guardrail hook 全部自动激活。

/plugin marketplace add evanklem/evanflow
/plugin install evanflow@evanflow

重启 Claude Code（或 /reload-plugins）。Skills 显示为命名空间形式 /evanflow:evanflow-go、/evanflow:evanflow-tdd 等。无论命名空间如何，通过"let's evanflow this"自动调用仍然有效。

卸载：/plugin uninstall evanflow@evanflow。

路径 2 — npx skills@latest add CLI

对任何有 SKILL.md 形状文件夹的 GitHub 仓库有效。仅安装 skills——不安装 guardrail hook 或自定义 subagents（如果需要，你可以手动添加）。

# 一次安装所有 16 个 skills
npx skills@latest add evanklem/evanflow -s '*' -y

# 或安装单个 skills
npx skills@latest add evanklem/evanflow/evanflow-go
npx skills@latest add evanklem/evanflow/evanflow-tdd
# ...

这将 skills 放在 ~/.claude/skills/（全局）或 .claude/skills/（项目，自动检测）。

路径 3 — 手动

适合想要完全控制、无 CLI 依赖的用户。

git clone https://github.com/evanklem/evanflow.git
cd evanflow

# Skills（项目级——调整到 ~/.claude/skills/ 用于全局）
mkdir -p .claude/skills
cp -r skills/* .claude/skills/

# Agents（evanflow-coder-overseer 使用的自定义 subagents）
mkdir -p .claude/agents
cp agents/*.md .claude/agents/

# Git guardrails hook（可选但推荐）
mkdir -p .claude/hooks
cp hooks/block-dangerous-git.sh .claude/hooks/
chmod +x .claude/hooks/block-dangerous-git.sh

然后在你的 .claude/settings.json 中注册 hook：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}

可选地，将 examples/CLAUDE.md.snippet 粘贴到你的项目的 CLAUDE.md 中以向 Claude 说明 EvanFlow 的惯例。

验证任何安装路径

重启 Claude Code。尝试说：

"Let's evanflow this — I want to add a small feature that does X."

evanflow-go 应该启动并遍历循环。验证 guardrail hook（仅路径 1 和 3）：从 Bash tool 尝试 git reset --hard HEAD——它应该被阻止，提示"BLOCKED: ... matches dangerous pattern"。

自定义你的 EvanFlow 安装

每个 skill 都有一个清晰的结构，带有一个 ## Hard Rules 部分。若要适配你的项目：

如果你发现自己重复回答同一个问题，请替换像 evanflow-writing-plans 这样的 skills 中的 <frontend> 和 <backend> 占位符为你的实际路径。

在你的 CLAUDE.md 中记录你的项目的质量检查——精确的 typecheck、lint 和 test 命令。Skills 抽象地引用这些。

如果你没有 chromium 可用，请在 evanflow-iterate 中调整视觉验证步骤——替换为 google-chrome --headless 或另一个工具。

编辑 evanflow-coder-overseer 中的内聚契约模板以匹配你的项目惯例（你的认证中间件名称、你的数据库写助手等）。

Skills 设计为可编辑的。把它们当作起点，不是福音。

如果你 fork 制作供应商特定的变体（your-name-flow），很好——这就是精神所在。

EvanFlow 端到端工作方式

You say: "let's evanflow this — I want to add a feature that does X"
           │
           ▼
       evanflow-go (the conductor)
           │
           ├─ Phase 0: Restate idea, scope check
           ├─ Phase 1: evanflow-brainstorming (CHECKPOINT: design approval)
           ├─ Phase 2: evanflow-writing-plans (CHECKPOINT: plan approval)
           │            └─ Step 2.5: parallelization check
           ├─ Phase 3: evanflow-executing-plans (sequential)
           │            OR
           │            evanflow-coder-overseer (parallel)
           │              ├─ contract with named tests + integration tests
           │              ├─ RED checkpoint (all coders write failing tests, orchestrator verifies)
           │              ├─ GREEN phase (vertical-slice TDD per coder)
           │              ├─ per-coder overseers (review, never fix)
           │              └─ integration overseer (runs touchpoint tests)
           ├─ Phase 4: evanflow-iterate (5x cap, Five Failure Modes pass)
           └─ Phase 5: STOP. Report what was done. Await your direction.

跨越：evanflow-compact 在清晰的边界运行，当上下文变重时。

特殊用途的 skills（evanflow-debug、evanflow-improve-architecture、evanflow-design-interface、evanflow-glossary、evanflow-prd、evanflow-qa、evanflow-review）在流程中相关时被拉入。

项目结构

.
├── .claude-plugin/
│   ├── plugin.json          — plugin identity (name, description, version)
│   └── marketplace.json     — marketplace manifest (lists EvanFlow as one bundled plugin)
├── skills/                  — 16 SKILL.md folders
│   ├── evanflow/
│   ├── evanflow-go/
│   ├── evanflow-brainstorming/
│   ... (etc)
├── agents/                  — 2 custom subagent definitions
│   ├── evanflow-coder.md
│   └── evanflow-overseer.md
├── hooks/
│   ├── hooks.json           — auto-activated when plugin installs
│   └── block-dangerous-git.sh
├── examples/
│   └── CLAUDE.md.snippet    — for the manual-copy install path
├── docs/
│   └── skills-audit.md      — verdict on all 38 candidate skills considered
├── README.md
└── LICENSE                  — MIT

致谢与来源

EvanFlow 综合了以下想法：

mattpocock/skills by Matt Pocock——vertical-slice TDD、深模块、删除测试、双重设计、通用语言、grill-me、caveman。

superpowers by Jesse Vincent——completion 前验证、代码审查模式、并行 agent 调度、finishing-a-development-branch（4 选项呈现）。

git-guardrails-claude-code——捆绑在 hooks/ 中（脚本逐字复制）。原作者 Matt Pocock。

指导设计的行业研究：

Anthropic 的 2026 Agentic Coding Trends Report

9 Critical Failure Patterns of Coding Agents (DAPLab, Columbia)

Test-Driven Development for Code Generation (arXiv 2402.13521)——断言正确性研究

贡献

欢迎 issues 和 pull requests。EvanFlow 的设计本身是有主见的——添加仪式或自动动作的提议会被礼貌地拒绝。进一步减少仪式、锐化规则或添加证据支持的改进的提议非常欢迎。