Loop Engineering

现在很多人用 Claude Code、Codex 或者 Cursor 的时候，

还跟聊天机器人一样操作：

先扔个 prompt → 等它回 → 复制出来 → 改改 bug → 再扔新 prompt……循环往复。

这个 repo 直接告诉你：

别再自己一直 prompt 了，

你去设计一个 loop，

让这个 loop 自动去给 agent 下指令、指挥它干活。

里面已经帮你准备好好几种现成的 loop，比如：

• 每天任务分流 loop • PR 自动审查 loop • CI 检查 loop • 依赖更新 loop • 写 changelog loop • 合并后自动清理 loop • issue 分类处理 loop

还附带了好几个 CLI 工具，能让你：

• 把 loop 放大规模 • 估算大概花多少 token • 检查你的 repo 适不适合用这套东西 • 给 agent 加记忆/状态 • 加人工接管环节 • 加验证关卡 • 还能安全地通过 GitHub Actions 跑

以前 Prompt Engineering 是教你怎么写好指令，

现在 Loop Engineering 是让你搭一个系统， 让 agent 自己跑、自己检查、自己改、自己扩展，

你只要在关键节点看看就行。

https://github.com/cobusgreyling/loop-engineering…

cobusgreyling/loop-engineering

Source: https://github.com/cobusgreyling/loop-engineering

Loop Engineering

Stop prompting. Design the loop. Get a score.

npx @cobusgreyling/loop-init .

loop-init scaffolds skills, state, and budget files, then prints your Loop Ready score and first loop command. Swap --tool for claude, codex, or opencode.

Loop engineering replaces you as the person who prompts the agent — you design the system that does it instead.

New here? Quickstart (5 min) · Interactive picker

For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agents.

→ Interactive showcase + pattern picker · Essay · Addy Osmani

Contents

• Quickstart (5 min)
• Quick Links
• Why This Matters
• The Five Building Blocks + Memory
• Patterns
• Getting Started (5 minutes)
• Examples by Tool
• Operating & Safety
• Caveats
• Contributing
• Sources
• License

Quick Links

Why This Matters

Peter Steinberger:

“You shouldn’t be prompting coding agents anymore. You should be designing loops that prompt your agents.”

Boris Cherny (Head of Claude Code at Anthropic):

“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 leverage point has moved from crafting individual prompts to designing the control systems that orchestrate agents over time.

The Five Building Blocks + Memory

Full detail: docs/primitives.md · Cross-tool matrix: docs/primitives-matrix.md

Visual Overview

Anatomy of a Loop

flowchart LR
    A[Schedule / Automation] --> B[Triage Skill]
    B --> C[Read + Write STATE / Memory]
    C --> D[Isolated Worktree]
    D --> E[Implementer Sub-agent]
    E --> F[Verifier Sub-agent<br/>tests + gates]
    F --> G[MCP / Git / Tickets]
    G --> H{Human Gate?}
    H -->|safe / allowlisted| I[Commit / PR / Action]
    H -->|risky / ambiguous| J[Escalate to human<br/>with full context]
    I --> A
    J --> A

This reference repo now runs its own validate-patterns + audit workflows on every push/PR (see .github/workflows/). We also added LOOP.md describing the loops that will maintain it.

Patterns

Not sure which to pick? Try the interactive picker or pattern-picker.

Machine-readable index: patterns/registry.yaml (7 patterns)

Getting Started (5 minutes)

# 1. Scaffold + get your Loop Ready score (printed automatically)
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok

# 2. Estimate token spend for your cadence
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1

# 3. Re-audit after improvements
npx @cobusgreyling/loop-audit . --suggest

# Optional: paste Loop Ready badge into your README
npx @cobusgreyling/loop-audit . --badge

# 4. See scores climb: empty → L1 → L2
bash scripts/before-after-demo.sh

# 5. Start report-only (Grok example)
/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.

All three CLIs publish to npm from tagged releases — see docs/RELEASE.md. No clone required.

Develop from source (monorepo contributors):

cd tools/loop-init && npm ci && npm test && node dist/cli.js /path/to/project --pattern daily-triage --tool grok
cd tools/loop-audit && npm ci && npm test && node dist/cli.js /path/to/project --suggest
cd tools/loop-cost && npm ci && npm test && node dist/cli.js --pattern ci-sweeper --cadence 15m

Phased rollout: L1 report → L2 assisted fixes → L3 unattended — see loop-design-checklist.

Examples by Tool

• Grok
• Claude Code
• Codex
• OpenClaw
• Opencode
• GitHub Actions

Operating & Safety

• Failure Modes — incident-style catalog
• Anti-Patterns — design mistakes before production
• Multi-Loop Coordination — when loops collide
• Operating Loops — cost, logging, when to kill
• Safety — denylist, auto-merge, MCP scopes
• Security — reporting and unattended automation risks
• Concepts — intent debt, comprehension debt, harness vs loop
• MCP Cookbook — connector examples by pattern

Caveats

Loop engineering amplifies judgment — both good and bad.

• Token costs can explode with sub-agents and long-running loops.
• Verification is still on you. Unattended loops make unattended mistakes.
• Comprehension debt grows faster unless you read what the loop ships.
• Two people can run the same loop and get opposite results. The loop doesn’t know. You do.

Addy Osmani:

“Build the loop. But build it like someone who intends to stay the engineer, not just the person who presses go.”

Help wanted

First PR? Start with the contributor quickstart — ~10 min to ~1 hr tasks with same-day review on stories and adopters.

Comment “I’ll take this” on any good first issue for assignment.

Contributing

Share production patterns, tool mappings, and failure stories. See CONTRIBUTING.md (contribution ladder + good first issue backlog), adopters, and GitHub Discussions.

Sources

• Cobus Greyling – Loop Engineering (Substack)
• Addy Osmani – Loop Engineering
• Attribution & further reading

License

MIT

Practical, tool-aware reference for loop engineering, patterns you can clone, checklists you can ship against, and stories that include what broke.

Essay · Showcase · Cobus Greyling