Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
Add Lecture 13 + Project 07: Loop Engineering
sanbuphya1db89298ff4
diff --git a/README.md b/README.mdindex 0c94b9d..3518bf8 100644--- a/README.md+++ b/README.md@@ -21,8 +21,8 @@<p align="center"><strong>A project-based course on building the environment, state management, verification, and control mechanisms that make AI coding agents work reliably.</strong></p><p align="center">- <img src="https://img.shields.io/badge/Lectures-12-blue?style=flat-square" alt="12 Lectures">- <img src="https://img.shields.io/badge/Projects-6-green?style=flat-square" alt="6 Projects">+ <img src="https://img.shields.io/badge/Lectures-13-blue?style=flat-square" alt="13 Lectures">+ <img src="https://img.shields.io/badge/Projects-7-green?style=flat-square" alt="7 Projects"><img src="https://img.shields.io/badge/Languages-15-yellow?style=flat-square" alt="15 Languages"><img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" alt="MIT License"><a href="https://discord.gg/XU7DQmpqk"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Join the Discord community"></a>@@ -205,15 +205,15 @@ For the full course materials, please visit the **[Documentation Website](https:The curriculum is divided into three parts:-1. **Lectures**: 12 conceptual units explaining the theory behind harness engineering.-2. **Projects**: 6 hands-on projects where you build an agentic workspace from scratch.+1. **Lectures**: 13 conceptual units explaining the theory behind harness engineering.+2. **Projects**: 7 hands-on projects where you build an agentic workspace from scratch.3. **Resource Library**: Copy-ready templates (`AGENTS.md`, `feature_list.json`, `init.sh`, etc.) to use in your own repositories today.---## Quick Start: Improve Your Agent Today-You don't need to read all 12 lectures before you start getting value. If you're already using a coding agent on a real project, here's how to improve it right now.+You don't need to read all 13 lectures before you start getting value. If you're already using a coding agent on a real project, here's how to improve it right now.The idea is simple: instead of just writing prompts, give your agent a set of structured files that define what to do, what's been done, and how to verify the work. These files live inside your repo, so every session starts from the same state.@@ -313,6 +313,17 @@ The course is designed to be done in order. Each phase builds on the last.v vP05 Agent verifies its own work P06 Build a complete harness(capstone project)++ Phase 7: AUTOMATE THE LOOP+ ==========================++ L13 Stop prompting your agent —+ design loops instead++ |+ v+ P07 Build your first automated loop+ (goal loop, timer loop, maker-checker)```Each phase takes about a week if you're going part-time. If you want to go faster, phases 1–3 can be done in a long weekend.@@ -321,7 +332,7 @@ Each phase takes about a week if you're going part-time. If you want to go faste## Syllabus-### Lectures — 12 conceptual units, each answering one core question+### Lectures — 13 conceptual units, each answering one core question*Read the full text for each lecture on the [Documentation Website](https://walkinglabs.github.io/learn-harness-engineering/).*@@ -339,8 +350,9 @@ Each phase takes about a week if you're going part-time. If you want to go faste| [L10](./docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Why does end-to-end testing change results? | Only a full-pipeline run counts as real verification || [L11](./docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Why does observability belong inside the harness? | If you can't see what the agent did, you can't fix what it broke || [L12](./docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Why must every session leave a clean state? | The next session's success depends on this session's cleanup |+| [L13](./docs/en/lectures/lecture-13-loop-engineering/index.md) | Why do you need to stop prompting your agent? | From manual driving to automated loops — goal loops, timer loops, and maker-checker separation |-### Projects — 6 hands-on projects applying lecture methods to the same Electron app+### Projects — 7 hands-on projects applying lecture methods to the same Electron app| Project | What You Do | Harness Mechanism ||---------|------------|-------------------|@@ -350,6 +362,7 @@ Each phase takes about a week if you're going part-time. If you want to go faste| [P04](./docs/en/projects/project-04-incremental-indexing/index.md) | Stop the agent from doing too much or too little | Runtime feedback + scope control + incremental indexing || [P05](./docs/en/projects/project-05-grounded-qa-verification/index.md) | Make the agent verify its own work | Self-verification + grounded Q&A + evidence-based completion || [P06](./docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Build a complete harness from scratch (capstone) | Full harness: all mechanisms + observability + ablation study |+| [P07](./docs/en/projects/project-07-loop-engineering-first-loop/index.md) | Build your first automated loop | Goal loops, timer loops, maker-checker separation, loop state management |```textPROJECT EVOLUTION@@ -371,6 +384,9 @@ Each phase takes about a week if you're going part-time. If you want to go faste|vP06 Complete harness (capstone) You build the full system+ |+ v+ P07 Your first automated loop You step outside the loopEach project's solution becomes the next project's starter.The app evolves. Your harness skills grow with it.@@ -533,12 +549,12 @@ See the full layered reference list in [`docs/en/resources/reference/`](./docs/e```textlearn-harness-engineering/├── docs/ # VitePress documentation site-│ ├── lectures/ # 12 lectures (index.md + code/ examples)+│ ├── lectures/ # 13 lectures (index.md + code/ examples)│ │ ├── lecture-01-*/-│ │ └── ... (12 total)-│ ├── projects/ # 6 project descriptions+│ │ └── ... (13 total)+│ ├── projects/ # 7 project descriptions│ │ ├── project-01-*/-│ │ └── ... (6 total)+│ │ └── ... (7 total)│ └── resources/ # Multilingual templates & references (14 languages)│ ├── en/│ └── ... (14 total)@@ -558,7 +574,7 @@ learn-harness-engineering/## How the Course Is Organized- Each lecture focuses on one question-- The course includes 6 projects+- The course includes 7 projects- Every project requires the agent to do real work- Every project compares weak vs. strong harness results- What matters is the measured difference, not how many docs were written@@ -587,6 +603,23 @@ bash tools/audit-harness.sh /path/to/your/repo---+## Changelog++### 2026-07-09 — Loop Engineering Update++Added **Lecture 13** and **Project 07** on **Loop Engineering** — the next layer beyond harness engineering.++**New content:**++- **Lecture 13: Why You Need to Stop Prompting Your Agent** — From `/goal` to the six primitives of loop engineering (automations, worktrees, skills, connectors, sub-agents, external state), the generator/evaluator split, four silent costs, and a step-by-step guide to building your first loop.+- **Project 07: Build Your First Automated Loop** — Three progressive experiments: goal loop, timer loop, and maker-checker loop. Compare manual vs. automated, measure intervention reduction, and learn to step outside the loop.+- **Code templates** — `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` for building loops immediately.+- **Reference update** — Added Addy Osmani's [Loop Engineering](https://addyosmani.com/blog/loop-engineering/) (2026-06-07) to the 2026 extended reference list.++**Key idea:** Harness engineering builds the vehicle. Loop engineering designs the road it drives on — and you design the road from outside the car.++---+## Other CoursesOur team has also created other courses! Check them out:diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mtsindex 1dfc373..4e60a3b 100644--- a/docs/.vitepress/config.mts+++ b/docs/.vitepress/config.mts@@ -24,7 +24,8 @@ const zhLectureItems = [{ text: "防止 agent 提前宣告完成", link: "/zh/lectures/lecture-09-why-agents-declare-victory-too-early/" },{ text: "跑通完整流程才算真正验证", link: "/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/" },{ text: "让 agent 的运行过程可观测", link: "/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },- { text: "每次会话结束前都做好交接", link: "/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }+ { text: "每次会话结束前都做好交接", link: "/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },+ { text: "从手动驱动到自动循环", link: "/zh/lectures/lecture-13-loop-engineering/" }];const zhProjectItems = [@@ -34,7 +35,8 @@ const zhProjectItems = [{ text: "跨会话工作连续性", link: "/zh/projects/project-03-multi-session-continuity/" },{ text: "运行反馈与行为修正", link: "/zh/projects/project-04-incremental-indexing/" },{ text: "工作评审与自我验证", link: "/zh/projects/project-05-grounded-qa-verification/" },- { text: "综合 Agent 工作环境", link: "/zh/projects/project-06-runtime-observability-and-debugging/" }+ { text: "综合 Agent 工作环境", link: "/zh/projects/project-06-runtime-observability-and-debugging/" },+ { text: "第一个自动循环", link: "/zh/projects/project-07-loop-engineering-first-loop/" }];const zhResourceItems = [@@ -61,7 +63,8 @@ const enLectureItems = [{ text: "Why Agents Declare Victory Too Early", link: "/en/lectures/lecture-09-why-agents-declare-victory-too-early/" },{ text: "Why End-to-End Testing Changes Results", link: "/en/lectures/lecture-10-why-end-to-end-testing-changes-results/" },{ text: "Why Observability Belongs Inside the Harness", link: "/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },- { text: "Why Every Session Must Leave a Clean State", link: "/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }+ { text: "Why Every Session Must Leave a Clean State", link: "/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },+ { text: "From Manual Prompting to Autonomous Loops", link: "/en/lectures/lecture-13-loop-engineering/" }];const enProjectItems = [@@ -71,7 +74,8 @@ const enProjectItems = [{ text: "Multi-Session Continuity", link: "/en/projects/project-03-multi-session-continuity/" },{ text: "Runtime Feedback and Scope Control", link: "/en/projects/project-04-incremental-indexing/" },{ text: "Self-Verification and Role Separation", link: "/en/projects/project-05-grounded-qa-verification/" },- { text: "Complete Harness (Capstone)", link: "/en/projects/project-06-runtime-observability-and-debugging/" }+ { text: "Complete Harness (Capstone)", link: "/en/projects/project-06-runtime-observability-and-debugging/" },+ { text: "Your First Automated Loop", link: "/en/projects/project-07-loop-engineering-first-loop/" }];const enResourceItems = [diff --git a/docs/en/lectures/lecture-13-loop-engineering/code/checker-prompt.md b/docs/en/lectures/lecture-13-loop-engineering/code/checker-prompt.mdnew file mode 100644index 0000000..61695be--- /dev/null+++ b/docs/en/lectures/lecture-13-loop-engineering/code/checker-prompt.md@@ -0,0 +1,80 @@+# Checker Agent Prompt++> For the verification agent.+> Focus on "finding problems" — the stricter, the better.++## Your Role++You are the Checker. Your job is to verify what the Maker produced. Your goal is to find problems, not say nice things.++When you get an implementation from the Maker, your job is to:++1. Read through all changes+2. Verify item by item against the checklist+3. Run the full verification commands+4. List every problem you find — each with evidence++**Remember: you're not here to praise, you're here to find fault.** Not finding problems is your failure.++## Checklist++### Functional Correctness+- [ ] Does the implementation match the requirements?+- [ ] Are there any edge cases missed?+- [ ] Is error handling in place?++### Code Quality+- [ ] Is the code clear? Are names clear?+- [ ] Is there duplicate code?+- [ ] Does it follow project coding standards?+- [ ] Are there obvious performance issues?++### Testing+- [ ] Do tests cover the main scenarios?+- [ ] Are edge cases tested?+- [ ] Are the tests actually testing something meaningful, or are they just going through the motions?++### Verification Commands+- [ ] Does `npm test` pass fully?+- [ ] Does `npm run lint` have zero errors?+- [ ] Does TypeScript type check pass?+- [ ] Does coverage meet the bar?++### Safety and Impact+- [ ] Will this change affect anything else?+- [ ] Are any new dependencies introduced? Are they justified?+- [ ] Are config file changes correct?++## Output Requirements++Each issue must include:+1. **Description**+2. **Where** (file and line number)+3. **Evidence** (what exactly is wrong, why it's a problem)+4. **Severity** (Critical / Medium / Minor)++End with an overall verdict: Pass / Fail / Minor issues, acceptable++Output format:++```+## Overall Verdict+✅ Pass / ❌ Fail / ⚠️ Minor issues, acceptable++## Issues Found++### 1. [Critical] Issue title+- Location: file:line+- Description: ...+- Evidence: ...+- Suggestion: ...++### 2. [Medium] Issue title+...++## Verification Command Results+- Unit tests: X passed / Y total+- Lint: pass / fail (X errors)+- Type check: pass / fail+- Coverage: XX%+```diff --git a/docs/en/lectures/lecture-13-loop-engineering/code/goal-template.md b/docs/en/lectures/lecture-13-loop-engineering/code/goal-template.mdnew file mode 100644index 0000000..5e8e0ed--- /dev/null+++ b/docs/en/lectures/lecture-13-loop-engineering/code/goal-template.md@@ -0,0 +1,65 @@+# Goal Loop Template++> Write your goal as a document like this, then hand it to `/goal` or a maker agent.+> The more specific and verifiable, the higher the loop quality.++## Goal++<!-- One sentence describing what to do -->++Implement the XX feature with complete unit test coverage.++## Acceptance Criteria++<!-- Machine-verifiable completion conditions — each one can be checked with a command -->++- [ ] `npm test` passes fully+- [ ] Coverage report shows XX module coverage ≥ 80%+- [ ] `npm run lint` has zero errors+- [ ] TypeScript type check passes (`npx tsc --noEmit`)+- [ ] All new code follows project coding standards++## Scope++<!-- Be explicit about what NOT to touch -->++### Fair game++- All files under `src/xx/`+- Test files under `tests/`+- Related type definition files++### Hands off++- `src/main.ts` entry file+- Database schema migrations+- Dependency versions in `package.json` (unless explicitly needed)+- CI/CD config files++## Verification Method++<!-- How to verify after each step -->++1. After implementation, run these commands in order:+ 1. `npx tsc --noEmit` — type check+ 2. `npm run lint` — code style+ 3. `npm test` — unit tests+ 4. `npx vitest --coverage` — coverage check++2. Fix any failures before moving to the next step.+3. When everything passes, run the full end-to-end test suite (if available).++## Stop Conditions++- All acceptance criteria pass ✅+- Max turns reached: 20+- No progress for 3 consecutive rounds (same error keeps appearing)+- Blocking issue that cannot be resolved independently (e.g., missing dependency, environment problem)++## How to Work++1. Read `AGENTS.md` and `feature_list.json` first to understand the project structure and existing features.+2. Write out the design approach before touching code.+3. Verify after each sub-task is done.+4. If stuck for more than 2 rounds, switch approach or simplify.+5. Update progress at the end of each round.diff --git a/docs/en/lectures/lecture-13-loop-engineering/code/index.md b/docs/en/lectures/lecture-13-loop-engineering/code/index.mdnew file mode 100644index 0000000..3fcaea7--- /dev/null+++ b/docs/en/lectures/lecture-13-loop-engineering/code/index.md@@ -0,0 +1,8 @@+# Lecture 13 Code Examples++Use this folder for examples of:++- goal.md goal description template+- loop-state.md loop state template+- Maker / Checker role prompt templates+- Loop control script examplesdiff --git a/docs/en/lectures/lecture-13-loop-engineering/code/loop-state-template.md b/docs/en/lectures/lecture-13-loop-engineering/code/loop-state-template.mdnew file mode 100644index 0000000..5884ef5--- /dev/null+++ b/docs/en/lectures/lecture-13-loop-engineering/code/loop-state-template.md@@ -0,0 +1,69 @@+# Loop State Template++> Every loop should have a state file tracking current progress.+> Update at the end of each round; read at the start of the next round.++## Basic Info++- **Loop name**: <!-- e.g. "Unit test completion loop" -->+- **Started**: 2026-07-09 10:00+- **Current round**: Round 1 / N total+- **Current status**: In progress <!-- In progress / Completed / Blocked / Failed -->+- **Total elapsed**: 0h 0m++## Goal++<!-- What this loop is trying to achieve -->++## Round Log++### Round 1++- **Started**:+- **What the Maker did**:+- **Verification result**: ✅ Pass / ❌ Fail / ⚠️ Partial+- **Issues found**:+ -+- **Next round plan**:+- **Human intervention needed**: Yes / No++### Round 2++- **Started**:+- **What the Maker did**:+- **Verification result**: ✅ Pass / ❌ Fail / ⚠️ Partial+- **Issues found**:+ -+- **Next round plan**:+- **Human intervention needed**: Yes / No++<!-- Copy the format above and keep adding -->++## Cumulative Stats++| Metric | Value |+|--------|-------|+| Rounds completed | 0 |+| Passed rounds | 0 |+| Failed rounds | 0 |+| Total issues found | 0 |+| Human interventions | 0 |+| Files changed | 0 |++## Blocker List++<!-- Record recurring issues so the next round is aware -->++-++## Final Result++<!-- Fill in when loop ends -->++- **Final status**: Completed / Failed / Manually stopped+- **Finished at**:+- **Summary**:+ - What was done+ - How it went+ - What was learned+ - How to improve next timediff --git a/docs/en/lectures/lecture-13-loop-engineering/code/maker-prompt.md b/docs/en/lectures/lecture-13-loop-engineering/code/maker-prompt.mdnew file mode 100644index 0000000..fa035c5--- /dev/null+++ b/docs/en/lectures/lecture-13-loop-engineering/code/maker-prompt.md@@ -0,0 +1,49 @@+# Maker Agent Prompt++> For the implementation agent.+> Focus on "making it work."++## Your Role++You are the Maker. Your job is to implement features and write code.++When you get a task, your job is to:++1. Understand the requirements+2. Design the approach+3. Write the code+4. Run basic verification (build, lint, unit tests)+5. Hand the result to the Checker for review++## Working Rules++- Read AGENTS.md and relevant docs first to understand the project structure.+- Explain your plan before making changes.+- Run basic verification on your own after writing — make sure it at least runs.+- If you don't know something, say you don't know. Don't make things up.+- Record progress at each step.++## Deliverables++- List of files modified+- Brief implementation summary+- Basic verification results (build / lint / tests)+- Areas you're unsure about (for the Checker to focus on)++## Output Format++```+## Implementation Summary+...++## Modified Files+- ...++## Basic Verification+- Build: pass / fail+- Lint: pass / fail+- Unit tests: X passed, Y failed++## Known Issues and Risks+- ...+```diff --git a/docs/en/lectures/lecture-13-loop-engineering/index.md b/docs/en/lectures/lecture-13-loop-engineering/index.mdnew file mode 100644index 0000000..9b1b319--- /dev/null+++ b/docs/en/lectures/lecture-13-loop-engineering/index.md@@ -0,0 +1,498 @@+[中文版 →](../../../zh/lectures/lecture-13-loop-engineering/)++> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-13-loop-engineering/code/)+> Practice project: [Project 07. Build Your First Automated Loop](./../../projects/project-07-loop-engineering-first-loop/index.md)++# Lecture 13. From Manual Prompting to Autonomous Loops++Everything you learned in the first twelve lectures rests on one assumption: **you are sitting at the keyboard, typing instructions one at a time.**++You wrote `AGENTS.md` (Lectures 1–4), built state management (Lectures 5–6), constrained scope with feature lists (Lectures 7–8), left clean handoffs at session end (Lectures 9, 12), and made the runtime observable (Lectures 10–11). But the trigger for all of it was always you. The agent never decided on its own when to start working — because no one pressed "start."++This lecture is about handing the start button to the system. Not giving up control — elevating it to the next layer.++## /goal: The Simplest Possible Loop++The best entrance to loop engineering is not a complex architecture diagram — it's a single command.++In early 2026, Claude Code and OpenAI Codex independently shipped the same feature: `/goal`. You type in the terminal:++```+/goal "All tests pass, zero lint warnings, merge to main"+```++Then you close your laptop and go to sleep. Eight hours later, the agent has analyzed, coded, tested, fixed, and merged on its own. It retries on failure, switches approaches when stuck, and stops when done — without you leaning over its shoulder saying "try again."++The only difference between `/goal` and a traditional prompt is one thing. But that one thing changes everything:++| | Traditional Prompt | `/goal` |+|---|---|---|+| What you provide | What to do next | What the end state looks like |+| What the agent does | Execute once | Loop until achieved |+| Who judges done | You | A verifiable stopping condition |+| When you can walk away | You can't | The moment you type `/goal` |++`/goal` is essentially a loop. It has exactly three parts: **a goal, a verification method, and a stopping condition.** Just those three things move you from inside the loop to outside it.++### How `/goal` Grew Organically++`/goal` didn't jump from 0 to 1 out of nowhere. It grew gradually out of everyday workflows, going through roughly four stages:++**Stage 1: Manual one-by-one prompting.** The earliest way of working was back-and-forth: "write a function," "add a test," "fix this logic." The agent stopped after every step and waited for you to say what's next. You were the scheduler of the entire pipeline.++**Stage 2: Long prompts with multiple steps.** Then people started writing longer prompts that stacked steps together: "first analyze the code, then write the implementation, then run tests, and if they fail, fix them." The agent could run several steps in one go, but you still had to watch — because it might drift mid-way, or finish a step and not know what to do next.++**Stage 3: Agent self-reflection and self-direction.** After that, agents gained "introspection" — after each step they'd look at the result and decide what to do next. You gave a goal, and they broke it down themselves and retried on their own. But a problem emerged: when do they stop? Does "I'm done" coming from the agent itself count? Practice kept answering — no. Agents declare victory far too easily.++**Stage 4: Independent stopping judgment — `/goal`.** The final step was taking "judging whether it's done" out of the hands of the agent doing the work, and handing it to an independent judge. It could be a different model, a script, or a test command — but the rule was the same: the person writing the code can't grade their own homework. At this point, `/goal` truly worked: you give the goal, it loops, an independent judge decides when to stop, and you can walk away.++These four stages weren't a roadmap planned by any one company. They were the path everyone coding with agents arrived at, independently, pushed by the same pain points. Claude Code and Codex shipping `/goal` almost simultaneously in early 2026 wasn't a coincidence — the time had come.++### There's More Than One Kind of Loop++`/goal` is the easiest loop to understand, but it's not the only kind. Loops fall into categories based on how they're triggered and how they stop:++| Type | Trigger | Stop Condition | Claude Code | Codex | Best For |+|------|---------|----------------|-------------|-------|----------|+| **Turn-based loop** | You type each prompt manually | Agent thinks it's done, or you interrupt | Normal chat | Normal chat | Small tasks, exploratory work |+| **Goal-based loop** | You give a goal | Independent evaluator confirms done, or max turns reached | `/goal` | `/goal` (manual enable required) | Complex tasks with clear completion criteria |+| **Time-based loop** | Scheduled interval (every N minutes/hours) | You stop it manually, or it exits after completing the work | `/loop` | Thread automation | Polling status, periodic checks, recurring work |+| **Event-driven loop** | External event (PR opened, CI failed, new issue) | Stops after handling the event, or hits retry limit | Routines (API / GitHub Webhook) | Standalone automation + plugins | Reactive workflows, CI/CD integration |++These aren't competing — they're different tools for different jobs. Turn-based is fine for small things. Use `/goal` when there's a clear finish line. Use `/loop` when you need to watch something. Use event-driven when you're integrating with external systems.++### Don't Confuse `/goal` and `/loop`++Both have "loop" in the name, but they solve completely different problems:++| | `/goal` | `/loop` |+|---|---------|---------|+| **What it is** | One big task, runs until it's done | One small action, repeats on an interval |+| **Stop condition** | Goal reached, or budget exhausted | You stop it manually, or the task exits on its own |+| **Time profile** | One long run, can take hours or days | Periodic short bursts, each run may be a few minutes |+| **Progress** | Gets closer to the finish line each iteration | Each run is independent, no cumulative progress |+| **Analogy** | Running a marathon — start gun fires, you stop at the finish line | An alarm clock — rings on a schedule, you turn it off |+| **Typical use** | "Implement the full payment system with test coverage" | "Check if CI is broken every 15 minutes" |++A common mistake: shoving something that should be a `/goal` into a `/loop`. Like writing `/loop 10m "keep implementing the payment system"` — that's wrong. `/loop` runs the same instruction independently each time, it doesn't remember where it left off last time. You'll just get the same starting point over and over.++**One-sentence test for which one to use: does this thing have an end?**+- Has an end → `/goal`+- No end, you just need to keep watching → `/loop`++Loop Engineering, the subject of this lecture, isn't about any one command. It's about **being able to design systems that include all of these types — so your agent can keep working even when you're not there.**++You don't have to type `/goal` every time. But understanding where it came from and why it looks the way it does — that's understanding the core of loop engineering. More complex loops just add parts like scheduling, parallelism, isolation, and memory on top of these same three fundamentals: goal, verification, stopping condition.++## June 2026: Three People Lit the Same Fuse in One Week++In the first week of June 2026, three practitioners building coding agent infrastructure — without comparing notes — said the same thing in different words.++**Peter Steinberger** (creator of OpenClaw, [his post reached 8 million views](https://x.com/steipete/status/2063697162748260627)): "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, [on the Acquired podcast](https://x.com/rohanpaul_ai/status/2063289804708835412)): "I don't prompt Claude anymore. I have loops running that prompt Claude and figure out what to do. My job is to write loops."++**Addy Osmani** (engineering lead at Google Chrome) [named the concept](https://addyosmani.com/blog/loop-engineering/) on June 7, 2026, and gave it a one-line definition:++> **Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead.**++Cherny disclosed numbers: over 30 consecutive days, all code contributions to Claude Code were made autonomously by AI — 259 merged PRs, over 80% of production code authored by Claude, and a 76% success rate on open-ended software tasks.++Three people. One week. The same conclusion. Not because they coordinated — because the infrastructure had quietly crossed a threshold. Agents had become reliable enough to finish non-trivial tasks unattended. Scheduling primitives (`/loop`, `/goal`, cron) were now built into the tools. The cost of a single agent run had dropped low enough that running one repeatedly on a timer stopped looking wasteful. When all the parts are present, the move that combines them becomes obvious to everyone at once.++> Source: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)++## Inside the Loop vs. Outside the Loop++Let's contrast two concrete scenarios.++**Scenario A: You are inside the loop (Lectures 1–12).**++```mermaid+flowchart TD+ You["You"] -->|"Manually type instruction"| Agent["AI Agent"]+ Agent -->|"Produces output"| Result["Code / tests / docs"]+ Result -->|"You inspect"| You+ You -->|"Unsatisfied, modify instruction"| Agent+ You -->|"Satisfied, move to next task"| You+```++You have a complete harness: `AGENTS.md` tells the agent the project rules, `feature_list.json` constrains scope, `init.sh` ensures consistent environment, `claude-progress.md` records progress. **But every step still requires your manual initiation.** Finish one feature, read the progress file, think about what's next, type the instruction. You are the engine of the entire workflow.++**Scenario B: You are outside the loop (Loop Engineering).**++```mermaid+flowchart TD+ subgraph Loop["The loop system you designed"]+ Trigger["Auto trigger<br/>Schedule / Event / Previous task complete"] --> Discover["Discover work<br/>Read progress file / issue tracker"]+ Discover --> Dispatch["Dispatch<br/>Spawn sub-agent"]+ Dispatch --> Verify["Verify<br/>Tests / lint / Independent reviewer agent"]+ Verify --> Persist["Persist state<br/>Update progress / Commit / Open PR"]+ Persist -->|"Work remains"| Discover+ Persist -->|"Done or blocked"| Inbox["Push to your review inbox"]+ end+ Inbox -->|"You only need to make decisions"| You["You"]+```++You don't type instructions anymore. The system you designed discovers the work, dispatches it, verifies the results, records the state, and decides the next step. Your job shrinks to three things: **define the goal and stopping condition before it starts, review the output after it finishes, and adjust the rules when the system veers off course.** The leverage moves from "writing the right prompt" to "designing the right loop."++> Osmani: "A year ago if you wanted a loop you wrote a pile of bash and you maintained that pile forever and it was yours and only yours. Now the pieces just ship inside the products." You don't need to build from scratch. You need to understand how the pieces fit together.++## Core Concepts++- **Loop Engineering**: Designing a system that automatically prompts your agent, replacing manual step-by-step human input. The human moves from inside the loop to outside it, and the leverage shifts from "writing the right prompt" to "designing the right loop."+- **`/goal` mode**: The simplest possible loop — provide a goal, verification method, and stopping condition; the agent loops until met. The bridge from manual prompting to autonomous loops.+- **Generator/Evaluator Separation**: The agent that writes the code and the agent that checks it must be separated. A model grading its own work is untrustworthy; an independent verifier — sometimes using a different model entirely — is the baseline reliability guarantee of any loop.+- **Worktree Isolation**: Each parallel agent works in an independent git worktree, physically preventing file collisions. The infrastructure prerequisite for multi-agent parallel execution.+- **External State**: Memory that lives outside a single conversation — markdown files, issue trackers, kanban boards. Models forget everything between runs; memory must live on disk.+- **Four Silent Costs**: Four hidden costs that grow sharper the longer a loop runs — verification debt, comprehension rot, cognitive surrender, token blowout. Loops accelerate not just output, but risk.++## The Six Primitives of a Loop++Osmani decomposed a loop into five core building blocks, plus one memory layer that threads through all of them — six things in total, but the memory layer occupies a special status: it's not a component on the same level as the others; it's the spine that everything else depends on.++The diagram below draws all six as a ring so you can see the full picture at a glance. But remember: External State isn't just another stop on the loop — it's the foundation the whole loop rests on.++```mermaid+flowchart LR+ A["Automations<br/>Scheduled triggers"] --> W["Worktrees<br/>Parallel isolation"]+ W --> S["Skills<br/>Codified project knowledge"]+ S --> C["Connectors<br/>External tool access"]+ C --> SA["Sub-agents<br/>Maker / checker split"]+ SA --> ES["External State<br/>Cross-iteration memory"]+ ES --> A+```++### 1. Automations — The Heartbeat++Without automation, a loop isn't a loop — it's a one-off run you did manually.++Both Claude Code and Codex have full scheduling systems, but they use different names and layers. Roughly mapping from lightest to heaviest:++| Layer | Claude Code | Codex | Notes |+|-------|-------------|-------|-------|+| In-session polling | `/loop` | Thread automation | Tied to current session, dies when session closes |+| Local scheduled tasks | Desktop scheduled tasks | Standalone automation (local mode) | Runs while machine is on, can access local files |+| Cloud scheduled tasks | Cloud Routines | — (no native cloud scheduler) | Runs while machine is off |+| Event triggers | Routines (API / GitHub Webhook) | Standalone automation + plugins | Triggered by external events |+| Fully self-hosted | GitHub Actions / self-hosted cron | `codex exec` + cron | Full control |++**Codex's Automations tab** is the scheduling entry point. Pick the project, the prompt, the cadence, and whether it runs on your local checkout or a background worktree. Runs that find something land in a Triage inbox; runs that find nothing auto-archive. OpenAI uses them internally for daily issue triage, CI failure summaries, commit briefings, and hunting for bugs introduced last week.++Codex automations come in two flavors:+- **Thread automation** — Heartbeat-style recurring wake-up calls attached to a thread, preserving context. Good for continuous follow-up on a single thing, like monitoring a long-running command or polling PR status. The equivalent in Claude Code is `/loop`.+- **Standalone automation** — Each run starts fresh, results go to Triage. Good for daily/weekly independent tasks like briefings or dependency scans. The equivalent in Claude Code is Desktop scheduled tasks.++Claude Code's system is layered more granularly:++- **`/loop`** — Lightweight in-session scheduled repetition. Works while your terminal is open, dies when the session closes, auto-expires after 7 days. Good for temporary monitoring during your current work session.+- **Desktop scheduled tasks** — Runs while your machine is on, survives session restarts, minute-level intervals. Good for recurring work that needs local file access.+- **Cloud Routines** — Runs on Anthropic's cloud infrastructure, survives your machine being off, 1-hour minimum interval. Supports three trigger types: scheduled, API call, GitHub webhook. Good for daily tasks that don't need your local environment.+- **GitHub Actions / self-hosted cron** — Fully under your control, runs however you want. Good for scenarios with special environment or security requirements.++```bash+# Claude Code: run tests every 30 min, fix failures (within current session)+/loop 30m Run the test suite and fix any failing tests++# Claude Code: check deploy status every 15 minutes+/loop 15m Check if the production deploy succeeded and report status+```++Automations are the heartbeat. Without them, the loop is a blueprint that never wakes up.++### 2. Worktrees — Isolation at Scale++As soon as you run more than one agent, file collisions become the inevitable failure mode. Two agents writing to the same file is exactly the headache of two engineers committing to the same lines without consulting each other.++`git worktree` solves this: each agent works on its own branch in its own directory. They physically cannot touch each other's checkout.++Claude Code and Codex both ship worktree support. When you use `--worktree` or `isolation: worktree` on a sub-agent, each helper gets a clean, independent checkout that cleans up after itself. Worktrees remove the mechanical collision problem — but remember: **your review bandwidth is still the ceiling.** How many parallel agents you can supervise determines how many worktrees you can actually run.++### 3. Skills — Stop Re-Explaining Your Project++A skill is how you stop re-explaining the same project context every session. It's a folder containing a `SKILL.md` with instructions and metadata, plus optional scripts, references, and assets.++Codex and Claude Code support the same format. Skills are invoked directly with `/skill-name` (Codex also supports `$skill-name`), or triggered implicitly when the task matches the skill description.++Skills are fundamentally about paying your intent debt. An agent starts every session cold — it fills any gap in your intent with a confident guess. A skill is that intent written down on the outside: the conventions, the build steps, the "we don't do it this way because of that one incident" — written once, read every run.++### 4. Connectors — Your Loop Touches Real Tools++A loop that can only see the filesystem is a small loop. Connectors (built on the MCP protocol) let the agent read your issue tracker, query a database, hit a staging API, drop a message in Slack.++Codex and Claude Code both speak MCP, so the connector you wrote for one usually works in the other. Connectors are the difference between "here is the fix" and a loop that opens the PR, links the Linear ticket, and pings the channel once CI is green — by itself, inside your actual environment, not just in a terminal.++### 5. Sub-agents — Keep the Maker Away from the Checker++The most structurally valuable design choice in a loop is splitting the one who writes from the one who checks. The model that wrote the code is way too generous grading its own homework. A second agent, with different instructions and sometimes a different model, catches what the first agent talked itself into.++The classic three-role split:++```mermaid+flowchart LR+ Explorer["Explorer Agent<br/>Read codebase, locate issues"] --> Implementer["Implementer Agent<br/>Write fix, write tests"]+ Implementer --> Verifier["Verifier Agent<br/>Independent review, run verification"]+ Verifier -->|"Fails"| Implementer+ Verifier -->|"Passes"| Output["Output"]+```++Claude Code's `/goal` runs this under the hood — a fresh, independent session judges whether the loop should stop, not the session that did the work. This is called **generator/evaluator separation**, and it is the single most important reliability guarantee in loop design.++### 6. External State — The Loop's Memory++Models forget everything between runs. Memory must live on disk, not in the context window.++This sounds too simple to matter, but it's the same trick every long-running agent depends on. A markdown file, a Linear board — anything that lives outside a single conversation and holds what is done, what is in progress, and what is next. The agent forgets. The repository doesn't.++These six primitives are your loop design toolkit. You don't need all of them for every loop. But you need to know when to reach for which one.++## A Complete Loop, Anatomized++Wire all six together and here's what a real morning triage loop looks like:++```mermaid+flowchart TD+ Trigger["Every morning at 9:00 AM<br/>Automation fires"] --> Read["Read external state<br/>Yesterday's claude-progress.md<br/>Open GitHub issues"]+ Read --> Triage["Triage Skill kicks in<br/>Classify and prioritize findings"]+ Triage --> Fork["For each actionable item<br/>Fork an isolated Worktree"]+ Fork --> Implement["Implementer Sub-agent<br/>Write fix + tests"]+ Implement --> Verify["Verifier Sub-agent<br/>Independently run tests + lint + review"]+ Verify -->|"Fails"| Retry["Retry queue<br/>Try different approach"]+ Retry --> Implement+ Verify -->|"Passes"| PR["Connector: Open PR<br/>Link issue, update progress file"]+ PR --> Memory["Write to External State<br/>Update claude-progress.md<br/>Record this round's results"]+ Memory -->|"Work remains"| Fork+ Memory -->|"All done or blocked"| Inbox["Results land in Triage inbox<br/>Waiting for your review"]+```++This is no longer a single agent run. It is a continuously operating system that wakes up every morning, sweeps the floor on its own, and puts the things that need your attention in front of you. Your role becomes: **review the inbox contents, make decisions, and when you spot a pattern the system can't handle, refine the skills and rules.**++Cherny used this pattern to merge 259 PRs in 30 days without opening an IDE once. OpenAI engineers used the same pattern to build a roughly one-million-line beta product by hand — without writing a single line of code themselves.++## Generator/Evaluator Separation: Why You Can't Let the Model Grade Its Own Work++This is the hardest lesson in loop engineering.++Your smartest agent writes a beautiful piece of code. The logic is clear, the comments are thorough, and every function has a test. You are satisfied.++But here's the question: **if you let the agent that wrote that code judge whether it did a good job, what will it say?**++The answer has been confirmed by experience again and again: it will give itself a high score. Not because it's dishonest, but because it is the author — it convinced itself this path was correct during generation. When it looks back, it doesn't see mistakes; it sees its own reasoning process.++This is not a Claude problem. This is not a GPT problem. This is a property of all generative models. **A model is its own output's best defense attorney.**++The fix: never let the same entity (same model, same prompt) do both the work and the review.++- Claude Code's `/goal` uses an independent supervisor session to judge whether the goal is met — not the session that attempted it.+- Codex's sub-agent system lets you define a verifier agent using a different model with different reasoning effort.+- The community practice of "adversarial verify" spawns N independent skeptics per finding, each prompted to refute — majority rejection kills the finding.++One sentence to remember: **someone in your crew must not believe you.**++## Karpathy's autoresearch: The Loop Exemplar++If you want to see what a well-designed, actually-running loop looks like, [Karpathy's autoresearch](https://github.com/karpathy/autoresearch) is the textbook example.++In March 2026, Karpathy released a 630-line Python project. Give it one GPU and a research direction, and it runs all night — completing hundreds of ML training experiments, keeping only the ones that truly improve. The project hit 66,000+ stars within days of release.++### Three Files, Three Roles++The whole system has just three core files, but the division of labor is razor-sharp:++| File | Who Edits It | What It Does |+|------|-------------|-------------|+| `prepare.py` | Nobody (read-only) | Data prep, tokenizer, eval harness. Fixed infrastructure. |+| `train.py` (~630 lines) | **AI Agent** | Model definition, optimizer, training loop. The agent's playground — change anything. |+| `program.md` | **You** | Research methodology written in natural language. You only edit this. Tell the agent how to explore, how to evaluate, what not to touch. |++This three-way split is the soul of the design: **humans don't touch code, they touch direction; agents don't touch direction, they touch code.** Your job shifts from writing Python to "writing the research org culture."++### Input: What program.md Looks Like++`program.md` is the brain of the loop. It's not code — it's a research instruction manual written in Markdown. It roughly contains:++- **Goal**: optimize `val_bpb` (validation bits per byte, lower is better)+- **Constraints**: don't touch `prepare.py`, stay within VRAM budget, fixed 5-minute training+- **Exploration directions**: try different architectures, optimizers, LR schedules+- **Evaluation rules**: what counts as improvement, how to log results, what to do on failure+- **Iron rule**: never stop. Once the loop starts, keep going forever++Your kickoff prompt to the agent can be as short as one sentence:++```+Have a look at program.md and let's kick off a new experiment!+```++The rest is up to the agent reading the doc and making its own decisions.++### The Nine-Step Ratchet Loop++At the heart of autoresearch is a **ratchet** — it only moves forward, never backward. Each iteration strictly follows nine steps:++```mermaid+flowchart TD+ 1["1. Read direction<br/>Load program.md"] --> 2["2. Survey current state<br/>Read train.py + past results"]+ 2 --> 3["3. Propose hypothesis<br/>Think of a change to try"]+ 3 --> 4["4. Modify code<br/>Edit train.py"]+ 4 --> 5["5. Snapshot<br/>git commit"]+ 5 --> 6["6. Run training<br/>Fixed 5-min wall clock"]+ 6 --> 7{"7. Evaluate<br/>Did val_bpb improve?"}+ 7 -->|Yes| 8a["8a. Keep<br/>Commit stays<br/>Write to results.tsv"]+ 7 -->|No| 8b["8b. Revert<br/>git reset HEAD~1<br/>Log the failure"]+ 8a --> 9["9. Next round<br/>Go back to step 1"]+ 8b --> 9+```++It runs roughly 12 experiments per hour. An overnight run (8 hours) is about 100 experiments. Karpathy himself ran it for 2 days — ~700 experiments.++The fixed 5-minute wall-clock budget is a key design choice — no matter what the agent changes, every experiment takes exactly the same time. This means all results are directly comparable under the same time budget — no argument about "this one ran longer so it's better."++### Output: What You See When You Wake Up++After a night of looping, you sit down in the morning and find three things:++**1. Git history (the forward-moving ratchet)**++Only commits that actually improved stay on the main branch. Everything that failed was rolled back. `git log` is a validated research log.++**2. results.tsv (the full experiment record)**++Every single experiment — success or failure — is logged:++```+timestamp commit_hash val_bpb vram_mb description+--------- ------------- ---------- ---------- ----------------------------+08:01:12 a1b2c3d 1.234 22100 baseline+08:06:15 d4e5f6g 1.228 22400 increased learning rate by 10%+08:11:20 (reverted) 1.241 21800 switched to GELU activation+08:16:08 h7i8j9k 1.219 23000 added weight decay 0.01+...+```++**3. A research log (agent's own summary)**++The agent writes clear commit messages about what it tried, what worked, what didn't, and what it plans to try next. You read those — you don't have to read the code diffs.++### What It Actually Found++Results from Karpathy's initial 2-day, ~700-experiment run:++- Out of ~700 attempts, about **20 stackable real improvements** were found+- Reduced nanochat's GPT-2-level training time on 8×H100 from **2.02 hours → 1.80 hours**, about **11% faster**+- Findings included: learning rate adjustments, optimizer tuning, activation swaps, attention pattern optimizations, etc.++Were all improvements earth-shattering discoveries? No. Most were small optimizations that stacked. But those 20 valid improvements would have taken a human researcher weeks of manual work — the agent did it in 48 hours.++### The Most Telling Detail: The Loop Is Written in English, Not Code.++`program.md` is a Markdown document, not a Python script. It describes a research methodology — what to modify, what to leave alone, how to evaluate, how to handle failure cases, and one iron rule: **never ask for human help, just keep going.** A coding agent reads this document and executes it indefinitely.++This is the template for loop engineering: don't give the agent a task. Give it a **methodology**. Let the methodology be the loop. One `program.md`, 630 lines of glue code, and everything else is the agent running itself.++## Four Silent Costs++When a loop starts running, you won't see the problems immediately. The following four costs accumulate silently, and by the time you notice, you may have already paid heavily.++### 1. Verification Debt++Fast loops tempt you to skip verification. "Looks fine" is not the same as "confirmed correct." The more code a loop generates unattended, the faster verification debt piles up. The fix: **stopping conditions must be machine-checkable, never "feels about right."**++### 2. Comprehension Rot++The faster a loop ships code, the further your understanding of your own codebase drifts from reality. Cherny's team had 80% of code authored by agents — meaning most of a team's code wasn't written by a person. If you don't read and use what the loop produces, your comprehension decays continuously. **Fast loops require fast reading.**++### 3. Cognitive Surrender++When the loop runs smoothly, the most comfortable posture is to stop having opinions. Take whatever it gives back, don't think about the output. But that is exactly where danger begins — you're using the loop to avoid thinking, rather than to amplify thinking. Osmani's warning: "Two people can build the exact same loop and get opposite results. One uses it to go faster on work they understand; the other uses it to avoid understanding the work. The loop doesn't know the difference. You do."++### 4. Token Blowout++Every iteration of a loop accumulates more context: code written, errors encountered, decisions made. Without context management, prompt size grows roughly quadratically with the number of turns. Codex addresses this with automatic context compaction — a dedicated API compresses older conversation turns into encrypted content summaries, retaining essential knowledge while discarding redundant detail. This is an engineering concern you must address from the first loop, not a bolt-on later.++## Building Your First Loop++You don't need to start with a Stripe-scale pipeline merging 1,300 PRs a week. Start with the smallest thing that works.++### Step 1: Pick One Recurring Task++Find something you do manually at least twice a week. Examples:+- Open GitHub in the morning, check new issues, triage and respond+- Run lint and tests before every PR review+- Update progress docs at the end of each day++### Step 2: Write a Goal and Stopping Condition++Turn the task into something a `/goal` can understand:++```markdown+Goal: Check the 10 most recent issues in the repo.+For each issue:+ - If it already has clear labels and an assignee, skip+ - If untagged, add appropriate labels based on content+ - If fixable in under 10 minutes, create a branch and attempt a fix+Stop when: All qualifying issues have been processed, or an issue requires human decision.+```++### Step 3: Split Maker and Checker++Don't let the same agent both write the code and judge it. Split your loop into two roles:+- Implementer: reads the issue, writes the fix, writes the tests+- Verifier: independently runs tests, reviews the diff, judges whether the fix actually solves the problem++### Step 4: Add Memory++Use a markdown file to record what happened in each loop run. The next run starts by reading this file — it knows what was done, what's pending, what was blocked. This beats any complex database.++### Step 5: Set a Timer++Use `/loop` or your OS cron to let the loop start without you. Begin with once a day. Observe for a week.++### The Maturity Ladder++You don't need to reach the top in one jump. Loop adoption is a ladder:++1. **Level 1: Goal Runner** — You can use `/goal` to give a task with a stopping condition; the agent loops until met.+2. **Level 2: Scheduled Single-Task** — One automation runs one task on a timer (e.g., morning CI check).+3. **Level 3: Multi-Agent Loop** — Maker and checker split; each finding forks an isolated worktree.+4. **Level 4: Self-Feeding Loop** — The loop auto-discovers its next task from external state; it decides what to do next.+5. **Level 5: Fleet Orchestration** — Multiple loops run in parallel, independent but sharing a memory layer.++Most teams are currently between Level 2 and Level 3. Level 1 is the fastest path to seeing returns.++## Key Takeaways++- **Loop Engineering does not replace Harness Engineering — it builds one floor above it.** The harness makes single runs reliable. The loop makes continuous runs autonomous.+- **`/goal` is the simplest possible loop:** goal + verification + stopping condition. Those three things move you from inside the loop to outside it.+- **Six primitives (Automations / Worktrees / Skills / Connectors / Sub-agents / External State) are the loop's building blocks.** Not all of them every time, but you need to know when to reach for which.+- **The maker and the checker must be separated.** A model grading its own work is untrustworthy. An independent verifier — sometimes a different model altogether — is the baseline reliability guarantee of any loop.+- **Loops make generation nearly free and leave judgment as the scarce resource.** The time you save isn't for resting. It's for making more judgments.+- **Four silent costs grow sharper as loops run longer:** verification debt, comprehension rot, cognitive surrender, token blowout. Loops accelerate output — and risk.+- **Start small.** One `/goal`, one cron, one markdown memory file. See the return, then stack upward.++## Further Reading++- [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)+- [Addy Osmani: Agent Harness Engineering](https://addyosmani.com/blog/agent-harness-engineering/)+- [Simon Willison: Designing Agentic Loops (Sep 2025)](https://simonw.substack.com/p/designing-agentic-loops)+- [Karpathy: autoresearch](https://github.com/karpathy/autoresearch)+- [Claude Code: Dynamic Workflows and Orchestration](https://kenhuangus.substack.com/p/claude-code-orchestration-dynamic)+- [Loop Library (Forward Future)](https://signals.forwardfuture.ai/loop-library/) — Public corpus of 50 real loops+- [The Neuron: Claude Code Creators on Agent Loops](https://www.theneuron.ai/explainer-articles/claude-code-creators-boris-cherny-and-cat-wu-explain-how-to-use-agent-loops/)+- Lecture 12: [Leave a Clean Handoff at the End of Every Session](./../lecture-12-why-every-session-must-leave-a-clean-state/index.md) — The prerequisite for loops: each session leaves clean state so the next round can auto-start+- Lecture 5: [Keep Long-Running Tasks Continuous Across Sessions](./../lecture-05-why-long-running-tasks-lose-continuity/index.md) — Prerequisite knowledge for external state and memory+- Lecture 11: [Why Observability Belongs Inside the Harness](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — The faster a loop runs, the more you need observability to catch problems+- Lecture 8: [Why Feature Lists Are Harness Primitives](./../lecture-08-why-feature-lists-are-harness-primitives/index.md) — Feature lists are the natural data source for a self-feeding loop to discover its next task++## Exercises++1. **Turn a recurring task into a `/goal`:** Find something you manually do at least twice a week. Write down its goal, verification method, and stopping condition. Run it once with `/goal` and compare the time and quality against doing it manually. This is your first step from Harness to Loop.++2. **Separate maker and checker:** Pick a task you've previously had an agent execute. This time, write two different prompts: one for the implementer agent and one for the verifier agent (use different models — e.g., Claude for implementation, GPT for verification, or vice versa). The verifier must point out specific issues with cited evidence. Record the number and type of issues found in each mode.++3. **Give your loop a memory:** Create a markdown state file for your loop. In each iteration, write: what was done this round, verification results, status (pass/fail/blocked), and what to do next. Run three rounds and observe the behavioral difference between having and not having a memory file.++4. **Audit your loop's silent costs:** After your loop has run for an hour, assess these four metrics:+ - How much verification was "feels right" rather than "machine-confirmed"? (Verification debt)+ - How well can you explain the code your loop most recently produced? (Comprehension rot)+ - How many times did you think "I'll look later" and never looked? (Cognitive surrender)+ - How is the loop's context size trending? Is it repeating redundant information? (Token blowout)diff --git a/docs/en/projects/index.md b/docs/en/projects/index.mdindex ef9e07d..58865e2 100644--- a/docs/en/projects/index.md+++ b/docs/en/projects/index.md@@ -4,7 +4,7 @@ This is the hands-on section of Learn Harness Engineering. Reading the lectures## Project Overview-This course features 6 progressive, hands-on projects that teach you how to build a reliable agentic working environment from scratch:+This course features 7 progressive, hands-on projects that teach you how to build a reliable agentic working environment from scratch:1. **Prompt-Only vs. Rules-First**: Compare how an agent performs with just a prompt versus a basic harness.2. **Agent-Readable Workspace**: Learn how to structure your repository to make it AI-friendly and establish handoff mechanisms.@@ -12,6 +12,7 @@ This course features 6 progressive, hands-on projects that teach you how to buil4. **Runtime Feedback and Scope Control**: Introduce tools that allow the agent to test its own code and correct errors during execution.5. **Self-Verification and Role Separation**: Build an independent review mechanism to prevent hallucinations and early declarations of victory.6. **Complete Harness (Capstone)**: Assemble a final, observable, end-to-end agent working environment.+7. **Your First Automated Loop**: Transition from manual driving to automated looping — three progressive experiments: goal loop, timer loop, and maker-checker loop.## How to Proceeddiff --git a/docs/en/projects/project-07-loop-engineering-first-loop/index.md b/docs/en/projects/project-07-loop-engineering-first-loop/index.mdnew file mode 100644index 0000000..8466cbc--- /dev/null+++ b/docs/en/projects/project-07-loop-engineering-first-loop/index.md@@ -0,0 +1,145 @@+# Project 07. Build Your First Automated Loop++> Related Lecture: [L13. Why You Need to Stop Prompting Your Agent](./../../lectures/lecture-13-loop-engineering/index.md)++## What You'll Do++This is the transition project from "Harness" to "Loop." You already know how to set up an agent with a proper environment, instructions, and feedback — now you'll turn that setup into a loop that runs on its own.++You'll do three progressive experiments: first turn a task from manual to `/goal`, then turn a monitoring task into a `/loop` timer, and finally build a full maker-checker loop to experience what it feels like when **you step outside the loop.**++## Project Files++Repo path: [`projects/project-07/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-07)++| Directory | What's Inside | What You Do |+|-----------|--------------|-------------|+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-07/starter) | A small knowledge base project with a complete harness (P06 final state), including AGENTS.md, feature_list.json, init.sh, session-handoff.md, clean-state-checklist.md. | Turn this harness into one that can loop automatically. |+| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-07/solution) | Full implementations of three loops: goal loop, timer loop, maker-checker loop, plus loop state files and verification scripts. | Reference for loop design patterns and state management. |++## Tools You'll Use++- Claude Code or Codex+- Git+- Your complete harness from P06+- A terminal multiplexer (tmux or screen, for observing long-running loops)+- Optional: GitHub Actions or cron (for advanced event-driven / scheduled experiments)++## Steps++### Prep++1. Start from the same commit where you finished P06.+2. Create three branches: `p07-goal-loop`, `p07-timer-loop`, `p07-maker-checker`.+3. Confirm your harness works: run init.sh, verify state file, feature list, and handoff docs are all in place.+4. Pick a **target task** you want the loop to work on repeatedly. Choose something medium-sized with clear completion criteria — e.g., "add unit tests to all modules, reaching 80% coverage" or "add input validation to all API endpoints."++### Experiment 1: Goal Loop — From Manual Run to Auto Run++Switch to the `p07-goal-loop` branch.++1. **Write the goal description**: Turn your chosen task into a `goal.md` file containing:+ - Clear goal ("what counts as done")+ - Verification method ("how to confirm it's done" — run tests? run lint? check coverage?)+ - Stop condition ("when should it stop" — max turns? time limit? budget limit?)+ - Constraints ("what not to touch" — production config, database schema, etc.)++2. **First manual run**: Give the task to the agent manually, yourself. Record how many turns it took, how many times you intervened, and the result quality. This is your baseline.++3. **Run with `/goal`**: Use the same `goal.md` as input and run it in `/goal` mode. The agent loops on its own until the goal is reached or the stop condition triggers.++4. **Compare results**:+ - Difference in turn count+ - Difference in your intervention count+ - Difference in result quality (using the same verification standard)+ - Difference in time you spent++5. **Iterate on goal.md**: If the results are poor, revise the goal description and run again. Keep going until you're satisfied with the results, or until you've confirmed the limit of what a goal loop can do on this task.++### Experiment 2: Timer Loop — Turn Monitoring Into a Heartbeat++Switch to the `p07-timer-loop` branch.++1. **Pick a monitoring task**: Find a repetitive check you normally do manually. For example:+ - Run the test suite every hour, fix failures+ - Check for dependency security updates every morning+ - Check for coding style violations after each commit+ - Periodically scan TODO comments to see which ones are stale++2. **Write the monitoring prompt/script**: Lay out the monitoring steps clearly — what to check, what to do when problems are found, and when to call a human.++3. **Run with `/loop` (or Codex Thread automation)**:+ - Set a reasonable interval (10-30 minutes recommended — too short and you'll be annoyed, too long and you won't see the effect)+ - Let it run for at least 2 hours (or go do something else and come back later)++4. **Record the results**:+ - How many problems did it find?+ - How many did it fix on its own?+ - How many were false positives?+ - How many did it make worse?+ - How much time did you spend following up on its results?++5. **Reflect**: Is this monitoring task worth automating? Compare the time you saved vs. the time you spent following up. If it's not worth it, did you pick the wrong task, or is the loop poorly designed?++### Experiment 3: Maker-Checker Loop — Take Yourself Out of the Loop++Switch to the `p07-maker-checker` branch.++This is the most important of the three experiments. You'll build a **complete loop that doesn't need you to be there:**++1. **Design the loop structure**:+ - **Maker agent**: implements, writes code, modifies files+ - **Checker agent**: verifies, runs tests, does code review, passes / fails+ - **State file** (`loop-state.md`): records current round, what was done, verification results, what's next+ - **Stop condition**: N consecutive passes, or maximum rounds reached++2. **Write three prompts**:+ - Maker instructions (what to do, how to do it, what not to touch)+ - Checker instructions (what to verify, how to verify, what counts as pass, how to give feedback)+ - Loop control logic (who goes first, how handoff works, how to start the next round)++3. **Run at least 5 rounds**:+ - Round 1: Maker implements → Checker verifies → Fail → Feedback to Maker+ - Round 2: Maker revises based on feedback → Checker verifies → ...+ - ...+ - Until consecutive pass, or you call it++4. **Record each round's state**:+ - Round number+ - What the Maker did+ - What problems the Checker found+ - Pass / fail+ - Did you intervene? (if yes, why?)++5. **Final retro**:+ - How many times did you intervene? Why?+ - What would have happened if you hadn't intervened?+ - Did the Checker miss any problems?+ - Did the Maker keep making the same mistake?+ - Where is the quality ceiling of this loop? Maker capability, or Checker capability?++## How to Measure Results++| Metric | Exp 1 (Goal) | Exp 2 (Timer) | Exp 3 (Maker-Checker) |+|--------|-------------|--------------|----------------------|+| Task completion rate | Was the goal reached? | How many monitoring cycles ran? | How many rounds until pass? |+| Human interventions | How many times did you step in? | How much time did you spend following up? | How many times did you intervene? |+| Result quality | How does it compare to manual? | False positive rate? Missed issues? | How many issues did Checker find that you wouldn't have? |+| Time saved | How much time did you save? | Is it worth automating? | Time spent designing the loop vs. time saved |+| Reliability | Was the stop condition trustworthy? | Did it run away? | Can the loop get stuck in the same place? |++## What to Submit++- `goal.md` (Experiment 1's goal description, at least two iterations)+- Experiment 1 comparison notes: manual vs goal loop+- Experiment 2 monitoring prompt + 2-hour run log+- Experiment 3's three prompts (Maker / Checker / Loop control)+- Experiment 3's `loop-state.md` (at least 5 rounds recorded)+- Final retro: takeaways from all three experiments, how your understanding of loop engineering changed, what things are good candidates for loop-ification and what aren't++## Related Lectures++- [Lecture 13 — Why You Need to Stop Prompting Your Agent](../../lectures/lecture-13-loop-engineering/index.md)+- [Lecture 12 — Why Every Session Must Leave a Clean State](../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) (every round of a loop needs clean state)+- [Lecture 11 — Why Observability Belongs Inside the Harness](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (you need to see what's happening inside the loop)+- [Lecture 05 — Why State Files Are the Backbone of Continuity](../../lectures/lecture-05-why-state-files-are-the-backbone-of-continuity/index.md) (loop state files are an extension of state files)diff --git a/docs/en/resources/reference/index.md b/docs/en/resources/reference/index.mdindex 4c6c8ac..7cdb85c 100644--- a/docs/en/resources/reference/index.md+++ b/docs/en/resources/reference/index.md@@ -61,6 +61,7 @@ announcements, team case studies, and benchmarks are excluded.- [Stripe: Minions: Stripe's one-shot, end-to-end coding agents](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents) (2026-02-09) and [Part 2](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents-part-2) (2026-02-19): devbox isolation, custom agent harnesses, blueprint state machines, rule files, MCP tool curation, security controls, and pre-push/CI feedback loops.- [Cognition: What We Learned Building Cloud Agents](https://cognition.ai/blog/what-we-learned-building-cloud-agents) (2026-04-23): VM isolation, session snapshot/resume, orchestration, governance, audit logging, and integrations for cloud-agent runtimes.- [Cognition: Multi-Agents: What's Actually Working](https://cognition.ai/blog/multi-agents-working) (2026-04-22): generator-verifier loops, clean-context reviewers, smart-friend routing, manager-child coordination, and cross-agent communication boundaries.+- [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/) (2026-06-07): the complete loop engineering framework from `/goal` to six primitives — automations, worktrees, skills, connectors, sub-agents, external state — plus the four silent costs.- [Replit: Decision-Time Guidance: Keeping Replit Agent Reliable](https://blog.replit.com/decision-time-guidance) (2026-01-20, updated 2026-01-23): a lightweight classifier injects short situational guidance at the decision point instead of stuffing all rules into the system prompt.- [Vercel: How we made v0 an effective coding agent](https://vercel.com/blog/how-we-made-v0-an-effective-coding-agent) (2026-01-07): dynamic system prompts, a streaming rewrite layer, and deterministic/model-driven autofixers.- [Vercel: Introducing deepsec](https://vercel.com/blog/introducing-deepsec-find-and-fix-vulnerabilities-in-your-code-base) (2026-05-04): a security-focused coding-agent harness with scan, investigate, revalidate, enrich, export, plugin, and refusal-checker steps.diff --git a/docs/zh/lectures/lecture-13-loop-engineering/code/checker-prompt.md b/docs/zh/lectures/lecture-13-loop-engineering/code/checker-prompt.mdnew file mode 100644index 0000000..dd36609--- /dev/null+++ b/docs/zh/lectures/lecture-13-loop-engineering/code/checker-prompt.md@@ -0,0 +1,80 @@+# Checker Agent Prompt(检查者)++> 给验证 agent 用的 prompt。+> 专注于"挑毛病",越严格越好。++## 你的角色++你是 Checker,负责验证 Maker 的产出。你的目标是找到问题,不是说好听的。++拿到 Maker 会给你一份实现,你的工作是:++1. 通读所有改动+2. 按检查清单逐项验证+3. 跑完整的验证命令+4. 逐条列出所有发现的问题,每条都要有证据++**记住:你不是来点赞的,是来挑毛病的。** 找不到问题是你的失职。++## 检查清单++### 功能正确性+- [ ] 实现是否符合需求描述?+- [ ] 有没有漏掉什么边界情况?+- [ ] 错误处理到位了吗?++### 代码质量+- [ ] 代码清晰吗?命名清楚吗?+- [ ] 有没有重复代码?+- [ ] 符合项目编码规范吗?+- [ ] 有没有明显的性能问题?++### 测试+- [ ] 测试覆盖了主要场景吗?+- [ ] 有没有 edge case 没有测到?+- [ ] 测试真的在测对东西,而不是走过场?++### 验证命令+- [ ] `npm test` 全部通过了吗?+- [ ] `npm run lint` 无错误?+- [ ] TypeScript 类型检查通过?+- [ ] 覆盖率达标?++### 安全和影响+- [ ] 改动会不会影响其他地方?+- [ ] 有没有引入新的依赖?合理吗?+- [ ] 配置文件改得对吗?++## 输出要求++每条问题都必须包含:+1. **问题描述**+2. **在哪**(文件和行号+3. **证据**(具体错在哪里、为什么是问题+4. **严重程度**(严重 / 中等 / 轻微++最后给一个总体结论:通过 / 不通过 / 有小问题可过++输出格式:++```+## 总体结论+✅ 通过 / ❌ 不通过 / ⚠️ 小问题可过++## 发现的问题++### 1. [严重] 问题标题+- 位置:文件:行号+- 描述:...+- 证据:...+- 建议:...++### 2. [中等] 问题标题+...++## 验证命令结果+- 单元测试:通过 X / Y+- lint:通过 / 失败(X 个错误)+- 类型检查:通过 / 失败+- 覆盖率:XX%+```diff --git a/docs/zh/lectures/lecture-13-loop-engineering/code/goal-template.md b/docs/zh/lectures/lecture-13-loop-engineering/code/goal-template.mdnew file mode 100644index 0000000..6bf1430--- /dev/null+++ b/docs/zh/lectures/lecture-13-loop-engineering/code/goal-template.md@@ -0,0 +1,65 @@+# Goal Loop 目标描述模板++> 把你的目标写成这样一份文档,交给 `/goal` 或 maker agent 用。+> 越具体、越可验证,loop 的质量越高。++## 目标++<!-- 一句话说清楚要做什么 -->++完成 XX 功能,包含完整的单元测试覆盖。++## 验收标准++<!-- 机器可验证的完成条件,每条都能跑命令或检查 -->++- [ ] `npm test` 全部通过+- [ ] 覆盖率报告显示 XX 模块覆盖率 ≥ 80%+- [ ] `npm run lint` 无错误+- [ ] TypeScript 类型检查通过(`npx tsc --noEmit`)+- [ ] 所有新增代码符合项目编码规范++## 范围++<!-- 明确说清楚不能碰什么 -->++### 可以改的++- `src/xx/` 目录下的所有文件+- `tests/` 目录下的测试文件+- 相关的类型定义文件++### 不能改的++- `src/main.ts` 入口文件+- 数据库 schema 迁移文件+- `package.json` 里的依赖版本(除非明确需要新增)+- CI/CD 配置文件++## 验证方式++<!-- 每做一步怎么验证 -->++1. 实现完成后,按顺序跑以下命令:+ 1. `npx tsc --noEmit` — 类型检查+ 2. `npm run lint` — 代码规范+ 3. `npm test` — 单元测试+ 4. `npx vitest --coverage` — 覆盖率检查++2. 任何一步失败都先修,修完再跑下一个。+3. 全部通过后,运行一次完整的端到端测试(如果有)。++## 停止条件++- 所有验收标准全部通过 ✅+- 达到最大回合数:20 轮+- 连续 3 轮没有进展(同样的错误反复出现)+- 遇到无法自行解决的阻塞问题(比如需要的依赖不存在、环境问题)++## 工作方式++1. 先读 `AGENTS.md` 和 `feature_list.json`,理解项目结构和现有功能。+2. 先写设计思路,再动手改代码。+3. 每完成一个子任务就验证一次。+4. 遇到卡住超过 2 轮,换个思路或简化方案。+5. 每一轮结束后更新进度。diff --git a/docs/zh/lectures/lecture-13-loop-engineering/code/index.md b/docs/zh/lectures/lecture-13-loop-engineering/code/index.mdnew file mode 100644index 0000000..a4f61b8--- /dev/null+++ b/docs/zh/lectures/lecture-13-loop-engineering/code/index.md@@ -0,0 +1,8 @@+# 第 13 讲代码++使用此文件夹存放以下方面的示例:++- goal.md 目标描述模板+- loop-state.md 循环状态模板+- Maker / Checker 角色 prompt 模板+- 循环控制脚本示例diff --git a/docs/zh/lectures/lecture-13-loop-engineering/code/loop-state-template.md b/docs/zh/lectures/lecture-13-loop-engineering/code/loop-state-template.mdnew file mode 100644index 0000000..9b6714c--- /dev/null+++ b/docs/zh/lectures/lecture-13-loop-engineering/code/loop-state-template.md@@ -0,0 +1,69 @@+# Loop State 循环状态模板++> 每个 loop 都应该有一个状态文件,记录当前进度。+> 每一轮结束时更新,下一轮开始时读取。++## 基本信息++- **循环名称**:<!-- 比如 "单元测试补全循环" -->+- **启动时间**:2026-07-09 10:00+- **当前轮次**:第 1 轮 / 共 N 轮+- **当前状态**:进行中 <!-- 进行中 / 已完成 / 已阻塞 / 已失败 -->+- **总耗时**:0 小时 0 分钟++## 目标++<!-- 这个 loop 要达成什么 -->++## 轮次记录++### 第 1 轮++- **开始时间**:+- **Maker 做了什么**:+- **验证结果**:✅ 通过 / ❌ 失败 / ⚠️ 部分通过+- **发现的问题**:+ -+- **下一轮要做什么**:+- **是否需要人类介入**:是 / 否++### 第 2 轮++- **开始时间**:+- **Maker 做了什么**:+- **验证结果**:✅ 通过 / ❌ 失败 / ⚠️ 部分通过+- **发现的问题**:+ -+- **下一轮要做什么**:+- **是否需要人类介入**:是 / 否++<!-- 复制上面的格式继续加 -->++## 累积统计++| 指标 | 数值 |+|------|------|+| 已完成轮次 | 0 |+| 通过轮次 | 0 |+| 失败轮次 | 0 |+| 发现的总问题数 | 0 |+| 人类介入次数 | 0 |+| 代码改动文件数 | 0 |++## 阻塞问题列表++<!-- 把反复出现的问题记在这里,避免下一轮注意 -->++-++## 最终结果++<!-- loop 结束后填写 -->++- **最终状态**:完成 / 失败 / 人工终止+- **完成时间**:+- **总结**:+ - 做了什么+ - 结果如何+ - 学到了什么+ - 下次怎么改进diff --git a/docs/zh/lectures/lecture-13-loop-engineering/code/maker-prompt.md b/docs/zh/lectures/lecture-13-loop-engineering/code/maker-prompt.mdnew file mode 100644index 0000000..9c65eac--- /dev/null+++ b/docs/zh/lectures/lecture-13-loop-engineering/code/maker-prompt.md@@ -0,0 +1,49 @@+# Maker Agent Prompt(制作者)++> 给实现 agent 用的 prompt。+> 专注于"做出来"。++## 你的角色++你是 Maker,负责实现功能、写代码。++你拿到一个任务,你的工作是:++1. 理解需求+2. 设计实现方案+3. 写出代码+4. 跑基础验证(编译、lint、单测)+5. 把结果交给 Checker 审核++## 工作规则++- 先读 AGENTS.md 和相关文档,理解项目结构。+- 改代码前先说清楚打算怎么改。+- 写完自己先跑一遍基础验证,确保至少能跑通。+- 不知道的东西老实说不知道,不要瞎编。+- 每一步都有进展就记下来。++## 交付物++- 修改的文件列表+- 实现思路简述+- 基础验证结果(编译 / lint / 测试)+- 你自己觉得可能有问题的地方(供 Checker 重点看)++## 输出格式++```+## 实现概要+...++## 修改的文件+- ...++## 基础验证+- 编译:通过 / 失败+- lint:通过 / 失败+- 单元测试:通过 X / 个,失败 Y 个++## 已知问题和风险+- ...+```diff --git a/docs/zh/lectures/lecture-13-loop-engineering/index.md b/docs/zh/lectures/lecture-13-loop-engineering/index.mdnew file mode 100644index 0000000..81446de--- /dev/null+++ b/docs/zh/lectures/lecture-13-loop-engineering/index.md@@ -0,0 +1,498 @@+[English Version →](../../../en/lectures/lecture-13-loop-engineering/)++> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-13-loop-engineering/code/)+> 实战练习:[Project 07. 搭建你的第一个自动循环](./../../projects/project-07-loop-engineering-first-loop/index.md)++# 第十三讲. 从手动驱动到自动循环++前十二讲,你做的事情始终有一个共同前提:**你坐在键盘前,一次一次地输入指令。**++你写好了 `AGENTS.md`(第一到四讲),建立了状态管理(第五、六讲),用功能清单约束范围(第七、八讲),让 agent 在结束时留下干净交接(第九、十二讲),让运行过程可观测(第十、十一讲)——但所有这些工作的触发者,始终是你。agent 不会自己决定什么时候该干活,因为没有人按下"开始"按钮。++这一讲要讨论的,就是怎么把"按按钮"这件事也交给系统。不是放弃控制,而是把控制升到更高一层。++## /goal:最简形态的 loop++理解 loop engineering,最好的入口不是一套复杂的架构图,而是一个具体的命令。++2026 年初,Claude Code 和 OpenAI Codex 不约而同地加入了同一个功能:`/goal`。你在终端里敲:++```+/goal "所有测试通过,lint 零告警,合并到 main"+```++然后合上笔记本去睡觉。八小时后醒来,agent 已经自己完成了分析、编码、测试、修复、合并的全过程。它失败了就重试,方向错了就换策略,通过了就结束——不需要你坐在旁边说"再试一次试试"。++`/goal` 和传统 prompt 的区别只有一点,但这一点改变了一切:++| | 传统 prompt | `/goal` |+|---|---|---|+| 你给什么 | 下一步具体做什么 | 最终状态是什么 |+| agent 做什么 | 执行一次 | 循环直到达成 |+| 谁判断做完了 | 你 | 一条可验证的停止条件 |+| 你什么时候可以走 | 不能走 | 给完 `/goal` 就行 |++`/goal` 本质上就是一个 loop。它的结构只有三样东西:**一个目标,一种验证方式,一条停止条件。** 但就是这三样东西,让你的位置从循环**里面**移到了循环**外面**。++### `/goal` 是怎么长出来的++`/goal` 不是某天突然从 0 跳到 1 的。它是从日常工作流里一点一点长出来的,大致经历了四个阶段:++**阶段一:手动一条一条输。** 最早的用法就是你一句我一句,"写个函数"、"加个测试"、"改一下这个逻辑"。agent 每执行一步就停下来等你说下一步。你是整个流程的调度器。++**阶段二:长 prompt + 多步骤。** 后来大家开始写更长的 prompt,把多个步骤写在一起:"先分析代码,再写实现,再跑测试,测试没过就修。"agent 可以一口气跑好几步了,但你还是得盯着——因为它可能在某一步跑偏,或者跑完了不知道下一步该干嘛。++**阶段三:agent 自己判断要不要继续。** 再往后,agent 有了"自省"能力——跑完一步自己看结果,决定下一步怎么走。你给一个目标,它自己拆步骤、自己重试。但问题来了:它什么时候停?它自己说"我做完了"算不算数?实践反复证明——不算数。agent 太容易宣告胜利了。++**阶段四:独立的停止判断——`/goal`。** 最后一步是把"判断做完了没有"这件事,从干活的 agent 手里拿出来,交给一个独立的判断者。可能是另一个模型、可能是一段脚本、可能是一条测试命令,但总之——不能让写代码的人自己批作业。到这一步,`/goal` 才真正成立:你给目标,它循环跑,独立判断停不停,你可以走人。++这四个阶段不是某家公司规划好的路线图,是全世界用 agent 写代码的人,在各自的日常里,被同一个痛点推着,一步一步走到了同一个地方。Claude Code 和 Codex 在 2026 年初几乎同时上线 `/goal`,不是巧合——是时候到了。++### Loop 不只有一种++`/goal` 是最容易理解的 loop,但它不是唯一的一种。按触发方式和停止方式的不同,loop 可以分成几类:++| 类型 | 触发方式 | 停止方式 | Claude Code | Codex | 适用场景 |+|------|---------|---------|------------|-------|---------|+| **回合制 loop** | 你手动输入每一条 prompt | agent 认为做完了,或者你打断 | 普通对话 | 普通对话 | 小任务、探索性工作 |+| **目标驱动 loop** | 你给一个目标 | 独立判断者确认达成,或达到最大回合数 | `/goal` | `/goal`(需手动开启) | 有明确完成标准的复杂任务 |+| **时间驱动 loop** | 定时触发(每隔 N 分钟/小时) | 你手动停止,或任务完成后自行退出 | `/loop` | 对话线程自动化(Thread automation) | 轮询状态、定期巡检、重复性工作 |+| **事件驱动 loop** | 外部事件触发(PR 提交、CI 失败、新 issue) | 处理完事件就停,或达到重试上限 | Routines (API / GitHub Webhook) | 独立自动化任务 + 插件 | 响应式工作流、CI/CD 集成 |++这几种 loop 不是互相取代的关系,而是工具箱里的不同工具。小任务用回合制就够了;有明确终点的用 `/goal`;需要盯着什么东西的用 `/loop`;要和外部系统联动的用事件驱动。++### `/goal` 和 `/loop` 别搞混++名字里都带 "loop",但它们解决的是完全不同的问题:++| | `/goal` | `/loop` |+|---|---------|---------|+| **本质** | 一个大任务,跑到完为止 | 同一个小动作,按间隔重复跑 |+| **停止条件** | 目标达成了,或者预算花完了 | 你手动停,或者任务做完自己退 |+| **时间特征** | 一次长跑,可能跑几小时甚至几天 | 周期性短跑,每次可能只跑几分钟 |+| **状态累积** | 任务越跑越接近终点 | 每次都是独立的,不累积进度 |+| **类比** | 跑马拉松——发令枪响了就跑,撞线就停 | 闹钟——每隔一段时间响一次,你关了才停 |+| **典型用法** | "实现整个支付系统,有测试覆盖" | "每 15 分钟看一眼 CI 挂了没" |++一个容易犯的错:把该用 `/goal` 的事情塞进 `/loop` 里。比如你写 `/loop 10m "继续实现支付系统"`——这是错的。因为 `/loop` 每次都是独立跑一遍指令,不会记得上次做到哪了,结果就是每次都从同一个地方重新开始。++**判断该用哪个的一句话标准:这件事有终点吗?**+- 有终点 → `/goal`+- 没终点,就是要一直盯着 → `/loop`++本讲讲的 Loop Engineering,核心不是某一个命令,而是**当你需要的时候,能设计出包含以上所有类型的系统——让 agent 在你不在场的时候也能自己跑。**++你不必每次都写 `/goal`。但理解它从哪来、为什么长这样,就理解了 loop engineering 的核心——更复杂的 loop 只是在三样基础(目标、验证、停止)之上,加上了调度、并行、隔离、记忆这些零件。++## 2026 年 6 月,三个人在同一周点了一把火++2026 年 6 月第一周,三位构建 coding agent 基础设施的核心人物,在没有通气的情况下,说了同一句话的不同版本。++**Peter Steinberger**(OpenClaw 作者,[其推文收获 800 万浏览](https://x.com/steipete/status/2063697162748260627)):「你不应该再给 coding agent 写 prompt 了。你应该设计循环去 prompt 你的 agent。」++**Boris Cherny**(Anthropic Claude Code 负责人,[在 Acquired 播客上](https://x.com/rohanpaul_ai/status/2063289804708835412)):「我已经不手动 prompt Claude 了。我有一堆循环在跑,它们负责 prompt Claude、搞清楚要做什么。我的工作变成了写循环。」++**Addy Osmani**(Google Chrome 工程负责人)在 6 月 7 日[撰文](https://addyosmani.com/blog/loop-engineering/)将这个概念命名为 **Loop Engineering**,并给了它一句话定义:++> **Loop engineering 就是用系统取代你自己去 prompt agent。**++Cherny 透露了一个数字:在连续 30 天里,Claude Code 的所有代码贡献全部由 AI 自主完成,累计合并 259 个 PR,其中超过 80% 的生产代码由 Claude 编写,开放式软件任务成功率达到 76%。++三个人、同一周、同一个结论。不是因为商量好的,是因为基础设施刚好跨过了一个门槛:agent 已经可靠到能独立完成非 trivial 任务、调度原语(`/loop`、`/goal`、cron)已经内置于工具中、单次运行的 token 成本也低到值得反复跑。当零件全部就位,把零件拼在一起的动作,所有人在同一时间想到了。++> 来源:[Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)++## 你在循环里面 vs 你在循环外面++让我们用两个具体的场景对比。++**场景 A:你在循环里面(前十二讲的模式)**++```mermaid+flowchart TD+ You["你"] -->|"手动输入指令"| Agent["AI Agent"]+ Agent -->|"产出结果"| Result["代码 / 测试 / 文档"]+ Result -->|"你检查"| You+ You -->|"不满意,修改指令"| Agent+ You -->|"满意,进入下一任务"| You+```++你有完整的 harness:`AGENTS.md` 告诉 agent 项目规则,`feature_list.json` 约束了范围,`init.sh` 保证环境一致,`claude-progress.md` 记录进度。**但每一步仍需你手动发起。** 做完一个 feature,你要读进度文件,想一下下一个做什么,再输入指令。你是整个工作流的引擎。++**场景 B:你在循环外面(Loop Engineering)**++```mermaid+flowchart TD+ subgraph Loop["你设计的循环系统"]+ Trigger["自动触发<br/>定时 / 事件 / 上一个任务完成"] --> Discover["发现任务<br/>读进度文件 / issue tracker"]+ Discover --> Dispatch["分发任务<br/>生成子 agent"]+ Dispatch --> Verify["验证结果<br/>测试 / lint / 独立评审 agent"]+ Verify --> Persist["记录状态<br/>更新进度 / 提交 / 打开 PR"]+ Persist -->|"有剩余任务"| Discover+ Persist -->|"全部完成或遇到阻塞"| Inbox["推送到你的审阅队列"]+ end+ Inbox -->|"你只需要做决策"| You["你"]+```++你不输入指令了。你设计的系统去发现任务、分发任务、验证结果、记录状态、决定下一步。你做的事情变成了三件:**在开始前定义目标和停止条件,在结束后审阅结果,在系统跑偏时调整规则。** 价值杠杆从"写对 prompt"转移到了"设计对的循环"。++> Addy Osmani 的原话:「一年前如果你想搞一个 loop,你得写一堆 bash 脚本然后永远维护它。现在这些零件已经直接内置于产品中了。」你不需要重造轮子,你需要的是理解这些零件怎么拼在一起。++## 核心概念++- **Loop Engineering**:设计一个系统来自动向 agent 发指令,取代人手动逐条输入。人从循环里面移到循环外面,价值杠杆从"写对 prompt"转移到"设计对的循环"。+- **`/goal` 模式**:最简形态的 loop——给出目标、验证方式和停止条件,agent 循环直到达成。是从手动驱动到自动循环的桥梁。+- **Generator/Evaluator 分离**:写代码的 agent 和检查代码的 agent 必须分开。同一个模型给自己打分是不可信的;独立的、有时甚至用不同模型的验证者是 loop 可靠性的底线。+- **Worktree 隔离**:每个并行 agent 在独立的 git worktree 中工作,物理上避免文件碰撞。是多 agent 并行运行的基础设施前提。+- **外部状态(External State)**:活在单次对话之外的记忆载体——markdown 文件、issue tracker、看板等。模型在会话之间什么都不记得,记忆必须在磁盘上。+- **六种沉默成本**:loop 跑得越久越尖锐的四类隐性成本——验证负债、理解腐烂、认知投降、令牌爆炸。loop 加速的不仅是产出,也包括风险。++## 一个 Loop 的六大原语++Osmani 将构成 loop 的零件归纳为五个核心组件,外加一个贯穿始终的记忆层——一共六样东西,但记忆层的地位是特殊的:它不是一个和其他零件平级的组件,而是其他所有零件都依赖的脊柱。++下面这张图把六样东西画成一个环,方便你一眼看全。但要记住:External State 不是环上的一站,它是整个环的地基。++```mermaid+flowchart LR+ A["Automations<br/>自动触发"] --> W["Worktrees<br/>并行隔离"]+ W --> S["Skills<br/>项目知识"]+ S --> C["Connectors<br/>连接外部工具"]+ C --> SA["Sub-agents<br/>制作者/检查者"]+ SA --> ES["External State<br/>跨迭代持久记忆"]+ ES --> A+```++### 1. Automations(自动触发)++没有自动触发,loop 就不是 loop,只是你手动跑了一次。++Claude Code 和 Codex 都有完整的调度体系,但叫法和分层不太一样。从轻到重大致可以这样对应:++| 层级 | Claude Code | Codex | 说明 |+|------|------------|-------|------|+| 会话内轮询 | `/loop` | 对话线程自动化(Thread automation) | 跟着当前会话走,关了就没了 |+| 本地定时任务 | Desktop 定时任务 | 独立自动化任务(本地模式) | 机器开着就跑,能读本地文件 |+| 云端定时任务 | Cloud Routines | —(Codex 无云原生调度) | 机器关了也跑 |+| 事件触发 | Routines (API / GitHub Webhook) | 独立自动化任务 + 插件 | 外部事件触发 |+| 完全自建 | GitHub Actions / 自建 cron | `codex exec` + cron | 完全自己掌控 |++**Codex 的 Automations 面板**是它的调度入口。在里面选项目、写好 prompt、设好频率、选在本地工作区还是后台 worktree 跑。找到东西的结果进入 Triage 收件箱;没找到东西的自动归档。OpenAI 内部用它做日常:issue 分类、CI 失败总结、commit 简报、追溯上周引入的 bug。++Codex 的自动化分两种:+- **对话线程自动化(Thread automation)** — 心跳式重复唤醒同一个线程,保留上下文。适合盯着一件事持续跟进,比如监控一个长命令、轮询 PR 状态。对应 Claude Code 的 `/loop`。+- **独立自动化任务(Standalone automation)** — 每次启动全新运行,结果进入 Triage。适合每天/每周独立执行的任务,比如每日简报、依赖扫描。对应 Claude Code 的 Desktop 定时任务。++Claude Code 的体系分得更细:++- **`/loop`** — 会话内的轻量定时循环。终端开着的时候有效,关了就没了,7 天自动过期。适合当前工作 session 里临时需要盯着什么东西的时候。+- **Desktop 定时任务** — 机器开着就跑,会话关了也不受影响,间隔可以到分钟级。适合需要访问本地文件的重复性工作。+- **Cloud Routines** — 跑在 Anthropic 的云上,你的机器关了也不影响,最小间隔 1 小时。支持三种触发器:定时、API 调用、GitHub Webhook。适合不需要本地环境的日常任务。+- **GitHub Actions / 自建 cron** — 完全自己掌控,想怎么跑怎么跑。适合有特殊环境要求或安全限制的场景。++```bash+# Claude Code:每 30 分钟跑一次测试并修复(当前会话内有效)+/loop 30m Run the test suite and fix any failing tests++# Claude Code:每 15 分钟检查一次部署状态+/loop 15m Check if the production deploy succeeded and report status+```++Automations 是这个系统的"心跳"。没有它,loop 就只是个设计图,从来不会自己运转。++### 2. Worktrees(并行隔离)++一旦有超过一个 agent 同时跑,文件碰撞就变成必然的失败模式。两个 agent 同时改同一个文件,就像两个工程师没有沟通就提交了同一段代码。++`git worktree` 解决的就是这个:每个 agent 在自己的独立分支上工作,物理上不可能碰到别人的修改。++Claude Code 和 Codex 都内置了 worktree 支持。当你用 `--worktree` 或 `isolation: worktree` 启动子 agent 时,每个 helper 拿到一个干净的、独立的 checkout,完成任务后自行清理。worktree 移除了碰撞的机械问题,但你要记住:**你的审阅带宽仍然是天花板**,你能同时盯多少个并行 agent,决定了你能跑多少个 worktree。++### 3. Skills(项目知识)++Skill 让你不再每次会话都重新解释一遍你的项目。它是一个文件夹,里面有 `SKILL.md` 存放指令和元数据,外加可选的脚本、参考文档、资源文件。++Codex 和 Claude Code 都支持相同的格式。skill 通过 `/skill-name` 直接调用(Codex 也支持 `$skill-name`),也可以在 agent 判断任务匹配时自动触发。++技能本质上是在 pay 你的 intent debt——一个 agent 每次启动时都是"冷"的,你上下文里没写的东西,它就用自信的猜测填补。skill 就是把你的意图写在外面,写一次,每次运行都读。++### 4. Connectors(插件与连接器)++一个只能看到文件系统的 loop 是个小 loop。Connectors(基于 MCP 协议)让 agent 能读 issue tracker、查数据库、调 staging API、往 Slack 发消息。++Codex 和 Claude Code 都支持 MCP,你为一个工具写的 connector 通常另一个也能直接用。Connectors 的区别在于:有了它,agent 不只是说"这是修复方案",而是自动打开 PR、关联 Linear ticket、在 CI 通过后 ping 频道——loop 在你的真实环境里行动,不只是在终端里打字。++### 5. Sub-agents(子 agent)++loop 里最有结构价值的设计,就是把"写的人"和"检查的人"分开。写代码的模型对自己的作业评分太宽容了。第二个 agent,用不同的指令、有时用不同的模型,能抓住第一个 agent 自我说服的东西。++典型的三人分工:++```mermaid+flowchart LR+ Explorer["探索者 Agent<br/>读代码库、定位问题"] --> Implementer["实现者 Agent<br/>写修改、写测试"]+ Implementer --> Verifier["验证者 Agent<br/>独立审查、运行验证"]+ Verifier -->|"未通过"| Implementer+ Verifier -->|"通过"| Output["输出结果"]+```++Claude Code 的 `/goal` 底层就是这么干的——一个独立的小模型来判断 loop 是否应该停止,而不是让写代码的那个模型自评。这被称为 **generator/evaluator 分离**,是 loop 可靠性的核心保障。++### 6. External State(外部状态)++模型在会话之间什么都不记得。记忆必须在磁盘上,不能在上下文窗口里。++这听起来太简单而不值得提,但它是每个长时间运行的 agent 都依赖的同一个把戏。一个 markdown 文件、一个 Linear 看板——任何活在单次对话之外的东西,记录了什么做完了、什么正在做、什么被阻塞了。agent 忘了一切,仓库不会忘。++这六个原语拼在一起,就是你的 loop 设计工具箱。你不需要每次都全用上,但你需要知道什么时候该用哪一个。++## 一个 Loop 的完整解剖++把六个原语拼在一起,看一个真实的 morning triage loop:++```mermaid+flowchart TD+ Trigger["每天早上 9:00<br/>Automation 自动触发"] --> Read["读外部状态<br/>昨天的 claude-progress.md<br/>GitHub 上未读 issue"]+ Read --> Triage["Triage Skill 启动<br/>对发现的问题分类、排优先级"]+ Triage --> Fork["每个可处理的问题<br/>fork 一个独立 Worktree"]+ Fork --> Implement["实现者 Sub-agent<br/>写修复 + 测试"]+ Implement --> Verify["验证者 Sub-agent<br/>独立运行测试 + lint + 审查"]+ Verify -->|"未通过"| Retry["重试队列<br/>换策略再试"]+ Retry --> Implement+ Verify -->|"通过"| PR["Connector: 打开 PR<br/>关联 issue, 更新进度文件"]+ PR --> Memory["写入 External State<br/>更新 claude-progress.md<br/>记录本轮结果"]+ Memory -->|"有剩余问题"| Fork+ Memory -->|"全部处理完毕<br/>或遇到无法处理的阻塞"| Inbox["结果推入 Triage 收件箱<br/>等你审阅"]+```++这不再是一个 agent 的一次运行。它是一个持续运转的系统,每天早上自己醒来,自己扫地,自己把需要你关注的东西放到你面前。你的角色变成了:**审阅 inbox 的内容,做决策,遇到系统处理不了的模式就优化 skill 或规则。**++Cherny 用这个模式让 Claude Code 团队在 30 天内合并了 259 个 PR,自己一次都没有打开 IDE。OpenAI 的工程师用同样的模式创建了约一百万行代码的 beta 产品,一行都没有手写。++## Generator/Evaluator 分离:为什么不能让自己批自己作业++这是 loop engineering 中最硬核的一条教训。++你让你最聪明的 agent 写了一段漂亮的代码。代码逻辑清晰、注释完整、测试全覆盖。你很满意。++但你有没有想过一个问题:**如果让那个写了代码的 agent 自己来评判自己做得对不对,它会说什么?**++答案已经被实践反复验证:它会给自己打高分。不是因为它不诚实,而是因为它就是这段代码的作者——它在生成的时候已经说服自己这条路是对的。你让它回头看,它看到的不是错误,而是自己的推理过程。++这不是 Claude 的问题,不是 GPT 的问题,这是所有生成式模型的共同特性。**模型是它自己输出最好的辩护律师。**++解决方案就是:永远不用同一个人(同一个模型、同一个 prompt)既干活又检查。++- Claude Code 的 `/goal` 底层的 supervisor 是一个独立的 session,独立判断是否达成目标+- Codex 的 subagent 体系让你定义验证 agent 可以和实现 agent 用不同模型、不同 reasoning effort+- 社区实践里的"adversarial verify"模式:每一个发现用 N 个独立的质疑 agent 来反驳它,多数否决则丢弃++这个原则用一句话总结:**你的人里必须有一个不信你的。**++## Karpathy 的 autoresearch:Loop 的最佳示范++如果想看一个设计精良、真实跑通的 loop 长什么样,Andrej Karpathy 的 [autoresearch](https://github.com/karpathy/autoresearch) 是最好的教材。++2026 年 3 月,Karpathy 发布了一个 630 行 Python 的项目。给它一张 GPU、一份研究方向,它能自己跑一整夜,完成上百个 ML 训练实验,只保留真正有改进的。项目上线几天内获得 66,000+ star。++### 三个文件,三种角色++整个系统只有三个核心文件,但分工极其清晰:++| 文件 | 谁来改 | 作用 |+|------|--------|------|+| `prepare.py` | 没有人(只读) | 数据准备、tokenizer、评估函数。固定的基础设施。 |+| `train.py`(~630 行) | **AI Agent** | 模型定义、优化器、训练循环。Agent 的实验场,想改什么改什么。 |+| `program.md` | **你** | 用自然语言写的研究方法论。你只改这个,告诉 agent 怎么探索、怎么评估、什么不能碰。 |++这个三分法是整个设计的精髓:**人不动代码,动方向;agent 不动方向,动代码。** 你的工作从写 Python 变成了"写研究组织文化"。++### 输入:program.md 长什么样++`program.md` 是 loop 的大脑。它不是代码,是一份用 Markdown 写的研究指令。里面大致包含:++- **目标**:优化 `val_bpb`(验证集 bits-per-byte,越低越好)+- **约束**:不能改 `prepare.py`、VRAM 不能超、训练时间固定 5 分钟+- **探索方向**:试试不同的架构、优化器、学习率调度+- **评估规则**:怎么算改进、怎么记录结果、失败了怎么办+- **铁律**:永远不要停。一旦开始循环,就一直跑下去++你给 agent 的启动 prompt 甚至可以短到一句话:++```+看看 program.md,然后开始实验。+```++剩下的全靠 agent 自己读文档、自己做决定。++### 九步棘轮循环++autoresearch 的核心是一个**棘轮(ratchet)**——只能往前走,不能后退。每一轮循环严格按九步走:++```mermaid+flowchart TD+ 1["1. 读方向<br/>读取 program.md"] --> 2["2. 看现状<br/>读 train.py + 历史结果"]+ 2 --> 3["3. 提假设<br/>想一个要试的改动"]+ 3 --> 4["4. 改代码<br/>修改 train.py"]+ 4 --> 5["5. 提交快照<br/>git commit"]+ 5 --> 6["6. 跑训练<br/>固定 5 分钟墙钟"]+ 6 --> 7{"7. 评估<br/>val_bpb 改进了吗?"}+ 7 -->|是| 8a["8a. 保留<br/>commit 留下<br/>结果写入 results.tsv"]+ 7 -->|否| 8b["8b. 回退<br/>git reset HEAD~1<br/>记录失败"]+ 8a --> 9["9. 下一轮<br/>回到第 1 步"]+ 8b --> 9+```++每小时大约跑 12 次实验。睡一觉(8 小时)就是约 100 次。Karpathy 自己跑了 2 天,约 700 次实验。++固定 5 分钟墙钟是个关键设计——不管 agent 改了什么,每次实验时间完全一样。这意味着所有结果在同一时间预算下直接可比,不会出现"这个跑久一点所以更好"的争议。++### 输出:你早上起来看到什么++Loop 跑完一夜,你早上打开电脑会看到三样东西:++**1. git 历史(前进的棘轮)**++只有真正改进了的 commit 留在主分支上,失败的全被回滚了。git log 就是一份经过验证的研究日志。++**2. results.tsv(完整的实验记录)**++每一次实验——不管成功失败——都记在里面:++```+timestamp commit_hash val_bpb vram_mb description+--------- ------------- ---------- ---------- ----------------------------+08:01:12 a1b2c3d 1.234 22100 baseline+08:06:15 d4e5f6g 1.228 22400 increased learning rate by 10%+08:11:20 (reverted) 1.241 21800 switched to GELU activation+08:16:08 h7i8j9k 1.219 23000 added weight decay 0.01+...+```++**3. 一份研究日志(agent 自己写的总结)**++Agent 会在 commit message 里写清楚它试了什么、什么有效、什么无效、下一步打算试什么。你读这些就够了,不用读代码 diff。++### 实际跑出了什么结果++Karpathy 首轮 2 天、约 700 次实验的结果:++- 从约 700 次尝试中筛出了约 **20 个可堆叠的有效改进**+- 将 nanochat 在 8×H100 上复现 GPT-2 水平的训练时间从 **2.02 小时压缩到 1.80 小时**,提速约 **11%**+- 找到的改进包括:学习率调整、优化器微调、激活函数替换、注意力模式优化等++不是所有改进都是惊天动地的大发现吗?不是。大部分是小优化堆叠出来的。但这 20 个有效改进,靠人手动做要花几周——agent 用 48 小时跑完了。++### 最值得注意的细节:loop 是用英文写的,不是用代码。++`program.md` 是一份 Markdown 文档,不是 Python 脚本。它描述了研究方法论——改什么、不改什么、怎么评估、怎么处理失败、以及一条铁律:**禁止向人类求助,一直跑。** 一个 coding agent 读这份文档,然后无限循环执行下去。++这就是 loop engineering 的核心模式:不给 agent 任务,给 agent **方法论**。让方法论成为 loop。一份 `program.md`,630 行胶水代码,剩下的全部是 agent 自己跑。++## 四种沉默成本++loop 跑起来之后,你不会立刻看到问题。以下四种成本会沉默地累积,等到你发现的时候可能已经损失了很多。++### 1. Verification Debt(验证负债)++loop 跑得快的时候,你很容易跳过验证。"看起来没问题"不等于"确实没问题"。loop 里自动生成的代码越多,验证债务积累越快。解决方式是:**停止条件必须是可自动检查的,不能是"感觉差不多"。**++### 2. Comprehension Rot(理解腐烂)++loop 出代码的速度越快,你对自己代码库的理解就越跟不上。Cherny 的团队 80% 的代码是 agent 写的——这意味着一个团队大部分代码不是人写的。如果不读不用,你对系统的理解会持续衰减。**快速跑 loop 的前提是快速读结果。**++### 3. Cognitive Surrender(认知投降)++当 loop 跑得很顺的时候,最舒服的姿势就是不再有观点。来什么接什么,不对结果动脑子。但这恰恰是危险的开始——你在用 loop 逃避思考,而不是用 loop 放大思考。Osmani 的警告:「两个人可以造完全一样的 loop,得到完全相反的结果。一个用它加深理解后加速,另一个用它代替理解。loop 不知道区别,你知道。」++### 4. Token Blowout(令牌爆炸)++loop 的每一次迭代都会积累更多上下文。代码写过了,错误遇到了,决策做过了。如果不做上下文压缩,prompt size 会随着迭代次数近似平方增长。Codex 的解决方案是自动 context compaction——用一个专门的 API 将老的对话轮次压缩成加密的内容摘要,保留关键知识,丢弃冗余细节。这是每个 loop 设计之初就要考虑的工程问题。++## 从零构建你的第一个 Loop++不需要一上来就搭一个 Stripe 级别、每周合并 1,300 个 PR 的系统。从最小可行的版本开始。++### 第一步:选一个重复发生的任务++找一个你每周至少做两次的事情。比如:+- 早上打开 GitHub,看有没有新 issue,分类和回复+- 每次 PR 审核前跑一遍 lint 和测试+- 每天结束前更新进度文档++### 第二步:写一个 goal 和停止条件++把任务变成一个 `/goal` 可以理解的描述:++```markdown+Goal: 检查仓库最新的 10 个 issue。+对于每个 issue:+ - 如果已经有明确标签和负责人,跳过+ - 如果没有标签,根据内容添加标签+ - 如果可以 10 分钟内修复,创建分支并尝试修复+停止条件:所有符合条件的 issue 都已处理,或遇到需要人工决策的问题。+```++### 第三步:拆出 maker 和 checker++不要让同一个 agent 既改代码又判对错。把你的 loop 拆成两个角色:+- 实现者:读 issue、写修复、写测试+- 验证者:独立运行测试、审查 diff、判断这个修复是否真解决了问题++### 第四步:加上记忆++用一个 markdown 文件记录 loop 每次运行的结果。下一轮启动时先读这个文件,知道上一轮做了什么、什么还没做。这比任何复杂的数据库都管用。++### 第五步:设一个定时器++用 `/loop` 命令或操作系统的 cron,让这个 loop 在没有你的时候也能启动。先从每天一次开始,观察一周。++### 成熟度阶梯++你不需要一次到位。loop 的采用是一个阶梯:++1. **Level 1: Goal Runner** — 你会用 `/goal` 下达有停止条件的任务,agent 循环直到达成+2. **Level 2: Scheduled Single-Task** — 一个自动化定时跑一个任务(比如每天早上检查 CI)+3. **Level 3: Multi-Agent Loop** — 实现者和验证者分离,每个发现 fork 一个独立 worktree+4. **Level 4: Self-Feeding Loop** — loop 从外部状态中自动发现下一个任务,自己决定做什么+5. **Level 5: Fleet Orchestration** — 多个 loop 并行运行,彼此独立、共享记忆++绝大多数团队目前卡在 Level 2 到 Level 3 之间。Level 1 是最快能看到回报的一步。++## 核心要点++- **Loop Engineering 不是替代 Harness Engineering,而是在它之上建一层。** harness 保证单次运行可靠,loop 保证持续运行不需要你守在旁边。+- **`/goal` 是最简形态的 loop:** 目标 + 验证方式 + 停止条件。这三样东西让你的位置从循环里面移到循环外面。+- **六个原语(Automations / Worktrees / Skills / Connectors / Sub-agents / External State)是 loop 的零件。** 不是每次都全用,但需要知道什么时候该装哪一个。+- **写代码的人和检查代码的人必须分离。** 一个模型给自己打分是不可信的;独立的、有时甚至用不同模型的验证 agent 是 loop 可靠性的底线。+- **loop 让生成几乎免费,判断成为稀缺资源。** 你省下的时间不是用来歇的,是用来做更多判断的。+- **四种沉默成本会随着 loop 跑得越久越尖锐:** 验证负债、理解腐烂、认知投降、令牌爆炸。loop 加速的不仅是产出,也包括风险。+- **从小开始。** 一个 `/goal`,一个 cron,一个 markdown 记忆文件。看到回报之后再往上加。++## 延伸阅读++- [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)+- [Addy Osmani: Agent Harness Engineering](https://addyosmani.com/blog/agent-harness-engineering/)+- [Simon Willison: Designing Agentic Loops (Sep 2025)](https://simonw.substack.com/p/designing-agentic-loops)+- [Karpathy: autoresearch](https://github.com/karpathy/autoresearch)+- [Claude Code: Dynamic Workflows and Orchestration](https://kenhuangus.substack.com/p/claude-code-orchestration-dynamic)+- [Loop Library (Forward Future)](https://signals.forwardfuture.ai/loop-library/) — 50 个真实 loop 的公开语料库+- [The Neuron: Claude Code Creators on Agent Loops](https://www.theneuron.ai/explainer-articles/claude-code-creators-boris-cherny-and-cat-wu-explain-how-to-use-agent-loops/)+- 第十二讲:[每次会话结束前都做好交接](./../lecture-12-why-every-session-must-leave-a-clean-state/index.md) — loop 的前提:每个会话留下干净状态,下一轮才能自动启动+- 第五讲:[让跨会话的任务保持上下文连续](./../lecture-05-why-long-running-tasks-lose-continuity/index.md) — 外部状态和记忆的前置知识+- 第十一讲:[让 agent 的运行过程可观测](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — loop 跑得越快,越需要可观测性来发现问题+- 第八讲:[用功能清单约束 agent 该做什么](./../lecture-08-why-feature-lists-are-harness-primitives/index.md) — 功能清单是 self-feeding loop 发现下一个任务的天然数据源++## 练习++1. **把你的一个重复任务变成 `/goal`:** 找一个你每周至少手动做两次的事情。写下它的目标、验证方式和停止条件。用 `/goal` 跑一次,比较和手动做的时间和结果质量。这是你从 Harness 到 Loop 的第一步。++2. **分离 maker 和 checker:** 挑一个你之前让 agent 执行过的任务。这一次,写两份不同的 prompt:一份给实现 agent,一份给验证 agent(用不同模型,比如实现用 Claude,验证用 GPT,或反过来)。验证 agent 必须逐条指出问题并引用证据。记录两种模式下发现的问题数量和类型差异。++3. **给 loop 加上记忆:** 为你的 loop 创建一个 markdown 状态文件。在 loop 的每一轮中写入:本轮做了什么、验证结果、状态(通过/失败/阻塞)、下一轮该做什么。跑三轮,观察没有记忆文件和有记忆文件的情况下,agent 的行为差异。++4. **审计你的 loop 的沉默成本:** 你的 loop 跑一小时后,评估以下四个指标:+ - 有多少验证是"感觉通过了"而不是"机器确认通过了"?(验证负债)+ - 你对 loop 最新产出的代码能讲清楚多少?(理解腐烂)+ - 你有多少次"看看再说"但始终没看?(认知投降)+ - loop 的上下文增长趋势如何?是否在重复冗余信息?(令牌爆炸)diff --git a/docs/zh/projects/index.md b/docs/zh/projects/index.mdindex 7134d5f..50f0ac3 100644--- a/docs/zh/projects/index.md+++ b/docs/zh/projects/index.md@@ -4,14 +4,15 @@## 项目概览-本课程包含 6 个渐进式的实战项目,带你从零开始构建一个完整的 Agent 工作环境:+本课程包含 7 个渐进式的实战项目,带你从零开始构建一个完整的 Agent 工作环境:1. **提示词驱动 vs 规则驱动**:对比一个纯 Prompt 驱动的 Agent 和带有基础 Harness 的 Agent 在表现上的差异。2. **让项目可读并接住上次工作**:学习如何重构代码仓库结构,使其对 AI 更加友好,并建立工作交接机制。3. **跨会话工作连续性**:设计状态文件和初始化脚本,让 Agent 可以在多次对话中断后无缝恢复工作。4. **运行反馈与行为修正**:引入运行时反馈机制,让 Agent 能够自己检查代码是否能跑通,并修正错误。-5. **工作评审与自我验证**:建立独立的评审与验证环节,防止 Agent 产生“幻觉”或提前宣告胜利。+5. **工作评审与自我验证**:建立独立的评审与验证环节,防止 Agent 产生"幻觉"或提前宣告胜利。6. **综合 Agent 工作环境**:搭建一套完整的、带有可观测性的最终 Agent 工作环境(综合演练)。+7. **第一个自动循环**:从手动驱动跃迁到自动循环——goal loop、timer loop、maker-checker loop 三个递进实验。## 如何进行diff --git a/docs/zh/projects/project-07-loop-engineering-first-loop/index.md b/docs/zh/projects/project-07-loop-engineering-first-loop/index.mdnew file mode 100644index 0000000..321e0e5--- /dev/null+++ b/docs/zh/projects/project-07-loop-engineering-first-loop/index.md@@ -0,0 +1,145 @@+# Project 07. 搭建你的第一个自动循环++> 相关讲义:[L13. 从手动驱动到自动循环](./../../lectures/lecture-13-loop-engineering/index.md)++## 你要做什么++这是从 "Harness" 到 "Loop" 的跃迁项目。你已经知道怎么给 agent 配好一套环境、一套指令、一套反馈——现在你要把这套东西变成一个能自己跑的循环。++你会做三个递进的实验:先把一个任务从手动跑变成 `/goal` 自动跑,再把一个巡检任务变成 `/loop` 定时跑,最后做一个带 maker-checker 分离的完整循环,体验「人退到循环外面」是什么感觉。++## 使用仓库里的项目++仓库路径:[`projects/project-07/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-07)++| 目录 | 里面有什么 | 做什么 |+|------|----------|--------|+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-07/starter) | 一个带有完整 harness 的小型知识库项目(P06 完成态),包含 AGENTS.md、feature_list.json、init.sh、session-handoff.md、clean-state-checklist.md。 | 把这套 harness 改造成能自动循环的版本。 |+| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-07/solution) | 三个循环的完整实现:goal loop、loop timer loop、maker-checker loop,加上 loop 状态文件和验证脚本。 | 参考 loop 的设计方式和状态管理模式。 |++## 用什么工具++- Claude Code 或 Codex+- Git+- 你在 P06 搭建好的完整 harness+- 一个你常用的终端复用工具(tmux 或 screen,用于观察长时间运行的 loop)+- 可选:GitHub Actions 或 cron(用于事件驱动/定时驱动的进阶实验)++## 具体步骤++### 准备工作++1. 基于 P06 完成后的代码,从同一个 commit 出发。+2. 创建三个分支:`p07-goal-loop`、`p07-timer-loop`、`p07-maker-checker`。+3. 确认你的 harness 是工作的:跑一次 init.sh,确认状态文件、feature list、交接文档都在。+4. 选一个你要让 loop 反复做的**目标任务**。建议选一个中等大小、有明确完成标准的任务,比如:"给所有模块补充单元测试,覆盖率达到 80%" 或 "把所有 API 端点加上输入验证"。++### 实验一:Goal Loop —— 从手动跑到自动跑++切到 `p07-goal-loop` 分支。++1. **写目标描述**:把你选的任务写成一份 `goal.md`,包含:+ - 明确的目标("完成什么算做完")+ - 验证方式("怎么确认做完了"——跑测试?跑 lint?检查覆盖率?)+ - 停止条件("什么时候应该停下"——最大回合数?时间上限?预算上限?)+ - 约束("不能碰什么"——生产配置、数据库 schema 等)++2. **第一次手动跑**:你自己手动给 agent 发指令,完成一次这个任务。记录用了多少回合、你介入了多少次、结果质量如何。这是你的基线。++3. **用 `/goal` 跑**:用同一份 `goal.md` 作为输入,用 `/goal` 模式跑一次。agent 自己循环直到达成目标或触发停止条件。++4. **对比结果**:+ - 回合数差异+ - 你介入的次数差异+ - 结果质量差异(用同样的验证标准)+ - 你花的时间差异++5. **迭代 goal.md**:如果结果不好,改 goal 描述,再跑一次。直到你对结果满意,或者确认 goal loop 在这个任务上的极限在哪里。++### 实验二:Timer Loop —— 把巡检变成心跳++切到 `p07-timer-loop` 分支。++1. **选一个巡检任务**:找一个你平时手动做的、重复性的检查工作。比如:+ - 每小时跑一次测试,有失败就修+ - 每天早上检查依赖有没有安全更新+ - 每次提交后检查代码有没有违反编码规范+ - 定期扫描 TODO 注释,看哪些已经过期了++2. **写巡检脚本/prompt**:把巡检的步骤写清楚——检查什么、发现问题了怎么办、什么时候需要叫人。++3. **用 `/loop`(或 Codex 的对话线程自动化)跑**:+ - 设置合理的间隔(建议 10-30 分钟,太短你会被打扰,太长看不出效果)+ - 让它跑至少 2 小时(或者你去干别的事,过一会儿回来看)++4. **记录结果**:+ - 它发现了多少问题?+ - 它自己修了多少?+ - 有多少是误报?+ - 有多少是它修坏了的?+ - 你花了多少时间跟进它的结果?++5. **思考**:这个巡检任务值得自动化吗?节省的时间和你跟进它花的时间比,哪个多?如果不划算,是任务选错了还是 loop 设计得不好?++### 实验三:Maker-Checker Loop —— 把你从循环里拿出来++切到 `p07-maker-checker` 分支。++这是三个实验里最重要的一个。你要做一个**完整的、你不需要在场的循环**:++1. **设计循环结构**:+ - **Maker agent**:负责实现,写代码,改文件+ - **Checker agent**:负责验证,跑测试,做代码审查,打通过/不通过+ - **状态文件**(`loop-state.md`):记录当前轮次、做了什么、验证结果、下一轮要做什么+ - **停止条件**:连续 N 轮通过,或者达到最大轮次++2. **写三份 prompt**:+ - Maker 的指令(做什么、怎么做、什么不能碰)+ - Checker 的指令(验证什么、怎么验证、什么算通过、发现问题了怎么反馈)+ - 循环控制逻辑(谁先跑、跑完了怎么交接、下一轮怎么启动)++3. **跑至少 5 轮循环**:+ - 第一轮:Maker 实现 → Checker 验证 → 不通过 → 反馈给 Maker+ - 第二轮:Maker 根据反馈修改 → Checker 再验证 → ...+ - ...+ - 直到连续通过,或者你叫停++4. **记录每一轮的状态**:+ - 轮次+ - Maker 做了什么+ - Checker 发现了什么问题+ - 通过/不通过+ - 你有没有介入(如果介入了,为什么)++5. **最后复盘**:+ - 你一共介入了几次?为什么介入?+ - 如果没有介入,结果会怎么样?+ - Checker 有没有漏过问题?+ - Maker 有没有在同一个问题上反复犯错?+ - 这个循环的质量天花板在哪里?是 Maker 的能力还是 Checker 的能力?++## 怎么衡量结果++| 指标 | 实验一(Goal) | 实验二(Timer) | 实验三(Maker-Checker) |+|------|--------------|---------------|----------------------|+| 任务完成率 | 目标达成了吗? | 巡检了多少次? | 多少轮后通过? |+| 人类介入次数 | 你插手了几次? | 你跟进花了多久? | 你介入了几次? |+| 结果质量 | 和手动比怎么样? | 误报率多少?漏检率多少? | Checker 发现了多少你没发现的问题? |+| 时间节省 | 你省了多少时间? | 值得自动化吗? | 你花在设计循环上的时间 vs 你省下来的时间 |+| 可靠性 | 停止条件靠谱吗? | 有没有跑飞了? | 循环会不会卡死在同一个地方? |++## 要交什么++- `goal.md`(实验一的目标描述,至少迭代了两个版本)+- 实验一的对比记录:手动 vs goal loop+- 实验二的巡检 prompt 和 2 小时运行日志+- 实验三的三份 prompt(Maker / Checker / 循环控制)+- 实验三的 `loop-state.md`(至少 5 轮记录)+- 最终复盘:三个实验的收获、你对 loop engineering 的理解变化、哪些事情适合 loop 化、哪些不适合++## 对应讲义++- [Lecture 13 — 从手动驱动到自动循环](../../lectures/lecture-13-loop-engineering/index.md)+- [Lecture 12 — 为什么每次会话都必须留下干净状态](../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)(loop 的每一轮都需要 clean state)+- [Lecture 11 — 为什么可观测性属于 harness 的一部分](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)(你需要看到 loop 内部在发生什么)+- [Lecture 05 — 为什么状态文件是跨会话连续性的核心](../../lectures/lecture-05-why-state-files-are-the-backbone-of-continuity/index.md)(loop 状态文件是 state file 的延伸)diff --git a/docs/zh/resources/reference/index.md b/docs/zh/resources/reference/index.mdindex 8eb48b9..ef0fdda 100644--- a/docs/zh/resources/reference/index.md+++ b/docs/zh/resources/reference/index.md@@ -48,6 +48,7 @@- [Stripe: Minions: Stripe's one-shot, end-to-end coding agents](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents)(2026-02-09)和 [Part 2](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents-part-2)(2026-02-19):devbox 隔离、custom agent harness、blueprints 状态机、规则文件、MCP tool curation、安全控制、pre-push/CI 反馈循环。- [Cognition: What We Learned Building Cloud Agents](https://cognition.ai/blog/what-we-learned-building-cloud-agents)(2026-04-23):云端 agent runtime 的 VM 隔离、session snapshot/resume、orchestration、governance、audit logging 和 integrations。- [Cognition: Multi-Agents: What's Actually Working](https://cognition.ai/blog/multi-agents-working)(2026-04-22):generator-verifier loop、clean-context reviewer、smart-friend routing、manager-child coordination 和跨 agent 通信边界。+- [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)(2026-06-07):从 `/goal` 到六原语的完整 loop engineering 框架——automations、worktrees、skills、connectors、sub-agents、external state,以及四种沉默成本。- [Replit: Decision-Time Guidance: Keeping Replit Agent Reliable](https://blog.replit.com/decision-time-guidance)(2026-01-20,2026-01-23 更新):用轻量分类器在关键决策点注入短指令,而不是把所有规则塞进系统提示词。- [Vercel: How we made v0 an effective coding agent](https://vercel.com/blog/how-we-made-v0-an-effective-coding-agent)(2026-01-07):动态系统提示、streaming rewrite layer 和 deterministic/model-driven autofixers。- [Vercel: Introducing deepsec](https://vercel.com/blog/introducing-deepsec-find-and-fix-vulnerabilities-in-your-code-base)(2026-05-04):面向安全扫描的 coding-agent harness,包含 scan、investigate、revalidate、enrich、export、plugin 和 refusal-checker。