アシスタントの作業を遅らせるファイル

アシスタントにとって作業しにくいファイルというものがあり、その原因はたいていコードそのものではありません。ドキュメントに書かれたパスが移動していたり、安全に編集できない生成ファイルだったり、エージェントが持っていない権限を必要とするディレクトリだったりします。どのファイルがそうなのか、これまで手を焼いてきた経験からおおよそ見当はついているはずです。Pathruleはそれを正確に記録します。

記録される内容

アシスタントが呼び出したツールが失敗すると、ツールの種類、作業対象のファイル、失敗の種類を表す短いコードの3つが保存されます。コードはfile_not_found、permission_denied、timeout、rate_limit、token_limit、syntax_errorのいずれかで、失敗は確かに起きているもののどれにも該当しない場合はunknownになります。

記録されるのはこれだけです。コマンドも、エラーメッセージも、ファイルも保存されません。パスに紐づく件数とコードだけです。Cloudワークスペースでは、これらの件数とコードはワークスペースとともにPathrule Cloudに保存されます。

失敗は報告されるのではなく、観測されます。Pathruleのツールフックが呼び出しそのものを監視するため、アシスタントが自分のミスに気づくか、セッションを覚えているか、後から何かを呼び出すかには左右されません。何も言わずに失敗して次に進むアシスタントも、失敗を明言するアシスタントも、まったく同じように記録されます。呼び出しにかかった時間も同じ観測の一部として記録されるため、応答しなくなったコマンドと拒否されたコマンドを区別できます。これはPathruleのツールフックがあるクライアント(Claude Code、Codex、Cursor、GitHub Copilot)に適用されます。WindsurfにはPathruleのフックがないため、そのツール呼び出しはこの方法では観測されません。

パスは最初にワークスペース相対の形式に正規化されます。これは見た目以上に重要です。ノートPC上の絶対パスは/Users/<name>/…となり、このユーザー名を共有ナレッジに載せるべきではありません。また相対パスにすることで、同じファイルがマシンごとに別々に集計されることなく、チーム全体で正しくまとめて集計されます。

記録の使い道

作業が行き詰まる場所の把握。 失敗は時間の経過とともにファイル、ツール、コードごとに集計されます。得られるのはグラフではなく、アシスタントが最も多く失敗しているファイルとその失敗の種類を並べた短いリストです。file_not_foundに何度も登場するファイルは、たいていどこかの指示に古いパスが残っていることを示しています。syntax_errorに出てくるファイルは、たいてい本当に編集しにくいファイルです。permission_deniedに出てくるファイルは、たいてい一度直せば済むセットアップの問題です。

検索の学習。 あるターンでPathruleからナレッジを受け取ったにもかかわらず失敗が起きた場合、そのナレッジはネガティブシグナルを受けます。失敗の種類によっては、通常の失敗よりも重く扱われます。そうした失敗は、ガイダンスがアシスタントを行けない場所へ導いたことを意味する場合が多いからです。このシグナルは検索が適切なナレッジを見つける仕組みで説明しているループに組み込まれます。うまくいかなかったターンに繰り返し登場するナレッジは、誰かがレビューしなくても、徐々に選ばれにくくなります。

シグナルで捉えられないこと

この部分は使っているアシスタントによって異なり、一様ではありません。

ファイル系ツールは失敗を正しく報告します。失敗した読み取り、編集、書き込みはメッセージとともに届き、分類され、正しいファイルに紐づけられます。重要なのはこのケースです。件数を実際の対処につなげられるのは、ファイルパスがあってこそだからです。

シェルコマンドは報告されないことがよくあります。終了コードをまったく報告しないアシスタントもあり、その場合は失敗したコマンドも成功したコマンドも同じように見えます。Pathruleは出力テキストから失敗を推測しません。検索結果に「no such file or directory」という文字列が含まれるのはごく正当なことですし、誤った失敗がファイルに紐づくのは、記録が欠けているよりも悪いからです。アシスタントが失敗を報告しない場合は何も記録されず、報告された失敗がどのルールにも該当しない場合は、推測ではなくunknownというコードになります。

記録が行わないこと

失敗の記録によってツール呼び出しがブロックされることはなく、アシスタントのコンテキストに表示されることもありません。失敗はコードベースに関する事実であり、事後に記録されるものです。アシスタントに許可されている操作は変わらず、記録の多いファイルが立ち入り禁止として扱われることもありません。ここに個人に紐づくスコアは一切ありません。記録の対象はファイルであり、誰がそのファイルで作業していたかではありません。