ai-context-kit

ai-context-kit

コンテキストのトークンコストをどう測定しますか？

完璧な .md コンテキストファイルを書くのに何時間も費やしたのに、エージェントの性能が落ちていたと気づくことがあります。
これはバグではありません。コンテキストのコストを誰も測定していないと、こうなるのです。

     

 

---

CLAUDE.md を作成します。次に、誰かが .cursor/rules/ を追加します。その後、チームメイトが AGENTS.md を置き、さらに誰かがブログ記事から .cursorrules ファイルをコピーしてきます。古いファイルを削除する人はいません。

半年後、プロジェクトには内容が重複し、互いに矛盾するコンテキストファイルが4つもあり、ディレクトリ一覧や「ベストプラクティスに従う」という指示が会話のたびに8,000トークンも投入されるようになります。エージェントはそのすべてに従います。動作は遅くなり、混乱します。そして、モデルのせいにしてしまいます。

ETH Zurich の研究（2026年2月）では、エージェントにコンテキストファイルを与えると実際に何が起きるかを測定しました。

• 自動生成されたコンテキストファイルは、何も与えない場合と比べてタスクの成功率を低下させました
• 人間が作成したファイルでも、精度の向上はわずか**4%**でした
• 無駄なトークンにより、推論コストは20%以上増加しました
• エージェントが従順になりすぎて、実際の問題を解決する代わりに不要な指示に従った結果、一部のモデルでは性能が低下しました

自分のプロジェクトでも同じ問題に何度も直面したため、コンテキストを予算として扱うツールキット ai-context-kit を作りました。コストを測定し、無駄を削り、現在のタスクに必要なものだけを注入できます。

import { loadRules, measure, lint, select } from "ai-context-kit";

const rules = await loadRules("./");

measure(rules, 4000); // what does your context cost?
lint(rules); // conflicts? duplicates? dead weight?
select(rules, {
  task: "fix auth bug", // only inject what matters
  budget: 2000, // stay within token budget
});

---

クイックスタート

npm install ai-context-kit

任意のプロジェクトで CLI を実行し、実際に何を注入しているのかを確認します。

npx ai-context-kit measure

ai-context-kit measure - 6 rule file(s)

  Total: 4,821 tokens

  ############ 2,100 tokens (44%) - .cursor/rules/conventions.mdc
  ######## 1,200 tokens (25%) - CLAUDE.md
  ##### 890 tokens (18%) - .cursor/rules/api-patterns.mdc
  ## 340 tokens (7%) - AGENTS.md
  ## 180 tokens (4%) - .cursor/rules/testing.mdc
  # 111 tokens (2%) - .github/copilot-instructions.md

次に、リントを実行します。

npx ai-context-kit lint

ai-context-kit lint - 6 rule file(s)

  [!] .cursor/rules/conventions.mdc
      Rule is 2100 tokens. Consider splitting to keep each file under 2000 tokens.

  [x] CLAUDE.md
      Conflicts with AGENTS.md: "always use semicolons" vs "never use semicolons"

  [!] CLAUDE.md
      Duplicated line also found in .cursor/rules/conventions.mdc. Duplicates waste tokens.

  [i] AGENTS.md
      Contains vague instruction matching "follow best practices".
      Specific instructions produce better results than general advice.

  Score: 70/100 (FAILED)

これが、推測と把握の違いです。

---

異なる点

	他のアプローチ	ai-context-kit
コンテキストコスト	誰も測定しません	ファイルごとのトークン数と予算チェック
矛盾	エージェントの動作がおかしくなって初めて気づきます	すべてのファイル間の矛盾を自動検出します
重複	同じルールが3つのファイルにあり、トークンも3倍になります	検出してスコアを付けます
タスクとの関連性	毎回すべてのルールが注入されます	select() が現在のタスクに必要なものだけを選びます
複数ツール対応	1つの IDE の形式に限定されます	Cursor、Claude Code、Copilot、Windsurf、Cline で動作します
CI	うまくいくことを願うだけです	エラーがある場合、lint は終了コード1を返します。パイプラインに追加できます

---

解決できること

1. どれだけのコンテキストを注入していますか？ ファイルごとのトークン数、割合の内訳、予算チェック
2. ルール同士が競合していませんか？ すべてのファイルと形式を対象とした矛盾検出
3. 何がトークンを無駄にしていますか？ ディレクトリ一覧、重複コンテンツ、曖昧なアドバイス
4. このタスクに関係するルールはどれですか？ トークン予算に応じた、タスクに関連するルールの選択

---

仕組み

ai-context-kit は、エコシステム内のあらゆるコンテキストファイル形式を読み込み、フロントマターを解析し、トークンコストを推定して、分析と管理のためのツールを提供します。

loadRules()	.cursor/rules/、.cursorrules、CLAUDE.md、AGENTS.md、copilot-instructions.md、.windsurfrules、.clinerules を自動検出します
measure()	ルールごとのトークンコスト、合計に対する割合、予算チェック
lint()	矛盾、重複、冗長さ、曖昧な指示、不要なディレクトリツリーを検出します。0～100でスコアを付けます
select()	現在のタスクに関連するルールを選びます。トークン予算に従います。まず alwaysApply ルールを選び、その後、関連性に基づいて選びます
sync()	信頼できる唯一の情報源を使います。.cursor/rules/ に一度書き込み、CLAUDE.md、AGENTS.md などに同期します
init()	調査から得られたヒントを含むスターターテンプレート

---

API

loadRules(rootDir?)

const rules = await loadRules("./");
// Finds every context file in the project

const rules = await loadRules(".cursor/rules/");
// Or load from a specific directory

フロントマター、本文、形式、パス、トークン数を解析した RuleFile[] を返します。

measure(rules, budget?)

const report = measure(rules, 4000);

report.totalTokens; // 3847
report.overBudget; // false
report.rules; // sorted by size, each with tokens + percentage

lint(rules)

const report = lint(rules);

report.score; // 85/100
report.passed; // true (no errors, warnings don't fail)
report.issues; // array of { rule, path, severity, message }

リンターが検出する内容：

ルール	重大度	検出内容
token-budget	警告／エラー	2,000トークン（警告）または5,000トークン（エラー）を超えるファイル
empty-rule	警告	何の役にも立たないほど短いファイル
duplicate-content	警告	複数のファイルで繰り返される同じ指示
conflict	エラー	あるファイルでは「Xを必ず使う」、別のファイルでは「Xを使わない」
directory-listing	警告	エージェントに不要な10行以上のディレクトリツリー
vague-instruction	情報	「ベストプラクティスに従う」「クリーンなコードを書く」「一貫性を保つ」

select(rules, options)

この研究から得られた重要な知見は、すべてを注入するのではなく、重要なものを選ぶことです。

const relevant = select(rules, {
  task: "fix auth bug in /api/auth",
  budget: 2000,
  tags: ["security", "api"],
  exclude: ["style"],
});

スコアリングでは、フロントマターの alwaysApply: true が最も高い優先度になります。次に、タスクに関する単語とファイルパスおよびコンテンツの一致を確認し、その後にタグの一致を確認します。予算は遵守され、予算を使い切るまでスコアの高いルールから順に含まれます。

sync(options)

ルールを一度記述すれば、あらゆる場所に同期できます。

await sync({
  source: ".cursor/rules/",
  targets: ["CLAUDE.md", "AGENTS.md", ".github/copilot-instructions.md"],
});

書き込みを行わずに変更をプレビューする dryRun: true に対応しています。

init(options?)

await init({ format: "cursor-rules" });
// Creates .cursor/rules/conventions.mdc with research-backed starter template

---

CLI

npx ai-context-kit lint                    # find issues
npx ai-context-kit lint --json             # machine-readable output
npx ai-context-kit measure                 # token cost breakdown
npx ai-context-kit measure --budget 4000   # check against budget
npx ai-context-kit sync --source .cursor/rules/ --target CLAUDE.md,AGENTS.md
npx ai-context-kit init                    # scaffold starter rules
npx ai-context-kit init --format claude-md

すべてのコマンドで、別のプロジェクトルートを指定する --path <dir> を使用できます。lint はエラーがある場合に終了コード 1 を返します（警告の場合は成功します）。

---

Vercel AI SDK／LangChain／カスタムエージェントでの使用

これは Cursor だけを対象としたものではありません。Vercel AI SDK、LangChain、または独自のフレームワークでエージェントを構築する場合、ai-context-kit は同じ問題を解決します。システムプロンプトにどれだけのコンテキストを詰め込んでいるか、そしてそれが役に立っているのか、それとも逆効果なのかという問題です。

import { loadRules, select } from "ai-context-kit";
import { generateText } from "ai";

const allRules = await loadRules("./rules");

const relevant = select(allRules, {
  task: userMessage,
  budget: 3000,
});

const systemPrompt = relevant.map((r) => r.body).join("\n\n");

const { text } = await generateText({
  model: openai("gpt-4o"),
  system: systemPrompt,
  prompt: userMessage,
});

システムプロンプト文字列を受け取るフレームワークなら何でも使えます。Markdown ファイルに保存されたルールなら何でも使えます。

---

対応フォーマット

フォーマット	ファイル	使用先
Cursor（最新）	.cursor/rules/*.mdc	Cursor IDE
Cursor（旧式）	.cursorrules	Cursor IDE
Claude Code	CLAUDE.md	Claude Code
AGENTS.md	AGENTS.md	エージェント間の標準
GitHub Copilot	.github/copilot-instructions.md	GitHub Copilot
Windsurf	.windsurfrules	Windsurf
Cline	.clinerules	Cline

ai-context-kit はファイルパスからフォーマットを検出します。設定は不要です。

---

ルールをもっと適切に書けばよいのではありませんか？

ETH Zurich の研究では、人間が記述したコンテキストファイルと LLM が生成したコンテキストファイルの両方が検証されました。人間が記述したもののほうが優れていましたが、その差はわずか 4％でした。本当の問題は品質ではなく、量です。コンテキストが増えるほど、エージェントが現在のタスクで必要としない指示にもトークンが消費されます。最も効果的なのは、文章をより良くすることではなく、タスクに関連するルールを絞り込むことです。

トークン数の推定はどれくらい正確ですか？

ai-context-kit は、1 トークンあたり 4 文字という近似値を使用します。これは意図的にシンプルかつ高速にしています。予算の管理や比較には十分な精度です（英語のテキストでは GPT-4 は平均して 1 トークンあたり約 4 文字です）。正確な数を求める場合は、出力を tiktoken または使用するモデルのトークナイザーに渡してください。

CI で動作しますか？

はい。npx ai-context-kit lint は、エラーがある場合に終了コード 1 を、成功した場合に 0 を返します。eslint を追加する場合と同様に、CI パイプラインに追加してください。--json フラグを使うと、カスタムレポート用の機械可読な出力が得られます。

---

技術スタック

コンポーネント	技術
言語	strict mode
テスト
バンドラー	ESM + CJS
依存関係	実行時の依存関係はゼロ

---

コントリビューション

PR を歓迎します。新しい lint ルール、フォーマット検出機能、バグ修正など、コントリビューションガイドをご確認ください。

---

作成者

---

_{README Builder で作成した README}

ライセンス

MIT © Ofer Shapira

---

このリポジトリにスターを付ける · フォークする · バグを報告する · ディスカッションに参加する