Your Handoff Doc Isn't Working. Make the Next Session Behave, Not Just Know.

This article first appeared on Medium: https://medium.com/@r3dtuxedo/your-handoff-doc-isnt-working-make-the-next-session-behave-not-just-know-e0eedc9abd86

A handoff carries facts, not habits. Your working style only survives a fresh session if the agent runs it or gets checked against it: skills, checklists, hooks and worked examples.

TL;DR

• A handoff doc tells the next session what happened. It can't make that session work the way you two worked.
• Behaviour survives a reset when it lives in something the agent invokes or something that checks it: a skill or command, a checklist with visible output, a hook or test, a worked example.
• Keep the handoff for facts. Add a short "Behaviour" section that names the skills, checks and examples to load, plus one probe prompt that shows whether it worked.

Earlier this week I argued that you should treat agent sessions as disposable and hand off to a fresh one instead of compacting a long one. The best objection to that advice appeared in r/ClaudeCode the same morning the article went live.

The author had kept one Claude Code session running since 30 September, and it had been compacted 62 times. They went back about ten compactions, listed 12 decisions made in that stretch, and checked the current summary. It held 0 of the 12. Their memory files held about 8. The other 4 were gone, including a one-line product positioning and a bug they had tracked down. The most recent stretch was fine: 20 of 21 items survived. As they put it, "It's the summary of a summary of a summary that quietly drops the older stuff."

That part is a compaction problem, and the replies covered it well: write decisions to a file, start fresh sessions more often. The interesting part is the edit the author added afterwards. They had tried fresh sessions. At about 80% context they'd have Claude write a handoff doc, and that doc wasn't only facts. It described the way of working in detail: how to check their reasoning, how to answer, what to push back on, along with the rules and skills.

"The new session knew the facts but didn't work that way."

So they were stuck between two bad options. A fresh session loses the way of working. A long session keeps it but slowly forgets decisions. Their question: "Has anyone gotten a new session to actually work the way a written handoff describes?"

Mostly, yes. But not by writing a better handoff.

Why prose handoffs fail

A handoff document is read once, at the start, as information. It sits in the context next to the system prompt, your instruction files and the task you just typed. A paragraph that says "challenge my claims before agreeing" is a request, and requests compete. The agent will remember it. Whether it acts on it in turn forty, while doing something else, is a different question.

Anthropic's own best-practices page draws this line for Claude Code. It calls CLAUDE.md instructions advisory, and an AGENTS.md is no different. Hooks, by contrast, "are deterministic and guarantee the action happens." The same page says to "test changes by observing whether Claude's behavior actually shifts," which is exactly the check the Reddit author ran and failed.

There's a second reason, and this one is my reading rather than something the docs say. In a long session, the working style wasn't learned from a description. It was learned from dozens of exchanges: you made a claim, the agent pushed back, you corrected the push-back, and so on. A summary of that ("be critical, but not about X") throws away the examples, and the examples were doing the teaching.

The long-session option doesn't escape this either. Claude Code's context-window docs list what survives compaction. The project-root CLAUDE.md is re-read from disk, and skill bodies are re-injected, though large ones are truncated. Instructions given only in conversation are not. Whatever kept the long session "working that way" was partly living in files already. The rest was luck.

Facts versus behaviour

It helps to separate the two things a handoff tries to carry.

A handoff is good at the left column. The right column needs a different carrier.

	Facts	Behaviour
Example	"Tenant isolation uses Postgres RLS"	"Challenge my product claims before agreeing"
Next session must	know it	do it, unprompted, every time
Lives best in	handoff, spec, ADR, decision log	skill, checklist, hook, worked example
How you check it	ask "what did we decide about X?"	give it a claim and watch what it does

Facts are easy. "What did we decide about X?" has one right answer, and a file can hold it. For durable decisions I keep ADRs in the repo. For the small ones, a one-line-per-decision log is enough, which is what one commenter in the thread suggested: date, decision, why, appended whenever something gets decided. That alone would likely have saved the 4 lost decisions.

Behaviour is different. You can't check it by asking. You have to watch it.

Four ways to encode behaviour

Here's how I'd turn "the way we work" into things a fresh session can't skip.

The further down the stack, the less the next session has to remember on its own.

1. Skills or commands: make it a procedure

If you have a way of doing something, write it as a procedure the agent invokes, not a preference it should remember. In Claude Code that's a skill at .claude/skills/<name>/SKILL.md. Custom commands have been merged into skills, so the same file also gives you /<name>. Codex reads skills from .agents/skills/ in the repo. Both follow the Agent Skills open standard, so a skill is just a folder with a SKILL.md that has a name and a description.

Both tools use progressive disclosure: only the name and description sit in context until the skill is used, then the full instructions load. That suits behaviour well. The procedure doesn't cost context until it's needed, and when it's needed it arrives as a fresh, complete set of steps rather than a fading paragraph from the start of the session.

A reply in a different r/ClaudeCode thread about whether skills are worth it put the rule simply: "if you have a workflow you dont want the AI to rediscover every time, document it as a skill."

---
name: pressure-test
description: Challenge a product or strategy claim before agreeing.
  Use when the user states a claim about users, market, pricing or
  positioning, or asks "does this make sense?"
---
1. Restate the claim in one sentence.
2. List the assumptions it depends on. Mark each: evidence / guess.
3. Give the strongest counterargument, citing docs/positioning.md
   or an ADR if one applies.
4. Say what evidence would change your mind.
5. Only then give your view. Keep the whole answer under 200 words.
See examples/pushback.md for the tone and depth we want.

One Claude Code detail: after compaction, large skills are truncated and the docs say truncation keeps the start of the file. Put the steps first and the background last.

2. Checklists: make it visible

A checklist turns a habit into output you can see. "Check my reasoning" is invisible when it happens and invisible when it doesn't. "Every answer to a strategy claim starts with Assumptions and Counterpoint headings" is something you notice missing in two seconds.

Keep them short and tie each one to a moment: before planning, before claiming done, before answering a claim. The skill above is really a checklist with an output format. The format is the point.

3. Hooks or tests: make it run anyway

Some behaviour shouldn't depend on the agent remembering at all. That's what hooks are for.

In Claude Code, a Stop hook runs when the agent finishes a turn, and exiting with code 2 "prevents Claude from stopping" and feeds your message back as the reason. Codex has the same event: a Stop hook can return "decision": "block" with a reason, which Codex turns into a new continuation prompt. Codex makes you review and trust each non-managed hook (via /hooks) before it runs.

For deterministic checks, use a script: tests pass, the decision log was touched if the diff adds a dependency, the progress file was updated. For judgment calls, Claude Code also supports prompt-based hooks, where a model evaluates the hook input and returns ok: false with a reason to keep the agent working:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "prompt",
        "prompt": "If the last reply agreed with a product or strategy claim, check it has 'Assumptions' and 'Counterpoint' sections. If not, return {\"ok\": false, \"reason\": \"Run /pressure-test before agreeing.\"}. Otherwise {\"ok\": true}. $ARGUMENTS"
      }]
    }]
  }
}

The docs build in loop protection: a stop_hook_active flag in the input and a cap of 8 consecutive continuations. Keep the condition narrow, or you'll be blocked on every turn.

The other hook worth knowing is SessionStart with the compact matcher. According to the context-window docs, Claude Code runs it after compaction and adds its output to the compacted context. If you insist on long sessions, that's how you get your decision log back after every compaction instead of hoping the summary kept it.

4. Worked examples: show, don't describe

This is the one people skip, and it's the one that fixes "doesn't work that way." Take two or three real exchanges from the long session where the agent did exactly what you wanted. A claim, the push-back, how it ended. Trim them and save them as examples/pushback.md. Point to them from the skill, as in the snippet above.

A description says "be critical but constructive." An example shows how critical, about what, in how many words. If the long session learned your style from examples, the fresh one needs examples too.

A before and after

Here's the Reddit author's situation, rebuilt. The before is what most handoffs look like.

Before: a section at the bottom of HANDOFF.md.

## Working style
Be critical. Push back on my product claims and check my
reasoning against our positioning. Don't just agree. Keep
answers short. Use the skills we built.

The fresh session reads this, agrees with it, and then agrees with your next claim.

After: the handoff names things instead of describing them, and the repo carries them.

Same intent. The difference is what the next session can't skip.

# AGENTS.md (excerpt)
## Working agreements
- Product or strategy claim from the user -> run the pressure-test
  skill before answering. Never agree first.
- Decisions: append one line to docs/decisions.log (date, decision,
  why). Durable ones become an ADR in docs/decisions/.

The skill, the examples file and the Stop hook from above live in the repo. And the handoff's job shrinks back to facts plus a short list of what to load.

One gotcha if you're on Claude Code and also have a CLAUDE.md, like the Reddit author. Since v2.1.277 Claude Code reads AGENTS.md natively, but only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above. If you have one, either put @AGENTS.md at the top of it, or set Project instructions in /config to read both. Otherwise your working agreements never load.

How to tell if it worked

Don't judge a handoff by reading it. Judge it by a probe. Start a fresh session from the handoff and, before any real work, give it one prompt that exercises the behaviour:

I think we should drop the free tier next month. Agree?

If it agrees, the behaviour didn't transfer, and no amount of extra prose in the handoff will fix that. Move the behaviour one layer down the stack: from prose to a skill, from a skill to a checklist with a visible format, from a checklist to a hook. Then probe again. It takes two minutes and tells you more than rereading the doc.

The template

This is the handoff template from Compact, Clear or Hand Off? with one section added. The facts sections are unchanged. The new section names behaviour instead of describing it.

# HANDOFF: <task>
Updated: <date>  Branch: <branch>  Last commit: <sha>

## Goal / State / Next step
(as before: what done means, where I stopped, the single next action)

## Decisions
- New since last handoff: see docs/decisions.log lines <n>-<m>
- Durable ones: ADR <numbers>

## Ruled out
- What was tried, why it failed, the evidence

## Behaviour (load, don't just read)
- Skills to use: pressure-test, decision-log
- Checklists in force: docs/checklists/before-done.md
- Hooks active: Stop -> pressure-test format; Stop -> tests
- Examples: examples/pushback.md
- Probe: "I think we should drop the free tier. Agree?"
  Expected: Assumptions + Counterpoint before any opinion.

## How to verify the work
Commands to run, and what passing looks like.

If you use the handoff skill from my skills repository, it already ends with a "suggested skills" section naming which skills the next agent should call. That's the same idea in its smallest form: the handoff points at behaviour instead of paraphrasing it.

The habit

The Reddit author's two bad options come from storing working style in the one place that doesn't survive: the conversation. A long session keeps it until the summaries wear it down. A fresh session never had it.

Write the handoff for facts. Write the repo for habits. When a habit matters, ask where it will live once the session is gone. If the answer is "in a paragraph," it won't survive the next reset.

Sources

• r/ClaudeCode: 60+ compactions into one Claude Code session, the summary had kept 0 of 12 older decisions. How do you keep yours? (21 Oct 2026)
• r/ClaudeCode: Does Plugins/Skills and other external stuff actually help? (20 Oct 2026)
• Claude Code docs: Best practices, Skills, Hooks reference, Hooks guide, Context window, Memory and AGENTS.md (read 21 Oct 2026)
• OpenAI Codex docs: Skills, Hooks (read 21 Oct 2026)
• Agent Skills open standard
• Previous articles: Compact, Clear or Hand Off?, Put Your Decisions in the Repo

---

If this was useful, subscribe to Agents in Practice for one practical note on AI coding agents a week. Helping your team adopt Claude Code or Codex safely and without the surprise bill? I consult on exactly that: https://andre-burgstahler-9n5.pages.dev/.

This article was written with AI assistance and reviewed by the author.