AIエージェントのセッション引き継ぎを自動化する（閉じる→票→開く の3点セット）

これは何を解決するか

コーディングエージェント（Claude Code / Codex CLI 等）を長く使うと、次の3つが必ず起きる。

1. 1つの会話に無関係なタスクを積む → 毎ターン巨大な履歴を再処理し、品質が落ちてトークン単価が上がる
2. 会話をリセットするコマンド（/clear 等）を「履歴の削除」だと誤解する → 実際は削除ではなく、押すたびに空のセッションが増えていく
3. 引き継ぎが「画面に出した文章」で終わる → 人がコピペしないと次のセッションに渡らず、結局失われる

この指示書は、セッションを閉じる → 引き継ぎ票をファイルに残す → 次のセッションが票から再開するという一方向のループを作り、 そのうち機械にできる部分（票の鮮度維持・開始時の案内）をフックで自動化する手順である。

成果物: 引き継ぎ票1ファイル + スキル2本（開始/終了）+ フック2本（開始時案内 / 終了時自動更新）。

---

設計の原則（ここを外すと必ず壊れる）

• 自動化するのは「票の鮮度維持」までにする。 コミット・プッシュ・長期メモリへの書き込みは自動化しない。 判断を伴う操作を自動で走らせると、未完成の変更を公開したり誤った記録を残す。人が明示的に閉じる時だけ実行する。
• 票の見出し構成を契約にする。 開始側スキルはこの見出しを読む前提で書く。見出し名を変えるとサイレントに壊れる。
• 票は「上書き」でなく「統合」する。 未着手の項目を消してはいけない。
• フックは失敗しても本体をブロックしない。 例外は全て握って終了コード0で抜ける。

---

1. 引き継ぎ票（~/.claude/next-session.md 等の固定パス1ファイル）

固定の見出し構成にする。これが開始側スキルとの契約になる。

<!-- NEXT-SESSION v1 -->
<!-- 前セッション: <sid> / 更新: <YYYY-MM-DD> / cwd: <作業ディレクトリ> -->

## 次の1目的
<1件のみ。決まっていなければ「未定」>

## 対象
<ファイルパス>

## 完了条件
<検証手段まで含めて。「何が確認できたら終わりか」>

## 直前セッションの成果（3行）
- …

## 残TODO（次の1件を先頭に）
1. …

## 触る前に読む memory
- …

## 未決（判断待ち）
- …

ポイント:

• 「完了条件」を検証手段まで書かせる（例:「該当エンドポイントを実際に叩いて200、DBを読み直して値一致」）。 ここが書けないタスクは、実装タスクではなく調査タスクとして切り直す。
• 「触る前に読む memory」は索引ではなく本体を読ませる。 開始側スキルにそう明記する。ここを飛ばすと前回の失敗を繰り返す。
• 「残TODO」は次にやる1件を先頭にする。 一覧の順序自体が優先順位になる。

---

2. 終了スキル（/session-close 相当）

~/.claude/skills/session-close/SKILL.md:

---
name: session-close
description: セッションを綺麗に閉じて次に引き継ぐ。「終わりにする」「一旦区切る」「今日はここまで」「次に引き継いで」などセッション終了・区切りの合図が来たら必ずこのスキルを使う。タスクが1件完了した時点でエージェント側から自発的に提案してよい。
---

# セッションを綺麗に閉じて次へ引き継ぐ

## 1. 成果を3行で要約
- 何を変えたかを3行で。長い引用やコード本体は載せない。

## 2. 未コミット差分の確認
- `git status --short` を実行する。
- 自分が出した差分は commit → push → PR まで自分で行い、放置して閉じない。
- **他セッション/他人由来の差分は勝手にコミットしない。** 報告に明記して残す。

## 3. 長期メモリへ永続化
- 次回も効く恒久的な事実だけを書く。既存ファイルを先に探し、重複を作らず更新を優先する。
- 会話固有の一時情報・コード構造・git 履歴が既に記録していることは書かない。

## 4. 残TODO を列挙
- 「次に最初にやる1件」を先頭にする。ブロッカーは理由も添える。

## 5. 引き継ぎ票をファイルへ書き出す
- **画面に出すだけで終わらせない。** 人にコピペさせるのは手作業。必ずファイルへ書く。
- 既存の票を先に読み、**未着手の残TODO を消さずに引き継ぐ**。
- `## 自動収集: <sid>` ブロックがあれば中身を `## 残TODO` へ統合し、そのブロックを削除する。
  （フックが機械的に書いた下書きであり、整えるのは閉じる側の仕事）
- 見出し構成は上の契約どおりにする。

## 6. リセットを促す
- 「ここで会話をリセットしてよい。継続は票とメモリが担保している」と1行で伝える。

---

3. 開始スキル（/session-start 相当）

~/.claude/skills/session-start/SKILL.md:

---
name: session-start
description: 新しいセッションを前セッションの引き継ぎから開始する。「次の作業を始める」「続きから」「引き継いで始めて」などセッション開始・作業再開の合図が来たら必ずこのスキルを使う。
---

# 前セッションの引き継ぎから作業を開始する

## 1. 引き継ぎを読む
- 引き継ぎ票を読む。`## 触る前に読む memory` に挙がっているファイルは**本体まで実際に読む**。
  ここを飛ばすと前セッションの失敗を繰り返す。

## 2. 目的を1件に確定する
- 票に目的があればそれを採用し、着手前に1行で宣言する。
- 未定・複数あるなら**1件だけ**選ばせる（選択肢を提示して確認する）。選ばれなかった候補は票に残す。

## 3. 完了条件を先に決める
- 「何が確認できたら終わりか」を検証手段まで含めて1行で書く。書けないならまず調査タスクとして切り直す。

## 4. 分解して委譲する
- 監督役がやるのは 設計・分解・指示・レビュー・検証だけ。実装本体は実装用エージェント/CLIへ渡す。
- **渡す時は蓄積（長期メモリの関連分）をキュレートして同梱する。** 別プロセスの実装役は履歴を継承しない。

## 5. 着手する
- ここまでを1〜3行で報告してから作業に入る。
- 1件終わったら終了スキルを提案する（積み残しを増やさない）。

## 注意
- 票を読まずに「続きから」を始めない。文脈は履歴ではなく票とメモリが担保している。
- 目的外の依頼が来たら、着手前に「別セッションに分けましょう」と提案する。

---

4. フックA: 開始時に票を案内する（打ち忘れ保険）

開始スキルを人が打ち忘れても気づけるようにする。票が新しく、その版を未提示の時だけ1回案内する。 以下は PowerShell 版（SessionStart フックに登録）。

# 票が24時間以内に更新され、かつその版が未提示のときだけ1回案内する。
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$ErrorActionPreference = 'SilentlyContinue'
$H = $env:USERPROFILE
$f = Join-Path $H '.claude\next-session.md'
if (-not (Test-Path $f)) { return }

$mt = (Get-Item $f).LastWriteTime
if (((Get-Date) - $mt) -ge [TimeSpan]::FromHours(24)) { return }   # 古い票を毎回蒸し返さない

$guard = Join-Path $H '.claude\.next-session-shown'
if (Test-Path $guard) {
  if ((Get-Content -LiteralPath $guard -Raw -Encoding UTF8).Trim() -eq $mt.ToString('o')) { return }
}

$txt = Get-Content -LiteralPath $f -Raw -Encoding UTF8
$purpose = '未定'
if ($txt -match '(?ms)^##\s*次の1目的\s*\r?\n+(.+?)\r?\n') { $purpose = $Matches[1].Trim() }
$todo = @()
if ($txt -match '(?ms)^##\s*残TODO[^\r\n]*\r?\n(.*?)(\r?\n##\s|\z)') {
  foreach ($l in ($Matches[1] -split "`r?`n")) {
    if ($l -match '^\s*\d+\.\s*(.+)$') {
      $t = $Matches[1].Trim() -replace '\*\*',''
      if ($t.Length -gt 90) { $t = $t.Substring(0,89) + '…' }
      $todo += $t
    }
  }
}
if ($purpose -eq '未定' -and $todo.Count -eq 0) { return }

Set-Content -LiteralPath $guard -Value $mt.ToString('o') -Encoding UTF8
$head = if ($todo.Count) { "次の1件: " + $todo[0] } else { '' }
$ctx = "【前セッションからの引き継ぎ票あり｜この応答の冒頭で必ず提示すること】`n" +
  "票が " + $mt.ToString('MM-dd HH:mm') + " に更新されている。`n目的: $purpose`n$head`n`n" +
  "依頼に答える前に1〜2行でこれを伝え、開始スキルで再開できると添える。票の全文は貼らない。"
@{ hookSpecificOutput = @{ hookEventName = 'SessionStart'; additionalContext = $ctx } } |
  ConvertTo-Json -Depth 6 -Compress | Write-Output

版ガードが要る理由: これが無いと同じ案内が毎セッション出て、人が読まなくなる。票が更新された時だけ再通知するのが正しい。

---

5. フックB: 終了時に残TODOを票へ自動収集する

エージェントが完了報告に書いた「残TODO」を拾って票へ反映する。LLMを呼ばないので追加コストはゼロ。 以下は Stop（応答終了）フックに登録する PowerShell 版の要点。

$ErrorActionPreference = 'Stop'
try { [Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false) } catch {}
$reader = New-Object System.IO.StreamReader -ArgumentList ([Console]::OpenStandardInput()), ([System.Text.UTF8Encoding]::new($false))
$stdin = $reader.ReadToEnd()
if ([string]::IsNullOrWhiteSpace($stdin)) { exit 0 }
try { $data = $stdin | ConvertFrom-Json } catch { exit 0 }
if ($data.stop_hook_active) { exit 0 }          # フック起因の再入を防ぐ
$tp = $data.transcript_path
if (-not (Test-Path $tp)) { exit 0 }

# 直近ターン相当だけを見る（古い残TODOを蒸し返さない）
$assistantText = ''
foreach ($ln in (Get-Content -Path $tp -Encoding UTF8 -Tail 40)) {
  $e = $null; try { $e = $ln | ConvertFrom-Json } catch { continue }
  if ($e.type -ne 'assistant' -or -not $e.message.content) { continue }
  foreach ($b in $e.message.content) { if ($b.type -eq 'text' -and $b.text) { $assistantText += "`n" + $b.text } }
}

# 起点は「見出し/強調としての残TODO」のみ。本文中の言及では発火させない（後述の落とし穴1）
$items = @(); $inBlock = $false
foreach ($l in ($assistantText -split "`r?`n")) {
  if (-not $inBlock) {
    if ($l -match '^\s*#{1,6}\s*.*残\s*TODO' -or
        $l -match '^\s*\*\*\s*残\s*TODO[^*]*\*\*\s*[:：]?\s*$' -or
        $l -match '^\s*残\s*TODO\s*[:：]\s*$') { $inBlock = $true }
    continue
  }
  if ($l -match '^\s*#{1,6}\s' -or $l -match '^\s*\*\*[^*]+\*\*\s*$') { break }
  if ($l -match '^\s*(?:[-*]|\d+\.)\s+(.+)$') {
    $t = $Matches[1].Trim() -replace '\*\*',''
    if ($t.Length -gt 160) { $t = $t.Substring(0,159) + '…' }
    if ($t) { $items += $t }
    continue
  }
  if ([string]::IsNullOrWhiteSpace($l)) { if ($items.Count -gt 0) { break } else { continue } }
  if ($items.Count -gt 0) { break }             # 箇条書き以外の本文が来たら打ち切る
}
if ($items.Count -eq 0) { exit 0 }              # 残TODOが無いターンは何もしない

# セッションID別ブロックにして自分の分だけ差し替える（後述の落とし穴2）
$sid8 = ([string]$data.session_id).Substring(0,8)
$block = "## 自動収集: $sid8`r`n`r`n更新: " + (Get-Date -Format 'yyyy-MM-dd HH:mm') + "`r`n`r`n"
foreach ($t in $items) { $block += "- $t`r`n" }
# 票を読み → 24時間より古い他セッションのブロックを削除 → 自分のブロックを置換 or 追記 → 書き戻す

---

6. 実際に踏んだ落とし穴（ここが本体の価値）

落とし穴1: 本文に語が出ただけで誤抽出する

最初の実装は「残TODO を含む行」を起点にしていた。すると 「残TODOはありません」と書いた応答の直後の箇条書き（無関係な説明）を 票に流し込んだ。実データで、別作業の説明文3行が引き継ぎ票に入った。

→ 起点は見出し・強調・行末コロンの形に限定する。さらに「箇条書き以外の本文が来たら打ち切る」を入れる。

落とし穴2: 並行セッションが票を奪い合う

同じマシンで複数セッションを同時に開いていると、最後に応答を終えたセッションが票を上書きする。 実測で、別セッションの内容だけが票に残った。

→ 収集ブロックをセッションID別にして自分の分だけ差し替える。増殖を防ぐため、24時間より古い他セッションのブロックは削除する。 票の本体（人が整えるセクション）はフックから触らない。

落とし穴3: 「リセット」を「削除」と誤解する

会話リセットのコマンドは履歴を削除しない。押すたびにそのコマンドの記録だけを持つ空セッションが1件増える。 「消しても消えない」と感じる原因はこれ。一覧から消す操作（削除アイコン等）は別に存在する。

→ 空セッション（実発言0・応答0）を定期的に退避するスクリプトを常駐させると一覧が汚れない。 判定は「ユーザーの実発言が0 かつ 応答が0」。コマンド記録（<command-name> 等）は発言に数えない。 サイズ上限を設けて大きいファイルは読まない（誤退避とI/Oの両方を防ぐ）。

落とし穴4: 検証方法を間違えて「直っていない」と誤判定する

落とし穴1の修正を検証する時、「票に古い文字列が残っているか」で判定してしまった。 フックは正しく発火しなかった（＝正解）のに、票に元から残っていた汚れを検出して失敗と読み違えた。

→ 「何も書かないこと」を検証したいなら、対象ファイルのハッシュが変わらないことを見る。

落とし穴5: フックの環境依存で沈黙する

• 日本語を含む PowerShell スクリプトは BOM 付き UTF-8 で保存する（BOM 無しだと環境によって文字化けする）
• 標準入力は UTF-8 として明示的に読む（既定エンコーディングに任せると日本語が壊れる）
• コンテキストを注入するフックを非同期にしない（非同期だと出力が捨てられ、黙って効かなくなる）
• スクリプトの検証は正規表現ではなく実パーサに通す（静的解析ツールは偽陽性が多い）

落とし穴6: 常駐プロセスはコード更新で自動反映されない

票の掃除などを常駐スクリプトでやっている場合、ファイルを更新してもプロセスは起動時のコードを保持している。 必ず「旧プロセスを止める → 死活ファイルを消す → 再起動」まで実施する。消さないと「まだ生きている」と誤判定して再起動をスキップする実装が多い。

---

7. 導入後の使い分け（人に伝えること）

やりたいこと	操作
会話の文脈を切りたい	リセットコマンド（票とメモリが継続を担保するので履歴は惜しまなくてよい）
一覧から消したい	削除操作（リセットでは消えない）
次の作業を始めたい	開始スキルを1回打つ
区切りたい	終了スキルを1回打つ（コミット・メモリ・票の整形まで走る）

---

8. 完了条件（この指示書の成果を検証する手順）

1. 終了スキルを実行 → 票のファイルが実際に更新される（画面出力だけで終わらない）
2. 新しいセッションで開始スキルを実行 → 票を読み、目的が1件に確定し、「触る前に読む memory」が実際に読まれる
3. フックAの単体実行 → 1回目は JSON を出力、2回目は無音（版ガード）
4. フックBを模擬入力で単体実行:
   • 見出し形式の残TODO → 票に反映される
   • 本文中の言及だけ → ファイルのハッシュが変わらない
   • 別セッションIDで実行 → 2つのブロックが共存し、互いを消さない
   • 既存の人手セクションが1バイトも変わらない（差分を取って確認する）
5. 設定ファイルを編集した場合はバックアップを取り、構文が壊れていないことをパーサで確認する