evanklem/evanflow

# EvanFlow **一个由TDD驱动的、用于与Claude Code进行软件开发的迭代反馈循环。** 16项内聚技能 + 2个自定义子智能体，将一个想法从头脑风暴引导至实现，全程设有检查点让您保持掌控。一个入口点：说*"let's evanflow this"*，编排器即运行该循环。 ``` brainstorm → plan → execute (vertical-slice TDD per task) → iterate → STOP └─ sequential, or parallel coder/overseer ``` TDD不是在执行之后的独立阶段——它是*嵌入*在每个编码任务中的纪律。执行阶段是脚手架（任务跟踪、阻塞项、质量检查）；`evanflow-tdd`是在任何产出生产代码的任务内部运行的内容。 该循环是**指挥者，而非自动驾驶**：在设计审批、计划审批和迭代后均设有真正的检查点。智能体会在每次git操作前停下，等待您的指示。无自动提交。无强制仪式。无“必须调用技能”的负担。 ## 快速安装 **推荐**路径 — Claude Code的插件市场： ``` /plugin marketplace add evanklem/evanflow /plugin install evanflow@evanflow ``` 重启，然后尝试： `evanflow-go` 会触发并引导整个循环。Git防护栏钩子会随插件自动激活（无需编辑settings.json）。技能出现在 `evanflow:` 命名空间下（例如，`/evanflow:evanflow-go`）。 下方见[安装说明](#installation)以了解两种替代路径。 ## 是什么使其成为反馈循环 该循环围绕**跨越迭代累积的纪律**构建，而非一次性生成。每个步骤都有一个门控下一步的检查点： - **头脑风暴**澄清意图，提出2-3种带有嵌入式压力测试的方法 → 您批准设计 - **计划**首先映射文件结构（深度模块、删除测试） → 您批准计划 - **执行**逐任务运行，并进行内联验证 → 阻塞项会停止循环并呈现给您。在每个编码任务内部，**TDD**是纪律（而非之后才有的独立阶段）。 - **TDD**仅采用垂直切片方式，**每个周期都进行完整的 RED → GREEN → REFACTOR**：一个失败的测试 → 最小化实现 → 重构*（在您刚刚编写的测试作为安全网仍然新鲜时进行）* → 下一个测试。重构不被推迟到末尾。测试通过公共接口验证行为，因此它们能经受住重构 - **迭代**用新眼光重新审视差异，运行质量检查，截取UI变更屏幕截图，并依据一份五项失效模式检查清单（虚构操作、范围蔓延、级联错误、上下文丢失、工具误用）运行。硬性上限为5次迭代 - **停止。**报告。等待您的指示。智能体从不自动提交，从不自动暂存，从不提议创建PR 对于包含3个以上真正独立单元的计划，该循环会分叉成一个**并行编码器/监督者编排**：每个单元一个编码器（使用带RED检查点的垂直切片TDD），每个编码器一个监督者（只读审查子智能体，不能修改代码），加上一个集成监督者在每个连接点运行指定的集成测试。集成测试*就是*可执行的契约——如果双方都必须满足相同的通过测试，接口就不会漂移。 ## 内嵌的硬性规则 下面每条规则都引用了其来源。如果缺少引用，该规则源于在实际项目上运行循环得出的经验观点，而非研究——已如此标明。 - **绝不虚构数值** — 文件路径、环境变量、ID、函数名、库API。如果不确定，智能体会停止并询问。*来源：在[DAPLab/Columbia《编码智能体的9种关键失效模式》](https://daplab.cs.columbia.edu/general/2026/01/08/9-critical-failure-patterns-of-coding-agents.html)中，虚构动作是头号失效模式。* - **断言正确性警告** — 在对四种LLM进行的HumanEval评估中，超过62%的LLM生成的测试断言是不正确的。*来源：[《面向代码生成的测试驱动开发》(arXiv 2402.13521)](https://arxiv.org/pdf/2402.13521)，§3.2。* `evanflow-tdd`和监督者审查都会显式检查：实现中一个字符的错误是否仍能让断言通过。 - **五项失效模式检查** 在迭代 + 监督者审查中进行 — 虚构动作、范围蔓延、级联错误、上下文丢失、工具误用。*来源：综合自上述DAPLab失效模式论文。* - **上下文漂移监控** — `evanflow-compact` 在清晰的阶段边界以及出现漂移症状（重复询问已确定的问题、与先前决策矛盾）时触发。*来源：2025年近65%的企业AI失败归因于多步推理过程中的上下文漂移或记忆丢失，而非原始上下文耗尽——参见[Alex Merced，《OpenCode的上下文管理策略》（2026年3月）](https://datalakehousehub.com/blog/2026-03-context-management-opencode/)。* - **永不自动提交，永不自动暂存** — 经验观点，非研究。源于在实际项目上运行循环：每次智能体决定集成，它都集成错了。 - **无技能税** — 经验观点。技能是工具，而非收费站。 ## 技能集 ### 默认循环 (5项技能) | 技能 | 用途 | |---|---| | `evanflow-brainstorming` | 澄清意图，提出2-3种带有嵌入式压力测试的方法。为纯视觉请求提供快速模式原型。 | | `evanflow-writing-plans` | 首先规划文件结构，细分任务，嵌入式压力测试。步骤2.5在计划可并行化时提供`evanflow-coder-overseer`。 | | `evanflow-executing-plans` | 逐任务执行，并进行内联验证。步骤0再次提供并行路径选项。交给迭代阶段，然后停止。 | | `evanflow-tdd` | 垂直切片TDD。一个测试 → 一个实现 → 重复。通过公共接口验证行为。断言正确性警告。 | | `evanflow-iterate` | 实现后的自我审查循环。重新阅读差异，修复问题，运行质量检查，截取UI屏幕截图（通过无头Chromium）。五项失效模式检查清单。硬性上限为5次迭代。 | ### 专用技能 (9项) | 技能 | 用途 | |---|---| | `evanflow-go` | **单一入口点。** 说"let's evanflow this"，它将引导整个循环。 | | `evanflow-coder-overseer` | 并行实现：编码器/监督者对 + 集成监督者 + 可执行的内聚性契约。适用于包含3个以上独立任务的计划。 | | `evanflow-glossary` | 提取规范领域术语到`CONTEXT.md`。标记歧义和同义词。 | | `evanflow-improve-architecture` | 通过删除测试 + 深度模块词汇来揭示重构机会。 | | `evanflow-design-interface` | "设计两遍" — 生成3个以上具有截然不同约束的并行子智能体，从深度/简单性/效率方面进行比较。 | | `evanflow-debug` | 根本原因分析纪律。明确陈述假设，在修复前进行嵌入式压力测试，先写失败测试。 | | `evanflow-review` | 代码审查的双方（给出 + 接收）。不要向您无法辩解的反馈妥协。 | | `evanflow-prd` | 从现有上下文综合出PRD。用于实质性新功能。 | | `evanflow-qa` | 对话式bug发现 → issue草稿。提交前先询问。 | ### 横切技能 (1项) | 技能 | 用途 | |---|---| | `evanflow-compact` | 长会话上下文管理。在清晰边界进行主动总结的策略。漂移症状检查清单。 | ### 元技能 (1项) | 技能 | 用途 | |---|---| | `evanflow` | 索引。共享词汇 + 何时调用每个 `evanflow-*` 技能。 | ### 自定义子智能体 (2个) 位于 `agents/` — 通过带 `subagent_type:` 参数的 `Agent` 工具调用： | 子智能体 | 工具限制 | 用途 | |---|---|---| | `evanflow-coder` | 读取, 编辑, 写入, Glob, Grep, Bash, TodoWrite | `evanflow-coder-overseer` 的实现子智能体。工具 + 系统提示防止git操作、范围外编辑、数值虚构。 | | `evanflow-overseer` | 读取, Grep, Glob（无编辑/写入/Bash） | 只读审查子智能体。工具从物理上强制"报告发现，永不修复"。 | ### 捆绑钩子 `hooks/block-dangerous-git.sh` — PreToolUse钩子，阻止破坏性git操作（`git push`, `git reset --hard`, `git clean -f`, `git branch -D`, `git checkout .`, `git restore .`）。随插件安装路径自动激活。 ## 硬性规则 (适用于所有技能) 1. **永不自动提交，永不自动暂存，永不自动完成。** 每次git写入操作都需要您在当前轮次中明确要求。 2. **永不虚构数值。** 文件路径、环境变量、ID、函数名、库API — 如果不确定，智能体会停止并询问。 3. **无技能税。** 临时问题不需要调用技能。技能是工具，而非收费站。 4. **无强制的规范/计划路径。** 文件放在您希望的位置。 5. **声称完成前需验证。** 在任何"完成"报告前运行质量检查（类型检查、lint、测试）。 ## 要求 - **[Claude Code](https://claude.com/claude-code)** （任何近期版本） - **Bash** — 用于捆绑的钩子脚本（Linux、macOS或Windows + WSL） - **`jq`** — 钩子脚本使用它来解析Claude的JSON工具输入。通过 `apt install jq`, `brew install jq` 或您平台的包管理器安装。**如果缺少 `jq`，防护栏钩子会静默失败，且危险的git操作不会被阻止。** 可选但推荐： - **`chromium`** 或 **`google-chrome`** — 用于 `evanflow-iterate` 对UI变更的视觉验证（`chromium --headless --screenshot=...`）。如果缺失会优雅降级 — 技能会标记并要求您进行视觉验证。 ## 安装 三条路径，按优先级排序。所有三条路径最终都会将相同的技能集放入您的 `.claude/skills/`。插件路径还会自动连接防护栏钩子。 ### 路径 1 — Claude Code 插件市场 (推荐) 这是最干净的安装方式。技能、智能体和防护栏钩子全部自动激活。 ``` /plugin marketplace add evanklem/evanflow /plugin install evanflow@evanflow ``` 重启 Claude Code（或 `/reload-plugins`）。技能以命名空间形式出现，如 `/evanflow:evanflow-go`, `/evanflow:evanflow-tdd` 等。通过"let's evanflow this"的自动调用无论命名空间如何都有效。 卸载：`/plugin uninstall evanflow@evanflow`。 ### 路径 2 — `npx skills@latest add` CLI 适用于任何具有 `SKILL.md` 形式文件夹的GitHub仓库。仅安装技能 — **不安装防护栏钩子或自定义子智能体**（如果您需要，需手动添加）。 ``` # 一次性安装全部 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 # ... ``` 这会将技能放置在 `~/.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 使用的自定义子代理） 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` 中注册钩子： ``` { "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。尝试说： `evanflow-go` 应该会触发并引导您完成循环。要验证防护栏钩子（仅路径1和3）：尝试从Bash工具运行 `git reset --hard HEAD` — 它应被阻止并显示"BLOCKED: ... matches dangerous pattern"。 ## 定制 每个技能都有一个清晰的结构，包含 `## 硬性规则` 部分。要适应您的项目： - **替换技能（如 `evanflow-writing-plans`）中的 `` 和 `` 占位符** 为您的实际路径，如果您发现自己重复回答相同问题。 - **在您的 `CLAUDE.md` 中记录您项目的质量检查** — 确切的 `typecheck`, `lint` 和 `test` 命令。技能会抽象地引用这些命令。 - **调整 `evanflow-iterate` 中的视觉验证步骤**，如果您没有可用的 `chromium` — 替换为 `google-chrome --headless` 或其他工具。 - **编辑 `evanflow-coder-overseer` 中的内聚性契约模板** 以匹配您项目的约定（您的认证中间件名称、您的数据库写入助手等）。 这些技能被设计为可编辑的。将它们视为起点，而非金科玉律。 如果您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` 会在清晰边界运行。 专用技能（`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 ``` ## 许可证 MIT。详见 [LICENSE](LICENSE)。 ## 贡献 欢迎提交问题和拉取请求。EvanFlow在设计上是有主见的——旨在增加仪式感或自动操作的提议将被礼貌地拒绝。旨在**进一步减少**仪式感、强化规则或添加有证据支持的改进的提议非常受欢迎。

标签：AI编程, AI辅助编码, Claude Code, SOC Prime, 代码质量保障, 任务管理, 反馈循环, 垂直切片开发, 应用安全, 开发工具, 开发插件, 开发效率, 开发流程优化, 插件市场, 敏捷开发, 数据管道, 检查点控制, 测试驱动开发, 编程助手, 网络可观测性, 软件工程, 软件开发, 迭代开发