How to hand off an AI coding task to another developer

Owner

Accountable for the outcome. Writes the task, answers the decisions only they can make, and stays responsible even while someone else runs it.

Runner

Executes and supervises. Uses their own agent subscription, stays inside the stated scope, performs the human checks, and reports what actually happened.

Reviewer

Accepts or returns the work. A second decision, separate from delivery — the runner reporting that they are finished is not the same as the work being done.

• A transcript is a log, not a brief. The next person has to reconstruct your reasoning from your dead ends.
• Session context is local to the tool. What transfers as text is not what the agent actually had in memory.
• It leaks scope. A transcript contains everything you explored, including the things the runner should now not do.
• It hides the current state. Which of the twelve things you tried is actually in the branch right now?
• A compacted summary is written to keep a model working, not to orient a human.

• Outcome — one sentence, stated as a result rather than an activity
• Acceptance criteria — the checks the reviewer will actually run
• Repository, branch and base commit — and whether anything is still uncommitted
• Relevant files — path and line, not “somewhere in auth”
• Current state — what works, what does not, what is half-finished
• Test state — the command, what passes, what fails and why
• Decisions already made, and the alternatives rejected
• Constraints — an explicit list of what not to do
• Open questions, each with the person who owns the answer
• The single next action — the next command or edit, not a plan
• People — owner, runner and reviewer, by name
• Access — what the runner supplies from their own accounts

# HANDOFF.md

## 1. Outcome
Done means:

## 2. Acceptance criteria
- [ ]
- [ ]

## 3. Repository and branch
- Repo:
- Branch:
- Base commit:
- Uncommitted work? (push it first — the runner cannot see your working tree)

## 4. Where the work is
| File | What's there |
|---|---|

## 5. Current state
- Working:
- Not working:
- Half-finished:

## 6. Test state
- Command:
- Passing / failing (and why):

## 7. Decisions already made
| Decision | Why | Alternative rejected |
|---|---|---|

## 8. Constraints — do not do these
- Do not open a pull request, merge, deploy or take destructive action
  unless stated here

## 9. Open questions
| Question | Who decides |
|---|---|

## 10. Next action

## 11. People
- Owner / Runner / Reviewer

## 12. Access the runner needs
- Runner uses their own agent subscription
- Required env vars (values from:)

1. 01

   Push your branch

   The runner cannot see your working tree.
2. 02

   Fill in HANDOFF.md

   At the repository root, committed on the branch.
3. 03

   Send the branch name

   Plus one line of context. Nothing more is needed.
4. 04

   The runner works

   In their own agent session, inside the constraints you wrote.
5. 05

   The runner reports back

   Including failures. A failed run reported accurately is worth more than a vague success.
6. 06

   A reviewer accepts or returns it

   Someone other than the runner.

What the first credential can reach

It refreshes the claimed task, and where that task belongs to a Story, the permitted Story overview and relevant published linked tasks.

What it cannot do

Browse the board, comment, edit, change status, or deliver. Copying the read prompt never authorizes a status change.

How it is held

Rooted in the exact active claim, stored only as a hash, sent in an authorization header, and expiring after at most seven days. Ending the claim invalidates it.

Use Git and a file when

You hand off roughly one task a week, everyone involved is an engineer, and you can name the reviewer in a message. Adding a system here is overhead, not process.

Use a shared task record when

Several handoffs are in flight at once, the roles are mixed, or “who may mark this done” has to be enforced rather than assumed.

• Handing off a task whose acceptance criteria do not exist yet
• Forgetting to push, so the runner starts from a stale branch
• Pasting a credential into the agent session
• The runner improving adjacent code because no constraint said not to
• Reporting success without running the human checks
• No named reviewer, so finished work sits unaccepted

How do I hand a Claude Code task to another developer?

Push the branch, then write down the outcome, acceptance criteria, current state, decisions already made and the single next action. The other developer reads that and starts their own agent session on their own account. Do not send the conversation transcript: it is a log of everything you tried, not a brief for what to do next.

Can another developer continue my AI task without my account?

Yes, and that is the point of a handoff. The task moves; the provider account, API key and token balance do not. The runner uses the agent subscription they already have.

What is better than a handoff.md file?

Nothing, for a single handoff between two people. A file in the repository is the right tool. Once several teammates and agents share one project you need shared task state instead: who has claimed what, what is in flight right now, and a separate step that records delivery so that reading a task and marking it finished are not the same permission.

Do I need a new cloud agent runtime to hand off coding work?

No. The runner uses the agent they already run locally. A handoff moves the task definition and the accountability, not the execution environment.

Can product, design or QA hand off AI tasks too?

Yes, if the record holds the outcome and the checks rather than assuming everyone is an engineer. The author who prepares the task, the runner who supervises it and the reviewer who accepts it can be three different people in three different roles.

What has to be written down before an AI coding task can be handed off?

Outcome, acceptance criteria, repository and branch, base commit, the specific files involved, what currently works and what does not, test state, decisions already made and the alternatives rejected, explicit scope limits, open questions with owners, the single next action, and the named owner, runner and reviewer.