EvanFlow – A TDD driven feedback loop for Claude Code

Apr 27, 2026•evanklem2004•View Original

TL;DR Highlight

16 Claude Code skills enforce a TDD loop with approval checkpoints and git guardrails

Who Should Read

A backend or full-stack developer using Claude Code who worries the agent skips tests or commits on its own

Core Mechanics

Brainstorm→plan→execute→iterate loop
- Saying "let's evanflow this" makes evanflow-go run the whole loop.
- Checkpoints sit at design approval, plan approval, and after iteration.
- It ends with STOP and waits for your direction.
TDD is discipline inside each task, not a phase
- Each cycle is one failing test, minimal impl, then refactor.
- Refactoring is not deferred to the end.
- Tests check behavior through public interfaces so they survive refactors.
Iterate is capped at 5 rounds
- It re-reads the diff, runs quality checks, and screenshots UI changes.
- It uses a Five Failure Modes checklist: hallucinated actions, scope creep, cascading errors, context loss, tool misuse.
Git is never touched automatically
- No auto-commit, no auto-stage, no PR proposals.
- A PreToolUse hook blocks git push, reset --hard, clean -f and similar.
- If jq is missing, the hook fails silently and nothing is blocked.
Parallel coder/overseer mode for 3+ independent tasks
- Each unit gets one coder and one read-only overseer.
- The overseer only has Read, Grep, Glob, so it cannot edit code.
- An integration overseer runs touchpoint tests that act as the executable contract.
Every rule cites its source
- The never-invent-values rule cites the DAPLab/Columbia failure patterns paper.
- Over 62% of LLM-generated test assertions were incorrect in a HumanEval evaluation, which motivates the assertion checks.
- No-auto-commit and no-skill-tax are labeled as the author's opinion, not research.

Community Reactions

Opinion that superpowers already covers TDD
- Several commenters said superpowers/brainstorming already does TDD well.
- They saw little need for this project.
Opinion that hooks, not prompts, should enforce TDD
- One commenter said nizos/tdd-guard is the only project they've seen that enforces TDD by blocking edits with hooks.
- They argued prompt-based rules get lost as context rots.
Experience that parallel mode needs worktree isolation
- A commenter said parallel agents pass their own tests but seams break at merge.
- Each branch needs a failing test not masked by another branch's green run, and worktree isolation handles that.
Pushback on vertical slice and refactoring
- One commenter worried vertical-slice TDD lets the LLM tailor tests to the implementation, and considered horizontal TDD.
- Another said refactoring is the first casualty in AI-assisted TDD once a test goes green.
- The author mentioned making refactoring happen every cycle.

How to Apply

Install the plugin and run one small feature
- In Claude Code, run /plugin marketplace add evanklem/evanflow then /plugin install evanflow@evanflow and restart.
- Start with "Let's evanflow this — I want to add a small feature X".
- Confirm it stops at the design and plan approval checkpoints.
Install jq and verify the git guard hook
- Without jq the hook fails silently, so run apt install jq or brew install jq first.
- Try git reset --hard HEAD from the Bash tool and check for the BLOCKED message.
Write your quality check commands in CLAUDE.md
- List the exact typecheck, lint, and test commands.
- The skills reference them before reporting done.
Use parallel mode only for 3+ independent tasks
- When step 2.5 offers parallelization, name the touchpoint integration tests in the contract first.
- Edit the contract template to your conventions, such as auth middleware or DB write helper.

Try It

copy & run

# Paste into Claude Code as-is (simplified EvanFlow-style loop, works without the plugin)

Let's work on {{feature description}} with this loop:
1. Brainstorm: propose 2–3 approaches and stress-test each (what breaks if a user does X? rollback? out of scope?). Wait for my approval.
2. Plan: list file structure first, then small tasks. Wait for my approval.
3. Execute with vertical-slice TDD: write ONE failing test, run it and show it fails, write minimal impl, refactor while the test is fresh, then next test. Test behavior through public interfaces. For each assertion, check whether a one-character bug in the implementation would still pass it.
4. Iterate (max 5 rounds): re-read the diff; check dead code, naming, and these failure modes: hallucinated actions, scope creep, cascading errors, context loss, tool misuse. Run {{typecheck/lint/test commands}}.
Rules: never invent file paths, env vars, IDs, or APIs; ask if unsure. Never run git commit/add/push. When done, STOP and report.

Terminology

vertical-slice TDDInstead of writing all tests first, you finish one test and one implementation at a time. Like cooking one dish fully before starting the next.

overseerA review subagent that can only read and report, not fix. Tool permissions make editing impossible.

deletion testAsk what happens if you delete a module: does complexity vanish? If nothing changes, the module is unnecessary.

grillA stress test before locking a plan: what breaks, what is the rollback, what is out of scope.

PreToolUse hookA script that runs right before the agent executes a tool. It acts like a bouncer that blocks dangerous commands at the door.

Related Resources

EvanFlow – A TDD driven feedback loop for Claude Code

Apr 27, 2026•evanklem2004•View Original

TL;DR Highlight

16 Claude Code skills enforce a TDD loop with approval checkpoints and git guardrails

Who Should Read

A backend or full-stack developer using Claude Code who worries the agent skips tests or commits on its own

Core Mechanics

Brainstorm→plan→execute→iterate loop
- Saying "let's evanflow this" makes evanflow-go run the whole loop.
- Checkpoints sit at design approval, plan approval, and after iteration.
- It ends with STOP and waits for your direction.
TDD is discipline inside each task, not a phase
- Each cycle is one failing test, minimal impl, then refactor.
- Refactoring is not deferred to the end.
- Tests check behavior through public interfaces so they survive refactors.
Iterate is capped at 5 rounds
- It re-reads the diff, runs quality checks, and screenshots UI changes.
- It uses a Five Failure Modes checklist: hallucinated actions, scope creep, cascading errors, context loss, tool misuse.
Git is never touched automatically
- No auto-commit, no auto-stage, no PR proposals.
- A PreToolUse hook blocks git push, reset --hard, clean -f and similar.
- If jq is missing, the hook fails silently and nothing is blocked.
Parallel coder/overseer mode for 3+ independent tasks
- Each unit gets one coder and one read-only overseer.
- The overseer only has Read, Grep, Glob, so it cannot edit code.
- An integration overseer runs touchpoint tests that act as the executable contract.
Every rule cites its source
- The never-invent-values rule cites the DAPLab/Columbia failure patterns paper.
- Over 62% of LLM-generated test assertions were incorrect in a HumanEval evaluation, which motivates the assertion checks.
- No-auto-commit and no-skill-tax are labeled as the author's opinion, not research.

Community Reactions

Opinion that superpowers already covers TDD
- Several commenters said superpowers/brainstorming already does TDD well.
- They saw little need for this project.
Opinion that hooks, not prompts, should enforce TDD
- One commenter said nizos/tdd-guard is the only project they've seen that enforces TDD by blocking edits with hooks.
- They argued prompt-based rules get lost as context rots.
Experience that parallel mode needs worktree isolation
- A commenter said parallel agents pass their own tests but seams break at merge.
- Each branch needs a failing test not masked by another branch's green run, and worktree isolation handles that.
Pushback on vertical slice and refactoring
- One commenter worried vertical-slice TDD lets the LLM tailor tests to the implementation, and considered horizontal TDD.
- Another said refactoring is the first casualty in AI-assisted TDD once a test goes green.
- The author mentioned making refactoring happen every cycle.

How to Apply

Install the plugin and run one small feature
- In Claude Code, run /plugin marketplace add evanklem/evanflow then /plugin install evanflow@evanflow and restart.
- Start with "Let's evanflow this — I want to add a small feature X".
- Confirm it stops at the design and plan approval checkpoints.
Install jq and verify the git guard hook
- Without jq the hook fails silently, so run apt install jq or brew install jq first.
- Try git reset --hard HEAD from the Bash tool and check for the BLOCKED message.
Write your quality check commands in CLAUDE.md
- List the exact typecheck, lint, and test commands.
- The skills reference them before reporting done.
Use parallel mode only for 3+ independent tasks
- When step 2.5 offers parallelization, name the touchpoint integration tests in the contract first.
- Edit the contract template to your conventions, such as auth middleware or DB write helper.

Try It

copy & run

# Paste into Claude Code as-is (simplified EvanFlow-style loop, works without the plugin)

Let's work on {{feature description}} with this loop:
1. Brainstorm: propose 2–3 approaches and stress-test each (what breaks if a user does X? rollback? out of scope?). Wait for my approval.
2. Plan: list file structure first, then small tasks. Wait for my approval.
3. Execute with vertical-slice TDD: write ONE failing test, run it and show it fails, write minimal impl, refactor while the test is fresh, then next test. Test behavior through public interfaces. For each assertion, check whether a one-character bug in the implementation would still pass it.
4. Iterate (max 5 rounds): re-read the diff; check dead code, naming, and these failure modes: hallucinated actions, scope creep, cascading errors, context loss, tool misuse. Run {{typecheck/lint/test commands}}.
Rules: never invent file paths, env vars, IDs, or APIs; ask if unsure. Never run git commit/add/push. When done, STOP and report.

Terminology

vertical-slice TDDInstead of writing all tests first, you finish one test and one implementation at a time. Like cooking one dish fully before starting the next.

overseerA review subagent that can only read and report, not fix. Tool permissions make editing impossible.

deletion testAsk what happens if you delete a module: does complexity vanish? If nothing changes, the module is unnecessary.

grillA stress test before locking a plan: what breaks, what is the rollback, what is out of scope.

PreToolUse hookA script that runs right before the agent executes a tool. It acts like a bouncer that blocks dangerous commands at the door.

EvanFlow – A TDD driven feedback loop for Claude Code

TL;DR Highlight

Who Should Read

Core Mechanics

Community Reactions

How to Apply

Try It

Terminology

Related Papers

Related Resources

EvanFlow – A TDD driven feedback loop for Claude Code

TL;DR Highlight

Who Should Read

Core Mechanics

Community Reactions

How to Apply

Try It

Terminology

Related Papers

Related Resources