session-reflection

セッションの振り返り

価値： フィードバック — ユーザーからの介入はすべて、システムプロンプトが不完全であることを示すシグナルです。修正を永続的な指示に変えることで、セッションを重ねるごとに改善が積み上がります。

目的

エージェントがセッション履歴を分析して繰り返される修正を特定し、既知の失敗パターンを防ぐプロジェクト固有の指示を作成し、コンテキストの圧縮やクラッシュ後も維持される作業状態を保てるようにします。事後対応的な修正を事前の予防へと転換します。

プラクティス

振り返りのトリガー

次のタイミングで振り返ります。マイルストーンの達成時（PR のマージ、機能の完成）、ユーザーから3回以上同じ修正を受けたとき、セッションの再開またはクラッシュからの復旧時、タスクを5件完了するごと、ユーザーから明示的に求められたときです。「ちょうどよいタイミング」を待たず、トリガーに該当したら振り返ります。

セッション履歴の分析

会話履歴、git log、メモリファイル、WORKING_STATE.md、セッションログを確認します。ユーザーからの介入を、次の5種類に分類します。

• 修正：エージェントが誤った対応をした（指示の不足）
• 繰り返し：同じことを再度伝えられた（強調の不足）
• 役割の逸脱：エージェントが役割の範囲を超えた（境界の不足）
• 不満のエスカレーション：ユーザーの指摘がより強い表現になった（劣化の問題）
• 回避策：ユーザーが自分で対応した（スキルの不足）

分類と優先順位付けの詳細については、references/analysis-framework.md を参照してください。

プロジェクト指示の作成または改良

内容に応じて、プロジェクト固有の指示を適切な指示ファイルに振り分けます。独立したシステムプロンプトファイルはありません。すべては CLAUDE.md → AGENTS.md → .team/coordinator-instructions.md の順に受け継がれます。

• CLAUDE.md — セッション管理（開始手順、圧縮からの復旧、状態の追跡）、ハーネス固有の設定
• AGENTS.md — プロジェクト全般のルール、すべきこと・すべきでないこと、コーディング規約、ワークフローの設定
• .team/coordinator-instructions.md — コーディネーター／パイプラインコントローラーの役割の区別、ビルド前の事前チェック、起動時の規律、ドメインレビューのチェックリスト

改良のルール：新たな不足には新しい項目を追加し、不足が繰り返されたら推奨事項を構造的なルールに引き上げ、曖昧な項目は明確になるよう書き直します。不足が3回以上のセッションにわたり解消されたと確認できるまで、項目を削除してはいけません。記述パターンについては references/system-prompt-patterns.md を、ハーネス固有のファイル振り分けについては references/launcher-templates.md を参照してください。

セルフリマインダープロトコル

統合されたセルフリマインダープロトコル（頻度、まとめて再読するファイルの一覧、圧縮後のルール）については、テンプレートディレクトリの CONSTRAINT-RESOLUTION.md を参照してください。

作業状態の永続化

コンテキストの圧縮やクラッシュに備え、WORKING_STATE.md を維持します。状態に重要な変化があるたびに更新します。中断後に作業を再開する際は、必ず行動する前に読みます。保存先：.factory/WORKING_STATE.md（パイプラインの場合）、またはプロジェクトのルートディレクトリ（単独の場合）。形式については references/working-state-schema.md を参照してください。

行うこと：

• タスクの開始時、フェーズの変更時、判断時、ブロッカー発生時に更新する
• 追記ではなく、現在の状態で上書きする
• 中断後は最初に読む

行わないこと：

• 圧縮や再起動後に、記憶を頼りに状態を推測する
• 日誌として使う — 簡潔で最新の状態を保つ
• 「重要な変化は何もなかった」という理由で更新を省略する

セッション後の学習ループ

セッション終了時に、そのセッションでのパターンを特定し、メモリファイルを更新し、トリガーに該当した場合はプロジェクト指示を改良し、作業状態をアーカイブします。

同じ種類の介入が繰り返されなくなれば、ループは完了です。指示を改良した後も、介入の種類が3回以上のセッションにわたって続く場合は、エスカレーションします。不足を解消するには、新しいスキルやワークフローの構造的な変更が必要かもしれません。

適用に関する注記

すべてのモードで推奨事項です。振り返りのトリガーと指示の作成は、自己管理で実施します。

厳守事項：

• コンテキスト圧縮後は必須です：[H] — コンテキスト圧縮によって暗黙の状態が失われるため、再読は省略できません。

制約

• 「3回以上繰り返された修正」：「繰り返された修正」とは、ユーザーが同じ根本的な動作を複数回修正したことを意味します。同じ修正を異なる表現で伝えた場合も、1つの修正が繰り返されたものとして数えます。同じカテゴリー内の異なる修正（例：異なる書式設定の好みが2つある場合）は、それぞれ別に数えます。
• 「3回以上のセッションで解決が確認されるまで指示を削除しない」：これは早まった整理を防ぐためのものです。3回のセッションで問題が発生していない指示は、問題を防いでいる可能性があります。これは古くなったのではなく、うまく機能しているということです。根本的な動作が修正されたという確かな証拠（例：問題の原因となったコードパターンが存在しなくなったこと）が得られた場合にのみ削除してください。

検証

このスキルに沿って作業を完了した後、以下を確認してください。

• すべてのトリガーポイント（マイルストーン、修正の繰り返し、再起動）で振り返りを実施した
• 5種類の分類体系を使ってユーザーの介入を分類した
• プロジェクトの指示を、助言にとどまらない構造的な表現で改善した
• 指示を適切なファイル（CLAUDE.md / AGENTS.md / coordinator-instructions.md）に割り当てた
• セルフリマインダーのプロトコルに従った（5～10メッセージごとに状態を再読み込みした）
• WORKING_STATE.md が最新かつ正確である
• コンテキストが圧縮されるたびに、推測ではなく状態を再読み込みした

いずれかの基準を満たしていない場合は、該当するプラクティスを見直してから先に進んでください。

依存関係

このスキルは単独で動作します。ワークフローを強化するため、以下と連携します。

• memory-protocol： セッションの学びと作業状態を永続的に保存します
• agent-coordination： 指示の生成で参照される調整パターンを提供します
• pipeline： パイプラインコントローラーは、セルフリマインダーとクラッシュリカバリーの恩恵を受けます
• ensemble-team： チームの振り返りがセッションの振り返り分析に役立ちます

依存関係が不足していますか？次のコマンドでインストールしてください。

npx skills add jwilger/agent-skills --skill memory-protocol