セッション振り返り
意図
セッション中の作業から知見を抽出し、プロジェクトの知識資産として定着させる。 「振り返りのコストを低く保ちつつ、価値のある知見を逃さない」ことを目指す。
振り返り手順
1. セッションの変更を俯瞰する
bash
git log --oneline <session-start-commit>..HEAD git diff --stat <session-start-commit>..HEAD
変更の全体像を把握する。「何をやったか」ではなく「何が見えたか」に注目する。
2. 知見の候補を抽出する
以下の観点でセッションを振り返る:
| 観点 | 問い |
|---|---|
| パターン | 同じ構造・手法が2回以上出てきたか？ |
| 設計判断 | 複数の選択肢から何かを選んだか？その理由は？ |
| 型の問題 | 型システムとの摩擦があったか？回避策は？ |
| 躓き | 予想外の問題にぶつかったか？どう解決したか？ |
| 命名・規約 | 新しい命名パターンや規約が生まれたか？ |
すべてのセッションに知見があるわけではない。無理に絞り出さない。
3. 配置先を判断する
知見の性質に応じて配置先を選ぶ。判断基準の詳細は docs/DOCUMENTATION.md の「知見の落とし込み」セクションを参照。
| 知見の性質 | 配置先 | 例 |
|---|---|---|
| コーディングパターン・規約 | docs/CONVENTIONS.md | keyed() のインターセプトパターン |
| 設計判断・教訓 | docs/PROJECT_KNOWLEDGE.md | 暗黙的状態→明示的データの原則 |
| 繰り返すワークフロー | .claude/skills/ | この振り返り skill 自体 |
| 実装パターンの躓き | examples/*/README.md | 特定 showcase での注意点 |
| API 仕様の変更 | packages/*/README.md | 新 API の追加 |
| Claude の行動指針 | MEMORY.md | プロジェクト固有の知識 |
4. ドキュメント更新を実行する
- •変更ファイルを確認し、関連する README の更新が必要かもチェックする
- •実装と乖離したドキュメントがあれば合わせて修正する
- •コミットは実装とは分けて
docs:プレフィックスで作成する
5. ユーザーと確認する
配置先や内容について迷いがあれば、判断をユーザーに仰ぐ。 「記録すべきか迷っている」と正直に伝えることも立ち回りの一部。
現時点の方針
- •振り返りは提案ベースで進める。知見の候補を提示し、ユーザーと一緒に取捨選択する
- •「とりあえずメモ」は MEMORY.md に。成熟したら docs/ や skill に昇格する
- •skill は「完成した手順書」ではなく「現時点の方針 + 発展の余地」として作る
- •方針ドキュメント自体もレビュー対象。振り返りの中で方針の摩擦に気づいたら記録する
今後の検討事項
- •振り返りの頻度: 毎セッション vs 大きな作業の区切りのみ
- •MEMORY.md の定期的な棚卸し（昇格 or 削除）のタイミング
- •知見の追跡: 過去に記録した知見が実際に役立っているかの検証