II · Planning & Control FlowEmerging★

Spec-Driven Loop

also known as Naive Iterative Loop, Ralph Wiggum Loop, Ralph Loop

Run the same prompt against a fixed spec in a deterministic outer loop until the spec is satisfied.

This pattern helps complete certain larger patterns —

  • used-byControl-Flow Integrity★— Treat the agent's planned step sequence as a trusted control-flow graph that tool outputs, retrieved content, and user-supplied data cannot redirect at runtime.

Context

A team works on a task with a clear or steadily-improvable specification — a long bug-fix list, a feature build that decomposes into small chunks, a migration whose end state is well-defined. Each iteration can move the codebase a little closer to the spec without trying to land everything at once. The team has a test suite or a similar gate that can tell whether the spec has been satisfied.

Problem

Agents that try to plan and implement the whole feature in a single turn are brittle because they have to hold too many decisions in one context and they cannot back out of a bad early commitment. Agents driven from a free-form chat wander, lose their plan, and produce work that is hard to resume after an interruption. Custom orchestration frameworks add their own complexity for what should be a simple loop. The team wants something brutally simple — re-run the agent against the spec until the spec is satisfied — without losing the ability to inspect, pause, and resume.

Forces

  • The spec must be good or the loop polishes the wrong artefact.
  • Tests gate progress; without them the loop has no error signal.
  • Cost per iteration must be tolerable for hundreds of runs.

Example

A team is fixing a long-tail bug list across a large repo. A free-form chat session wanders, plans become stale, and progress is hard to measure. They write a deterministic outer loop (`while :; do cat PROMPT.md | claude-code; done`) where the prompt names one task, references a fix_plan.md the agent itself updates, and exits when the spec is satisfied. Progress becomes legible: tasks tick off, the loop terminates, and resuming after interruption is a no-op.

Diagram

Solution

Therefore:

An outer shell loop (`while :; do cat PROMPT.md | claude-code ; done`) runs the same prompt repeatedly. The prompt encodes one task at a time, references a fix_plan.md that the agent itself updates, and ends with a test invocation that gates the next iteration. Subagents are used for parallel reads; build/test stays serial.

What this pattern forbids. Each loop iteration is constrained by the spec and the test gate; the agent cannot expand scope without editing the spec first.

The smaller patterns that complete this one —

  • usesSpec-First Agent★— Drive the agent loop from a human-authored specification document rather than free-form prompts.

And the patterns that stand alongside it, or against it —

  • complementsStep Budget★★— Cap the number of tool calls or loop iterations the agent is allowed within a single request.
  • alternative-toScheduled Agent★★— Run the agent on a fixed schedule independent of user requests.
  • composes-withPre-Flight Spec Authoring★— Before any code is generated, author a multi-pillar spec and have the agent critique it for ambiguity and edge cases, so that the loop executes against a reviewed target rather than a fresh prompt.
  • complementsRigor Relocation★— Relocate verification rigor from the model loop to surrounding scaffolding (evals, judges, decision logs, policy gates) so failures are caught by the wrapper rather than the agent.
  • complementsDeterministic Control Flow, Not Prompt★— Branching decisions live in deterministic application code while the LLM is invoked at strategic points to produce structured signals that the code branches on.
  • complementsOwn Your Prompts (12-Factor Agents)★— Every prompt in a production agent is versioned, tested, and owned by the team in the application repo — never inherited as a framework default.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

Used in frameworks

Show 1 more

References

Provenance