セッションハンドオフスキル
目的
大規模なコンテキストウィンドウは、トークン数が蓄積するにつれて、命令の遵守、推論の精度、ツールの正確性が低下します。長いセッションは、置き換えられた計画、中断されたスクラッチパッド、繰り返されるエラートレースで埋め尽くされます。新しいセッションにリセットするとパフォーマンスは回復しますが、コンテキストを盲目的に破棄すると、状態の喪失、幻覚的な進捗、繰り返しのミスが発生します。
session-handoff スキルは、エージェントがアクティブな状態をスナップショットする方法を標準化します。一時的なワーキングメモリを、次のセッションのための実行可能で検証可能な橋渡しドキュメントに変換します。
ワークフロー: セッションの終了 (6ステップ)
エージェントセッションが運用上の限界に達したとき、または作業を中断するときに、このシーケンスを実行します。
-
Gitとワークスペースの状態を監査する
git status -sとgit diff --statを実行して、現実的な基準を確立します。何が変更されたかをチャットのメモリに頼ってはいけません。変更されたファイル、追跡されていないファイル、ステージングされたファイルを特定します。 -
目標の状態と実装された現実を把握する 元の目標を一文で定義します。何が検証済みで動作しているか(テストコマンドやランタイムチェックの合格で確認)を、何が部分的または未検証かを正確に文書化します。
-
決定事項と破棄したアプローチを記録する セッション中に行われたアーキテクチャおよび設計上の選択と、その具体的な理由を列挙します。否定的な判断(試行して破棄したアプローチ)を明示的に記録し、次のエージェントが失敗した解決策を再度試みることを防ぎます。
-
変更・参照したファイルと関連シンボルを一覧化する 変更または参照された主要なファイルパス、関数、クラス、スキーマ定義をリストアップします。必要に応じて行番号も含めます。
-
未解決の問題を所有者と検証条件とともに特定する 未対応のエッジケース、失敗するテスト、延期されたタスク、環境の制約をすべてリストアップします。すべての未解決問題には、誰が解決するか(人間またはエージェント)と、完了をどのように検証するかを指定する必要があります。
-
次の即時アクションを指定する 次のエージェントが最初のターンで実行するための、単一の、分割不可能で、曖昧さのない指示を起草します。広範なリストは提供せず、最初に実行する正確なコマンドまたは編集するファイルを指定します。
運用ルール
- 事実と推測を区別する: 合格したテストは事実です。コードがコンパイルされたから動作すると仮定するのは推測です。未検証の仮定は明示的に
[UNVERIFIED]とラベル付けします。 - 未解決の問題には所有者と検証を必須とする: すべての未解決問題は、所有者 (
HumanまたはAgent) と決定論的な検証基準(例:pytest tests/auth/test_token.py:test_refresh_rotation passes)を記載しなければなりません。 - 曖昧な継続を禁止する: 「認証の作業を続ける」や「フロントエンドコンポーネントを仕上げる」とは決して書かないでください。正確なシンボル、ファイル、および失敗モードを記述します。
- 実際のワークスペース識別子を参照する: コードへのすべての参照は、正確なファイルパスとシンボル名を使用しなければなりません。一般化された疑似コードの説明は使用しないでください。
実例: セッションハンドオフノート
# セッションハンドオフ: JWTローテーション実装
### 目標と現在の状態
- **目標**: FastAPI認証サービスにリフレッシュトークンのローテーションと失効を実装する。
- **現在の状態**: リフレッシュトークンのデータベースマイグレーションを適用し、ローテーションエンドポイントを作成しました。トークン生成とデータベースへの永続化は動作します。失効ブラックリストキャッシュは、依存性バリデータにまだ配線されていません。
- **検証**: `pytest tests/test_auth_tokens.py` が合格 (4/4テスト)。
### 決定事項(理由付き)
- **トークン失効リストにRedisを使用**: 保護されたルートでレイテンシを5ms未満に抑えるため、失効したJTIトークンの検索にPostgresではなくRedisを選択しました。
- **ステートレスリフレッシュトークンを却下**: JWTクレーム内でのスライディング期限と永続化なしを初期に評価しましたが、侵害されたトークンを自然期限前に失効できないため却下しました。
- **トークン形式**: 既存のセッションストレージスキーマとの互換性を維持するために、`jti` クレームにUUIDv4を選択しました。
### 変更されたファイル
- `src/services/auth.py`: `rotate_refresh_token(old_token: str)` 関数とRedis無効化呼び出しを追加。
- `src/models/tokens.py`: トークンファミリーを追跡するための `RefreshTokenRecord` SQLModelテーブルを追加。
- `alembic/versions/20261005_add_token_families.py`: `token_records` テーブルを作成するマイグレーション。
- `tests/test_auth_tokens.py`: トークンファミリーの生成とローテーションのための単体テストを追加。
### 未解決の問題
- [Agent] `verify_token_not_revoked` を `src/api/deps.py` に配線 -> `tests/test_auth_deps.py` がブラックリスト登録されたトークンで失敗することを確認して検証。
- [Agent] ローテーション中にRedisが到達不能になった場合のデータベースロールバックを処理 -> 単体テストでRedis接続障害をモックして検証。
- [Human] CI実行のために `REDIS_AUTH_URL` シークレットを `.env.test` に設定。
### 次のアクション
`src/api/deps.py` を開き、`is_token_blacklisted` を `src.services.auth` からインポートします。JWTデコード検証の直後に、`get_current_user` にチェックを挿入します。
### 注意点
- `src/core/config.py` の既存の `access_token` 有効期限(現在15分)は変更しないでください。
- Alembicマイグレーション `20261005_add_token_families.py` は、ローカルでAPIサーバーを起動する前に実行する必要があります (`alembic upgrade head`)。
アンチパターン
- チャットトランスクリプトのダンプ: 生の会話ログをハンドオフノートに貼り付けること。次のセッションのコンテキストウィンドウは、まさに逃避しようとした会話のノイズで即座に汚染されます。
- 幻の合格: 実行もテストもされていないモジュールを「完了」とマークすること。
- 行き止まりの省略: 失敗した解決策を除外すること。次のエージェントはコードベースを読み、同じ明白な経路を見て、失敗したアプローチを再実装するでしょう。
- 抽象的な次のステップ: 「次: 残りのテストを実装」で終わること。新しいエージェントは、何をテストすべきかを発見するために3〜5ターンの無駄なやり取りを費やします。
制限事項
- このスキルは書面によるハンドオフのみを生成します。実行中のプロセス、コミットされていないターミナル出力、メモリ内のデバッグコンテキストなどのライブ状態を保持することはできません。重要なものはすべてノートに明示的に記録してください。
- ハンドオフの品質は、終了するセッションが記録する内容に依存します。文書化されていない決定、行き止まり、ファイル変更は、次のセッションで回復できません。
- バージョン管理や課題追跡の代わりにはなりません。まず作業をコミットし、ノートでは重複する代わりにコミットやチケットを参照してください。