# AIエージェントのセッション引き継ぎを自動化する（閉じる→票→開く の3点セット） ## これは何を解決するか コーディングエージェント（Claude Code / Codex CLI 等）を長く使うと、次の3つが必ず起きる。 1. **1つの会話に無関係なタスクを積む** → 毎ターン巨大な履歴を再処理し、品質が落ちてトークン単価が上がる 2. **会話をリセットするコマンド（`/clear` 等）を「履歴の削除」だと誤解する** → 実際は削除ではなく、押すたびに空のセッションが増えていく 3. **引き継ぎが「画面に出した文章」で終わる** → 人がコピペしないと次のセッションに渡らず、結局失われる この指示書は、**セッションを閉じる → 引き継ぎ票をファイルに残す → 次のセッションが票から再開する**という一方向のループを作り、 そのうち機械にできる部分（票の鮮度維持・開始時の案内）をフックで自動化する手順である。 **成果物**: 引き継ぎ票1ファイル + スキル2本（開始/終了）+ フック2本（開始時案内 / 終了時自動更新）。 --- ## 設計の原則（ここを外すと必ず壊れる） - **自動化するのは「票の鮮度維持」までにする。** コミット・プッシュ・長期メモリへの書き込みは自動化しない。 判断を伴う操作を自動で走らせると、未完成の変更を公開したり誤った記録を残す。人が明示的に閉じる時だけ実行する。 - **票の見出し構成を契約にする。** 開始側スキルはこの見出しを読む前提で書く。見出し名を変えるとサイレントに壊れる。 - **票は「上書き」でなく「統合」する。** 未着手の項目を消してはいけない。 - **フックは失敗しても本体をブロックしない。** 例外は全て握って終了コード0で抜ける。 --- ## 1. 引き継ぎ票（`~/.claude/next-session.md` 等の固定パス1ファイル） 固定の見出し構成にする。これが開始側スキルとの契約になる。 ```markdown ## 次の1目的 <1件のみ。決まっていなければ「未定」> ## 対象 <ファイルパス> ## 完了条件 <検証手段まで含めて。「何が確認できたら終わりか」> ## 直前セッションの成果（3行） - … ## 残TODO（次の1件を先頭に） 1. … ## 触る前に読む memory - … ## 未決（判断待ち） - … ``` ポイント: - **「完了条件」を検証手段まで書かせる**（例:「該当エンドポイントを実際に叩いて200、DBを読み直して値一致」）。 ここが書けないタスクは、実装タスクではなく調査タスクとして切り直す。 - **「触る前に読む memory」は索引ではなく本体を読ませる。** 開始側スキルにそう明記する。ここを飛ばすと前回の失敗を繰り返す。 - **「残TODO」は次にやる1件を先頭にする。** 一覧の順序自体が優先順位になる。 --- ## 2. 終了スキル（`/session-close` 相当） `~/.claude/skills/session-close/SKILL.md`: ```markdown --- name: session-close description: セッションを綺麗に閉じて次に引き継ぐ。「終わりにする」「一旦区切る」「今日はここまで」「次に引き継いで」などセッション終了・区切りの合図が来たら必ずこのスキルを使う。タスクが1件完了した時点でエージェント側から自発的に提案してよい。 --- # セッションを綺麗に閉じて次へ引き継ぐ ## 1. 成果を3行で要約 - 何を変えたかを3行で。長い引用やコード本体は載せない。 ## 2. 未コミット差分の確認 - `git status --short` を実行する。 - 自分が出した差分は commit → push → PR まで自分で行い、放置して閉じない。 - **他セッション/他人由来の差分は勝手にコミットしない。** 報告に明記して残す。 ## 3. 長期メモリへ永続化 - 次回も効く恒久的な事実だけを書く。既存ファイルを先に探し、重複を作らず更新を優先する。 - 会話固有の一時情報・コード構造・git 履歴が既に記録していることは書かない。 ## 4. 残TODO を列挙 - 「次に最初にやる1件」を先頭にする。ブロッカーは理由も添える。 ## 5. 引き継ぎ票をファイルへ書き出す - **画面に出すだけで終わらせない。** 人にコピペさせるのは手作業。必ずファイルへ書く。 - 既存の票を先に読み、**未着手の残TODO を消さずに引き継ぐ**。 - `## 自動収集: ` ブロックがあれば中身を `## 残TODO` へ統合し、そのブロックを削除する。 （フックが機械的に書いた下書きであり、整えるのは閉じる側の仕事） - 見出し構成は上の契約どおりにする。 ## 6. リセットを促す - 「ここで会話をリセットしてよい。継続は票とメモリが担保している」と1行で伝える。 ``` --- ## 3. 開始スキル（`/session-start` 相当） `~/.claude/skills/session-start/SKILL.md`: ```markdown --- name: session-start description: 新しいセッションを前セッションの引き継ぎから開始する。「次の作業を始める」「続きから」「引き継いで始めて」などセッション開始・作業再開の合図が来たら必ずこのスキルを使う。 --- # 前セッションの引き継ぎから作業を開始する ## 1. 引き継ぎを読む - 引き継ぎ票を読む。`## 触る前に読む memory` に挙がっているファイルは**本体まで実際に読む**。 ここを飛ばすと前セッションの失敗を繰り返す。 ## 2. 目的を1件に確定する - 票に目的があればそれを採用し、着手前に1行で宣言する。 - 未定・複数あるなら**1件だけ**選ばせる（選択肢を提示して確認する）。選ばれなかった候補は票に残す。 ## 3. 完了条件を先に決める - 「何が確認できたら終わりか」を検証手段まで含めて1行で書く。書けないならまず調査タスクとして切り直す。 ## 4. 分解して委譲する - 監督役がやるのは 設計・分解・指示・レビュー・検証だけ。実装本体は実装用エージェント/CLIへ渡す。 - **渡す時は蓄積（長期メモリの関連分）をキュレートして同梱する。** 別プロセスの実装役は履歴を継承しない。 ## 5. 着手する - ここまでを1〜3行で報告してから作業に入る。 - 1件終わったら終了スキルを提案する（積み残しを増やさない）。 ## 注意 - 票を読まずに「続きから」を始めない。文脈は履歴ではなく票とメモリが担保している。 - 目的外の依頼が来たら、着手前に「別セッションに分けましょう」と提案する。 ``` --- ## 4. フックA: 開始時に票を案内する（打ち忘れ保険） 開始スキルを人が打ち忘れても気づけるようにする。**票が新しく、その版を未提示の時だけ**1回案内する。 以下は PowerShell 版（`SessionStart` フックに登録）。 ```powershell # 票が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 版の要点。 ```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」。コマンド記録（`` 等）は発言に数えない。 **サイズ上限を設けて大きいファイルは読まない**（誤退避と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. 設定ファイルを編集した場合はバックアップを取り、構文が壊れていないことをパーサで確認する ---