# Session Handoff

> 会话将尽、上下文窗口即将压缩、或工作必须转到另一个 agent 或运行环境时用它。把会话压进一份平铺文件，让一个全新的 agent 冷启动就能读懂并接着干——状态、半成品、下一条确切命令、待定决策——密钥已脱敏，并发工作已核实保全。Trigger words: handoff, hand off, compact, save state, continue in another session, portable handoff, before restart. 中文触发词：交接、留档、保存状态、换个会话接着干、重启之前、交接文档。

- Skill: `tcuzzo/session-handoff-7` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tcuzzo/session-handoff-7`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tcuzzo/session-handoff-7/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: Tcuzzo (https://skillmd.com/u/tcuzzo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tcuzzo/session-handoff-7

---


# Session Handoff
**Effort:** free — 上下文死掉之前写一份平铺文件；零模型调用，还让下个会话一开局就直接省下成本。消除：新 agent 重新推导状态、把已付过学费的坑再付一遍，以及随死去的上下文窗口一起丢失的决定。

上下文窗口会死；工作不能陪葬。会话结束或压缩之前，写一份平铺文件，让一个全新的 agent 冷启动就能读懂并接着干——在做什么、东西在哪、什么做了一半、下一条确切命令是什么。只停在聊天散文里或记忆里的交接，等于不存在。

## 什么时候写

- 上下文窗口压缩或清空之前。
- 会话结束、工作还没收尾时。
- 刚落地一件大事之后（趁热记下 commit id）。
- 一个真正的决定递到你的人面前的那一刻（记下每个选项各意味着什么）。

## 写到哪

一个下一位 agent**最先**会看的固定地方。下一位 agent 和你共享项目，就用仓库里一个稳定的台账文件，并把更新 commit 掉，让它扛得住机器重启，而不只是上下文清空。下一位 agent 是另一个运行环境或一次全新登录，就往临时目录写一份平铺的可携带文件——它是脚手架，不是要跟踪的产物。

## 先核实并发工作（一个字都别急着写）

先确认**其他**会话的工作已被保全。跑 `git status`、`git log`、`git worktree list`。把脏文件和未合并的分支如实记进文档。绝不为了让交接显得干净而变更另一个会话未提交的工作——那正是数据丢失缺陷。另一个会话还有工作在飞，交接文档却描述一片干净，这是虚假声明。

## 写什么 — 每项一小节

1. **目标。** 一句话说清这份工作。下一位 agent 不该去猜"做完"是什么意思。
2. **状态。** 已落地（commit id）、在建、排队。spec、计划、issue、diff 用路径或 URL 引用——绝不复制内容。
3. **工作住在哪。** 分支、worktree、脏文件。点名下一位 agent 必须最先读的确切文件。
4. **裁决轨迹。** 每一块是谁或什么评的、真正抓到了什么。带具名缺陷的失败裁决比一个绿更值钱——把缺陷逐字写下。
5. **半成品和下一条确切命令。** 什么在半途，以及接着跑的字面命令。
6. **待定决策。** 还在等你的人的事项，以及每个选项意味着什么。一个决定绝不能只活在一个死掉的上下文窗口里。
7. **未兑现的契约。** 还红着的测试、还缺的证明、许了还没还的承诺。
8. **坑。** 每个一行。你已经付过学费的坑比一个绿更值钱——写下来，让下一个会话不用再付一遍。
9. **建议加载的技能。** 下一位 agent 该先加载哪些技能，各一行理由。这是让文档跨运行环境可携带的关键。

## 硬性规则

- **脱敏。** 不放 API key、密码、令牌、个人数据。不放真实主机名、内网 IP、家目录路径——只用占位符；真实值用环境变量名指过去。交接文档是最可能离开这台机器的文件；经它泄露的密钥本身就是 bug。
- **"不存在"类的说法烂得最快。** 写下"X 不存在"或"X 没落地"之前，在当前 commit 上重新核实——你写的时候，并行工作正在落地。
- **每项两个词的状态：PROVEN 或 STILL-BUILDING。** 测试绿了但没有实况证明就是 STILL-BUILDING，而且交接文档要写明缺的是哪种证明。
- **保持两分钟能读完**（约 120 行）。超了就把最旧的块挪进历史小节归档——绝不靠删除。

## 接手（另一半）

从交接文档启动的会话**最先**读它，然后在动手之前，把最上面的两三条声明对照 `git log` 和实况目录树验证一遍。交接是地图，不是真相——信它告诉你**去哪看**；核实它**说了什么**。

## 搭配使用

- [root-cause-first](../root-cause-first/SKILL.md) — 下一个会话接着做的那场调查。
- [repair-loop](../repair-loop/SKILL.md) — 循环中途交接，不丢那条接缝。
- [decision-bar](../decision-bar/SKILL.md) — 待定决策怎样递到你的人面前。

> 脚手架致谢：Matt Pocock, handoff (mattpocock/skills)。此处的组合方式与硬性规则属于 BACKS AIOS。