Ralph Wiggum Bdd

[](https://github.com/hesreallyhim/awesome-claude-code)

Co-Authored-By: Claude

Functionality overview

A standalone Bash script that runs the Claude Code agent in a loop to implement software requirements using Behavior-Driven Development (BDD). Inspired by the [Ralph Wiggum](https://ghuntley.com/ralph/) approach.

In principle, while running unattended, the script can keep code and requirements in sync. In practice, it requires interactive human supervision.

See [scripts/ralph-wiggum-bdd.sh](scripts/ralph-wiggum-bdd.sh) for the functionality details (yes, read the script).

The script may improve generated code quality compared to a standalone agent because:

• Each iteration of the loop uses a fresh prompt, avoiding the quality and speed degradation caused by growing context rot.
• Each commit represents a completed, tested unit, which simplifies review.

It may fail to generate the desired code because, among others:

• Requirements are incomplete, ambiguous, or contradictory.
• The agent does not reliably follow instructions (anthropics/claude-code/issues/13689); for example, it may silently skip tests when unable to run them, or decide to implement multiple features in one iteration.
• The agent does not terminate the iteration and enters a whack-a-mole pattern, switches between non-working solutions, requests human guidance, or continues despite task completion.

Usage examples

Prerequisites

• Linux or macOS (Windows users need WSL)
• Claude Code CLI installed and configured (claude command available)
• Git installed and configured
• A Gherkin test framework installed (Behave for Python, Cucumber for Ruby/JS/TS, etc.)

Installation

git clone https://github.com/marcindulak/ralph-wiggum-bdd
cd ralph-wiggum-bdd
export PATH="${PATH}:$(pwd)/scripts"

The [scripts/ralph-wiggum-bdd.sh](scripts/ralph-wiggum-bdd.sh) script is standalone.

...