AIDive

動画パック

CLAUDE.mdを削除する、計測つき: ablationの表、チェックリスト、出典

11 分で読めます

TL;DR

  • 177行のCLAUDE.md、3つのskill、1つのhookを持つ実リポジトリで、すべてを削除して壊れたルールはたった1つ、状況もたった1つでした。まっさらな新規ファイルでのi18nルールです。ほかの規約は、周囲のコードがすでに教えていたので守られました。
  • 出力が同一だったタスクでは、このファイルのコストは読み取りトークンの4〜14%、10ドルのうち約1ドルでした。目立つ32%の削減は、ファイルのせいでモデルの作業が増えた1つのタスクに支配されています。
  • skillとhookに測定できるコストはありませんでした。skillは呼び出したときだけ読み込まれ、1つも呼び出されず、hookが注入するのは1文だけです。
  • 82行のアーキテクチャ概要は、アーキテクチャの質問に何ももたらしませんでした。ファイルの有無にかかわらず、6回の回答はすべて正解でした。
  • Anthropic自身の言葉での「delete」は、消去ではなく、ablateしてprogressive disclosureへ移すことです。コードが教えられないルールは残し、残りはrulesファイルとskillへ移し、譲れないものはhookにします。
  • 設定ごとに2回の実行は床であって結論ではありません。タスクごとの差が15%未満なら、実行間のノイズの範囲内です。

What the measurements say

みんなが反応するあの講演は2つのことを言っていて、2つ目が落とされがちです。Boris Chernyは登壇で、Claude Codeがシステムプロンプトの80%を削除したことを認め、その方法を説明しています。システムプロンプト全体を削除し、1行ずつ戻して各行の影響を測る、というものです s2。「every 6 months」の箇所は00:06:58から00:07:05にあり、言い方は「strongly recommend」ではなく「really do recommend」です s1。彼の発言として広まっている2つの言葉は、講演にはありません。「context, goals and a definition of done」(15:22で最も近い実際のフレーズは「describe the task, the guardrails, the exit criteria」)と「64 agents」です。彼は「eleven days」と言い、エージェント数を聞かれて「I'm not sure」と答えています s2。64という数字はBunの書き直しの記事のものです。「64 Claudes running for 11 days」、APIの価格で約165,000ドル、キャッシュされていない入力トークン90億、出力トークン6.9億、キャッシュ入力トークンの読み取り720億です s14。

これらを測定可能にする仕組みは読み込みです。CLAUDE.mdとrulesファイルは毎ターン注入され、skillは呼び出されたときだけ読み込まれます。memoryのドキュメントには、誰もが言い換えるサイズの指針もあります。「target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.」 s4。Anthropicの文章版のアドバイスは、リポジトリ中央のCLAUDE.mdを神話と位置づけ、progressive disclosureとauto-memoryを示しています s3。

私たちより前の統制された研究は、AGENTS.mdに関するETHの論文だけです。12リポジトリの138件のissueで、「providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average」。開発者がコミットしたファイルはLLM生成のものを平均7%上回り、特定のツール名を挙げる指示は効果があります s5。

ファイルの中身と読まれ方についての2つのデータです。28,721リポジトリ、165,063ファイルで、中央値の指示ファイルは50の内容項目を持ち、そのうち実際の指示は12。著者の言い方では、ファイルのうち思っている通りに働いているのは27%だけです s8。本当に衝突する2つの指示を使った統制実験では、1つのルールをファイルの先頭から末尾へ動かすだけで、モデルが従う頻度が約90ポイント変わり、ほぼ従わないからほぼ必ず従うへと振れました s9。同じ発行元が、私たちの実験が従う線引きをしています。ablationは削除ではなく、hookは強制であり、モデルのアップグレードで失効しません s7。

私たちの結果と一致した非公式な事前知見が2つあります。同じGitHub issueと同じモデルで、1,000行のCLAUDE.mdを約20行に削った版と比べると、アーキテクチャは保たれ、ハウスルールは壊れました s6。すべてをprogressive disclosureに移したコメント投稿者は、自動で読み込まれるコンテキストがセッションあたり約35kトークンから約4.5kへ減り、知識は1つも失っていないと報告しています s11。skillのablationを採点するツールもあります。caliperの--ablateはskillとMCPサーバーを対象にし、compareは成功率、トークン、実行時間を報告します。CLAUDE.mdの入れ替えは手作業のままです s16。

Measurements

プロトコル: 非公開のExpo / React Nativeリポジトリ1つ(追跡ファイル1,021)、CLAUDE.mdは177行、7,243文字、約1,800トークン、skill 3つ、スラッシュコマンド4つ、PreToolUse hook 1つ。全実行でモデルはclaude-opus-5に固定、Claude Code 2.1.278、ヘッドレスのclaude -p、--max-turns 40、ユーザー設定ディレクトリは空、MCPなし、実行ごとに新しいcloneをリセット。日常的な5つのタスク(新規コンポーネント、コンポーネントの編集、共有ヘルパーのリファクタ、storeフィールドの永続化、データ経路の説明)で、1つずつablationしました。44回の実行、APIの価格で38.97ドル、エージェントの実行時間は92分。採点は、追加行に対するリポジトリ自身のハウスルール、tsc --noEmit、eslint、回答は手作業の採点です。

品質、何が壊れたか:

設定 編集の実行数 ハウスルール違反 tscの新規エラー eslintエラー
A フル 8 0 0 0
B CLAUDE.mdなし 8 1 (新しい見出しがハードコード、.content.tsなし) 0 0
C skillなし 4 0 0 0
D hookなし 4 0 0 0
E 何もなし 8 2 (見出しが2回ハードコード、.content.tsなし) 0 0

1回の実行あたりのコスト、設定ごとの実行の平均(トークン = キャッシュ読み取り、毎ターン再読み込みされるコンテキスト):

設定 実行数 $ / 回 ターン / 回 読み取りトークン / 回
A フル 10 0.95 25.6 829k
B CLAUDE.mdなし 10 0.74 21.9 568k
C skillなし 5 0.96 28.2 819k
D hookなし 5 0.96 27.8 851k
E 何もなし 10 0.85 25.7 655k

タスクごと、AからB(各2回の平均):

タスク A $ B $ コスト 読み取りトークン
T1 新規コンポーネント 1.72 0.96 -44% -61%
T2 コンポーネント編集 1.49 1.26 -15% -15%
T3 リファクタ 0.64 0.63 -1% -5%
T4 store 0.57 0.53 -6% -4%
T5 質問 0.34 0.31 -9% -14%
全10回 9.51 7.40 -22% -32%

表の読み方。CLAUDE.mdがないと、新規コンポーネントの4回中3回が見出しを単なる文字列として書きました。あると、4回中4回が、ENとFRを持つ.content.tsを作りました。編集タスクでは、Eを含むすべての設定が新しい文字列を.content.tsに置きました。隣のファイルが規約を示していたからです。それ以外は、44回すべてで守られました。相対importは0、型ファイルの6回の編集でinterfaceではなくtype、すべてのdiffでデザイントークン、16進カラーは0、barrelファイルなし。誰も従えなかった指示が1つあります。ファイルは@design-tokensからthemeをimportするよう言っていますが、このエイリアスはtsconfig.jsonに存在しません。どの設定のどの実行も使わず、毎セッション1,800トークンが無駄に読まれていました。T1の削減は、安く済んだ実行が作業を減らしたためです。実行間のばらつきは、ほとんどの設定の効果より大きいです。フル設定のT1は2.11ドル、次に1.33ドルでした。333 MBのコードグラフを置いた対照実験は、フル設定の数字に収まりました(T1で1.59対1.72ドル、T5で0.38対0.34ドル)。グラフのブロックとhookに、測定できる変化はありませんでした。

Do this Monday

  • CLAUDE.mdを数えます。行数、文字数、実際の指示(Always、Never、Use、Prefer)の行数。残りはモデルが毎ターン再読み込みするコンテキストです。
  • セクションごとに規約を1つ選び、隣のファイルがすでにそれを示していないか確認します。フォルダ内の3ファイルがそのルールに従っているなら、その行は削除候補です。
  • まっさらな新規ファイルで、コードが教えられないルールを1つ見つけます(i18n、テレメトリ、ライセンスヘッダー、必須の登録手順など)。それを残し、1行で書き、先頭近くに置きます。
  • ファイルが挙げるimportパスとコマンドをすべて試します。死んだエイリアスや名前の変わったスクリプトは、誰も従えない指示です。
  • 長いアーキテクチャ概要やセットアップ手順を、rulesファイルかオンデマンドで読み込まれるskillへ移し、自動で読み込まれるコンテキストの前後を比べます。
  • 譲れない2、3のルールをhookかlintルールにします。強制は、モデルが段落を読むかどうかに左右されません。
  • 最もよく行う2つのタスクを、固定したモデルで、ファイルありで2回、なしで2回実行し、トークンとdiffを読みます。2回の実行は、どこを見るべきかを教えてくれますが、何を結論すべきかは教えてくれません。

Go further

  • 名言ではなく方法のために、講演そのもの。削除して、1行ずつ戻す s2。
  • 論文の全結果。開発者がコミットしたファイルが生成ファイルを7%上回ること、ツール名を挙げると効果があることを含む s5。
  • 変数としてのルールの位置。約90ポイントの差と、モデルが衝突する指示を黙って解決する様子 s9。
  • 30kリポジトリによる指示ファイルの解剖。50項目、12の指示、残りの38が何か s8。
  • 良いCLAUDE.mdの書き方に関するHumanLayerのガイドと、それに反論するスレッド s10。
  • 「MUST use agent, ignored 80% of the time」のスレッド。文章が通じない場面でhookが必要になる例 s12。
  • 「Claude Code now ignores everything」のスレッド。モデルのドリフトと指示の衝突を切り分けるのに役立ちます s13。
  • caliper。skillとMCPのablationを、成功率、トークン、実行時間で採点するために s16。

Sources

FAQ

CLAUDE.mdは削除すべきですか?

やみくもには勧めません。私たちのリポジトリで失われたのは、新規ファイルでの1つのルールだけで、コードがすでに示していたものはファイルなしでも守られました。セクションを1つずつablateして、出力を変えるものを残してください。

ファイルのコストが4〜14%なのに、なぜ32%のトークン削減になったのですか?

合計は新規コンポーネントのタスクに支配されているからです。そこではファイルのせいで、モデルが2言語の2つ目のファイルを書きました。安く済んだ実行は作業を減らしていたのです。出力が同一だったタスクでは、削減は4〜14%でした。

skillとhookは毎ターントークンを消費しますか?

skillは呼び出されたときだけ読み込まれるので、呼び出されないskillのコストはゼロです。hookが注入するのは1文だけです。両方を削除しても、私たちの実行の数字は変わりませんでした。毎ターン再読み込みされるのは、rulesファイルとCLAUDE.mdです。

設定ごとに2回の実行で足りますか?

足りません。2回の実行は効果の場所を示すだけで、大きさは測れません。フル設定は同じタスクで2.11ドル、次に1.33ドルでした。タスクごとの差が15%未満なら、ノイズの範囲内です。