---
title: "Loop Engineering"
section: "raw"
type: "source"
created: "2026-08-27"
updated: "2026-08-27"
canonical: "https://pyweb.dev/wiki/raw/articles/addy-osmani-loop-engineering-2026"
---
# Loop Engineering

By Addy Osmani (2026). Originally published on Substack.

A comprehensive analysis of loop engineering: replacing manual prompting with autonomous systems, the 5 core primitives, and managing comprehension debt.

## Core Extraction Summary

### 1. Named Frameworks & Patterns (Author's Exact Words)
- **"Loop Engineering"**: "Replacing yourself as the person who prompts the agent. You design the system that does it instead."
- **"The Five Pieces of a Loop"**:
  1. *Automations*: Heartbeat running on schedules to discover and triage work.
  2. *Worktrees*: Git worktrees isolating parallel agent file checkouts.
  3. *Skills*: `SKILL.md` files encoding project conventions and intent so agents don't guess.
  4. *Plugins and Connectors*: Model Context Protocol (MCP) servers connecting agents to issue trackers, DBs, Slack.
  5. *Sub-agents*: Splitting the maker from the checker.
- **"Memory/State file"**: Durable markdown (`AGENTS.md`, Linear board) holding task state outside the context window ("the agent forgets, the repo doesn't").
- **"The Orchestration Tax"**: Cognitive overhead of coordinating and reviewing multiple parallel agent streams.
- **"Intent Debt"**: Accumulation of unstated requirements where agents fill holes with plausible but incorrect assumptions.
- **"Comprehension Debt"**: The growing delta between the repository's complexity and the human engineer's mental model when agents generate code unread.
- **"Cognitive Surrender"**: Passively accepting AI output to avoid thinking.

### 2. Decision Rules
- **When running parallel agents on the same repository**, assign each session its own git worktree, **because** shared working directories lead to mechanical file collision and merge chaos.
- **When establishing project standards**, write them down once as an agent skill (`SKILL.md`), **because** without skills the agent re-derives project conventions from zero every session and fills gaps with guesses.
- **When structuring agent architectures**, split the drafting sub-agent from the reviewing sub-agent, **because** the model that wrote the code is excessively lenient grading its own work.
- **When operating loops**, review the code yourself and maintain mental models, **because** unattended loops generate code faster than human comprehension, leading to compounding architectural rot.

### 3. Anti-Patterns & Failure Mechanisms
- **"Prompting the agent manually"**: Sitting in single-thread prompt-response cycles for repeatable tasks.
- **"Shared checkout concurrency"**: Multiple agents modifying the same file tree simultaneously without worktree isolation.
- **"Cognitive surrender"**: Trusting green checkmarks and agent self-reports without independent verification or understanding.

### 4. Quantitative Claims & Qualifiers
- Faros AI (March 2026 dataset, 22,000 developers across 4,000 teams):
  - Code churn up **+861%**.
  - Incidents-to-PR ratio up **+242.7%**.
  - Per-developer defect rate up from **9% to 54%**.
  - Median review duration up **+441.5%**.
  - PRs merged with zero review up **+31.3%**.
- GitClear (2025 dataset): daily AI users generate **~4x the raw output** for only **~12% real delivered value gain**.
- CodeRabbit (Dec 2025 study, 470 PRs): AI-written code produces **1.7x more issues** (logic/correctness issues +75%, security issues 1.5–2x).

### 5. What the Source Does NOT Claim
- Does **NOT** claim that loop engineering allows engineers to stop reviewing code; claims that review and verification become the primary bottleneck and most leveraged skill in software.

---

## Full Text

**Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead.** A loop here can be thought of a recursive goal where you define a purpose and the AI iterates until complete.

Peter Steinberger recently said: “You shouldn’t be prompting coding agents anymore. You should be designing loops that prompt your agents.” Similarly, Boris Cherny, head of Claude Code at Anthropic, said: “I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops”.

### The Five Pieces of a Loop

1. **Automations**: Discovery and triage on a schedule. In Codex app via Automations tab; in Claude Code via scheduled tasks, cron, `/loop`, `/goal`, and GitHub Actions.
2. **Worktrees**: Isolate parallel features. Built-in worktree per thread or `git worktree` / `--worktree`.
3. **Skills**: Codify project knowledge in `SKILL.md` so the agent doesn't start cold.
4. **Plugins and Connectors**: Connect external tools via MCP (Model Context Protocol).
5. **Sub-agents**: Keep the maker away from the checker.
6. **State (Memory)**: Markdown files (`AGENTS.md`) or Linear boards holding durable progress. "The agent forgets, the repo doesn't."

### What the Loop Still Does Not Do For You

1. **Verification is still on you**: A loop running unattended is a loop making mistakes unattended. "Done" is a claim, not a proof.
2. **Understanding rots**: The faster the loop ships code you did not write, the bigger the comprehension debt.
3. **Cognitive surrender**: Taking whatever the loop gives back without critical evaluation. Designing loops with judgment accelerates engineering; designing them to avoid thinking accelerates disaster.

---

## Agent Navigation

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt