Loop Engineering: Stop Prompting the Agent—Design a System That Prompts the Agent

Why Loop Engineering Matters

The PDF Loop Engineering: The Anthropic Playbook for Designing Systems That Prompt Your Agents argues that engineering AI agents is not about crafting prettier prompts; it is about constructing a system that repeatedly runs, can be audited, remembers its work, and self‑triggers without a human at the keyboard.

Four‑Layer Stack

Prompt Engineering focuses on a single sentence; Context Engineering decides what to put in the current window; Harness Engineering selects tools, actions, permissions, and completion criteria for one run. Loop Engineering sits above these layers and asks: How can a run become repeatable, verifiable, and self‑sustaining?

Five Essential Actions in a Loop

Discovery : the system autonomously identifies the work worth doing this round.

Handoff : the work is handed to an appropriate agent in an isolated execution environment.

Verification : an independent evaluator decides whether the result is acceptable.

Persistence : state is written outside the chat window (e.g., state.md, a linear board, PRs, inbox files).

Scheduling : the next round is triggered automatically at the right time.

Omitting any of these actions produces a “bad loop” that either stalls, repeats work, or runs without proper checks.

Six Core Components

The actions map to six system parts:

Automations – schedule or event triggers (Scheduling).

Worktrees – isolated directories for parallel agents (Handoff).

Skills – durable project knowledge files that drive Discovery.

Connectors – external interfaces (issue trackers, CI, databases) that expand the loop’s view.

Sub‑agents – separate generator and reviewer agents (Verification).

Memory – persistent state on disk (Persistence).

Generator / Evaluator Separation

The playbook stresses that the code‑writing agent must never judge its own output. An evaluator should:

Assume the code is bad until proven otherwise.

Validate behavior by running tests, lint, or real‑world actions.

Be a different model or instruction set from the generator.

Have explicit stop conditions (e.g., all tests pass, lint clean, UI behaves correctly).

This mirrors the maker‑checker principle: the maker creates, the checker validates.

Common Pitfalls (Five Bad Loops)

Missing Verification – the loop never says “no”, leading to unchecked runs.

Missing Persistence – the loop forgets yesterday’s work and repeats discoveries.

Missing Scheduling – the loop runs only when manually triggered.

Missing Discovery – humans still feed the task list each morning.

Missing Handoff – parallel agents clash on the same files.

Real‑World Example: Stripe’s Minions

Stripe merges >1300 machine‑generated PRs weekly. The key is not a giant LLM but a deterministic orchestrator that gathers links, Jira tickets, documentation, and code locations before handing creative work to the model. Rules handle the “gatekeeping”; the LLM handles only the creative part.

Implicit Debt Types

The PDF identifies four hidden debts that accumulate silently:

Verification debt – untested changes that explode later.

Comprehension rot – engineers lose mental models of the codebase.

Cognitive surrender – over‑reliance on the loop erodes judgment.

Token blowout – unbounded retries and helper calls cause cost overruns.

These debts reinforce each other, making long‑running loops risky.

Building Your First Loop

The playbook provides a concrete checklist:

What does Discovery read (CI, issues, commits, previous state)?

Where is the persistent state file?

Does an independent evaluator exist that can say “no”?

Is each parallel agent given its own git worktree?

Are per‑run, daily, and max‑retry token caps enforced?

Where does Human Review intervene?

Human review is not a temporary scaffold; it remains the permanent gate for any loop.

Full Example: Morning‑Triage Loop with Codex

A minimal, end‑to‑end loop is built around the Codex CLI. It runs every morning via a GitHub Actions cron, reads failed CI runs, new issues, and recent commits, writes findings to state/triage.md, creates an isolated git worktree for each “ready” finding, asks Codex to generate a fix, then runs a separate Codex evaluator that only outputs PASS or REJECT. Successful fixes are committed and opened as PRs; rejected ones are moved to an inbox for later human triage.

Key code snippets (wrapped in

tags) illustrate the workflow:</p><code>yaml
# .github/workflows/morning-triage.yml
name: morning-triage
on:
  schedule:
    - cron: "0 22 * * *" # UTC 22:00 = Beijing 06:00
  workflow_dispatch:
jobs:
  triage:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: write
      issues: read
      pull-requests: write
      actions: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Run Codex morning triage loop
        run: ./scripts/loop/morning-triage.sh
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          MAX_READY_FINDINGS: "3"

markdown
# .codex/skills/morning-triage/SKILL.md
---
name: morning-triage
description: 每天早上读取 CI、issue、commit，找出值得处理的工程 finding。
---
## Read
- 过去 24 小时失败的 CI run
- 过去 24 小时新开的 issue
- 昨天合并到 main 的 commit
- 上一次留下的 `state/triage.md`
## Judge
保留满足任一条件的 finding：
- 阻塞 main 分支
- 影响发布
- issue 有明确复现步骤
- commit 引入了可疑失败
## Write
把结果写入 `state/triage.md`，每条 finding 必须包含：
- id
- source
- priority
- hypothesis
- next_action
- status
## Stop
不要自动合并。不要删除代码。信心不足的 finding 写入 `state/inbox.md`

bash
#!/usr/bin/env bash
set -euo pipefail
codex --ask-for-approval never exec \
  -C "$PWD" \
  -s workspace-write \
  -o codex-triage-summary.md \
  - <<'PROMPT'
Use the morning-triage skill at .codex/skills/morning-triage/SKILL.md.
Read CI, issues, commits, and state/triage.md.
Update state/triage.md and state/inbox.md.
Do not modify application code in this discovery step.
PROMPT

After discovery, a Bash loop creates a git worktree for each ready finding, runs Codex to generate a fix, then runs a separate evaluator (also Codex) that checks tests, lint, boundary conditions, and UI behavior. Only when the evaluator returns PASS does the script commit, push, and open a PR; otherwise the report is saved to an inbox file for later human attention.

Design Discipline

The overarching lesson is to treat loop engineering as a disciplined engineering practice: let machines handle repeatable generation, enforce strict verification, persist state outside volatile chat, cap token usage, and always retain a human checkpoint. Designing loops this way lets engineers step out of mechanical toil while staying in the decision‑making seat.