retrospecting

セッション振り返りスキル

自動読み込みコンテキスト

セッション分析：contexts/session-analytics.md - データソース、指標、分析方法など、セッションを分析するための包括的なフレームワークを提供します。

振り返りテンプレート：templates/retrospective-templates.md - 振り返りの深さに応じた標準レポートテンプレートです。

主な役割

1. 複数ソースからのデータ収集

利用可能なすべてのソースから、体系的にデータを収集します。

• Git 履歴：セッション期間中のコミット、差分、ファイル変更
• Claude ログ：会話の記録、ツールの使用状況、意思決定の傾向
• プロジェクトファイル：テストカバレッジ、コード品質、コンパイル状況
• ユーザーフィードバック：目標、満足度、問題点に関する直接の意見
• サブエージェントとのやり取り：サブエージェントを使用した場合、そのフィードバックを収集します

2. 定量分析

測定可能な指標を算出します。

• セッションの範囲（所要時間、完了したタスク数、変更したファイル数）
• 品質指標（コンパイル率、テストカバレッジ、標準への準拠状況）
• 効率性指標（ツールの成功率、手戻り率、完了率）
• ユーザー体験のデータ（満足度、摩擦点）

3. 定性評価

傾向と洞察を特定します。

• 良い結果につながった効果的なアプローチ
• 問題や遅延の原因となった問題のある傾向
• 今後の利用に向けて抽出する価値のある再利用可能な解決策
• この種のプロジェクトに適用できる、コンテキスト固有の学び

4. レポートの作成

適切なテンプレートを使用して、構成された振り返りレポートを作成します。

• 簡易振り返り：短時間のセッションのまとめ（5～10 分）
• 包括的な振り返り：重要なセッションの詳細な分析
• セッションの複雑さとユーザーのニーズに応じてテンプレートを選択します

作業プロセス

ステップ 0：セッションの規模を簡易評価

データを収集する前に、適切な分析の深さを判断します。

1. セッションの規模を確認します：

   # Count recent commits
   git log --oneline --since="1 hour ago" | wc -l
   
   # List session log files with metadata
   ${CLAUDE_PROJECT_DIR}/.claude/skills/extracting-session-data/scripts/list-sessions.sh --sort date | head -5
   

2. 指標に基づいて推奨する分析の深さをユーザーに提案します：

   • 簡易（コミット数 <10、ログ <5MB）：「5～10 分の簡易分析」
   • 標準（コミット数 10～25、ログ 5～20MB）：「15～20 分のバランスの取れた分析」
   • 包括的（コミット数 >25、ログ >20MB）：「30 分以上の詳細な分析」

3. ユーザーが変更できるようにします：「[X commits, Y MB logs] に基づき、[MODE] の振り返り（約 Z 分）をおすすめします。この内容でよろしいですか？それとも、異なる深さを希望しますか？」

4. 早期終了の条件：ユーザーが「手短な要約だけ」や「概要だけ」と言った場合は、セッションの規模に関係なく、自動的に簡易モードを使用します。

ステップ 1：セッションの範囲を設定

1. セッションの範囲（期間またはコミット範囲）をユーザーに確認します
2. セッションの目標を明確にします：「何を達成しようとしていましたか？」
3. ステップ 0 で決めた振り返りの深さを確認します

ステップ 2：データを収集

確認済みの深さに基づいて、データ収集を実行します。

深さに応じたデータ収集

簡易モード：

• Git：git diff <start>..<end> --stat のみ（差分全体は取得しません）
• ログ：extracting-session-data スキルを使用して統計情報とエラーのみを抽出します
• ファイル：コンパイル状況のみを確認します
• ユーザー：対象を絞った質問を 2～3 個します
• 省略：サブエージェントのフィードバック、詳細なファイル分析

標準モード：

• Git：全コミット履歴と統計情報、主要ファイルの差分を選択的に確認します
• ログ：extracting-session-data スキルを使用して、メタデータ、統計情報、ツールの使用状況、エラーを抽出します
• ファイル：変更したファイルの品質指標を確認します
• ユーザー：主な領域を網羅する質問を 5～7 個します
• 含める内容：該当する場合はサブエージェントのフィードバック

包括的モード：

• Git：すべて（全ログ、差分、ファイル分析）
• ログ：extracting-session-data スキルを使用してすべての種類のデータを抽出します。500 行未満の場合は、ログ全体を読み取ることがあります
• ファイル：テストやアーキテクチャへの準拠状況など、詳細な分析を行います
• ユーザー：広範なフィードバックを求めます（質問 8～10 個）
• 含める内容：すべてのサブエージェントのフィードバック、パターンの抽出

Git 分析

analyzing-git-sessions スキルを使って、Git データを収集します。

クイックモード：出力を「簡潔」にするよう依頼します（統計情報のみ、差分なし） 標準モード：主要なファイルについて「詳細」な出力を依頼します 包括モード：「コードレビュー」形式で全体的な分析を依頼します

セッションの期間を指定してスキルを呼び出します。

Skill: analyzing-git-sessions
Input: "<start-time> to <end-time>" or "<start-commit>..<end-commit>"
Depth: [concise|detailed|code-review] based on retrospective mode

スキルは、振り返り分析に必要な構造化された Git 指標を返します。

ログ処理（サイズに応じた処理）

extracting-session-data スキルを使って、Claude Code のネイティブなセッションログに効率よくアクセスします。

1. 利用可能なセッションを一覧表示する：

   # List all sessions with metadata (size, lines, date, branch)
   ${CLAUDE_PROJECT_DIR}/.claude/skills/extracting-session-data/scripts/list-sessions.sh
   

2. セッションのサイズを確認する：

   # Get statistics for specific session
   ${CLAUDE_PROJECT_DIR}/.claude/skills/extracting-session-data/scripts/extract-data.sh \
       --type statistics --session SESSION_ID
   

3. セッションのサイズとモードに基づいてデータを抽出する：

   クイックモード（または 2000 行を超えるセッション）：

   # Extract only statistics and errors
   extract-data.sh --type statistics --session SESSION_ID
   extract-data.sh --type errors --session SESSION_ID --limit 10
   

   標準モード（500～2000 行のセッション）：

   # Extract metadata, statistics, tool usage, and errors
   extract-data.sh --type metadata --session SESSION_ID
   extract-data.sh --type statistics --session SESSION_ID
   extract-data.sh --type tool-usage --session SESSION_ID
   extract-data.sh --type errors --session SESSION_ID
   

   包括モード（500 行未満のセッション）：

   # Extract all available data
   extract-data.sh --type all --session SESSION_ID
   
   # Or read full log file if needed for detailed analysis
   # (Only for small sessions - check line count first!)
   

4. 複数セッションの分析：

   # Filter sessions by criteria
   filter-sessions.sh --since "7 days ago" --branch main
   
   # Extract data from all filtered sessions (omit --session flag)
   extract-data.sh --type statistics  # Runs on all sessions
   

5. 抽出したデータを統合する： 抽出後、分析に進む前に、データを簡潔な要約（最大 200 行）にまとめます。

パスの計算：extracting-session-data スキルがすべてのパスを自動的に計算します。セッションログは ~/.claude/projects/{project-identifier}/ に保存されます。識別子は作業ディレクトリのパスから生成されます。

プロジェクト分析

変更されたファイル、テスト、ドキュメントを、深さに応じて調査します。

ユーザーからのフィードバック

セッション体験について、ユーザーに直接フィードバックを求めます（質問数は分析の深さモードに応じて調整します）。

サブエージェントからのフィードバック

サブエージェントを使用した場合は、その視点を収集するためにサブエージェントを呼び出します（標準モード／包括モードのみ）。

ステップ 3：データを分析する

session-analytics.md のフレームワークを適用します。

• 定量的な指標を算出する
• 成功と問題の兆候を特定する
• パターン（成功したアプローチとアンチパターン）を抽出する
• コミュニケーションの有効性と技術的な品質を評価する

ステップ 4：インサイトを導き出す

分析結果を、実行可能なインサイトにまとめます。

• 何がうまくいったのか、その理由（具体的な根拠）
• 何が問題を引き起こしたのか、その根本原因
• 改善の機会（影響度の高い順）
• 今後のセッションで再現または回避すべきパターン

ステップ 5：レポートを作成する

retrospective-templates.md の適切なテンプレートを使用します。

• 根拠を示しながら、調査結果を明確に構成する
• 必要に応じて、ファイル名と行番号を具体的に記載する
• 推奨事項を影響度と実現可能性に基づいて優先順位付けする
• すべての提案を、具体的で実行可能なものにする

ステップ 6：ユーザーから検証を得る

レポートを提示して、以下を尋ねます。

• これはあなたの経験と一致していますか？
• 見落としている課題はほかにありますか？
• どの改善が最も役立ちますか？

ステップ 7：設定の改善を提案する

振り返りによって、Claude またはエージェントとのやり取りに改善の余地が見つかった場合：

1. 改善点を設定ファイルに反映できるか分析します。
   • CLAUDE.md：基本的な指示、ワークフローの実践方法、コミュニケーションのパターン
   • SKILL.md files：スキル固有の指示、作業プロセス、アンチパターン
   • Agent definition files：エージェントのプロンプト、ツールの使用方法、連携のパターン
2. 設定の更新について、具体的で実行可能な提案を作成します。
   • 既存の内容を更新する場合は、変更対象となる現在のテキストを引用する
   • 提案する新しいテキストまたは追加するテキストを示す
   • 振り返りの結果に基づき、変更の根拠を説明する
3. 提案をユーザーに提示します。
   • 「この振り返りに基づいて、[file] の改善案を特定しました。この変更を実施しますか？」
   • 実施する変更内容を具体的に示す
4. ユーザーが承認した場合：
   • Edit ツールを使って変更を適用する
   • 更新内容を確認する
5. ユーザーが承認しなかった場合：
   • 今後検討できるよう、振り返りレポートに提案を記録する

ステップ 8：セッションアーカイブ情報

振り返りレポートを作成し、検証した後は、次の手順を実行します。

1. セッションログの保存場所をユーザーに伝えます。
   • 「セッションログは ~/.claude/projects/{project-dir}/{session-id}.jsonl に永続的に保存されます」
   • 「これらのログは Claude Code によって管理されており、手動で削除しないでください」
2. 振り返りレポートは次の場所に別途保存されることを説明します。
   • ${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/
3. Claude Code がセッションログの保持を自動的に管理することを伝えます。

出力基準

レポートの品質要件

• エビデンスに基づく：すべての主張を具体例で裏付けます
• 実行可能：すべての推奨事項に実装方法を含めます
• 具体的：曖昧な記述を避け、具体例を使用します
• 優先順位付け：影響の大きい項目と小さい項目を明確に示します
• バランスが取れている：改善点を特定しながら、成功した点も認めます

ファイル参照

特定のコード箇所を参照するときは、file:line_number 形式を使用します。

メトリクスの提示

メトリクスは、解釈のためのコンテキストを添えて、わかりやすい表またはリストで提示します。

推奨事項の形式

各推奨事項には、次の内容を含めます。

• 内容：実施する具体的なアクション
• 理由：根本原因または根拠
• 方法：実装方法
• 影響：期待される効果

サブエージェントとの連携

セッション中にサブエージェントを使用した場合：

フィードバックの収集

参加した各サブエージェントに、次のようなプロンプトでフィードバックを求めます。

• 「このセッションでうまくいった点は何ですか？」
• 「どの指示やコンテキストが不明確でしたか？」
• 「必要だったのに使えなかったツールや機能は何ですか？」
• 「Claude との連携をどのように改善できますか？」

統合

サブエージェントからのフィードバックを振り返りに取り込みます。

• 連携上の問題や引き継ぎ時の問題を特定します
• 指示の明確さやコンテキストの不足を記録します
• うまくいった連携パターンを認識します
• サブエージェントの活用方法の改善を提案します

コンテキスト予算の管理

振り返り中は、コンテキストの使用量を監視し、上限超過を防ぎます。

予算のしきい値

• スキルの指示：およそ 6～8K トークン（このファイルと自動読み込みされるコンテキスト）
• 小さなログファイル：ファイルあたり 2～5K トークン
• 大きなログファイル：すべて読み込む場合は 10～50K トークン以上
• Git の差分：大規模な変更では 5～20K トークン
• ユーザーとの会話：変動します（2～10K トークン）

残りの予算に応じた適応型戦略

予算が多い場合（残り 100K トークン超）：

• 包括モードを安全に使用できます
• 2000 行未満であれば、ログ全体を読み込みます
• Git の差分をすべて含めます
• 必要に応じて、session-analytics.md から詳細なメトリクスを読み込みます

予算が中程度の場合（残り 50～100K トークン）：

• 既定では標準モードを使用します
• ログを読み込む前に要約します（bash による抽出を使用）
• 重要なファイルのみ、Git の差分を選択的に確認します
• 拡張コンテキストの読み込みは省略します

予算が少ない場合（残り 50K トークン未満）：

• セッションの規模にかかわらず、クイックモードを強制的に使用します
• bash のみでログを要約します（全体は読み込みません）
• Git の統計情報のみを使用し、差分は確認しません
• ユーザーに「利用できるコンテキストが限られているため、重要な項目に絞って分析します」と警告します

コンテキストを保持する方法

1. 抽出して破棄：大きなファイルから主要なメトリクスを取り出し、冗長なソースはすぐに破棄します
2. 早めに統合：作業を続ける前に、簡潔な要約（最大 200 行）を作成します
3. 段階的に詳細化：まず概要を把握し、ユーザーが関心を示した箇所のみ詳しく調べます
4. 部分的なサンプリング：ファイル全体ではなく、代表的なセクションを読み込みます

緊急時のフォールバック

分析中にコンテキストの上限に近づいた場合：

1. データ収集をただちに停止します
2. これまでに収集したデータからレポートを生成します
3. レポートに「コンテキストの制約により分析が限定されました。未確認の具体的な項目：[項目]」と記載します
4. 新しい会話で特定の項目を対象に追加分析することを提案します

避けるべきアンチパターン

しないこと：

• 実際のデータを収集せずに振り返りを作成する
• 曖昧で、実行に移せない提案をする
• 否定的な点だけに注目し、うまくいったことを認めない
• ユーザーが明示した優先事項や目標を無視する
• 重要な洞察が埋もれるほど長いレポートを作成する
• コンテキストや目標を把握せずにセッションを分析する

すること：

• セッションデータから得られる具体的な証拠に基づいて分析する
• 実装方法のガイダンスを添えて、具体的で実行可能な提案をする
• 成果を認めながら、改善の機会も示す
• ユーザーの優先事項に沿った提案をする
• 重要な洞察を目立つ形で示した、簡潔なレポートを作成する
• 効果を分析する前に、セッションのコンテキストを把握する

プラグイン間の情報補完

関連する Bitwarden プラグインがインストールされている場合、振り返りに専門的な分析が加わります。

セキュリティを考慮した振り返り（bitwarden-security-engineer plugin）

セッションから git の差分を収集した後：

• コミット済みの認証情報をスキャンする → セッションの git 差分に対して Skill(detecting-secrets) を有効化し、シークレットが誤ってコミットされていないか警告します
• 新しいコードのセキュリティ態勢を評価する → セッションで認証、暗号化、または入力処理のコードが追加された場合、Skill(analyzing-code-security) を有効化し、振り返りレポートで潜在的な脆弱性を指摘します

品質の分類（bitwarden-code-review plugin）

• セッションの変更を影響度別に分類する → Skill(classifying-review-findings) を有効化し、CRITICAL/IMPORTANT/DEBT/SUGGESTED のフレームワークを使ってセッションの変更を分類します。これにより、何に注意すべきかをユーザーが明確に把握できます

これらのスキルは任意です。利用できない場合は、通常の振り返り分析を行ってください。

成功基準

優れた振り返りには、次の要素が必要です。

1. 気づきを与える：ユーザーが自身のワークフローについて新たな発見を得られます
2. 導く：改善に向けた次のステップが明確です
3. 意欲を高める：成功を認めることで、良い習慣の継続を促します
4. 焦点を絞る：優先順位を示し、どこに力を注ぐべきかをユーザーが判断できます
5. 実践を可能にする：今後のセッションでユーザーが応用できるフレームワークやパターンを提供します

レポートの保存

ディレクトリ：${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/

ファイル名の形式：YYYY-MM-DD-session-description-SESSION_ID.md

• 時系列で並べ替えられるよう、ISO 日付形式（YYYY-MM-DD）を使用します
• 説明は短く（3～5 語）、ハイフンで区切ります
• 追跡可能性を確保するため、ログファイルのセッション ID を含めます

パスの例：${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/2025-10-23-authentication-refactor-3be2bbaf.md