編碼會話交接應記錄停步原因和待核查事項

I don't want to have to explain why we stopped at a particular point every time I start a new coding session.

Take a database migration. The code supports an old column and a new column, and the next agent sees an opportunity to clean up the old path.

But the previous session stopped there for a reason. An older worker still writes to the old column, and the updated worker hasn't been deployed yet. Removing the compatibility code would break that worker.

That's something I want the next session to find before it starts making changes. If the explanation only exists in the previous conversation, I still have to remember to pass it along.

What I'd want the previous session to leave behind

“Migration mostly complete, cleanup remaining” would be a bad handoff here. It makes removing the old code sound like the next thing to do.

For this example, I'd want something closer to:

Goal:
Move readers and writers to the replacement customer ID column.

Current state:
The application supports both columns.
The older worker still writes to the legacy column.

Why we stopped:
We need to deploy the updated worker before removing compatibility.
Removing it now would break writes from the older worker.

Checked:
The targeted compatibility tests passed locally.
Record the commit, command, and result with this entry.

Still needs checking:
Mixed-version behavior in staging.
Whether any other deployed writer uses the old column.

Next:
Check which versions of the writers are deployed.
Use that to decide whether we can continue the migration.

Now the next agent has a reason to keep the compatibility code and something specific to check before removing it. It also knows that passing local tests didn't establish what was running in staging.

Anthropic's write-up on long-running agent harnesses describes using progress files alongside Git history to help later sessions understand the work.

The part I want to get right is what we put in that record. I don't need every search or every command the agent ran. I want the things that would affect what someone does next:

• What changed from the original plan, and why.
• Which assumptions turned out to be wrong.
• What we tried that failed, and what happened.
• What we're waiting on.
• What still needs to be checked.

The failed attempts are useful too. If we tried an approach and found a problem with it, I'd like the next agent to know about that before it spends another session trying the same thing.

This is why I want a work log alongside the design doc. The plan can change while we're building, and I want to keep the explanation for those changes.

The next agent still needs to check the current state

The worker might have been deployed since that note was written. Someone else might have changed the compatibility code.

I'd want the next agent to read the handoff, compare the recorded commit with the current code, and check the deployment state before deciding what to do.

If the worker has now been deployed, add an update with the evidence for that. Keep the earlier entry so someone can still understand why we stopped and what allowed us to continue.

A short current summary would help too. The agent should be able to find where things stand without reading every entry from the start of the project.

A way to see whether your handoff is useful

Take a change that needed more than one session. Give a fresh agent the original task, the repository, and whatever handoff you normally leave.

Before it edits anything, ask it to explain what it would do next, what it would keep in place, and what it needs to check first.

For the migration example, I'd expect it to identify the worker deployment as something that needs checking. If it jumps straight to removing the old column, the handoff hasn't done what we needed.

I'm curious what people are keeping between sessions. Is it enough for the next agent to pick up the work, or do you still have to explain why the previous session made those decisions?