claude-code-audit

Claude Code の監査

これは何ですか

ユーザーの Claude Code セッションから大規模なサンプルを規律ある方法で監査し、大きな変化をもたらす改善策を見つけるためのフレームワークです。ワークフローを磨き上げるだけの20個ではなく、ワークフローを一変させる2〜3個の改善策を見つけます。

「ワークフローを改善するには？」と尋ねられたとき、よくある対応は、些細な提案を長々と並べることです。そのような出力は、役に立たないどころか有害です。耳当たりのよい雑音に、本当に効果のある改善策が埋もれ、ユーザーは何も実行しません。このスキルは、そうした結果を防ぐためにあります。

保証すること

この監査を終えるまでに、次のものを作成します。

1. 優先順位を付けた短いレポート — 実際に効果をもたらす少数の指摘と、定量化された根拠。
2. 実装案 — 上位の推奨事項に向けて、すぐにインストールできるスキル、CLAUDE.md のルール、フックスクリプト、または設定の差分。提案だけではなく、実際の実装案です。
3. 監査の記録 — 抽出したデータ、サンプリングしたセッションの一覧、サブエージェントの調査結果。これにより、ユーザーは統合結果を検証し、後から見直せます。

指摘だけを作成して監査を終えた場合、それは失敗です。

大きな変化と些細な改善 — 常にこの違いを意識してください

些細な改善	大きな変化
「スキル X をもっと頻繁に使うとよいでしょう」	「このようなプロンプトでは、スキル X は一度も起動しません。実際に使っている表現が説明に含まれていないからです。新しい説明はこちらです。」
「テストのスタイルについて、Claude をよく修正しています」	「30日間で、同じ修正を14回しています。根本的なパターンは、あなたが統合テストを望んでいるのに、Claude がユニットテストをデフォルトにしていることです。修正の繰り返しをなくす CLAUDE.md の段落案はこちらです。」
「もっと早い段階でテストを追加することを検討してください」	「60件のセッションのうち19件で、『後からテスト』→『リグレッションを修正』→『別のリグレッションを修正』というループが発生しており、平均35分、80kトークンを消費しています。既存のテストスクリプトを実行するコミット前フックを導入すれば、このループを防げます。」

左の列は観察です。右の列は、根本原因の診断、解決策、根拠を示しています。作成するのは右の列です。

セッションデータの保存場所

• ルート：~/.claude/projects/<encoded-project-path>/<session-id>.jsonl
• 各行は1件のイベントです：user、assistant、attachment（フックの結果）、system、file-history-snapshot、last-prompt。
• ユーザーの ~/.claude/ には、グローバルな CLAUDE.md、スキル、設定、フックがあります。統合時にこれらと照合します。
• JSONL のスキーマと重要なフィールドについては、references/session_format.md を参照してください。

セットアップ — 作業ディレクトリ

開始前に、SKILL_DIR と AUDIT_DIR を設定します。

• SKILL_DIR=~/.claude/skills/claude-code-audit（スクリプトの保存場所 — 変更しないでください）
• AUDIT_DIR=~/claude-audit/<date>（監査出力の保存場所 — 実行ごとに新しいサブディレクトリを作成するか、ユーザーが指定したパスを使用してください）

以下の python $SKILL_DIR/scripts/... の実行では、これらが設定済みであることを前提とします。任意の cwd から実行できます。スクリプトには絶対パスを渡してください。ステージ1の前に AUDIT_DIR を作成します。

5つのステージ

進捗をユーザーが確認できるよう、これらのステージの TaskList を作成します。これは長時間にわたる分析で、サンプルの規模に応じて20〜60分かかります。

ステージ1 — インベントリ

python $SKILL_DIR/scripts/inventory.py --out $AUDIT_DIR/inventory.json

すべてのセッションをカタログ化します。パス、プロジェクト、タイムスタンプ、サイズ、おおよそのメッセージ数・ターン数・ツール呼び出し数、トークンの合計、バージョン、Git ブランチを記録します。低コストで、決定論的です。出力される概要を読みます。

ステージ2 — サンプリング

python $SKILL_DIR/scripts/sample.py --inventory $AUDIT_DIR/inventory.json --count 60 --days 60 --out $AUDIT_DIR/sample.json

新しいセッションを重視しつつ、プロジェクトやセッションの規模に偏りが出ないよう、層化サンプリングします。分布を表示します。サンプルの概要を1文でユーザーに伝えます（「60件のセッション：直近2週間から40件、それ以前から20件。X個のプロジェクトにまたがっています」）。ユーザーから異議がなければ、そのまま進めます。

ステージ 3 — 抽出

python $SKILL_DIR/scripts/extract.py --sample $AUDIT_DIR/sample.json --out $AUDIT_DIR/extracted/

サンプリングした各セッションについて、以下を含む JSON を書き出します。ユーザープロンプト（コマンドのラッパーではなく、実際のもの）、アシスタントによるツール使用の順序、エラー数、スキル／コマンドの呼び出し、トークン使用量、おおよその経過時間、最初のプロンプトの意図、「修正」マーカー（失敗したツールの後に続くユーザーメッセージ、または修正を示す表現を使ったユーザーメッセージ）、セッションの結果を示す手がかりです。

次に、集計します。

python $SKILL_DIR/scripts/extract.py --aggregate $AUDIT_DIR/extracted/ --out $AUDIT_DIR/aggregate.json

これで定量的な情報が揃いました。ざっと目を通し、意外な点があれば印を付けます。意外な点は手がかりになります。

ステージ 4 — 並列サブエージェントによる詳細な読み込み

スクリプトでは、フラストレーション、混乱、堂々巡り、ブレークスルーの瞬間、メンタルモデルの不一致といった定性的なシグナルは見つけられません。これらはサブエージェントに任せます。

サンプルを 8～10 セッションずつのバッチに分けます。すべてのバッチを1 つのメッセージ内で並列に（順番ではなく）実行します。各バッチについて、references/subagent_brief.md の説明に加え、以下を渡して Explore サブエージェントを起動します。

• 担当バッチ内のセッションファイルパスの一覧。
• グローバルなコンテキストを把握できるよう、$AUDIT_DIR/aggregate.json のパス。
• 分析の視点として使う $SKILL_DIR/references/step_change_patterns.md のパス。
• 相互参照用に、ユーザーが現在使用しているスキルディレクトリ（~/.claude/skills）、CLAUDE.md（~/.claude/CLAUDE.md）、settings.json（~/.claude/settings.json）。
• 読みやすいトランスクリプトを取得するには python $SKILL_DIR/scripts/render.py <session-path> を使うよう指示します。render.py を使うことが重要です。生の JSONL ではコンテキストが溢れてしまいます。

各サブエージェントは、調査結果を構造化 JSON で返します。$AUDIT_DIR/batch-<N>-findings.json に保存します。

ステージ 5 — 統合

ここで、このスキルの真価が発揮されます。

1. すべてのバッチ調査結果ファイルと集計データを読みます。
2. バッチをまたいで調査結果をクラスタリングします。1 つのセッションにしか現れないパターンはノイズですが、8 つのセッションに現れるパターンはシグナルです。
3. クラスターを頻度 × 深刻度 × 改善の波及効果で順位付けします。波及効果とは、修正によって影響を受ける今後のセッション数です。特定のワークフローだけに役立つ修正には波及効果がありませんが、すべてのコーディングセッションの摩擦を取り除く修正にはあります。
4. references/step_change_patterns.md をフィルターとして適用します。上位のクラスターは小幅な改善でしょうか、それとも大きな変化でしょうか。小幅な改善なら、根本にある原則を見つけて、より大きな改善へ引き上げるか、除外します。
5. references/report_template.md を使ってレポートを作成します。
6. 修正案を作成します。 最上位の推奨事項にはすべて、修正案の説明ではなく、実際の草案を用意します。新しいスキルなら、SKILL.md を書きます。新しいルールなら、一字一句そのままの文章を書きます。新しいフックなら、スクリプトを書きます。設定変更なら、差分を示します。

絶対に守ること

修正案を作成します。 「ユーザーは X 用のスキルを追加するとよいでしょう」と書きそうになったら、立ち止まってスキルを書いてください。「Y に関する CLAUDE.md のルールが役立つでしょう」と書くなら、立ち止まって正確な段落を書いてください。このスキルが行うことの中で、これが最も重要です。省略すれば、監査に価値はありません。

網羅性より簡潔さを優先します。 ユーザーが実行に移す 3 項目のレポートは、ざっと読まれて忘れられる 30 項目のレポートに勝ります。波及効果のないものはすべて削ってください。

形容詞ではなく数値を使います。 「頻繁に」「よく」「ときどき」は事実を歪めます。「60 セッション中 17 件」や「サンプル全体で 23 回の修正」と書いてください。スクリプトで正確な数を取得できるので、それを使います。

セッションを引用します。 レポート内のすべての主張について、根拠となる具体的なセッション ID を示します。ユーザーがセッションを開いてパターンを検証できるようにします。

ユーザーではなく Claude を監査します。 ユーザーが同じことを何度も修正しているなら、ユーザーのプロンプトではなく、Claude のデフォルト設定がそのユーザーに合っていないのです。プロンプトの書き方をユーザーに責めないでください。修正を強いる Claude の振る舞いのパターンを見つけて、Claude の設定に修正を加えてください。

よくある失敗パターン

• 観察結果の羅列。 優先順位を付けずに40個のパターンを列挙します。対策：思い切って削ります。
• 自画自賛。 Claude がうまくできたことしか説明しません。対策：失敗、苛立ち、同じことの繰り返しを意識的に探します。
• 曖昧な提案。 「X の改善を検討します。」対策：改善案を自分で作成するか、含めないようにします。
• プロジェクトへの視野狭窄。 最も活発なプロジェクトについてしか報告しません。対策：サンプルには多様性を持たせ、レポートにも反映します。
• メタレベルの見落とし。 セッション内の振る舞いだけに注目し、セッションをまたぐパターン（セッションが早期に終了する、毎回同じコンテキストを再構築するなど）を見落とします。対策：references/step_change_patterns.md ではこうした点が明示されています。統合の前に読み直してください。

出力レイアウト

$AUDIT_DIR/
  inventory.json            # stage 1
  sample.json               # stage 2
  extracted/<session>.json  # stage 3
  aggregate.json            # stage 3
  batch-<N>-findings.json   # stage 4
  report.md                 # stage 5 — the deliverable
  drafts/                   # stage 5 — the implementations
    skills/<skill-name>/SKILL.md
    claude-md-additions.md
    hooks/<hook-name>.sh
    settings-diff.json

ユーザーが別途指定しない限り、$AUDIT_DIR はデフォルトで ~/claude-audit/<YYYY-MM-DD>/ に設定します。すべてをディスク上に保存するため、ユーザーは再実行、検証、共有ができます。

参照ファイル

• references/session_format.md — JSONL スキーマと各フィールドの意味
• references/step_change_patterns.md — 活用ポイントの分類体系。統合の観点となります
• references/report_template.md — 必須の出力構成
• references/subagent_brief.md — ステージ4のサブエージェントに渡すプロンプト