AIセッションが記録するもの

Pathruleがプロジェクトについて得る知見の多くは、ドキュメントからではなく実際の作業から得られます。AIセッションは作業を終えると短い構造化エントリを記録し、このひとつのエントリがほかのいくつもの機能の土台になります。

このページでは、エントリに含まれる内容、意図的に含めていない内容、そしてそのエントリが何に活用されるかを説明します。

記録される内容

各エントリはいくつかの小さなフィールドで構成されます。

• 領域、アクション、スコープ。 何の種類のものに手を入れたか（ui、backend、database、infra、config、test、docs）、それに何をしたか（create、update、fix、refactor、delete、style）、どのレベルの作業か（コンポーネント、ページ、API、マイグレーション、サービス）を表します。
• 対象。 最大5個の小文字のキーワードです。会話の中で作業にタグを付けるような感覚のものです。
• 1文の要約。 何をなぜ変更したかを1行で表します。
• 変更したパス。領域ごとにまとめられます。
• 使用したAIクライアントと、セッションの日時。
• ターンの経過。ツール呼び出しの回数、そのうち失敗した回数、そして失敗の種類ごとの短いコード（timeout、exit_nonzero、not_foundなど）です。記録されるのは件数とコードだけで、コマンドやエラーのテキストは含まれません。

記録はこれですべてです。数か月後に見返してもひと目でわかるように設計されており、短く保たれているのもそのためです。Pathrule for VS CodeのRecent Activityビューには、そのワークスペースの最新のエントリが一覧表示されます。

文章を書くのはアシスタントで、計測値を付加するのはPathruleです。要約、領域、パスは作業を行ったセッションから提供されますが、ツール呼び出しの回数、失敗、配信したエントリのうち実際に参照されたものは、それらを配信したレイヤーが観測します。この分担には意味があります。アシスタントが4つのコマンドの失敗に触れ忘れても、回数はきちんと残ります。

記録されないもの

コードは含まれません。ファイルの内容、差分、パッチ、コミットメッセージ、プロンプトのテキストはいずれも含まれません。パスを残しているのは、後続の機能が作業の場所を把握できるようにするためであり、変更の中身そのものは保存されません。

パスは保存前に正規化されます。パスはそのマシン上でエージェントが見たままの形で届き、ワークスペース相対の形式に変換されます。たとえば/Users/you/projects/app/src/api.tsはsrc/api.tsになります。マシン固有の情報がチームの共有ナレッジに入ることはなく、誰が触れたかにかかわらず同じファイルは同じファイルとして扱われます。

1つのエントリが支える機能

この記録を残す価値は、それを読み取る機能にあります。

• 作業エピソード。 1回の作業セッションにおける関連エントリが、チームが解決した1つの課題としてタイトル付きの記録にまとめられ、後のセッションで呼び出せるようになります。
• 一緒に変更されるファイル。 各エントリのパスから、Pathruleはどのファイルが対になって変更されるかを学びます。
• 検索の学習。 ナレッジがエージェントに提示され、その後エージェントが同じ領域で作業した場合、それはそのナレッジが関連していたことの裏付けになります。これが積み重なって優先順位が変わっていきます。詳しくは検索の仕組みを参照してください。

いずれも、別途の操作は必要ありません。すべて同じ短いエントリから得られます。

ログ記録が作業を妨げることはない

ツールの挙動に表れるため、意図的な設計判断をひとつ紹介しておきます。サイズを理由にログ記録が失敗することはありません。 要約が長くなったり、タスクが数十個のファイルに及んだりした場合でも、エントリは拒否されず、サーバー側で切り詰めたうえで保存されます。

拒否するほうが、切り詰めるよりも悪い結果になります。バリデーションエラーを受け取ったエージェントはそれを「引数を直して再試行せよ」と解釈し、タスクを完了させる代わりに、続く何ターンも要約の書き直しに費やしてしまいます。そのため制限は受け付け時に静かに適用され、何が保存されたかをレスポンスでエージェントに伝えます。

失敗回数の用途

ツール呼び出しと失敗の回数によって、Pathruleは「このコードベースではアシスタントがどのファイルで苦労しているか」という問いに、意見ではなく実際の作業に基づいて答えます。これらを読み取るものは2つあります。

1つ目は週単位の集計です。すべての失敗は、ツールの種類、作業対象のファイル、失敗の仕方を表す短いコードの3つ組として記録されます。これを週ごとにまとめると、アシスタントが最も頻繁に失敗しているファイルと、そこで起きている失敗の種類がシンプルな一覧になります。file_not_foundで繰り返し現れるファイルは、たいていドキュメント内の古いパスか、移動したのにどこも更新されていないモジュールです。syntax_errorで現れるファイルは、たいてい安全に編集しにくいファイルです。

2つ目は検索の学習です。Pathruleからナレッジを受け取ったターンでもツールの失敗が発生した場合、それは提供されたナレッジにとってマイナスの評価になります。このシグナルはナレッジの優先度が上がる要因で説明している学習ループに加わるため、うまくいかないターンに繰り返し登場するナレッジは、次第に選ばれなくなります。

失敗回数で見えるもの、見えないもの

これは使用するアシスタントによって異なり、正直なところ一様ではありません。

ファイル系のツールは適切に報告します。読み取り、編集、書き込みが失敗するとメッセージ付きで届くため、分類されたうえで正しいファイルに紐づけられます。数値を具体的な行動につなげられるのはファイルパスがあるからこそで、これは最も価値のあるケースです。

一方、シェルの終了ステータスは報告されないことがよくあります。アシスタントによっては非ゼロの終了コードをまったく報告せず、失敗したコマンドと成功したコマンドが同じ形で届きます。Pathruleは推測を行いません。アシスタントが実際に報告した内容だけを記録し、それ以外は失敗をでっち上げずに不明として分類します。誤った失敗がファイルに紐づけられるのは、失敗が記録されないことよりも悪いからです。

アクセスとスコープ

エントリは記録されたワークスペースに保存され、メモリ、ルール、スキルと同じユーザーごとのアクセス制御の対象になります。チームメンバーが見られるのは、すでに閲覧権限を持っているワークスペースのアクティビティだけです。古いエントリは際限なく蓄積されるのではなく、スケジュールに従って順次削除されます。