Harness retro
過去のセッションで問題が発生した箇所を特定し、同じ問題が再発しないように設定を変更します。すべての発見はトランスクリプト内の証拠に基づく必要があります。ユーザーの承認なしに変更を適用しないでください。
1. トランスクリプトのマイニング
マイナーはこのファイルと同じディレクトリにある stdlib のみを使用したスクリプトです。-I フラグを付けて実行し、出力をセッションスクラッチパッド、またはスクラッチパッドがない場合は一時ディレクトリに書き込みます:
python3 -I <このスキルのベースディレクトリ>/scripts/mine.py [PATH] [--since 30d] --out <scratchpad>/retro.json
- PATH なしの場合、カレントワーキングディレクトリのプロジェクトをマイニングします。別のプロジェクトをマイニングするには、そのワーキングディレクトリのパスを指定するか、
~/.claude/projects内のフォルダ名を--project=<key>で指定します。キーは-で始まる可能性があるため、=形式を使用してください。 - ユーザーが期間を指定した場合は
--sinceを使用します。出力が切り捨てられてさらにデータが必要な場合にのみ--max-bytes（デフォルト 40000）を増やしてください。 - ユーザーがすべてのプロジェクトについて尋ねた場合は、
~/.claude/projects内のフォルダごとにスクリプトを実行し、最も摩擦の多いプロジェクトを確認します。
スクリプトは1行のサマリーを出力します。スキャンしたセッションが少ないかゼロの場合は、その旨をユーザーに伝えてください。Claude Code は cleanupPeriodDays（デフォルト 30）の経過後にトランスクリプトを削除するため、古い履歴は存在しない可能性があります。将来より深いレトロスペクティブを行うために、この設定値を上げることを提案してください。
2. ヒットを読む
JSON には、摩擦スコアでランク付けされたセッションのリストが含まれています。各ヒットには、signal、score、ts、prior_prompt（ユーザーが要求した内容）、recent_actions（ヒット直前のClaudeの最後のツール呼び出し）、および user_reaction または detail が含まれています。
シグナル（価値の高い順）:
user_correction: ユーザーが反論した。スコア5以上は強いフラストレーションまたは繰り返し（「まだ」、「もう一度」、「言っただろ」、罵倒など）を示します。edit_revertおよびedit_churn: Claudeが同じファイルを行ったり来たり編集した。tool_error_streak: Claudeが同じ失敗に繰り返し遭遇した。interrupted: ユーザーがClaudeを途中で停止した。通常、間違った方向に進んでいたことを意味します。permission_denied: Claudeがユーザーまたは分類器によってブロックされた何かを試みた。self_retraction: Claudeがエラーを認めた。このシグナルはノイズが多いため、補足証拠としてのみ使用してください。
正規表現は大まかです。「don't」が通常の指示に含まれている場合や、ネットワークエラー後の「try again」など、誤検出は除外してください。ヒットが曖昧な場合は、その周辺のトランスクリプトを開いて確認します。ファイルは ~/.claude/projects/<key>/<session>.jsonl です。タイムスタンプでgrepし、その前後の数行を読んでください。トランスクリプト全体を読まないでください。
3. パターンにグループ化する
実際のヒットを繰り返し発生するパターンにグループ化します。パターンとは、Claudeが間違った動作をする1つの根本原因です。例：「承認されたアセットライブラリを使用せずに新しい画像を生成する」、「新しいバージョンを作成する代わりに現在のバージョンを編集する」、「ビルド出力を確認せずに変更が表示されたと主張する」。各パターンについて、以下を記録します:
- 発生頻度と、それが発生したセッション数。
- セッションタイトルと日付を含む、ユーザーからの短い引用を2、3件。
- 根本原因。次のいずれかを選択します: 知識不足、存在するが無視されたルール、デフォルトのワークフローの問題、検証不足、ツールまたは権限のギャップ。
単一のインシデントは、ユーザーが明らかに怒っている場合、またはコストが高い場合（例: 破壊的または作業の損失）にのみカウントします。
4. 現在のハーネスを確認する
何かを提案する前に、現在何が設定されているかを読んでください:
~/.claude/CLAUDE.md、プロジェクトのCLAUDE.md、およびネストされたものがあればそれら。~/.claude/settings.json、およびプロジェクトの.claude/settings.jsonと.claude/settings.local.json（フック、権限）。- プロジェクトのメモリディレクトリ
~/.claude/projects/<key>/memory/とそのMEMORY.md。 ~/.claude/skills/とプロジェクトの.claude/skills/内のスキル。
パターンがすでにClaudeに無視されたルールでカバーされている場合、同じルールを再度追加しても効果はありません。ルールをより具体的にし、それが認識される場所に配置するか、より強力なメカニズムに移行してください。
5. 修正を選択する
各パターンに対して、実際に機能する最も軽量なメカニズムを使用してください:
| 根本原因 | 修正方法 |
|---|---|
| Claudeが知らなかったプロジェクトの事実 | プロジェクトメモリディレクトリ内のメモリファイル。フロントマターに name、description、metadata.type を含め、本文に なぜ: と 適用方法: を記述し、MEMORY.md に1行のポインターを追加します。既存のメモリを重複させるのではなく更新します。 |
| このリポジトリの恒常的なルール | プロジェクトの CLAUDE.md |
| すべてのプロジェクトのルール | ~/.claude/CLAUDE.md |
| 何度も破られ、スクリプトでチェックできるルール（フォーマット、禁止文字列、コミット前の必須コマンドなど） | settings.json 内のフック。利用可能であれば update-config スキルを使用します。 |
| 安全なコマンドに対する繰り返しの権限プロンプトまたは拒否 | 許可リストエントリを提案するか、利用可能であれば fewer-permission-prompts スキルを提案します。破壊的なコマンドに対して権限を拡大しないでください。 |
| 何度も間違って実行されるマルチステップワークフロー | 新しいスキルまたは既存のスキルの編集（利用可能であれば skill-creator を使用）。 |
| Claude Code の製品バグ | レポートにその旨を記載します。ハーネスでの修正はありません。 |
ルールは、ファイル、アセットパス、コマンド、バージョン名など、具体的でチェック可能な指示として記述します。「画像に注意する」は曖昧すぎて実行できません。
6. 報告と承認を得る
パターンごとに1つのセクションを、コストが高い順に提示します。各セクション:
- パターン（1行）。
- 証拠: 件数、セッション、日付付きの2～3件の短い引用。
- 根本原因。
- 提案する変更: 対象ファイルと正確なテキストまたは差分。
次に、どの変更を適用するかを尋ねます。パターンごとに1つのオプションを持つ multiSelect AskUserQuestion が適しています。承認された変更のみを適用し、変更内容と場所をリストアップします。
ルールの記述
CLAUDE.md、メモリ、またはスキルに書き込むものはすべて、ユーザー自身の CLAUDE.md ファイルにあるトーン、禁止ワード、帰属ルールなどの記述ルールに従う必要があります。短く具体的に保ってください。トランスクリプトからの引用には、ユーザーが貼り付けたシークレットが含まれている可能性があります。マイナーは一般的なキー形式を編集により削除しますが、テキストをファイルにコピーする前に確認してください。