Claude Code の「毎リクエスト課金される文脈」を実測して削る

長い社内ルールやリファレンスを ~/.claude/rules/ に置くと、全プロジェクト・全リクエストに無条件でロードされる。 体感では気づけないが、実測すると 1 リクエストあたり数万トークンを払い続けていることがある。 この指示書は「どこが常時ロードされているかを実測 → 安全に外す → 配布済みの全端末を自動で移行させる」までの手順。

想定読者は AI エージェント（そのまま実行させてよい）。

---

前提知識: 何が常時ロードされるか

置き場所	挙動
~/.claude/CLAUDE.md	常時ロード（ユーザーグローバル）
<repo>/CLAUDE.md	そのリポジトリで作業する時にロード
~/.claude/rules/*.md（paths: フロントマター なし）	常時ロード（無条件）
~/.claude/rules/*.md（paths: フロントマター あり）	該当ファイルを触った時だけロード
それ以外の任意パス	ロードされない（AI が Read した時だけ読まれる）

paths: 付きの例（これはスコープされる）:

---
paths:
  - "**/*.gs"
  - "**/appsscript.json"
---

# GAS を触る時だけ効くルール

判断: 「特定のファイル種別を触る時だけ効くルール」だけを rules/ に置き、必ず paths: を付ける。 全文リファレンス・長い手順書・過去事例集は rules/ の外に置き、索引から「必要な時に Read せよ」と誘導する。

---

手順1: 常時ロード量をファイル単位で実測する

transcript の usage 合算では「どのファイルが何トークンか」を切り分けられない。 count_tokens API（無料・課金されない）でファイル単位に測る。

count-always-loaded.mjs として保存して実行する:

import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';

const home = os.homedir();
// API キーの置き場所は環境に合わせて変える
const env = fs.readFileSync(path.join(home, '.claude', 'anthropic.env'), 'utf8');
const key = (env.match(/ANTHROPIC_API_KEY\s*=\s*(.+)/) || [])[1]?.trim().replace(/^["']|["']$/g, '');
if (!key) { console.error('APIキーが見つからない'); process.exit(1); }

async function count(text) {
  const r = await fetch('https://api.anthropic.com/v1/messages/count_tokens', {
    method: 'POST',
    headers: { 'x-api-key': key, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
    body: JSON.stringify({ model: '<最新のモデルID>', system: text, messages: [{ role: 'user', content: 'x' }] }),
  });
  const j = await r.json();
  if (!r.ok) { console.error(r.status, JSON.stringify(j)); process.exit(1); }
  return j.input_tokens;
}

const base = await count('x');           // 空系プロンプトの下駄を引くための基準値
let total = 0;
const report = async (label, file) => {
  const text = fs.readFileSync(file, 'utf8');
  const scoped = /^---[\s\S]*?paths:/.test(text);   // paths: 付きはスコープ済み
  const n = (await count(text)) - base;
  console.log(`${label}: ${n} tok ${scoped ? '(paths: あり → 常時ロードされない)' : '(★常時ロード)'}`);
  if (!scoped) total += n;
};

await report('CLAUDE.md', path.join(home, '.claude', 'CLAUDE.md'));
const rulesDir = path.join(home, '.claude', 'rules');
if (fs.existsSync(rulesDir)) {
  for (const f of fs.readdirSync(rulesDir)) await report(`rules/${f}`, path.join(rulesDir, f));
}
console.log('---');
console.log('常時ロード合計:', total, 'tok / リクエスト');

実測例（ある組織の配布ルール）:

CLAUDE.md: 6007 tok (★常時ロード)
rules/gas.md: 1034 tok (paths: あり → 常時ロードされない)
rules/onboarding.md: 23288 tok (★常時ロード)     ← 66KB の全文がここにあった
---
常時ロード合計: 29295 tok / リクエスト

この時点で判断できること: 全文 23,288 tok は毎リクエスト課金される。 索引（要約版）が別途 CLAUDE.md にあるなら、全文を常時ロードする必要はない。

補足: セッション全体の文脈量は transcript の1本目の input_tokens + cache_creation_input_tokens + cache_read_input_tokens で見える。 count_tokens で出した差分がここに反映されるかで最終確認する。

---

手順2: 外す前に「索引側に判断基準が残っているか」を確かめる

全文を外すと、AI は「必要になったら読む」しかできなくなる。 外した瞬間に守られなくなるルールが無いかを先に確認する。

• 常時ロードに残る側（CLAUDE.md）に、絶対ルール・禁止事項・ルーティング方針の見出しと1行要約が残っているか
• 「必ずこう振る舞え」を強制したいものは、文書ではなく hook（UserPromptSubmit 等で毎回注入）に移す
• 索引の先頭行に、全文の場所と読み方を明示する

索引先頭行の文例:

全文は ~/.claude/<name>.md（および <配布元URL>）。
このファイルは自動ロードされない。判断に迷ったら Read ツールで該当節を読むこと

---

手順3: 配布ツール側で全端末を自動移行させる

複数端末に配っている場合、手元だけ直しても意味がない。配布スクリプトを直す。

実装上の必須ポイントは3つ。ここを外すと「一部の端末で永久に直らない」バグになる。

(a) 旧パスの後始末は「日次ガード・変更なし判定」より前に置く

多くの配布スクリプトは「前回同期から N 時間以内なら何もせず return」「内容が同じなら return」という 早期 return を持つ。後始末をこの後ろに書くと、すでに同期済みの端末では一生実行されない。

(b) 削除ではなく「移動」にする

旧パスを消して新パスを書くのが同じ実行内とは限らない（早期 return を挟むと最大で次の同期まで空く）。 その間、全文がローカルから消えて AI が読めなくなる。新パスが無ければ rename、あれば削除にする。

const oldPath = path.join(home, '.claude', 'rules', '<name>.md');   // 常時ロードされる旧位置
const newPath = path.join(home, '.claude', '<name>.md');            // ロードされない新位置

if (!dryRun && fs.existsSync(oldPath)) {
  try {
    if (fs.existsSync(newPath)) fs.rmSync(oldPath, { force: true });
    else { fs.mkdirSync(path.dirname(newPath), { recursive: true }); fs.renameSync(oldPath, newPath); }
  } catch {}   // 配布フローを止めないため失敗は握る
}

(c) dry-run では消さない

--dry-run で副作用を起こさない。テストで固定する。

---

手順4: テストで固定する

移行系は「一度動けば終わり」ではなく、旧状態の端末が後から来るので回帰テストを必ず書く。

最低限おさえる5ケース:

1. 全文が新パスにバイト一致で保存される
2. 旧パスがあれば消える
3. 同期済みで内容に変更が無いケースでも旧パスが消える（早期 return の落とし穴）
4. --dry-run では旧パスが残る
5. 索引の先頭行が新パスを指し、旧パス文字列を含まない

3 と 4 のテスト例（Node 標準テストランナー）:

test('同期済みで内容変更が無くても旧パスを消す', () => {
  const f = setup(null);
  assert.equal(run(f).status, 0);               // 1回目: 正常同期させる
  fs.mkdirSync(path.dirname(oldPath), { recursive: true });
  fs.writeFileSync(oldPath, source);            // 旧パスだけ後から生やす
  assert.equal(run(f).status, 0);               // 2回目: 内容は変わらない
  assert.equal(fs.existsSync(oldPath), false);  // それでも消えている
});

test('fetch が失敗しても全文を失わない', () => {
  const f = setup(null);
  fs.mkdirSync(path.dirname(oldPath), { recursive: true });
  fs.writeFileSync(oldPath, source);
  assert.equal(run(f, { FETCH_URL: 'https://127.0.0.1:9/absent' }).status, 0);
  assert.equal(fs.existsSync(oldPath), false);
  assert.ok(fs.readFileSync(newPath).equals(source));   // 移動されているので中身は残る
});

---

手順5: 完了と言う前の確認

• count_tokens を変更後にもう一度回し、常時ロード合計が落ちたことを数字で出す
• ローカルの実ファイルを見る（rules/ に残るのは paths: 付きだけか、全文は新パスにあるか、中身は一致するか）
  • 中身の比較は改行コード差（CRLF/LF）で偽陽性になる。正規化してから比較する
• テストと構文チェックを実際に走らせる（PowerShell 版も配るなら実パーサで parse させる）
• 最終確認は新しいセッションを1本開いて transcript の1本目の usage を見る

削減例:

	常時ロード
変更前	29,295 tok / リクエスト
変更後	6,020 tok / リクエスト
差	-23,275 tok / リクエスト

---

よくある失敗

• transcript の総トークンだけ見て原因ファイルを特定しようとする → 切り分けできない。count_tokens でファイル単位に測る
• 後始末を早期 return の後ろに書く → 同期済みの端末で永久に実行されない
• 旧ファイルを消すだけ → 次の同期まで全文がローカルから消える
• 索引に何も残さず全文を外す → 絶対ルールが守られなくなる。強制したいものは hook へ
• 手元だけ直して「完了」と言う → 他端末は変わっていない。配布スクリプトを直して初めて完了