編碼智能體開始工作前，交接簡報應寫哪些內容

Most agent runs that go sideways don't fail at the code. They fail at the handoff. The task lived in someone's head and the prompt carried only half of it. The diff that comes back answers a slightly different question than the one we meant to ask. Reviewing it then means working backwards from the output to the intent, and that is the slow direction.

So before we give any non-trivial task to Codex or Claude Code, we write a short handoff brief. Review then becomes a comparison: did the run do what the brief said, and nothing else?

What goes in a brief

• Goal: the outcome in one or two sentences, not the method.
• Scope: what the agent may change, as paths or modules.
• Off limits: files and behaviour it must not touch, even if it thinks it should.
• Checks: the exact commands that prove the change works.
• Done: the observable state that ends the task.
• Report back: what the summary must contain.
• Escalate, don't guess: decisions that belong to a human.

The last item does the most work. When an agent hits an ambiguity, it will usually resolve it somehow. If you name the ambiguities up front, a silent guess becomes a question in the report.

The template

## Goal
<What should be true when this is done.>

## Scope
May change:
- <path or module>

Off limits (do not edit, even to "fix" something):
- <generated code, migrations, lockfiles, CI config>
- <public interfaces other code depends on>

## Context
- <Why this change; constraints the code doesn't show>
- <Link to the issue or prior decision>

## How to check
- Run: <test command>
- Run: <lint / type-check command>
- Expected: all pass, no tests skipped or deleted

## Done means
- <Observable condition>

## Report back
- Files changed, one line on why for each
- Commands run and their results
- Anything noticed but not changed
- Every assumption made

## Escalate instead of guessing
- <Behaviour changes visible to callers or users>
- <New dependencies, secrets or credentials>
- <Checks that cannot pass without touching an off-limits path>

Keep it short. Codex's docs on managing usage advise controlling the size of prompts and reducing the size of AGENTS.md. The same logic holds for readability, because a brief that restates the codebase gets skimmed. Durable project rules belong in the instruction file the tool already reads (AGENTS.md, CLAUDE.md), and the brief covers only this task. Claude Code's guidance to use /clear when starting a new task fits well here: clear the context, then paste the brief.

A vague brief and a better one

The task: a small internal service still calls a deprecated fetchLegacy method on its HTTP client wrapper.

The vague version:

Replace the deprecated fetchLegacy calls with the new client API and make sure everything still works.

That brief leaves four questions open:

• Which files count?
• Must the retry behaviour be kept?
• What does "everything" mean?
• What happens to call sites that pass options the new API lacks?

The agent will answer all four. We just won't know how until we read the diff.

The better version:

Goal: no calls to fetchLegacy remain in src/; behaviour for callers is unchanged.
Scope: src/clients/ and src/handlers/. Off limits: src/generated/, the dependency manifest and lockfile, migrations/.
Check: unit tests and type-checker pass, with no tests skipped or deleted.
Done: a search for fetchLegacy in src/ finds only its definition, which stays for a follow-up.
Report: each call site changed, and how retries are handled now.
Escalate: any call site relying on an option the new API lacks. Leave it unchanged and list it.

It's the same task, but now the reviewer knows what a correct diff looks like before opening it.

When the run comes back

1. Diff first, summary second. The summary is an account of the work; the diff is the work. Check the file list against Scope and Off limits.
2. Rerun the checks yourself, using the commands from the brief, in a clean state. "Tests pass" in a report is a claim, not evidence.
3. Look for silent scope creep: reformatted files, renamed helpers, a nearby cleanup, a loosened assertion, a new dependency. Each may be fine. None should be a surprise.
4. Answer the escalations and write the answers down.
5. Record decisions in the brief, the commit message or the PR description, so the next brief starts from there.

Where context gets lost between tools

The weak point is rarely inside one run. It sits between runs:

• Reasoning from a planning chat never reaches the agent.
• An escalation gets answered in one terminal and then forgotten.
• A follow-up starts in another tool without any of the earlier decisions.

Each tool keeps its own session history. A brief kept in a file and updated with what came back is the one thing that carries across tools. Treat it like code: version it, review it and reuse it.

This post comes from the Octuo team at Tutuo, Inc. More of our notes on running coding agents are on our blog.

Drafted with AI assistance; the tool behaviour mentioned was checked against the Codex and Claude Code documentation before publishing.