session-close

/session-close -- セッションからメモリへの調整

現在のセッションで得られた永続的な成果を、永続化されたプロジェクトメモリファイルに反映します。これは状態の調整であり、セッションの記録ではありません。出力は、1週間にわたる作業の後に人間がプロジェクトメモリを更新したものと見分けがつかない内容にします。

基本原則

コードは成果を記録し、メモリは理由を記録します。 Git には変更内容がすでに記録されています。プロジェクトメモリファイルには、差分からは読み取れない、決定の理由、プロジェクトの現在の状態、そして次に取り組むことを記録します。

このスキルが防ぐアンチパターン

project_session_apr8_9.md のような、1回のセッションで複数のプロジェクトについて行った作業をすべて、構造化せずに書き出したファイルです。これでは「新しいチームメンバー」のテストに合格しません。翌日に加わった開発者は、重要な情報とノイズを見分けられません。状態の調整では、「今日何があったか」ではなく、「このプロジェクトは何か」に答えるファイルを作成します。

引数

• 引数 1（任意）： 更新するプロジェクト名です。省略した場合、このスキルは会話のコンテキストと作業ディレクトリからプロジェクトを特定します。

手順

フェーズ 1：特定 -- どのプロジェクトに変更を加えましたか？

次の3つの情報源を使って、このセッションで有意義な作業を行ったプロジェクトを特定します。

1. 会話のコンテキスト（主要）。 現在の会話を確認し、話題に上がったプロジェクトを特定します。これは最も豊富な情報源です。Git だけでは把握できない意図、決定、成果が含まれています。

2. 作業ディレクトリ。 現在の作業ディレクトリを確認します。

   • cwd がプロジェクトディレクトリ（.git/ がある）の場合、それが主要なプロジェクトです
   • cwd が複数のプロジェクトサブディレクトリを含むワークスペースの場合、最近活動のあったものを確認します
   • cwd がホームディレクトリ（~/）の場合、会話のコンテキストだけを参照します

3. Git の状態（検証）。 特定した各プロジェクトディレクトリについて：

   # Cross-platform: works on macOS and Linux
   git -C $PROJECT log --oneline --since="12 hours ago" 2>/dev/null
   git -C $PROJECT status --porcelain 2>/dev/null  # uncommitted work
   

   Git により、実際に変更されたコードを確認できます。会話では作業に触れているのに Git に何も示されていない場合は、その食い違いを記録します。また、コミットされていない変更にも注意します。これらは「状態」に記録することが特に重要です。

プロジェクトとメモリの対応付け： メモリディレクトリを動的に解決します。

• Claude Code はプロジェクトメモリを ~/.claude/projects/<escaped-project-path>/memory/ に保存します
• エスケープされたパスでは / が - に置き換えられます（例：/Users/alice/Projects/myapp は -Users-alice-Projects-myapp になります）
• メモリファイルは project_{name}.md という命名規則に従います
• プロジェクトのメモリディレクトリがすでに存在する場合は、それを使います。存在しない場合は作成します。

収束ルール： 対象に含めるには、プロジェクトが会話のコンテキストと、その他の情報源（Git または cwd）の少なくとも1つに登場する必要があります。これにより、単に言及されただけのプロジェクトのメモリを更新するのを防ぎます。

フェーズ 2：読み込み -- 既存のプロジェクトメモリを読み込む

特定した各プロジェクトについて：

1. 解決したメモリディレクトリから、プロジェクトのメモリファイル（project_{name}.md）を読み込みます
2. フロントマター、セクション見出し、内容など、構造を解析します
3. ファイルが存在しない場合は、その旨を記録します。既存のテンプレートに沿って新規作成します
4. サイズの確認： 行数を数えます。80行を超えている場合は、調整中に内容を整理する候補としてフラグを立てます。MEMORY.md はすべてのファイルから先頭200行を読み込むため、肥大化したプロジェクトファイルはほかのメモリを押し出します。

次も読み込みます。

• MEMORY.md のインデックス（インデックスの更新が必要か確認するため）
• スタックやアーキテクチャの情報が必要な場合は、プロジェクトの CLAUDE.md

フェーズ 3：抽出 -- セッションイベントを分類してフィルタリングする

会話と Git の履歴を確認します。重要なイベントごとに、分類します。

種類	保存するか	例
DECISION	常に	「認証方式をセッション Cookie から JWT に切り替えた」
STATUS_CHANGE	常に	「ステージング環境に昇格した」、「本番環境にデプロイした」
DISCOVERY	新規性がある場合	「Neon の無料プランには 100 接続の上限があることが分かった」
IMPLEMENTATION	結果のみ	「MCP サーバーを構築した」（「src/mcp/ に 12 個のファイルを作成した」ではない）
TROUBLESHOOTING	パターンのみ	「4.5MB を超えるファイルには Vercel Blob が必要だった」（5 つのデバッグ手順ではない）
EXPLORATION	保存しない	ドキュメントの閲覧、コードの検索、採用されなかったアプローチの試行

次に、3 つのゲートフィルターを適用します。すべての項目が 3 つすべてを通過する必要があります。

1. 持続性： 30 日後も、事実として有効または関連性がありますか？

   • はい：アーキテクチャ上の決定、リリース済みの機能、設定の変更、デプロイの状態
   • いいえ：デバッグ手順、エラーメッセージ、途中の試行、実行したコマンド

2. 具体性： 主語、動詞、具体的な値を含む明確な事実として記述できますか？

   • はい：「HyTek MDB ファイルから 457K 件の水泳記録をインポートした」
   • いいえ：「インポートシステムに取り組んだ」

3. 再取得の必要性： 将来のセッションで必要になる可能性は高いですか？

   • はい：制約、規約、根拠を伴う決定、統合の詳細
   • いいえ：何かをどうやって発見したか、読んだファイル、試した順序

3 つすべてを通過した項目について、以下を記録します。

• 何が変わったか（具体的な事実）
• なぜ変わったか（理由。コードだけでは分からない情報です）
• 下流の何に影響するか（影響範囲）

フェーズ 3.5：レイヤー別に振り分ける（V2）-- リポジトリとローカル

ローカルメモリは、リポジトリをクローンしただけのエージェントや共同作業者が必要とする情報の適切な保存先ではありません。2026 年の合意では、次の 3 層に分けます。規約 → CLAUDE.md／AGENTS.md、決定と根拠 → リポジトリの docs/decisions/（ADR）、現在の状況／次の作業 → docs/PROJECT_STATUS.md。そして、ローカルメモリには残りの情報だけを保存します（個人的な作業メモ、秘密情報の保存場所、プロジェクト横断のメモ）。永続的な項目を保存する前に、保存先を振り分けます。

項目	保存先	対応
チームメイトやリモートエージェントが必要とする、決定とその根拠	リポジトリの ADR（docs/decisions/）	リポジトリに記録し、根拠をローカルメモリに埋もれさせない
規約／アーキテクチャルール	CLAUDE.md／AGENTS.md	そのファイルの編集を提案する
現在の状態／次のステップ	リポジトリで使用している場合は PROJECT_STATUS.md、そうでなければメモリの Status	適切な保存先に振り分ける
秘密情報の保存場所、個人的なツール使用メモ、プロジェクト横断のメモ	ローカルメモリのみ	保存する（決してコミットしない）

これは余分な作業ではありません。それぞれの事実を、次に読む人が実際に探す場所に記録するということです。リポジトリにまだその仕組みがない場合（ADR／PROJECT_STATUS がない場合）は、その旨を記録し、これらのコミット対象ドキュメントの作成を提案します。それまではメモリを代替手段として使用します。メモリには、リポジトリ内に保存先が本当にない情報だけを残します。フェーズ 7 では、このステップで特定した CLAUDE.md／AGENTS.md の項目に対応し、claude-md 監査に渡して必要な箇所だけを昇格させます。

フェーズ 4：調整 -- セクションを考慮したマージ

各プロジェクトメモリファイルについて、セクションごとにマージの種類を分類し、適切な方法を適用します。

REPLACE セクション（全体を上書き）

Status セクション（見出しが ## Status で始まるもの）：

• 既存の Status ブロックをすべて削除する
• 新しいブロックを ## Status (Mon DD, YYYY) として書き込み、3～5 項目の箇条書きにする
• 現在のブランチ、デプロイの状態、主要な指標、直近の次のステップを記載する
• 未コミットの作業を含める： git status --porcelain に変更が表示される場合は、次のセッションで混乱が生じないよう、「作業ツリーに未コミットのファイルが N 個ある」と記載する
• このセクションは常に全体を上書きする。履歴ではなく現在の状態を表すため

MERGE-LIST セクション（重複を避けて更新・追加）

バックログ（または同等の項目：TODO、次のステップ、ロードマップ）：

• 項目の中心的な説明を基準に既存の項目と照合します（チェックボックスの状態、日付、タグは無視します）
• 完了した項目に印を付けます：- [ ] を - [x] に変更します（進捗追跡のため残します）
• セッション中に特定した新しい項目を追加します
• セッションによって優先順位が新たに判明した場合は、優先度順に並べ替えます

機能セクション（できること、機能、能力など）：

• エンティティ名（例：「MCP サーバー」「SSE ストリーミング」）を基準に照合します
• エンティティが存在する場合：新しい状態を反映するよう、その箇条書きを所定の位置で更新します
• 新しい場合：セクションに追加します
• すでに記載されている情報は重複させません

PRESERVE セクション（明示的に変更された場合のみ編集）

技術スタック、安全性、パラメーター、DB、アーキテクチャ、設定（または同等の項目）：

• このカテゴリに関してセッション中に明示的な変更があった場合のみ編集します
• 変更がない場合、セクションはバイト単位で完全に同一のままにします
• これらのセクションを再生成してはいけません。LLM による書き換えでは、細かなニュアンスや文体が失われるためです

フロントマター

• description は、プロジェクトの一行説明の範囲が変わった場合にのみ更新します（まれです）
• originSessionId を追加または変更しないでください

すり合わせのルール

1. すでに記載されている情報は重複させません
2. 事実を更新する場合は、既存の記述を探して、その箇所を編集します
3. 既存ファイルの文体と構成を維持し、変更しない文章は書き換えません
4. 変更があったかどうか不明な場合は、既存のテキストをそのままにします
5. 新しいセクションは、そのファイルで確立されている形式に従います

フェーズ 5：提示 -- 変更内容を確認してもらう

変更内容をユーザーに提示する前に、ファイルを書き込んではいけません。

プロジェクトごとに、変更案の明確な概要を提示します：

## project_{name}.md -- Proposed Changes

### Status (full replace):
- [new status bullets]

### Backlog (N completed, M added):
- [x] Completed item (done Mon DD)
- [ ] NEW: New item description

### [Section Name] (N updates):
- Added: [item]
- Changed: [old] -> [new]

### Size: current NN lines -> proposed NN lines

続けて、**「これらの変更を適用しますか？」**と尋ねます。

• はい -- すべて適用します
• 編集 -- 適用前にユーザーが変更できるようにします
• スキップ [project] -- 特定のプロジェクトをスキップします

承認されたら、Edit ツールを使って対象セクションのみを更新します。Status セクションについては、ブロック全体を置き換えます。変更のないセクションは書き換えません。

フェーズ 6：インデックス -- MEMORY.md を更新

新しいメモリファイルが作成された場合：

1. MEMORY.md の ## Projects セクションにエントリーを追加します
2. 既存の形式に従います：- [Project Name](memory/project_name.md) -- 一行の説明
3. セクション内でアルファベット順を維持します
4. 行数の確認： MEMORY.md が 180 行を超えた場合、200 行のコンテキスト読み込み上限が近づいていることを警告します

フェーズ 7：CLAUDE.md の監査 -- エージェント間で共有すべき教訓を反映する（任意。claude-md スキルが必要です）

このセッションで記録されたメモリは、推論についてのものです。しかし、フェーズ 3.5 で振り分けられた内容の中には、メモリが扱うべきでないものもあります。それは、あらゆるエージェントやチームメイトに必要な規約やアーキテクチャルールであり、コミット対象の CLAUDE.md／AGENTS.md に記載するものです。新しくクローンした人や別のエージェントが最初に読む、エージェント間の共有レイヤーです。ローカルメモリに埋もれた教訓は、そうした人たちには見えず、誰かが /init を再実行すると、気づかれないまま消えてしまいます。

CLAUDE.md／AGENTS.md がある（または作成すべき）作業対象のプロジェクトごとに、次の手順を行います。

1. CLAUDE.md に記載すべき項目を集めます。 フェーズ 3.5 で明らかになった規約、アーキテクチャルール、「必ず／決して」といった、このセッションで生まれた指針のうち、別のエージェントにも必要なものを集めます。（フェーズ 3.5 で何も見つからなかった場合は、このフェーズを省略します。）
2. claude-md がインストールされていれば、作業を引き継ぎます。（ngmeyer/skills でこのスキルとともに提供されています。）/claude-md audit（すべての CLAUDE.md ファイルの乖離、漏洩したシークレット、肥大化を監査）または /claude-md improve <path>（1 つのファイルをベストプラクティスに照らして評価し、必要最小限の差分を提案）を実行し、ステップ 1 の項目を渡します。claude-md は、すべての差分について承認を得てから反映します。
3. claude-md がない場合は、適切に対処します。 項目を出力して、"このセッションで生まれた N 件の規約は CLAUDE.md に記載するのが適切かもしれません。claude-md をインストールするか、手動で追加してください" と伝え、何も失われないようにします。決して、これを理由に処理を止めてはいけません。

既存の CLAUDE.md を更新するために /init を実行してはいけません。 /init はファイル全体を再生成します。アーキテクチャのセクションを独自に作り出し、ファイルにまだ書き込まれていない、精選された価値ある教訓を破棄してしまいます。このフェーズはファイルの再生成ではなく、必要最小限の反映です（追加するのは採用に値する数行だけとし、それ以外はバイト単位でそのまま残します）。プロジェクトにまだ CLAUDE.md がない場合は、最小限のファイルを作成するよう提案してください。大きなファイルを自動生成してはいけません。

これは意図的なソフト依存関係です。claude-md がなくても、項目のリストを出力して処理を続けられるため、個別に選んでインストールした場合でも、セッション終了処理は完結します。

フェーズ 8：クリーンアップ -- 成果物の削除を提案する

以下を確認し、削除を提案します。

1. セッション固有の計画ファイル：~/.claude/plans/ にある、すべてのタスクが完了したファイル
2. セッションダンプのメモリファイル：内容がプロジェクトごとのファイルに統合された project_session_*.md などのファイル
3. 完了済みタスクのディレクトリ：すべてのタスクのステータスが completed になっている ~/.claude/tasks/ 内のディレクトリ
4. 他のプロジェクトファイルにある古い Status セクション：プロジェクトファイルに 30 日以上前の日付が付いた Status セクションがあれば、確認対象として知らせます。

削除する前に、必ず確認を求めてください。 クリーンアップ対象の一覧を提示し、確認を待ちます。

注意点

• セッションのダンプは禁止です。 project_session_*.md ファイルを作成してはいけません。これを防ぐことが、このスキルの目的です
• セッションを軸に記述しないでください。 「4 月 11 日のセッションで……」とは書かず、履歴ではなく状態を記述してください
• 実装の詳細は記載しないでください。 アーキテクチャ上の要所でない限り、ファイルパス、行番号、関数名を含めてはいけません。コードには成果を、メモリには推論を記録します
• 黙って書き込まないでください。 メモリファイルを変更する前に、必ず差分のプレビューを表示して承認を得てください
• 更新を強制しないでください。 セッションに永続的な成果がなかった場合（純粋なデバッグ、調査、または中断した探索）は、「永続的な状態変更は検出されませんでした」と報告して終了してください
• 対象範囲を広げないでください。 project_*.md ファイルのみを更新し、フィードバック、ユーザー、リファレンスのメモリファイルには触れないでください
• リモートへの呼び出しは禁止です。 Git のリモートから取得したり、ネットワークリクエストを行ったりしてはいけません。ローカルの状態のみを使用してください
• 存在しないプロジェクトのメモリは作成しないでください。 言及されただけで作業していないプロジェクトのメモリを作成してはいけません
• 機能またはスタックのセクションに日付を付けた項目を記載しないでください。 日付を記載できるのは Status セクションのみです
• セクションを再生成しないでください。 変更しないセクションを書き直してはいけません。LLM による書き直しは、細部を失い、文体を変え、内容のずれを生じさせることがあります。ファイル全体への Write ではなく、特定の行に Edit ツールを使用してください
• 曖昧な要約は避けてください。 「認証機能の改善に取り組んだ」では具体性の基準を満たしません。保存するすべての事実に、主語、動詞、具体的な値を含めてください
• 既存の CLAUDE.md の更新に /init を使ってはいけません。 ファイル全体が再生成され、メモリにのみ存在していた厳選済みの知見が失われます。claude-md スキル（フェーズ 7）を使って、必要な内容だけを CLAUDE.md に反映してください。再生成は行わないでください。メモリは推論用、CLAUDE.md/AGENTS.md はエージェント間で共有する規約のレイヤーです。それぞれの役割を守ってください

セクションの命名規則

照合ロジックは、以下のパターンでセクションを照合します。メモリファイルでは、これらの見出し（または近い表現）を使用してください。

マージの種類	セクション見出し（柔軟に照合）
REPLACE	## Status、## Current Status
MERGE-LIST	## Backlog、## TODO、## Next Steps、## Roadmap、## What It Does、## Features、## Capabilities
PRESERVE	## Stack、## Architecture、## Safety、## Config、## Parameters、## Database

いずれのパターンにも一致しないセクションは、PRESERVE として扱われます（安全な既定値）。

エッジケース

既存のメモリファイルがない場合： 既存のプロジェクトファイルにあるテンプレート（フロントマターと、What It Does、Stack、Status、Backlog の各セクション）に従って新規作成してください。新しいファイル全体を提示し、承認を得てください。

永続的な成果がない場合： 「どのプロジェクトについても永続的な状態変更は検出されませんでした。更新する項目はありません。」と報告してください。問題なく終了します。デバッグ、調査・閲覧、中断した探索のセッションでは、これが正しい対応です。更新を強制してはいけません。

情報が矛盾する場合： 会話の内容と Git の内容に矛盾があれば、ユーザーに伝えてください。例：「会話では Fly.io へのデプロイに言及されていますが、デプロイに関するコミットは見つかりませんでした。ステータスの更新に含めますか？」

ホームディレクトリから複数のプロジェクトを扱ったセッション： 各プロジェクトを個別に処理してください。これにより、セッションのダンプというアンチパターンを防げます。

非常に長いセッション（4 時間以上）： すべてを一度に処理せず、プロジェクトを順番に処理してください。変更内容は一度に 1 つのプロジェクト分だけ提示してください。

更新後のファイルが 80 行を超える場合： ユーザーに警告し、完了したバックログ項目の削除や、冗長なセクションの圧縮を提案してください。プロジェクトファイルは簡潔に保つ必要があります。MEMORY.md の 200 行分のコンテキスト予算をめぐって競合するためです。

未コミットの作業がある場合： 必ず Status セクションに含めてください。以前のセッションでは未コミットの作業を追跡できず、次のセッションで混乱が生じています。

変更履歴

V2.1 (2026-06-11) -- CLAUDE.md 監査の引き継ぎ（Phase 7）

Phase 7: CLAUDE.md AUDITを追加しました。メモリを整理した後、Phase 3.5で特定したエージェント間の共通規約を、**claude-md**スキルの、承認を得てから行う外科的なaudit／improveに引き継ぎ、コミット済みのCLAUDE.md／AGENTS.mdに反映します。ファイルを再生成し、メモリだけにあった厳選された教訓を削除する/initは決して使いません。これにより、Phase 3.5で始めた作業を完了します。Phase 3.5ではCLAUDE.mdに反映すべき項目を特定しましたが、それに対して行動する仕組みはありませんでした。ソフト依存のため、claude-mdがインストールされていない場合は一覧を表示するだけとなり、セッション終了処理は単独で完結します。両スキルはngmeyer/skillsで配布されているため、兄弟スキルへの参照も安全です。CLEANUPを7から8に繰り下げました。

V2 (2026-05-27)

skillforge optimizeで最適化しました（成果に関する調査：AI エージェントのメモリ／コンテキストエンジニアリング 2026）。

• Phase 3.5 レイヤー別に振り分け — 長期的に有用な項目を適切な保存先に振り分けます（規約→CLAUDE.md／AGENTS.md、決定事項→リポジトリのADR、ステータス→PROJECT_STATUS）。すべてをローカルメモリに保存するのではなく、メモリには残りだけを保存します。この3層構成は、2026年のエンジニアリングにおけるコンセンサスです。
• 既存の「ダンプではない」ルールとサイズ確認ルールを、根拠の説明で補強しています。コンテキストの劣化（メモリが肥大化すると品質が低下する）を防ぐためであり、選択的なメモリは肥大化したコンテキストより約10～20倍低コストです。
• 成果目標：再開に不可欠な知識を、1台のマシンのローカルメモリに閉じ込めるのではなく、どのエージェントやチームメイトでも見つけられる場所に保存します。出典：AI エージェントのメモリの現状 2026 (mem0); エージェントのメモリとコンテキストエンジニアリング (Augment).

クレジット

スキル作成者：Neal Meyer