Claude Codeセッション引き継ぎテンプレート: 次の人とAIエージェントに文脈を残す方法

Claude Codeで数時間調査したあと、最後に「続きは明日」とだけ残すと、翌日の自分もチームメンバーもまた同じファイルを読み直すことになります。AIエージェントが優秀でも、セッションが切れた瞬間に、作業の意図、触ってよい範囲、検証できたこと、まだ怪しい場所は薄れます。

この問題を防ぐのがセッション引き継ぎメモです。handoffは直訳すると引き渡しですが、ここでは「次の人や次のAIセッションが迷わず再開するための短い作業メモ」と考えるとわかりやすいです。長い日報ではありません。目的、現在地、変更理由、検証、リスク、次のプロンプトを、再利用できる形で残すものです。

公式情報を確認するなら、Claude Codeがプロジェクト、ターミナル、git状態、CLAUDE.md、メモリをどう扱うかはHow Claude Code works、CLAUDE.mdの使い分けはMemory、CLIの再開や使い方はCLI referenceを基準にします。社内ルール化する場合は、ClaudeCodeLab内のCLAUDE.mdベストプラクティスと検証レシートワークフローも合わせて読むとつながります。

引き継ぎで守るべき考え方

初心者が最初に混同しやすいのは、CLAUDE.mdと引き継ぎメモの役割です。CLAUDE.mdは毎回守るプロジェクト規約です。ビルドコマンド、コード規約、触ってはいけない領域、レビュー観点のように、数週間後も有効な情報を置きます。

一方、引き継ぎメモは今日の作業状態です。どのファイルを読んだか、何を変えたか、どの仮説が外れたか、どの検証が未完か、次の一手は何かを残します。contextは「文脈」、verification receiptは「検証の領収書」、harnessは「エージェントの足場」と言い換えると、初心者にも説明しやすくなります。

flowchart LR
  A["Goal<br/>何を達成したいか"] --> B["Current state<br/>どこまで進んだか"]
  B --> C["Evidence<br/>何を確認したか"]
  C --> D["Risk<br/>何が未確認か"]
  D --> E["Next prompt<br/>次に何を頼むか"]

この流れがあると、次の人は会話履歴を全部読まなくても再開できます。特に複数人が同じリポジトリを触る、別ブランチで作業する、記事を10言語に展開する、CIの失敗をまたいで調査する、といった場面で効果が大きいです。

そのまま使えるMarkdownテンプレート

まずは短い型から始めます。完璧な文章ではなく、次の作業者が判断できる粒度を優先してください。

# Claude Code session handoff

## Goal
- 目標:
- 今回やらないこと:

## Current state
- branch:
- dirty files:
- 関連URL:
- いま分かっていること:

## What changed
- 変更したファイル:
- 変更理由:
- 触っていないが重要なファイル:

## Verification receipt
- 実行したコマンド:
- 結果:
- 手動確認:
- 未確認:

## Risks and constraints
- 壊れやすい場所:
- 触らない場所:
- 承認が必要な操作:

## Next prompt
次のセッションでは、まずgit statusとこのhandoffを照合し、未確認項目から再開してください。

このテンプレートのポイントは、未確認を隠さないことです。「build成功」だけでは公開URL、スマホ表示、CTA、分析イベントが正しいかは分かりません。検証できていないことを明示すると、次のセッションは最小の確認から入れます。

JSONで構造化して残す例

チームで集計したい場合は、Markdownに加えてJSONも便利です。GitHub Issue、Notion、Slack bot、社内ダッシュボードへ渡しやすくなります。

{
  "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状態を入れたMarkdownをhandoffs/に作ります。

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}`);

確認コマンドは次の2つです。node --checkは構文だけを見ます。2行目は実際にファイルを作ります。

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

実務で効く4つの引き継ぎユースケース

1つ目は、多言語記事の公開作業です。日本語を直したあと、英語、中国語、韓国語、スペイン語などへ展開すると、どのlocaleを直したか分からなくなりやすいです。引き継ぎには、対象slug、触ったlocale、残っている検証、内部リンク、/products/や/training/のCTA確認を入れます。

## Goal
- slug claude-code-session-handoff-template の10言語記事を公開品質へ上げる

## Current state
- 日本語本文は更新済み
- 英語とIDは自然さを確認済み
- zh, ko, hiは文字化け再発チェックが必要

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

## Next prompt
残りlocaleの文字化けとdescription長を確認し、未確認だけ報告してください。

2つ目は、バグ調査の途中停止です。例えば「390px幅で商品カードのCTAが横にはみ出す」と分かったのに、根本原因を書かないまま終えると、次の人はCSS全体を読み直します。引き継ぎには再現条件、怪しいCSS、外れた仮説、次の最小修正を書きます。

3つ目は、コードレビューの交代です。認証、課金、DB移行のような危険な差分では、単に「レビュー中」と残すだけでは不十分です。どのリスクを見たか、どのテストが足りないか、承認前に誰が確認すべきかを書きます。レビュー観点はチーム引き継ぎルールにもつなげると運用しやすいです。

4つ目は、複数AIエージェントの並行作業です。別slugや別ブランチを他の作業者が触っている場合、引き継ぎには「触ってよいファイル」と「触らないファイル」を必ず入れます。これを省くと、品質改善のつもりで別担当の差分を上書きする事故が起きます。

よくある失敗と落とし穴

失敗例1は、ファイル名だけを並べることです。site/src/pages/products.astroと書いても、なぜ重要かが分からなければ次の人は読み直しです。「価格カードのmin-widthが390px表示でoverflowを起こすため」と理由まで書きます。

失敗例2は、成功した検証だけを書くことです。npm run buildが通っても、公開URL、モバイル表示、クリック計測、フォーム送信は別物です。確認していない項目は「未確認」と書く方が、曖昧な合格より安全です。

失敗例3は、長い日記にすることです。会話ログの要約を20行並べても、次の一手がなければ価値は低いです。引き継ぎの最後は必ず「次のプロンプト」で終えます。

失敗例4は、秘密情報を貼ることです。APIキー、顧客情報、社内URL、未公開の価格条件をそのまま残すと、便利なメモが事故原因になります。必要なら「環境変数STRIPE_SECRET_KEYが必要」のように名前だけを書くか、社内の安全な場所へリンクします。

CLAUDE.mdへ移すもの、移さないもの

何度も同じ注意を書いているなら、それは引き継ぎではなくプロジェクト規約です。例えば「記事のdescriptionは120文字以内」「公開記事ではupdatedDateを更新する」「コード例は実行確認する」はCLAUDE.md向きです。

逆に「今日このslugの韓国語だけ未確認」「このPRではDB migrationをまだ見ていない」「2026年6月3日の公開URLは未確認」は引き継ぎメモ向きです。この分離ができると、CLAUDE.mdは短く保てます。短い規約はClaude Codeにも人間にも読まれやすく、長い一時メモで汚れません。

引き継ぎをレビューするチェックリスト

引き継ぎメモは書いて終わりではありません。次の人が安全に再開できるかを、公開前や交代前に30秒だけレビューします。まず、目標が成果物ベースになっているかを見ます。「記事を少し改善」ではなく「対象slugの10言語で文字化けを消し、descriptionを120文字以内にし、CTAを残す」のように、完了条件が見える表現にします。

次に、検証が作業内容と対応しているかを見ます。文章だけ直したなら、frontmatter、コードフェンス、内部リンク、description長、文字化けを確認します。UIを直したなら、画面幅、スクリーンショット、クリック、フォーム送信など、実際のユーザー行動に近い確認が必要です。Claude Codeに任せる場合も「確認したこと」と「確認していないこと」を分けるだけで、レビュー担当者の負担はかなり減ります。

最後に、次のプロンプトが独立して使えるかを見ます。会話履歴を読まないと意味が分からないプロンプトは、handoffとして弱いです。「この続き」ではなく「git statusを確認し、このhandoffの未確認項目だけを検証してください」のように、最初の行動、対象ファイル、報告形式まで書きます。ここまで残っていれば、翌日の自分、別担当者、別のAIエージェントのどれが担当しても、再開コストは下がります。

収益導線まで含めて引き継ぐ

ClaudeCodeLabのようなメディアでは、記事の品質と収益導線は分けて考えられません。技術本文が良くても、内部リンク、無料資料、商品、研修導線が欠けると読者の次の行動が途切れます。個人で型を整えるなら無料チートシートから始め、テンプレートや実務チェックリストをまとめて使いたい場合は商品一覧を確認してください。チームでCLAUDE.md、権限、レビュー、検証レシート、引き継ぎ運用まで設計するならClaude Code研修・導入相談が現実的です。

最後に、セッション終了前の30秒だけで構いません。目的、現在地、検証、未確認、次のプロンプトを書く習慣を作ると、Claude Codeは一回限りの相談相手ではなく、チームの作業プロセスに組み込める道具になります。実際に試した結果、Masaの公開作業では「どこまで見たか」を探す時間が減り、翌日の自分や別担当者が最初に打つプロンプトも短くなりました。