Claude Code 会话交接模板：把上下文留给下一个人或 AI Agent

Claude Code 最容易浪费时间的地方，不是它不会读代码，而是一次会话结束后，工作上下文没有被保存。它可能已经找到关键文件、排除了两个错误假设、改了一半实现，并跑过一部分检查。可是如果最后只留下一句“明天继续”，下一位同事或下一次 AI Agent 会话仍然要重新读文件、重新判断风险。

这篇文章给你一套可以直接复制的会话交接模板。handoff 在这里可以理解为“工作交接记录”，不是长篇日记，而是让下一位操作者能安全继续的最小信息包：目标、当前状态、改动原因、验证证据、剩余风险，以及下一条可以直接发给 Claude Code 的提示。

官方资料建议以当前 Claude Code 文档为准。How Claude Code works 解释了 Agent 循环、项目文件、git 状态、会话和上下文；Memory 解释 CLAUDE.md 和项目指令；CLI reference 说明命令行用法。站内可以结合 CLAUDE.md 最佳实践、验证收据工作流 和 团队交接规则 一起看。

先分清 CLAUDE.md 和交接记录

初学者常见的误区，是把所有内容都塞进 CLAUDE.md。CLAUDE.md 应该保存长期有效的项目规则，例如构建命令、代码风格、架构约束、评审标准、不能随意修改的目录。

交接记录保存的是今天这次任务的临时状态。哪些文件读过，哪个假设已经排除，哪些检查通过，哪些检查没做，下一步应该先做什么，都属于交接。context 可以理解为“工作背景”，verification receipt 可以理解为“验证收据”，harness 可以理解为“给 Agent 的安全工作框架”。

flowchart LR
  A["Goal<br/>要达成什么"] --> B["Current state<br/>停在什么位置"]
  B --> C["Evidence<br/>验证了什么"]
  C --> D["Risk<br/>还有什么不确定"]
  D --> E["Next prompt<br/>下一步先问什么"]

有了这条链路，下一位操作者不用通读完整聊天记录，也能从最小可执行动作开始。

可直接复制的 Markdown 模板

# Claude Code session handoff

## Goal
- target outcome:
- explicitly out of scope:

## Current state
- branch:
- dirty files:
- related URL:
- what is known:

## What changed
- changed files:
- reason for change:
- important files not touched:

## Verification receipt
- commands run:
- result:
- manual checks:
- not checked:

## Risks and constraints
- fragile area:
- do not touch:
- requires approval:

## Next prompt
In the next session, compare git status with this handoff, then continue from the unchecked verification items.

最重要的是 not checked。本地 build 通过，不等于公开 URL 正常、移动端布局正常、CTA 链接正确、分析事件触发、翻译自然。把没验证的内容写出来，下一次会话就不会从猜测开始。

用 JSON 留下可被工具读取的状态

如果团队会把交接发到 GitHub Issue、Slack、Notion 或内部看板，可以同时保留一份 JSON 摘要。

{
  "slug": "claude-code-session-handoff-template",
  "goal": "Improve the published multilingual article group",
  "status": "draft updated, verification pending",
  "files": [
    "site/src/content/blog/claude-code-session-handoff-template.mdx",
    "site/src/content/blog-en/claude-code-session-handoff-template.mdx"
  ],
  "checksRun": ["frontmatter parse", "code fence scan"],
  "checksMissing": ["production URL check"],
  "nextAction": "Run targeted validation and review locale copy"
}

JSON 适合机器读取，但不适合承载全部判断理由。实际使用时，Markdown 写判断和背景，JSON 只放状态、文件、检查项和下一步。

可运行的 Node.js 交接脚本

把下面内容保存为 scripts/write-handoff.mjs。它只使用 Node.js 内置模块，会读取当前 git 状态，并在 handoffs/ 目录下生成当天的 Markdown 文件。

import { execSync } from "node:child_process";
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";

function run(command) {
  try {
    return execSync(command, { encoding: "utf8" }).trim() || "(no output)";
  } catch (error) {
    return `ERROR: ${error.message}`;
  }
}

const date = new Date().toISOString().slice(0, 10);
const branch = run("git branch --show-current");
const status = run("git status --short");
const recentCommit = run("git log -1 --oneline");
const outDir = "handoffs";
const outFile = join(outDir, `${date}-session-handoff.md`);

mkdirSync(outDir, { recursive: true });

const body = `# Claude Code session handoff

## Goal
-

## Current state
- branch: ${branch}
- recent commit: ${recentCommit}
- dirty files:
\`\`\`text
${status}
\`\`\`

## What changed
-

## Verification receipt
- commands:
- result:
- missing:

## Risks and constraints
-

## Next prompt
Read this handoff, compare it with git status, and continue from the missing verification items.
`;

writeFileSync(outFile, body, "utf8");
console.log(`Wrote ${outFile}`);

先检查语法，再运行：

node --check scripts/write-handoff.mjs
node scripts/write-handoff.mjs

三个以上的实用场景

第一个场景是多语言内容发布。一个 slug 同时有日语、英语、中文、韩语、西班牙语、法语、德语、葡萄牙语、印地语、印尼语文件时，难点不是改一篇文章，而是确认哪些 locale 还需要自然度检查、乱码扫描、description 长度检查、内部链接，以及 /products/ 和 /training/ 的 CTA。

## Goal
- raise the 10-locale article group for slug claude-code-session-handoff-template to publish quality

## Current state
- Japanese canonical body updated
- English and Indonesian reviewed for natural tone
- zh, ko, and hi still need mojibake scan

## Verification receipt
- frontmatter parse: pass
- JSON code block parse: pass
- production URL: not checked

## Next prompt
Check the remaining locale files for mojibake, description length, and missing CTA links. Report only unresolved items.

第二个场景是 bug 调查中途停止。比如你已经发现“390px 宽度下商品卡片 CTA 溢出，因为价格卡片保留了固定 min-width”，就必须把这个结论写下来。只写“看过 CSS”没有帮助。

第三个场景是高风险代码评审。认证、计费、数据库迁移、权限变更都不能只写“review 进行中”。交接应该说明已经看过哪些风险、缺哪些测试、合并前需要谁批准。

第四个场景是多个 Agent 或多人并行工作。如果其他人正在改别的 slug 或分支，交接必须写清楚本次允许修改的文件和禁止触碰的文件。这样能避免“顺手整理”覆盖别人的差分。

第五个场景是商业导线或广告设置的维护。内容站常见的失败是文章本身已经修好，但免费资源、商品页、咨询页、AdSense、analytics、OGP、canonical 其中一个没有确认。交接里可以把这些项目分成“已验证”和“未验证”，例如“正文 CTA 已确认，移动端广告位置未看，Search Console 的索引状态未查”。这样下一次会话不会把技术修改当成全部完成。

交接的粒度也很重要。好的交接不是把所有聊天记录复制过去，而是把判断过程压缩成可以行动的事实。比如“因为 BlogPostLayout.astro 控制所有文章页，所以代码块问题优先看这个文件”比“我看了 layout”更有用。下一位操作者需要的是为什么走这条路、哪些路已经排除、剩下哪一步最小。

如果交接里出现多个未完成事项，按风险排序。先写会阻止发布、会影响收入、会暴露安全信息的事项，再写体验优化。这样下一个人不用猜优先级，也能把有限时间用在最可能造成损失的地方，而不是重复探索。

常见失败和坑

失败一：只列文件路径，不写原因。site/src/pages/products.astro 只是位置；“价格卡片的 min-width 导致 390px 溢出”才是可继续工作的线索。

失败二：只写成功的检查。npm run build 通过很有用，但它不能证明公开 URL、移动端布局、点击追踪、表单流程和翻译都正确。好的交接同时写证据和缺口。

失败三：把交接写成聊天记录摘要。很长的记录看起来负责，但下一位操作者需要的是下一步。最后一定要留下可复制的 next prompt。

失败四：泄露敏感信息。不要把 API key、客户数据、内部价格、私有事故链接贴进交接。写 secret 名称或安全记录位置即可。

收益导线也要交接

对 ClaudeCodeLab 这类内容站来说，技术质量和收益导线不能分开。文章写得再好，如果内部链接、免费资料、商品页、咨询页丢了，读者下一步就断了。个人读者可以先看免费资料，需要模板和检查表时看产品页，团队要把 CLAUDE.md、权限、评审、验证收据和交接制度放进真实仓库时，可以看 Claude Code 培训与咨询。

最后养成一个 30 秒习惯：会话结束前写目标、当前状态、证据、未验证项和下一条提示。实际在 Masa 的发布流程里，最大的收益不是模板多漂亮，而是第二天不用再猜“昨天到底查到哪里了”。