Claude Architect · 课时

反模式：任意设置迭代上限

上限是安全网，而不是停止机制。

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

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

The Tempting Shortcut

You build an agentic loop. To feel safe, you write for i in range(5) and call it done. The agent stops after 5 turns.

This feels responsible. It is actually an anti-pattern. An arbitrary iteration cap as your primary stop mechanism cuts the model off mid-thought and produces incomplete work.

This lesson shows you the right mental model: a cap is a safety net, never the thing that decides when the task is finished.

How the Loop Actually Ends

The agentic loop is simple: send a request, inspect stop_reason, and react.

tool_use → run the tools, append results to history, loop again
end_turn → the model is finished; you stop

The model signals completion via stop_reason. Your job is to listen for that signal, not to guess a turn count in advance.

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=tools,
)

if resp.stop_reason == "tool_use":
    # run tools, append results, loop again
    pass
elif resp.stop_reason == "end_turn":
    # task complete -- this is the real stop
    pass

Why a Cap Is the Wrong Primary Stop

A multi-step task does not have a fixed length. A code refactor might need 3 turns; a research task might legitimately need 14.

If your loop stops at i == 5:

The model may be mid tool-call, returning truncated or useless output.
You ship incomplete work and call it 'done'.
You are guessing the future instead of reacting to the model's actual stop_reason.

Decisions about when work is complete are model-driven. The cap knows nothing about the task.

The Even Worse Cousin

There is a related anti-pattern that often hides next to iteration caps: parsing the model's text for completion words like 'done', 'finished', or 'complete'.

This is fragile. The model might write 'I'm not done yet' and your if 'done' in text check would fire incorrectly. Worse, it might genuinely finish without ever saying the magic word.

Terminate on stop_reason, never by scanning prose. The protocol gives you a reliable signal; text does not.

# ANTI-PATTERN -- do NOT do this
if "done" in resp.content[0].text.lower():
    break  # fragile: text is not a control signal

# CORRECT -- react to the protocol
if resp.stop_reason == "end_turn":
    break

So What Is a Cap For?

Caps are not useless. They are a safety net for the case where the loop misbehaves — a tool that keeps failing, or a model that gets stuck cycling.

Think of it like a circuit breaker: it should almost never trip. If your cap is firing on normal, healthy tasks, it is set too low and it is doing the wrong job.

The primary stop is end_turn. The cap only catches runaway loops that would otherwise burn tokens forever.

The Correct Loop Shape

Here is the pattern that gets it right. The while True reacts to stop_reason; the cap sits outside as a guardrail with a generous limit.

Notice: a healthy task exits via end_turn. The cap only ever matters when something has gone wrong.

MAX_TURNS = 25  # generous safety net, not the plan

for turn in range(MAX_TURNS):
    resp = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=messages,
        tools=tools,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason == "end_turn":
        break  # PRIMARY stop -- model says it's finished

    if resp.stop_reason == "tool_use":
        results = run_tools(resp.content)
        messages.append({"role": "user", "content": results})
else:
    # reached only if the net trips -- log and escalate
    log.warning("Hit MAX_TURNS -- investigate stuck loop")

When the Net Trips, Don't Pretend Success

The difference between a safety net and a stop mechanism shows up in what you do when the limit is hit.

A correct safety net treats hitting the cap as an error condition: log it, surface partial results, and escalate. It is a signal that something is stuck.

An anti-pattern cap silently returns whatever it has as if the task succeeded. That is silent error suppression — you hide a failure and ship broken output downstream.

Hard Code for Guarantees, Not for Decisions

A useful rule for architects: reserve hard code for guarantees; leave decisions to the model.

'Is this task complete?' is a decision → the model answers it via end_turn.
'Never exceed N turns under any circumstances' is a guarantee → deterministic code enforces it.

An iteration cap is legitimately in the guarantee category. The mistake is letting a guarantee impersonate a decision — using the cap to decide completeness instead of to bound worst-case cost.

Compare: Caps vs. Hooks

Don't confuse an iteration cap with a policy hook — both are deterministic code, but they guard different things.

A hook (e.g. PostToolUse or an outgoing-call hook) gives 100% deterministic enforcement of a business rule: block a refund over $500, regardless of what the model wants.
An iteration cap bounds loop cost / runaway behavior.

Use hooks when failure has financial, legal, or safety consequences. Use a cap to keep a loop from running forever. Neither one decides whether the task is logically complete.

# Deterministic GUARANTEE via a hook -- for business rules
# (settings.json)
{
  "hooks": {
    "PostToolUse": [
      { "matcher": "process_refund",
        "command": "./block_refund_over_500.sh" }
    ]
  }
}

Picking a Cap Value

If a cap is a net and not a plan, how high should it be? High enough that healthy tasks never touch it.

Estimate the worst-case legitimate turn count for your task, then leave generous headroom on top.
If you find yourself tuning the cap to make outputs 'feel complete', stop — you've turned it back into a stop mechanism.
Track how often it trips. Frequent trips mean a stuck tool, a bad prompt, or a cap set too low.

The Architect's Checklist

Before you ship an agentic loop, confirm:

The loop terminates on stop_reason == "end_turn" — the primary, model-driven stop.
You inspect tool_use and append tool results to the full message history every turn.
You never parse text for 'done' / 'finished' as a control signal.
The iteration cap is generous and exists only as a safety net.
Hitting the cap logs, surfaces partial results, and escalates — it never masquerades as success.

Quick Check

Apply the lesson to a real design decision.

Recap

Key takeaways:

Completion is the model's decision, signalled by stop_reason == "end_turn". That is your primary stop.
An iteration cap is a safety net, never the primary stopping mechanism. Set it generously so healthy tasks never hit it.
Never parse text for words like 'done' to decide termination.
When the cap does trip, treat it as an error: log, surface partial results, escalate — don't fake success.
Reserve hard code for guarantees, decisions for the model. A cap bounds worst-case cost; it does not judge whether the work is finished.

常见问题解答

「反模式：任意设置迭代上限」课时是免费的吗？

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

「反模式：任意设置迭代上限」这节课中我会学到什么？

上限是安全网，而不是停止机制。你通过在浏览器中直接运行的动手代码来练习 Claude Architect，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Claude Architect 需要有经验吗？

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

「反模式：任意设置迭代上限」课时需要多长时间？

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

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

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

此课程中的所有课时

← 返回 Claude Architect