Claude Architect · 课时

循环与编排反模式

通过解析文本终止、任意设置上限以及过度狭窄的分解。

循环与编排反模式 是 CoddyKit 上的免费 Claude Architect 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Claude Architect 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Claude Architect 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why Loops Go Wrong

The agentic loop is deceptively simple: send a request, inspect the stop_reason, run any tools, append results to history, repeat until end_turn. Yet this is exactly where production agents fail most often.

This lesson dissects three orchestration anti-patterns that recur across the Claude Certified Architect exam:

Text-parsing termination — stopping when the reply contains a word like "done".
Arbitrary iteration caps used as the primary stop mechanism.
Over-narrow decomposition — slicing work so finely that quality and coordination collapse.

Each looks reasonable in a demo and breaks under real traffic. Let's make the correct patterns reflexive.

The Loop Contract

Claude keeps no server-side state. Every turn you resend the full messages history. The model signals control flow through stop_reason, not through prose.

The four stop reasons you orchestrate against:

end_turn — the task is complete; exit the loop.
tool_use — run the requested tools, append results, continue.
max_tokens — output was truncated.
stop_sequence — a configured sequence was emitted.

The contract is structural. Branch on the field the API guarantees, never on the text the model happens to produce.

import anthropic

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Audit the repo and summarize risks."}]

while True:
    resp = client.messages.create(
        model="claude-opus-4-1",
        max_tokens=2048,
        tools=tools,
        messages=messages,
    )
    if resp.stop_reason == "end_turn":
        break
    # ... handle tool_use, append results, loop ...

Anti-Pattern 1: Parsing Text for "Done"

The most common termination bug: scanning the assistant's text for a completion signal.

This fails in ways that are hard to debug:

The model writes "I'm not done yet" — your substring match on "done" fires anyway and exits early.
The model finishes but phrases it as "that completes the analysis" — your check never matches and the loop spins.
A tool result quotes the word "finished" — false termination.

Natural language is probabilistic; control flow must be deterministic. The stop_reason field exists precisely so you never have to guess from prose.

# ANTI-PATTERN — do NOT do this
text = resp.content[0].text.lower()
if "done" in text or "finished" in text:
    break  # brittle: false positives + missed completions

The Correct Termination

Terminate on stop_reason == "end_turn". When it is tool_use, execute every requested tool, append the results as a tool_result message, and continue. The model decides when it is finished by emitting end_turn — you simply honor that signal.

This keeps the decision model-driven where it belongs. The model has the full context to judge completion; your harness only routes the structured signal.

while True:
    resp = client.messages.create(
        model="claude-opus-4-1", max_tokens=2048,
        tools=tools, messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason == "end_turn":
        break

    if resp.stop_reason == "tool_use":
        results = run_requested_tools(resp.content)
        messages.append({"role": "user", "content": results})

Anti-Pattern 2: The Cap as Primary Stop

The next trap is treating an iteration cap as the way you stop. You write for _ in range(5) and call it orchestration.

The problem is intent. A cap that is your primary stop means:

Tasks that legitimately need 7 tool calls are silently truncated mid-investigation.
Tasks that finish in 2 calls still appear "capped" in your telemetry, hiding real behavior.
You have no signal distinguishing completed from ran out of budget.

The model's end_turn must remain the decision point. The cap is something else entirely.

# ANTI-PATTERN — cap IS the stop mechanism
for _ in range(5):
    resp = client.messages.create(...)
    run_tools(resp)
# loop exits by exhaustion, not because the task is done

Caps as a Safety Net

Iteration caps are valid — but only as a safety net against runaway loops, never as the primary termination logic. The reflex from the fact sheet: decisions are model-driven; reserve hard code for guarantees.

So the cap sits around the model-driven loop. end_turn is how you normally exit. The cap only fires in the pathological case, and when it does you treat that as an error condition worth logging and escalating — not a normal exit.

MAX_ITERS = 25  # safety net, not the plan
for i in range(MAX_ITERS):
    resp = client.messages.create(...)
    messages.append({"role": "assistant", "content": resp.content})
    if resp.stop_reason == "end_turn":
        break          # normal, model-driven exit
    handle_tools(resp)
else:
    log.error("hit safety cap without end_turn")
    escalate(messages)  # treat as anomaly, not success

When Guarantees DO Belong in Code

"Model-driven" does not mean "never use hard code." Reserve deterministic code for genuine guarantees — places where a probabilistic decision is unacceptable.

Examples from the exam's anti-pattern catalog:

A hook blocking a refund over $500 — deterministic enforcement, ~100% reliable, versus a prompt at ~90%.
A programmatic precondition: block process_refund until get_customer has returned a verified ID.

The line is clear: route open-ended decisions to the model; encode policy and safety in code. Caps belong to the latter only as a backstop.

Anti-Pattern 3: Over-Narrow Decomposition

Multi-agent systems use a hub-and-spoke shape: a coordinator decomposes, delegates, aggregates, routes, and handles errors. The orchestration failure here is slicing the work too finely.

Over-narrow decomposition spawns a subagent per trivial step. The costs compound:

Coordination overhead dwarfs the actual work.
Each subagent loses context — subagents do not inherit the coordinator's conversation history.
Cross-cutting judgment that needs a whole-picture view gets fragmented across isolated agents.

Decompose by meaningful unit of work, not by individual operation.

Context Must Be Passed Explicitly

Because subagents start with a blank history, the coordinator must pass all needed context explicitly in each subagent prompt. Over-narrow decomposition makes this worse: more agents means more boundaries where context is dropped and more prompts to keep in sync.

Note also that multiple Task calls in a single response run in parallel, and the coordinator's allowedTools must include "Task". Parallelism is a reason to decompose at the right granularity — independent, self-contained units — not to shatter one coherent task into fragments that each need the same shared context re-injected.

AgentDefinition(
    name="file_reviewer",
    description="Reviews a single source file for local correctness issues.",
    system_prompt=(
        "You review ONE file in isolation.\n"
        # subagent has NO coordinator history — pass everything it needs:
        "Project conventions: {conventions}\n"
        "File under review: {file_path}\n"
        "Known constraints: {constraints}\n"
    ),
    allowed_tools=["Read", "Grep"],  # least privilege
)

The Right Granularity: Code Review

Code review is the canonical example of correct decomposition — and it shows the difference from over-narrow slicing.

The right structure is a per-file local pass followed by a separate cross-file integration pass. A single-pass multi-file review dilutes attention; one agent juggling everything misses both local bugs and integration issues.

The wrong over-narrow extreme is the opposite error: a subagent per function or per line, none of which can see enough to judge correctness. Decompose into passes that each have a coherent scope — file-level, then integration-level — not into fragments below the level at which judgment is possible.

Fixed vs Adaptive Decomposition

One more lever prevents both over- and under-decomposition: match the strategy to the problem shape.

Fixed pipelines / prompt chaining for known, sequential steps — extract, then validate, then format.
Adaptive decomposition for open-ended investigations where the next step depends on what was just found.

Forcing a fixed pipeline onto an open-ended research task pushes you toward brittle over-narrow stages; using adaptive decomposition for a deterministic three-step transform adds needless coordination. Choose deliberately, and let the model drive the steps it should own while code owns the steps that must be guaranteed.

Quick Check: Loop Termination

An architect's agent loop calls tools across several turns. Pick the orchestration that matches the certification's reliability guidance.

Recap: Orchestrate on Signals, Decompose with Intent

Three reflexes to carry into the exam and into production:

Terminate on stop_reason. Exit on end_turn; never parse text for "done". The model owns the completion decision; you route its structured signal.
Caps are a safety net, not a plan. Keep a generous cap to catch runaways, treat hitting it as an anomaly, and reserve hard code for real guarantees (hooks, preconditions).
Decompose at the right grain. Hub-and-spoke with coherent units — per-file then cross-file passes, not a subagent per line. Pass all context explicitly, and match fixed vs adaptive strategy to the problem.

Get these three right and most loop-and-orchestration distractors on the exam fall away.

常见问题解答

「循环与编排反模式」课时是免费的吗？

是的 — 「循环与编排反模式」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Claude Architect 课程的其余内容，请升级到 CoddyKit PRO。 Claude Architect 课程共包含 4 节课。

「循环与编排反模式」这节课中我会学到什么？

通过解析文本终止、任意设置上限以及过度狭窄的分解。你通过在浏览器中直接运行的动手代码来练习 Claude Architect，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Claude Architect 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Claude Architect 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「循环与编排反模式」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Claude Architect 课中编写并运行代码吗？

能。每节 Claude Architect 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Claude Architect