多轮分解
先逐个文件进行局部处理，再进行跨文件整合处理。
多轮分解 是 CoddyKit 上的免费 Claude Architect 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Claude Architect 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Claude Architect 课程共包含 4 节课。
本课时的部分内容尚未翻译，以英文显示。
Why One Pass Isn't Enough
When you ask Claude to review a changeset spanning many files in a single pass, attention gets diluted. The model spreads finite focus across every file at once, so subtle per-file bugs slip through and genuine cross-file issues get buried.
The architect's answer is multi-pass decomposition: split the work into a per-file local pass first, then a separate cross-file integration pass. Each pass has one clear job, so attention stays sharp.
Two Different Questions
The two passes ask fundamentally different questions, which is exactly why they shouldn't be merged:
- Local pass: "Is THIS file internally correct?" — logic errors, null handling, naming, dead code, style within the file's own boundary.
- Integration pass: "Do these files work TOGETHER?" — mismatched function signatures, broken contracts, inconsistent assumptions across module boundaries.
Single-pass review forces both questions into one diluted prompt. Two passes keep each focused.
Pass 1 — Find the Files
The local pass starts with discovery. Use Claude Code's built-in tools incrementally: Glob to find files by pattern, then Read each one in isolation.
Reviewing one file per request keeps the context small and the attention concentrated. This is the opposite of dumping the whole diff into a single prompt.
# Discover changed source files, review each on its own
glob '**/*.py' | grep -Ff <(git diff --name-only main)
# Then, per file, a focused review request:
claude -p "Review ONLY src/billing/refund.py for local correctness: \
logic errors, null handling, edge cases. Do not assume anything \
about other files." --output-format jsonOne File, One Request
In the local pass, give Claude a tight, explicit boundary: review only this file, and judge it on its own terms. Vague instructions like "be thorough" underperform; explicit criteria win.
State exactly what counts as a finding so the model doesn't drift into speculation about files it hasn't seen.
from anthropic import Anthropic
client = Anthropic()
def local_pass(path, source):
return client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1500,
system=("You review ONE file in isolation. Flag a finding ONLY "
"when the code is internally wrong, never on guesses "
"about unseen files."),
messages=[{"role": "user",
"content": f"File: {path}\n\n{source}"}],
)Structured Findings Per File
Have each local pass emit structured output so findings are machine-mergeable for the next pass. Use tool_choice with a schema-backed tool to guarantee well-formed JSON.
Critically: mark a field required only if it is always present. Never require a field that may be absent — the model will fabricate a value to satisfy the schema.
tools = [{
"name": "report_findings",
"description": "Record local-pass findings for a single file.",
"input_schema": {
"type": "object",
"properties": {
"file": {"type": "string"},
"findings": {"type": "array", "items": {"type": "string"}},
},
"required": ["file", "findings"], # always present
},
}]
# force structured output -> no free-text parsing
resp = client.messages.create(model="claude-sonnet-4-5", max_tokens=1500,
tools=tools, tool_choice={"type": "tool", "name": "report_findings"},
messages=[{"role": "user", "content": file_blob}])Pass 2 — Cross-File Integration
Once every file passes its local review, run a separate integration pass. Now the goal flips: you deliberately load the relevant files together and ask whether their contracts line up.
Typical integration defects:
- A caller passes three arguments; the callee now expects four.
- One module returns
Noneon "not found"; the consumer treats it as an empty list. - A renamed enum value still referenced by a sibling file.
Tracing the Seams
The integration pass mirrors incremental investigation. Start at the boundaries and follow the wiring: Grep for a changed function's name to find every call site, then Read those consumers.
This way the integration pass concentrates on the seams between files — the exact place single-pass review tends to miss.
# Find everyone who calls the changed function, then read them
claude -p "Cross-file pass. process_refund() signature changed in \
refund.py. Grep its call sites, Read each consumer, and report \
ONLY mismatched arguments, return-type assumptions, or broken \
contracts across files." --output-format jsonWhy Order Matters
Run local before integration, not the reverse. If a file is internally broken, integration findings about it are noise — you'd flag a contract mismatch that disappears once the local bug is fixed.
Clean each file in isolation first, then the integration pass can trust that every file is locally sound and focus purely on how they fit together.
Fixed Pipeline, Not Improvised
Because the steps are known and sequential — discover, local pass, integration pass, report — this is a job for a fixed pipeline (prompt chaining), not adaptive, open-ended exploration.
Reserve adaptive decomposition for genuinely open investigations ("why is this flaky?"). Multi-pass review has a defined shape, so encode that shape.
def review_changeset(files):
# Stage 1: local pass, one request per file
local = {f: local_pass(f, read(f)) for f in files}
# Stage 2: integration pass over the seams
integration = cross_file_pass(files, local)
return merge(local, integration)Run It in an Isolated Session
Run each review pass in a fresh, isolated session, separate from whatever session generated the code. Independent review beats same-session self-review: an author retains its own reasoning and won't challenge its own assumptions.
In CI, drive this non-interactively with -p / --print and --output-format json so results are parseable. When re-running, feed in prior results and report only new or still-unfixed issues.
# CI: isolated, non-interactive, machine-readable
claude -p "$LOCAL_PASS_PROMPT" --output-format json > local.json
claude -p "$INTEGRATION_PROMPT" --output-format json > integ.json
# fresh process each pass -> no generation-context biasScaling with Subagents
For large changesets, fan out the local pass across subagents in a hub-and-spoke pattern: the coordinator splits files among parallel workers, then runs the integration pass itself once results return.
Remember the rule: subagents do not inherit the coordinator's history. Each subagent prompt must carry all the context it needs explicitly. Multiple Task calls in one response run in parallel.
# Coordinator: parallel local passes, then one integration pass
# (each Task gets full context — subagents inherit no history)
Task(subagent="reviewer", prompt=local_prompt_for("refund.py"))
Task(subagent="reviewer", prompt=local_prompt_for("ledger.py"))
# ...both run in parallel; coordinator aggregates, then integratesQuick Check
An architect must review a 9-file pull request and wants the highest-quality findings. What is the soundest decomposition?
Recap
Multi-pass decomposition, distilled:
- Two passes, two questions: local = is each file internally correct; integration = do the files work together.
- Local first, then integration — a broken file makes integration findings noise.
- One file per local request to keep attention sharp; emit structured output for clean merging.
- Fixed pipeline (discover → local → integration → report), not adaptive improvisation.
- Isolated/fresh sessions beat same-session self-review; in CI use
-pand--output-format json. - Scale the local pass across parallel subagents — each one needs context passed explicitly.
Single-pass multi-file review is the anti-pattern. Decompose, and your reviews get sharper, not just longer.
常见问题解答
「多轮分解」课时是免费的吗？
是的 — 「多轮分解」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Claude Architect 课程的其余内容，请升级到 CoddyKit PRO。 Claude Architect 课程共包含 4 节课。
「多轮分解」这节课中我会学到什么？
先逐个文件进行局部处理，再进行跨文件整合处理。 你通过在浏览器中直接运行的动手代码来练习 Claude Architect，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Claude Architect 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Claude Architect 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。
「多轮分解」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Claude Architect 课中编写并运行代码吗？
能。每节 Claude Architect 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。