ablate-ai-layer

AI レイヤーを取り除いて検証する

モデルのアップグレードによって、指示はいつの間にか役目を終えます。性能の低いモデルを補うために書かれたルールは、今も重要なルールと注意を奪い合う不要な負担になります。ファイルを読んでも、どれがどれなのかは分かりません。分かるのは実験だけです。

実験を実行するのはあなたです。タスクを選び、結論を承認するのはユーザーです。 ユーザーに実行するコマンドの一覧を渡さないでください。スクリプトが両方の条件を実行します。

結果を信頼できるものにする要素

• 両方の条件で複数回実行します。 レイヤーを取り除いたエージェントは、目に見える形で失敗しないことがあります。そのため、1 回だけ実行しても比較対象がなく、「問題なさそう」が「重要なものを削除しよう」に変わってしまいます。同じ条件でも実行ごとに結果が異なることがあり、その差が条件間の差を上回ることもあります。そのため、各条件で 1 回ずつ実行するのは最低限であり、目標ではありません。
• 何も別の場所に移しません。 各実行は、リポジトリの外にある一時ディレクトリで HEAD から作成した、切り離された git worktree 内で行い、実行後に削除します。ユーザーの作業ツリーは変更されないため、元に戻す手順を忘れる心配もありません。
• デフォルトでは、常時読み込まれる項目だけを取り除きます。 スキル、サブエージェント、パスごとのルールは、使われるまでコストがかからないため、削除してもコンテキストは節約できません。フックと権限には一切触れません。これらはコードとして実行され、注意を消費しないためです。

---

Step 1. レイヤーを把握する

python <skill>/scripts/map_layer.py [repo_root]

読み取り専用です。すべての項目を、常時読み込み、オンデマンド、強制適用に分類し、ユーザーが何か入力する前に、常時読み込みの項目が毎セッションで消費するコストを表示します。その数値をユーザーに見せてください。

何も見つからなければ、その旨を伝えて終了してください。検証するものはありません。

Step 2. 検証タスクを決める

これは、ユーザーに代わって決めてはいけない唯一のことです。 タスクによって、実験で何かを検出できるかどうかが決まります。

適切な検証タスクとは、ユーザーがいずれ行う実作業であり、プロジェクト固有の規約が関係しそうなコードに触れ、さらに組み込む必要があるものを追加するタスクです。たとえば、テスト、エンドポイント、マイグレーション、コマンドなどです。

不適切なタスクは、誤字の修正、名前の変更、1 行だけの修正などです。すべてが自明で、両方の条件で同じ結果になり、ユーザーはレイヤー全体に価値がないと誤って結論づけてしまいます。ユーザーがそのようなタスクを提案したら、その点をはっきり伝え、規約が関わるタスクを尋ねてください。

合意したタスクを、そのままファイルに書き込んでください。すべての実行で、バイト単位で同じ内容を再利用します。

Step 3. 計画を示して承認を得る

何かを実行する前に、実行回数、使用するモデル、おおよそのコスト、作業ツリーには触れないことを報告してください。

python <skill>/scripts/run_ablation.py <repo> --task-file <task.md> --dry-run

ドライランでは、次の 2 点も確認できます。必要に応じて一旦立ち止まってください。

• 作業ツリーに未コミットの変更がある場合。 worktree は HEAD から作成されるため、未コミットの編集内容は検証対象になりません。先にコミットするか、stash するかを提案してください。
• ビルド依存関係に関する警告が出た場合。 リポジトリによっては、ソースとして独自の AI レイヤーをインポートしています。ビルド時にスキルの Markdown を読み込む CLI は、そのファイルがなくなるとすぐに壊れます。その結果、ユーザーはコンパイルエラーをエージェントのリグレッションだと誤解してしまいます。この警告が出た場合は、--scope always を維持してください。

Step 4. 実行する

python <skill>/scripts/run_ablation.py <repo> --task-file <task.md> --runs 2

これで実験全体が完了します。実行ごとに新しい worktree を作成し、レイヤーを取り除いた条件ではレイヤーを取り除いて、両方の条件で同じプロンプトを実行し、差分をすべて保存し、worktree をすべてクリーンアップして、結果を .ablation/<timestamp>/（gitignored）に書き込みます。

便利なフラグ：ユーザーが結果に基づいて対応する予定なら --runs 3、スキルとサブエージェントも役目を終えているという、より踏み込んだ仮説を検証するなら --scope all、--model、並列実行には --jobs、標準入力からプロンプトを読み込む Claude 以外のエージェントには --runner を指定します。

いずれかの条件で、利用できる結果が得られなかった場合は中止してください。結果が空の条件は、発見ではなく、実験の失敗です。そこから結論を導く前に、再実行してください。

Step 5. 評価

分析する前に references/comparison.md を読んでください。これは評価基準であり、本当の結果と自信満々の誤った結論を分ける2つのポイントが含まれています。つまり、比較対象同士の差分を取るのではなく、ルールごとに評価すること、そして、どちらの比較対象から差分が得られたかを伏せた状態で評価することです。

要点は次のとおりです。

1. 常時読み込まれるファイルを、検証可能な主張の番号付きチェックリストにします。「きれいなコードを書く」のような反証不能な項目には、その旨を明記します。
2. 各実行の差分を、すべての主張に照らして評価します。結果は followed、violated、n/a のいずれかです。
3. その後で初めて、評価結果を比較対象に対応付け、全体の傾向を読み取ります。

Step 6. 報告

ユーザーには、ルールごとに1行を割り当て、実行可能な項目が先に来るよう並べ替えた表を提示します。

実行間のパターン	評価	対応
control は従い、stripped は違反	効果あり	維持し、より短く書き直す
両方の比較対象が従う	モデルが元から実行している	削除する
両方の比較対象が違反	読み込ませても無視される	フックまたはテストにするか、削除する
適用される場面がない	未テスト	維持する。どちらとも言えない
同じ比較対象内で結果にばらつきがある	ノイズ	実行回数を増やすか、タスクを改善する

「未テスト」は「差がない」と視覚的に区別してください。データ上は同じように見えても、意味は正反対です。この2つをまとめると、このタスクでは扱わなかったケースを保護するルールまで削除されてしまいます。

Step 7. ユーザーの承認を得て適用

ルールファイルを無断で編集してはいけません。編集案を提示し、差分を見せて、返答を待ちます。

観測された根拠があるルールに限り、1行ずつ再追加または維持します。テスト、フック、必要時に参照する指示、常時読み込む指示の順で優先してください。最後に map_layer.py を再実行し、新しい常時読み込みの合計が以前の値と並んで表示されるようにします。

---

ユーザーに伝える、誠実な説明

• 1つの検証タスクはデータポイントであり、結論ではありません。 大きな項目を削除する前に、コードベースの別の部分で2つ目のタスクを試すよう促してください。
• 結果がゼロでも、それは有効な結果です。 比較対象間に差がなければ、そのレイヤーの該当部分は実際に役目を終えているため、削除できます。
• 逆の場合も同様です。 1回の問題ない実行だけを根拠に、このタスクで試していないセキュリティ、コンプライアンス、リリース手順などのルールを削除してはいけません。
• 既存のコードがルールファイルの代わりになることがあります。 stripped の実行では、参照できる近隣のコードがあれば、その規約を引き継ぎます。同じルールでも、編集済みのファイルでは守られ、新規ファイルでは破られることがあります。新規ファイルで得られた根拠をより重視し、各評価がどちらの種類の根拠に基づくかを明記してください。
• 軽量なモデルや小規模なモデルは、最先端モデルより指示に頼る傾向があります。 最先端モデルでは冗長に見えるレイヤーでも、より安価なモデルでは役割を果たしている可能性があります。チームで複数のモデルを使っている場合は、使用中の最も弱いモデルを対象にアブレーションしてください。

リソース

• scripts/map_layer.py：レイヤーの読み取り専用インベントリです。エージェントに依存しません。
• scripts/run_ablation.py：両方の比較対象を実行し、差分を収集します。すべてのフラグは --help に記載されています。どちらのスクリプトもコンテキストに読み込まず、出力のみを確認してください。
• references/comparison.md：評価基準です。Step 5 の前に読んでください。