Claude Codeとの対話、空回りしていませんか？

Claude Codeを使っていて、こんな「もどかしさ」を感じたことはないでしょうか。

「要件を渡しそびれて、何度も修正指示を出している……」
「『そのファイルじゃない』と指摘したのに、また同じ間違いをされた」
「エラーログを見せたはずなのに、修正が的確じゃない」

私もClaude Codeで開発を進める中で、こうした「手戻りの多さ」に課題を感じていました。
肌感覚として「今日は調子が悪いな」「指示が悪かったかな」と感じることはあっても、「どれくらい非効率的で、どう改善すればいいか」までは掴めていなかったのです。

開発のPDCAを回すには、まず現状を数値化する必要があります。
そこで今回は、Claude Codeのフック機能を活用し、「何ターンで正しい指示を完結できているか（＝修正率）」を可視化する仕組みを作ってみました。

サマリ

Claude Code開発の生産性を阻害する要因を、修正率という定量指標で可視化
Hooks機能（UserPromptSubmit/PostToolUse）で、ユーザーの意図とツール実行結果を自動記録
3つのボトルネックパターン（Ping-Pong Loop、Context Miss等）を自動検出し、改善策を提示

自作ツールの概要

作成したのは、開発プロセスをモニタリングするプロトタイプです。
claude-code-monitoring-prototype

コンセプトは「タスク完了までに、人間が何回『修正』を命じたか」を記録することです。
これを実現するために、Claude CodeのHooksを利用します。

2つの重要なHooks

今回利用するのは、以下の2つのイベントです。

UserPromptSubmit: ユーザーがプロンプトを送信した瞬間をキャッチ
PostToolUse: Claudeがツール（コマンド実行やファイル操作）を行った結果をキャッチ

これらを組み合わせることで、以下の指標を計測可能にします。

修正率（Correction Rate）: ユーザーの発言のうち、何%が「手戻り・修正」だったか
ツールエラー率: Read/Bash等のコマンドがどれくらい失敗しているか
Turns Per Task（TPT）: 1つのタスク完了にかかった平均ターン数

システムの全体像は以下の通りです。

実装のポイント：stdin/stdoutでのデータ連携

Claude CodeのHooksは、イベント駆動型のアーキテクチャで動作します。
設定は ~/.claude/settings.json に記述するだけで有効化できます。

settings.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/telemetry_hook.py"
          }
        ]
      }
    ]
    // ... (PostToolUseも同様に設定)
  }
}

スクリプト側では、標準入力（stdin）からJSONを受け取り、処理を行います。

データの肝：「修正」か「新規指示」か？

単に発言回数を数えるだけでは意味がありません。「機能追加（ポジティブな指示）」と「手戻り（ネガティブな修正）」を区別する必要があります。
そこで、ユーザーの入力を4つのカテゴリに自動分類するロジックを組み込みました。

カテゴリ	意味	例	分類ロジック
INSTRUCTION	新規タスク	"認証機能を追加して"	デフォルト
CORRECTION	修正・否定	"エラーが出てる"、"違う、そのファイルじゃない"	否定語、エラーログの引用を検知
REFINEMENT	仕様詳細化	"ついでにログも出して"	（文脈解析が必要だが今回は簡易判定）
CONFIRMATION	承認	"yes", "ok", "進めて"	短い肯定の言葉

特に重要なのがCORRECTION（修正）の検知です。
「違う」「error」「直して」といったキーワードや、バッククォートで囲まれたエラーメッセージの引用を正規表現で検知し、「これは手戻りである」と判定します。
これにより、単なる承認（CONFIRMATION）を除外した、純粋な「手戻り率」が算出可能になります。

ボトルネックの特定：データから見えてきた「3つのパターン」

収集したデータを分析すると、Claude Code開発における「詰まりどころ」は、大きく3つのパターンに分類できることが分かりました。

1. Ping-Pong Loop（泥沼化）

現象: 3回以上連続でCORRECTIONが発生している。
原因: AIが根本原因を特定できず、対症療法的な修正を繰り返している状態。
対策: 一旦会話をリセットするか、人間がスタックトレースを詳細に読み込ませる。

2. Context Miss（文脈欠損）

現象: ファイルパスに関するCORRECTIONが多い。
原因: プロジェクト構造を理解していない。
対策: CLAUDE.md にディレクトリ構成やアーキテクチャ概要を追記する。

3. Permission Fatigue（承認疲れ）

現象: CONFIRMATION（承認）の発言割合が50%を超えている。
原因: セキュリティ設定が厳しすぎて、すべてのコマンドに「Yes」と言うだけの作業になっている。
対策: allowedTools 設定を見直し、信頼できる操作（ls, cat等）は自動承認にする。

ダッシュボード出力例と分析のヒント

実際にこのツールを使って計測を行うと、以下のようなダッシュボードが出力されます。
（※以下は、課題がわかりやすく出た場合のサンプル出力です）

📊 Claude Code 自律性評価ダッシュボード
================================================================
📈 グローバルメトリクス
   総セッション数        : 3
   総ターン数（有効）    : 24
   修正回数              : 7
   修正率 (Correction Rate)      :  29.17% ⚠️

🛠️  ツール実行分析
   総ツール実行回数          : 145
   ツールエラー回数          : 12
   ツールエラー率            :   8.28% ⚠️

   ツール別実行回数:
     - Read             :   42 回 (2 failures,  4.8%)
     - Bash             :   38 回 (7 failures, 18.4%)
     - Write            :   28 回 (0 failures,  0.0%)
     - Grep             :   25 回 (3 failures, 12.0%)

結果をどう読み解くか？

このサンプルの場合、修正率が約30%（警告レベル）となっています。これは「3回に1回はAIにダメ出しをしている」計算になり、明らかに指示出しのフローに問題があることが読み取れます。

また、Bashツールのエラー率が18.4%と高い点にも注目です。
ここから、「環境構築の手順がAIに伝わっておらず、コマンド実行に失敗して人間が介入している（＝Tool Failure Correction）」という仮説が立ちます。

このように可視化されることで、「なんとなく使いにくい」という感情論ではなく、
「エラーを減らすために、各種インストール手順をCLAUDE.mdに明記しよう」
「Context Missが多いから、必要なファイルと構成をプロンプトの最初に渡そう」
といった、必要な改善アクション（PDCA）が回せるようになります。

おわりに

「AIに任せる」と言いつつ、実際は人間がマイクロマネジメントをしすぎていてはなかなか生産性が上がらないなと思います。
AIが自律的に作業できる範囲を広げるためには、まず「どこでつまずいているか」を客観的に知ることが第一歩だと感じました。

今後はこのデータを元に、最適なプロンプトをAI自身に提案させる機能なども検討しています。
AI駆動開発のプロになるため、まずは「AIとの付き合い方」をハックしてみてはいかがでしょうか。

参考リンク

claude-code-monitoring-prototype
Claude Code 公式ドキュメント