Getting Started With Loops — Claude Code Loop Design ![rw-book-cover](https://readwise-assets.s3.amazonaws.com/static/images/article2.74d541386bbf.png) 🔗 **Source:** [Getting Started With Loops — Claude Code Loop Design](https://twitter.com/ClaudeDevs/status/2074208949205881033#thread) > [!note]+ Document Notes > tags: [ai-agents, claude-code, loop-design, developer-workflows, maker-checker, automation] > author: delba_oliveira (Delba de Oliveira) > source: Claude Code team / @ClaudeDevs > reference: https://readwise.io/reader/document_raw_content/01kx4nm310hydqkcvkta93dvrq > date created: {{date:YYYY-MM-DD}} {{time:HH:mm}} > > # 🏷️ Title: Getting started with loops — Claude Code loop design > <!-- deep-read:sections start --> ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ### 🔗 References - Claude Code `/goal`, `/loop`, `/schedule`, `/usage`, `/workflows` commands (product primitives referenced inline). - SKILL.md skill format for encoding verification steps. ## 📝 Summary - The Claude Code team defines a taxonomy of agent loops and explains when each fits. - It matters because "designing loops" is replacing one-shot prompting as the way to get durable work out of coding agents, and choosing the wrong primitive wastes tokens and trust. - Key stakeholders: engineers running agents, DevRel teams teaching agent patterns, and anyone operating a maker/checker practice. - Risks and tradeoffs: complex loops on simple tasks add overhead; unbounded loops burn tokens; self-verification is only as good as the checks you encode. - Bottom line: start with the simplest loop, encode "what good looks like," and add a fresh-context reviewer instead of trusting the agent to grade itself. ## 📖 Main Content - The piece categorizes loops along four axes: how they are triggered, how they are stopped, which Claude Code primitive is used, and which task fits. - Five loop types are named: turn-based (manual, per-prompt), goal-based (`/goal`, evaluator-gated), time-based (`/loop` local and `/schedule` cloud), and proactive (event/schedule-driven, no human in real time). - The agentic loop is defined as gather context → take action → check work → repeat → respond. Encoding manual steps as a SKILL.md improves the check step, and quantitative checks make self-verification easier. - Goal-based loops introduce an evaluator model: when Claude tries to stop, the evaluator tests the success condition and sends the work back until the goal is met or a turn cap is reached — so the agent can't declare "good enough" early. - Two operational sections close the piece: maintaining code quality (clean codebase, verifiable "what good looks like," reachable docs, a second reviewer agent, and encoding fixes into the system) and managing token usage (right primitive/model, clear stop criteria, pilot before scale, scripts for deterministic work, `/usage` review). - Contested/uncertain: the article asserts a "fresh context is less biased" reviewer improves quality; that is a design claim, not a measured result here. ### 🗒️ Notes - **Loop definition**: agents repeating cycles of work until a stop condition is met. Categorize by trigger, stop, primitive, task. Explicit caution: not all tasks require complex loops. - **Turn-based**: triggered by a user prompt; stops when Claude judges the task done or needs more context. Best for shorter, one-off tasks. Every prompt is already a manual loop with you directing each turn. - **Self-verification lever**: encode manual steps as SKILL.md → Claude checks more of its own work end-to-end; the more quantitative the checks, the easier self-verify. - **Goal-based (`/goal`)**: triggered manually; stops when goal achieved OR max turns hit. Best for verifiable exit criteria. Evaluator model gate prevents early stopping. Deterministic criteria (tests passed, score threshold) most effective. - **Time-based (`/loop`, `/schedule`)**: triggered by interval; stops on cancel or completion (PR merges, queue empties). `/loop` runs locally; `/schedule` promotes it to the cloud as a routine. - **Proactive**: triggered by event or schedule, no human in real time; each task exits at its goal, routine runs until turned off. Best for bug reports, triage, migrations, dependency upgrades. Route routines to smaller/faster models; reserve the most capable model for judgment calls. - **Code quality**: keep codebase clean, encode what good looks like with skills, make docs reachable, use a second agent for review (fresh context, less biased). When output misses the bar, encode the fix into the system for all future iterations — don't just fix the one instance. - **Token usage**: clear boundaries, right primitive/model, defined stop criteria, pilot before a large run, scripts for deterministic work, don't over-schedule routines, review with `/usage`, `/goal`, `/workflows`. - **Getting started**: find the task where you're the bottleneck; ask which piece to hand off (write the verification check? is the goal clear? does work arrive on a schedule?). Run, observe stalls/over-reach, iterate. ## 📚 References - [Claude Code](https://www.anthropic.com/claude-code) — the agent and primitives (`/goal`, `/loop`, `/schedule`) referenced throughout. - [Agent Skills / SKILL.md](https://docs.anthropic.com/en/docs/claude-code/skills) — mechanism for encoding verification steps. ## 🗣️ Paraphrase - Loops are agents cycling through work until a stop rule fires; sort them by trigger, stop, primitive, and task, and reach for complexity only when the task needs it. - Turn-based loops handle short one-offs; goal-based loops add an evaluator that refuses to stop until the criterion passes or the turn cap hits; time-based and proactive loops handle recurring and event-driven streams. - Quality comes from the surrounding system — clean code, encoded standards, reachable docs, and a fresh-context reviewer — plus disciplined token boundaries and piloting before scale. ## 📰 Newsletter - Fresh from the Claude Code team: a crisp taxonomy of agent "loops" — turn-based, goal-based (`/goal`), time-based (`/loop` and `/schedule`), and proactive. If you run any kind of automation, this is the mental model to steal. - The standout idea for WordPress and ops folks: encode "what good looks like" as a SKILL.md so the agent checks its own work, then add a second agent with fresh context to review — because an agent grading its own homework is exactly the trap maker/checker discipline exists to avoid. - Practical starter move: pick the one task where you're the bottleneck and ask "can I write the verification check?" Helpful commands to explore: `/goal`, `/loop`, `/schedule`, `/usage`, `/workflows`. ## ✅ Action Items #### DevRel - Developer advocacy: turn the five-loop taxonomy into a talk/demo mapping each type to a real repo task with measurable stop criteria. - Education: run an office-hours session on writing verification checks (the "can you write the check?" prompt) as the gateway skill for loops. - Developer experience: ship a SKILL.md template that encodes quantitative self-checks so downstream users get self-verifying loops by default. - Developer marketing: content series on maker/checker with a fresh-context reviewer as the differentiator. - Community management: collect examples of loops that stalled or over-reached to build a shared failure-mode library. - Internal/external/cross-project: align routine-scheduling SLAs so proactive loops don't over-run. #### OSPO - Policy & Governance: set a policy that any scheduled/proactive agent routine registers in a loop registry with an owner and stop condition. - License Compliance: not applicable to this source — the piece covers agent loop design, not licensing. - Security Management: gate proactive loops (migrations, dependency upgrades) behind review since they act with no human in real time. - Software Inventory: not applicable to this source — no SBOM content. - Developer Support: offer consultation hours on choosing the right primitive/model to control token spend. - Community Engagement: not applicable to this source — no upstream-funding content. - Strategic Alignment: report loop reliability (missed runs, over-reach) as an operational KPI. #### Community - Maintainers: add a "loop hygiene" checklist to release rituals (clear stop criteria, pilot before scale). - Contributors: create a "first loop" onboarding path — one bottleneck task, one verification check. - Sponsors: not applicable to this source — no sponsorship content. - Ecosystem: run cross-project drills on proactive-loop failure (unbounded runs, silent over-reach). #### WordPress - Core: not applicable to this source — no WordPress Core content; general agent-workflow piece. - Core Performance: not applicable to this source. - Core AI: adopt "encode what good looks like" + evaluator-gated goals as a responsible-AI guardrail for any agent tooling. - **Core Program Team:** map recurring coordination chores (triage) to proactive loops on smaller models. - Mobile: not applicable to this source. - Playground: build a reproducible lab demonstrating turn-based vs goal-based stop behavior. - Community: not applicable to this source. - Training: turn the taxonomy into a lesson path with a hands-on `/goal` exercise. - Marketing: not applicable to this source. - Support: encode common support-triage checks as SKILL.md self-verification. - Design: not applicable to this source. - Documentation: "make docs easy to reach" — ensure agent-facing docs are indexed for loop retrieval. - Photos / TV / Polyglots / Meta / CLI / Hosting / Tide / Openverse / Themes / Plugins: not applicable to this source — no coverage of these teams. - Accessibility: not applicable to this source — no accessibility content. #### The WPCC - Programs / Projects / Funding experiments: not applicable to this source — no funding or fellowship content. ### FAIR - Technical independence / Policies and covenants / Productized governance artifacts: not applicable to this source — no federation or governance-artifact content. ## 🧪 Hypotheses - Encoding manual verification steps as a SKILL.md measurably raises the rate at which an agent catches its own errors before responding. - Goal-based loops with deterministic criteria (tests passed, score threshold) reach acceptable output in fewer human interventions than turn-based loops on the same task. - A second agent with fresh context surfaces defects the original agent misses at a higher rate than the original agent re-reviewing its own output. - Routing proactive routines to smaller/faster models, reserving the capable model for judgment calls, lowers token cost without lowering task success. - Piloting a loop before a large run reduces total tokens spent versus launching at full scale and correcting mid-run. ### 📊 Methodology - Run A/B tasks: identical repo bug fixed via turn-based vs `/goal`; measure human turns to acceptance and defect escape rate. - Instrument SKILL.md self-checks on/off; count errors caught pre-response. - Compare self-review vs fresh-context second-agent review on a labeled defect set; measure detection rate. - Track token usage via `/usage` across small-model vs capable-model routing on the same proactive workload. ### ❓ Questions - What quantitative check density is enough before self-verification plateaus? - Where is the crossover point at which a turn-based loop should become a goal-based one? - How do you detect "over-reach" in a proactive loop early enough to stop it cheaply? - What belongs in a script (deterministic) vs a model turn (judgment) inside one loop? ### 🔮 Future Research - A shared benchmark for loop failure modes (stall vs over-reach) across task types. - Empirical curves of token cost vs stop-criteria strictness. - Reviewer-bias measurement: how much does "fresh context" actually reduce missed defects? ### 💡 Implications - For a maker/checker "Loop Engineering" practice, this article is near-perfect external validation: the "second agent with fresh context" is exactly the blind-checker pattern, and "a checker never re-reads the maker's draft — it re-derives from source" maps to the piece's fresh-context reviewer. - The taxonomy gives Courtney's loop registry a vocabulary: tag each registered loop as turn/goal/time/proactive, so the loop-fleet-checker can reason about expected trigger/stop behavior per row. - "Deterministic facts need no second agent: the script is the check" from the personal loop-OS matches the article's "use scripts for deterministic work" and "the more quantitative the checks, the easier it is for Claude to self-verify" — reinforcing script-first checks where possible. - `/schedule` as the cloud promotion of `/loop` clarifies the LOCAL-vs-cloud reliability tradeoff behind the ~51 routines that miss runs: local `/loop` depends on the machine being awake; cloud routines don't. - "Encode it to improve the system for all future iterations" is the operational core of the encode-what-good-looks-like habit — every checker catch should become a SKILL.md rule, not a one-off fix. - Policy: register every proactive/scheduled loop with owner + stop condition (already the memory-spine convention), matching the article's "don't run routines more often than needed." ### 🧠 Learning Styles Assessment - Reading level estimate: roughly grade 11–13 (Flesch-Kincaid), dense technical prose with compound sentences and product-specific jargon. #### 👀 Visual learners - Present: none — prose only, no diagrams or code beyond inline command names. - Improve: a 2x2 of trigger×stop, a flowchart of the agentic loop, and a table mapping loop type → primitive → best task. #### 🔊 Aural learners - Present: none. - Improve: a 3-minute audio walkthrough of the five loop types with one example each. #### 🗣️ Verbal learners - Present: clear definitions per loop type; the agentic-loop verb sequence. - Improve: a glossary (evaluator model, routine, primitive) and a plain-language analogy for goal-based gating. #### 🧩 Kinesthetic learners - Present: the "getting started" hand-off exercise. - Improve: a reproducible lab repo with a `/goal` task and a failing test to make pass. #### 🧠 Logical learners - Present: four-axis categorization; deterministic-criteria emphasis. - Improve: a decision tree for picking a primitive; an error-budget framing for token spend. #### 🧑‍🤝‍🧑 Social learners - Present: none. - Improve: a discussion prompt on where each reader's bottleneck task fits the taxonomy. #### 🧘‍♀️ Solitary learners - Present: the self-reflection "pick one task" prompt. - Improve: a self-check worksheet for "is my goal clear / can I write the check." #### 🌿 Naturalistic learners - Present: none. - Improve: frame routines as an ecosystem where over-running loops consume shared token "resources." ### 📊 Accessibility Assessment #### Screen reader semantics - Present: clean H2 heading structure, `<code>` for command names. - Improve: ensure headings aren't skipped when re-published; keep `<code>` for all primitives. #### Keyboard navigation - Present: not applicable to this source — plain article text, no interactive UI. - Improve: n/a. #### Contrast and readability - Present: not evaluable from raw HTML; depends on host theme. - Improve: verify 4.5:1 in the published render. #### Text resizing and reflow - Present: semantic HTML reflows well. - Improve: confirm inline `<code>` doesn't overflow at 200% zoom. #### Media and captions - Present: not applicable to this source — no media. - Improve: if a diagram or audio version is added, caption/transcribe it. #### Forms and interactions - Present: not applicable to this source — no forms. - Improve: n/a. #### Standards reference - Map any published-render contrast gaps to WCAG 2.2 AA 1.4.3; heading order to 1.3.1. ### 🌍 DEIB Assessment #### Cultural breadth - Present: neutral, region-agnostic technical content. - Improve: examples span only software-engineering contexts; broaden to non-engineering automation. #### Inclusive language - Present: plain, gender-neutral, jargon defined on first use. - Improve: expand a short glossary for readers new to agent tooling. #### Neurodiversity support - Present: chunked sections, consistent per-loop structure (trigger/stop/best-for). - Improve: add a summary table so readers don't hold five parallel structures in memory. #### Representation - Present: single-author byline (@delba_oliveira); no identity content. - Improve: n/a for this format. #### Psychological safety - Present: encouraging, low-pressure "start simple / iterate" framing. - Improve: none needed. ### ✅ Logical Validity #### Strong reasoning - Analogical/definitional: framing every prompt as "already a manual loop" (agentic loop) grounds the taxonomy in something readers already do — strong because it lowers the concept's activation energy. - Causal: "each time Claude tries to stop, an evaluator model checks your condition and sends it back until the goal is met or the turn cap is hit" gives a concrete mechanism for why goal-based loops don't stop early. - Inductive: "deterministic criteria (tests passed, score threshold) are most effective" generalizes from verifiable-exit examples; clarify with the evidence base. #### Fallacies - Mild appeal to authority: claims like "a reviewer with fresh context is less biased" are asserted as design fact without cited measurement. Fix: link an evaluation or label it as a design heuristic. - Hasty generalization risk: "route routines to smaller, faster models" as blanket advice ignores tasks where small models fail judgment silently. Fix: add the boundary condition (judgment calls stay on the capable model — which the text does note). #### Tone of voice - Instructional, confident, pragmatic ("start with the simplest solution"); coaching close ("Run the loop, observe where it stalls or over-reaches, and iterate"). ### 🛡️ DARVO Analysis - Not applicable to this source — the piece is neutral technical instruction with no accusation, defense, or victim/offender dynamic. No denial, attack, or reversal present. ## 🎯 Conclusion - Bottom line: pick the simplest loop that fits, categorize by trigger/stop/primitive/task, encode "what good looks like" so the agent self-verifies, and add a fresh-context reviewer instead of trusting self-grading. - Next steps for readers: identify your bottleneck task, decide whether you can write the verification check or whether the work arrives on a schedule, choose the matching primitive (`/goal`, `/loop`, `/schedule`), pilot small, then iterate on where it stalls or over-reaches. ## 🔄 Refactor Appendix — Getting started with loops > Density: 2–5 Literature atoms (H3), 0–3 Permanent candidates (H4). > Defaults: 3 Literature, 1 Permanent. Resonance filter: if you can't > articulate in one line why a claim matters, drop it. > > Konik claim-header rules: present tense, declarative, ≤10 words when > possible, searchable, unique, mirrors annotation focus if present. > > Atomicity: one declarative sentence per atom. "and"/"also" → split. > > Tag pool: #bmf · #addendum · #xref · #articleseed · #storystem · #share · #aphorisms ### 📚 Literature Atoms (H3) #### Loops repeat work until a stop condition > [!quote] ID:rw_01kx4nm310hydqkcvkta93dvrq > we define loops as agents repeating cycles of work until a stop condition is met **Context & use**: - Opening definition of the piece. - Gives the loop registry a precise definition to tag rows against (trigger/stop/primitive/task). **Tags**: #xref **Highlight**: [view highlight](readwise://read/document/01kx4nm310hydqkcvkta93dvrq) <!-- atomicity: 1 idea ✓ --> #### Quantitative checks make agent self-verification easier > [!quote] ID:rw_01kx4nm310hydqkcvkta93dvrq > The more quantitative the checks, the easier it is for Claude to self-verify. **Context & use**: - Turn-based loops section, on encoding manual steps as SKILL.md. - Directly supports script-first checks in the maker/checker OS. **Tags**: #xref #addendum **Highlight**: [view highlight](readwise://read/document/01kx4nm310hydqkcvkta93dvrq) <!-- atomicity: 1 idea ✓ --> #### A fresh-context second agent reviews less biased > [!quote] ID:rw_01kx4nm310hydqkcvkta93dvrq > use a second agent for code reviews (a reviewer with fresh context is less biased) **Context & use**: - Maintaining code quality section. - External validation of the blind-checker pattern (checker never re-reads the maker's draft). **Tags**: #xref #addendum **Highlight**: [view highlight](readwise://read/document/01kx4nm310hydqkcvkta93dvrq) <!-- atomicity: 1 idea ✓ --> #### Encode failures into the system, not one fix > [!quote] ID:rw_01kx4nm310hydqkcvkta93dvrq > When a result doesn't meet the standard, don't stop at fixing the individual issue — encode it to improve the system for all future iterations. **Context & use**: - Maintaining code quality section. - The operational core of "encode what good looks like" — every checker catch becomes a rule. **Tags**: #xref #aphorisms **Highlight**: [view highlight](readwise://read/document/01kx4nm310hydqkcvkta93dvrq) <!-- atomicity: 1 idea ✓ --> ### 🧠 Permanent Candidates (H4) #### A loop's output quality equals the system around it **Claim** (one sentence, Courtney's voice): An agent loop is only as reliable as the encoded checks, clean context, and independent reviewer surrounding it — the loop itself is the least of it. **Evidence pointer**: [[#A fresh-context second agent reviews less biased]] **Scope & conditions**: Holds for maker/checker loops where verification can be encoded; weaker for purely exploratory work with no definable "good." **Links**: - [[Loop-engineering OS]] — because extends - [[Maker-checker discipline]] — because evidence-for - [[SKILL.md self-verification]] — because applies-in loop design <!-- atomicity: 1 idea ✓ --> ### ✏️ Fleeting Queue - [F1] Tag every row in the loop registry with its loop type (turn/goal/time/proactive). — 2. Areas/Loop Reports/_loop-registry.md #fleeting #inbox - [F2] Audit ~51 missing-run routines for local `/loop` vs cloud `/schedule` placement. — courtney_scheduler_reliability #fleeting #inbox ### → Things 3 (max 2 actions) - [ ] Add a loop-type field (turn/goal/time/proactive) to the loop registry template — Loop Reports #things <!-- deep-read:sections end --> 📄 **Full text:** [[Full Document Contents/Articles/Getting Started With Loops — Claude Code Loop Design.md|Getting Started With Loops — Claude Code Loop Design by @ClaudeDevs (delba_oliveira)]] ## Highlights - we define loops as agents repeating cycles of work until a stop condition is met ([View Highlight](https://read.readwise.io/read/01kx4nw6st4zvargbpq19nv334)) - Note: Core definition — precise trigger/stop/primitive/task vocabulary for the loop registry. - Tags: atom/literature/h1 - The more quantitative the checks, the easier it is for Claude to self-verify. ([View Highlight](https://read.readwise.io/read/01kx4nwd9h73ayn34ek31yvpvw)) - Note: Supports the script-first, deterministic-check principle in the maker/checker OS. - Tags: atom/literature/h2 - each time Claude tries to stop, an evaluator model checks your condition and sends it back until the goal is met or the turn cap is hit. ([View Highlight](https://read.readwise.io/read/01kx4nx9tz8hg62v7w22fn27zq)) - Note: Mechanism behind /goal evaluator gating — prevents declaring good-enough early. - Tags: atom/literature/h6 - use a second agent for code reviews (a reviewer with fresh context is less biased) ([View Highlight](https://read.readwise.io/read/01kx4nwr1xbjp8s3xms3ax92zr)) - Note: External validation of the blind-checker pattern — a checker never re-reads the maker's draft. - Tags: atom/literature/h3 - When a result doesn't meet the standard, don't stop at fixing the individual issue — encode it to improve the system for all future iterations. ([View Highlight](https://read.readwise.io/read/01kx4nx0m3rrz5757zz429zsgg)) - Note: Operational core of encode-what-good-looks-like — every checker catch becomes a durable rule. - Tags: atom/literature/h4 ## Links - [[3. Resources/Permanent Notes/Human Review Capacity Sets the Agent WIP Limit]] — Loop cadence must remain bounded by the review capacity that can validate its output. - [[3. Resources/MOCs/AI Agent Safety MOC]] — Operational reference for bounded agent loops.