AIチュートリアル

harness-mapでClaude Codeハーネスをマッピング・監査

このチュートリアルでは、1つ以上のClaude Codeワークスペースをスキャンし、任意のエージェントプローブを実行し、インタラクティブなハーネスマップを生成して、機密性の高い設定データを保護しながら成熟度評価を解釈する方法を説明します。

2026年10月2日約17分で読了

harness-map の概要

harness-map は Claude Code を取り巻く設定を読み取り、1つの視覚的な構成マップにまとめます。この周辺設定はハーネスと呼ばれ、CLAUDE.md などの指示ファイル、自動メモリ、MCP サーバー、スキル、権限、フック、ルール、関連設定が含まれます。

有効なハーネスは、Claude Code を起動するフォルダーや、新しいエージェントの起動方法によって変わります。メインセッション、フォーク、サブエージェント、Explore エージェントや Plan エージェント、チームメイト、claude -p の呼び出しでは、異なる情報が渡される場合があります。harness-map は、選択した各開始フォルダーと起動方法について、こうした違いを可視化します。

このプロジェクトは Python 3 を使用し、追加の Python パッケージを必要としません。スクリプトは設定を変更せずに読み取り、構造化された harness.json ファイルを生成し、ブラウザーで表示できる harness-map.html レポートを作成します。

主な機能

フォルダー別分析: --cwd を繰り返して、必要な数の開始ディレクトリを比較できます。
エージェントへの引き継ぎの可視化: 各コンポーネントが親セッションから継承されたのか、ファイルから再度読み込まれたのか、新しいエージェントに渡されないのかを確認できます。
ルールの相互作用分析: 置換、拒否を優先したマージ、すべてのルールの実行、優先順位なしの連結、1つのルールだけの選択という5つの処理パターンを調べられます。
リスクと注意が必要なケース: フォルダーによって自動メモリが分割される状況や、チーム機能によって権限モードが新しいエージェントに渡される状況などを特定できます。
成熟度評価: 6つのハーネス分野について、六角形のチャートでレベル1から5までを確認できます。
プライバシーに配慮した出力: 指示本文、環境変数の値、トークン、コマンド引数などの機密情報を省略し、構造メタデータのみを記録します。
持ち運び可能な表示: 他の人の harness.json をレポート画面に貼り付けて、そのマップを再描画できます。

開始前の準備

Python 3、Git、そして通常のユーザーアカウントに属する Claude Code の設定へのアクセス権が必要です。pip によるパッケージのインストールは必要ありません。

harness-map は Claude Code を実行するユーザーと同じユーザーで実行してください。sudo は使用しないでください。管理者として実行すると有効なホームディレクトリが変わり、別のユーザーの設定が露出する可能性があるため、スクリプトはその方法での実行を拒否します。

普段 Claude Code を起動する実際のディレクトリを選択してください。親ディレクトリをスキャンしても、子プロジェクト内で起動した場合に適用されるすべての設定は確認できません。設定は開始フォルダーごとに上位へ向かって解決されるためです。

インストール

リポジトリをクローンして、そのディレクトリに移動します。

git clone https://github.com/Dominic-DK/harness-map.git
cd harness-map

github.com/Dominic-DK/harness-map でプロジェクトを確認できます。プロジェクトは MIT ライセンスで配布されています。

ステップ1: Claude Code のハーネスをスキャンする

比較したいワークスペースごとに --cwd 引数を1つ指定して、harness-map.py を実行します。次のコマンドは2つの例示フォルダーをスキャンし、結果を harness.json に書き込みます。

python3 harness-map.py --cwd ~/work/a --cwd ~/work/b -o harness.json

--cwd は必要な回数だけ繰り返せます。省略した場合、harness-map は現在のディレクトリだけをスキャンします。

python3 harness-map.py -o harness.json

初回スキャンでは設定ファイルを読み取り、それらのファイルと会話履歴の集計件数から実行できるチェックを行います。

会話履歴の期間を変更する

デフォルトの集計期間は30日です。異なる観測期間が必要な場合は --days を使用します。たとえば、次のコマンドは90日分を使用します。

python3 harness-map.py --cwd ~/work/a --days 90 -o harness.json

会話の分析ではイベント数だけを数えます。会話本文、コマンドの内容、ファイルの内容が結果にコピーされることはありません。

ステップ2: エージェントのプローブ計画を出力する

一部のチェックでは、静的な設定を調べるだけでなく、エージェントに制御されたテストを実行させる必要があります。プロジェクトが提供する手順と安全規則を次のコマンドで出力します。

python3 harness-map.py --probe-plan

エージェントにチェックを実行させる前に、この出力を読んでください。プローブ用のコマンドを独自に考えず、生成された指示に従ってください。チェックには、設定の読み取り、関連する履歴イベントの集計、一時ディレクトリ内での動作テストが含まれる場合があります。

ステップ3: プローブを実行またはスキップする

エージェントに出力されたプローブ計画を実行させ、その観察結果を probes.json に保存します。各プローブには、実行した内容と、裏付けとなる観察結果が記録されます。

このステップは任意です。プローブを実行しない場合、該当項目は未チェックとして表示され、レベル計算から除外されます。実際に観察していない動作を手動で成功扱いにすることは避けてください。特にレベル5のチェックでは注意が必要です。

ステップ4: プローブ結果を統合する

同じ開始フォルダーを指定して再度スキャンし、--probes probes.json を追加します。

python3 harness-map.py --cwd ~/work/a --cwd ~/work/b --probes probes.json -o harness.json

同じ --cwd のセットを使用すると、最終計算の対象を初回スキャンで扱ったワークスペースに揃えられます。

ステップ5: レポートを作成して開く

完成した JSON ファイルから HTML レポートを生成します。

python3 build.py harness.json

macOSでは、次のコマンドで開きます:

open harness-map.html

Linuxでは、次を使用します:

xdg-open harness-map.html

Windowsでは、次を使用します:

start harness-map.html

ハーネスマップの読み方

レポートで開始フォルダーと起動方法を切り替えると、それぞれの状況における実効的なハーネスを確認できます。各コンポーネントについて、レポートでは3つの受け渡し状態を区別します:

新しいエージェントが親セッションから直接受け取る。
新しいエージェントがファイルから再度読み込む。
コンポーネントが新しいエージェントに渡されない。

この比較により、同じリポジトリを使用する2つのエージェントの動作が異なる理由を説明できます。たとえば、サブエージェントはメインセッションで利用できるすべての情報を受け取るとは限りません。また、特定の開始フォルダーに関連付けられた設定は、別の場所では適用されない場合があります。

重複するルールを理解する

レポートには、重複するルールがどのように解決されるかも表示されます。設定の種類によって、後の値が別の値を置き換える場合、拒否を優先してルールが結合される場合、一致するすべてのアクションが実行される場合、優先順位なしでテキストが連結される場合、または1つのオプションだけが選択される場合があります。

指示、権限、またはフックが効果を示さないように見える場合は、これらの相互作用を確認してください。問題はファイルの欠落ではなく、ルールの組み合わせ方にある可能性があります。

成熟度評価を理解する

harness-mapは6つの領域をレベル1からレベル5で評価します:

指示の設計
メモリと場所
ツールのスコープ
予防的なブロック
アクション後の検証と可観測性
委任の設計

利用可能なデータが対応している場合、スクリプトはレベル4までを自動的に計算できます。結果には、どの条件に合格したか、どこで評価が停止したかが記録されます。スコアリングの定義は、harness-map.py内のSCORECARDに保存されています。

レベル5には、実際に観測されたチェックによる証拠が必要です。たとえば、予防的なブロックがレベル5に達するのは、禁止事項によってコマンドが実際に阻止されたことを示す記録がある場合だけです。設定に禁止事項が存在するだけでは不十分です。

設定が存在していても使用されていないように見える場合、評価が下がることもあります。たとえば、選択した履歴期間中に使用されなかったツールや、設定とは異なる権限モードで実行されたセッションなどが該当します。

複数の開始フォルダーをスキャンした場合、表示されるレベルはフォルダーごとのスコアの中央値です。フォルダー数が偶数の場合は、中央の2つの値のうち低い方が使用されます。レポートには最小値から最大値までの範囲も表示されます。

高いレベルが常に優れているとは限りません。harness-mapは、単独で作業するかどうか、下位エージェントを起動する頻度、元に戻すことが難しいコマンドを実行する頻度など、使用パターンから各領域に必要なレベルを推定します。レベル5未満のすべてのスコアを警告するのではなく、推定された必要レベルを下回る領域を強調表示します。

プライバシーと出力の確認

スキャナーはファイルを読み取りますが、設定は変更しません。出力にコピーする情報は意図的に制限されています:

CLAUDE.mdとルールファイルについては、パス、行数、読み取られるタイミングを記録しますが、本文は記録しません。
設定については、権限モード、ルール数、環境変数名を記録しますが、環境変数の値やルールの内容は記録しません。
フックについては、イベント、ソース、実行ファイル名を記録しますが、コマンド引数とパスは省略します。
MCPサーバーについては、名前とソースを記録しますが、コマンド、引数、ヘッダー、トークンは省略します。
パスについては、実際のホームディレクトリの接頭辞を~に置き換えます。

読み取れないファイルはunreadableリストに入れられます。プロジェクトによると、Claude Codeも同じユーザー権限ではこれらのファイルを読み取れません。

出力にはフォルダー名とインストール済みプラグインの一覧が含まれます。共有する前に、harness.jsonとharness-map.htmlの両方を開いて確認してください。

リポジトリの.gitignoreは、harness.jsonとharness-map.htmlをバージョン管理の対象外にするよう設定されています。ただし、コミットする前にステージされたファイルを確認してください。

ワークフローをコーディングエージェントに委任する

Claude Codeや別のコーディングエージェントに、リポジトリの指示に従うよう依頼できます。例のフォルダーを、普段使用する開始ディレクトリに置き換えてください。適切な依頼は次のとおりです:

https://github.com/Dominic-DK/harness-map のREADMEを読み、直接実行の手順に従ってください。
普段の開始フォルダーは ~/work/a と ~/work/b です。
文書化された安全ルールに従ってステップ3のエージェントチェックを実行し、結果を記録してください。
完了したら、ブラウザーで harness-map.html を開き、結果を明確な5文程度で要約してください。

プローブの段階では人間による監督を維持してください。エージェントは--probe-planで生成された正確な安全計画に従う必要があります。

高度なヒント

意味のあるすべてのエントリーポイントをスキャンする

リポジトリのルートをスキャンすれば、ネストされたプロジェクトも対象になるとは限りません。実際にClaude Codeを起動する各ディレクトリを、個別の--cwdとして追加してください。これにより、継承された指示、メモリの境界、利用可能なツールをより有用に比較できます。

作業に合った観測期間を選ぶ

デフォルトの30日間は最近の活動に適していますが、使用頻度の低いツールにはより長い期間が必要な場合があります。未使用の証拠は成熟度スコアに影響する可能性があるため、--daysは意図を持って使用してください。

設定と検証済みの動作を分離する

ファイルベースの検出結果は、意図された設定の証拠として扱い、実行時に制御が機能することの証明とは見なさないでください。フック、制限、その他の動作が実際に適用されているという確信が必要な場合は、オプションのプローブを使用します。

生の設定を公開せずにレポートを比較する

レビュー済みの harness.json が送られてきた場合は、レポートの貼り付け欄を使って再現します。機密性の高い値は省略されていますが、プロジェクト名、フォルダー名、プラグイン名は残っているため、双方でまずJSONを確認してください。

Pythonを利用できない場合は代替手段を使う

Python 3を利用できない場合は、PROMPT.md の内容をエージェントにコピーします。エージェントは設定を直接読み取り、同じ形式でJSONを作成し、画面を構築できます。READMEでは、この方法はスクリプトよりも項目の省略や誤カウントが発生しやすいと注意しています。

既知の制限

引き継ぎルールは harness-map.py の SPAWN_RULES に固定されており、実際のライブセッションの観察結果から導出されたものではありません。
READMEによると、これらのルールは2026年10月2日に確認されたClaude Code 2.1.287のドキュメントに基づいています。それ以降のバージョンでは動作が異なる場合があります。
引用元は、公式のサブエージェント、エージェントチーム、メモリのドキュメントです。
このプロジェクトでは、ドキュメントに「サブエージェントは自動メモリを読み取らない」と記載されている一方、作者の環境ではメモリ一覧がサブエージェントに渡されたと報告されている点を相違点として挙げています。レポートでは、これをドキュメントと観察結果の違いとして示しています。
--agents や --permission-mode など、コマンドラインでのみ指定する設定はファイルに保存されないため、スキャナーでは検出できません。
インストール済みのプラグインについては、スキャナーはプラグインのインストールディレクトリ内で見つかった最新バージョンを読み取ります。

まとめ

harness-mapは、プロジェクトやエージェントの起動モードをまたいで、Claude Codeが実際に受け取る設定を把握するための実用的な方法を提供します。まず意味のある作業ディレクトリをすべてスキャンし、必要に応じて記載されたプローブを実行し、それらの証拠を使ってデータを再構築し、HTMLレポートを生成します。可視化と成熟度評価を使って設定上の不足を見つけますが、生成されたファイルは共有前に確認し、記載された引き継ぎルールはバージョンに依存するものとして扱ってください。