prompt-compression

使用する場面

ドキュメント、フレームワークリファレンス、API インデックス、コーディングガイドラインなど、構造化された知識を圧縮し、AGENTS.md、CLAUDE.md、またはシステムプロンプトに含める場合にこのスキルを使用します。目的は、トークン使用量を最小限に抑えながら、情報密度を最大化することです。

背景

Vercel の調査（2026 年 1 月）では、AGENTS.md に 8KB の圧縮済みドキュメントインデックスを含めると、評価の合格率が 100% に達しました。一方、ベースラインは 53%、明示的な起動指示を含むスキルは 79% でした。常時読み込まれる受動的なコンテキストは、エージェントが起動を判断する必要のある能動的な検索よりも優れています。判断の段階をなくせるためです。圧縮が重要な鍵となります。コンテキストウィンドウを圧迫せずに、受動的なコンテキストを実用可能にするからです。

重要なルール

1. ファイル参照にはパイプ区切りのインデックス形式を使用する

誤り（エージェントがよく行う形式）：

## Documentation

- Getting Started: See docs/getting-started.md for installation instructions
- Routing: See docs/routing.md for route definitions
- API Routes: See docs/api-routes.md for API endpoint documentation

正しい形式：

[Docs Index]|root: ./docs |getting-started:{installation.md,project-structure.md}
|routing:{defining-routes.md,dynamic-routes.md,middleware.md}
|api:{endpoints.md,auth.md,validation.md}

理由： パイプ区切り形式は、主要なすべての LLM で解析可能なまま、トークン数を 70〜80% 削減できます。必要に応じて、エージェントは特定のファイルを見つけて読み込むこともできます。

2. ルールを 1 行の指示に圧縮する

誤り（エージェントがよく行う形式）：

## Coding Standards

### Import Organization

When writing imports, always organize them in the following order:

1. Built-in Node.js modules (fs, path, etc.)
2. External dependencies (react, express, etc.)
3. Internal modules (relative imports)
4. Type imports

Make sure to separate each group with a blank line.

正しい形式：

[Standards] |imports: builtin > external > internal > types (blank line between groups)

理由： エージェントに会話形式の説明は不要です。圧縮された指示なら、同じ動作上の指示をトークン数 5% で伝えられます。

3. 説明的な文章を削り、実行可能な内容だけを残す

誤り：

## Authentication

Our application uses JWT-based authentication. When a user logs in, the server generates a JWT token
that contains the user's ID and role. This token is sent back to the client and stored in an
httpOnly cookie. On subsequent requests, the middleware extracts the token from the cookie, verifies
it, and attaches the user object to the request.

The token expires after 24 hours, at which point the user must log in again. Refresh tokens are not
currently implemented but are planned for a future release.

正しい形式：

[Auth]|JWT in httpOnly cookie|24h expiry|no refresh tokens |middleware: extract token > verify >
attach user to req |login flow: validate creds > generate JWT(id,role) > set cookie

理由： エージェントに必要なのは、動作上の契約（何をするか）であり、説明（なぜそのように構築されたか）ではありません。経緯、動機、今後の計画は削除します。

4. 省略形のキーと記号を使用する

誤り：

- Required: true
- Type: string
- Default value: "production"
- Minimum length: 3
- Maximum length: 50

正しい形式：

|env: required string="production" len:3-50

理由： 標準的な省略形（req、opt、str、int、bool、len、min、max、def）は LLM に広く理解されており、構造化メタデータを 80% 以上圧縮できます。

5. 入れ子の階層をフラット化する

誤り：

## Project Structure

### Source Code

#### Components

##### UI Components

- Button.tsx
- Input.tsx
- Modal.tsx

##### Layout Components

- Header.tsx
- Footer.tsx
- Sidebar.tsx

正しい形式：

[Structure]|src/ |components/ui:{Button,Input,Modal}.tsx
|components/layout:{Header,Footer,Sidebar}.tsx

理由： Markdown の見出し階層は、空白と繰り返しでトークンを浪費します。ブレース展開とパスのプレフィックスなら、密度を高めつつ、エージェントにとって同等の読みやすさを保てます。

6. 検索を優先する推論指示を追加する

圧縮したコンテキストが検索可能なファイルを参照する場合は、必ず次の指示を含めます。

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any [DOMAIN] tasks.

理由： これがない場合、エージェントは学習データ（古い可能性があります）に頼りがちです。この 1 行によって、動作が「記憶から推測する」から「調べる」へと変わります。これが Vercel の合格率 100% を実現した重要な要因でした。

7. 構造上の境界を保つ

誤り：

routingdefiningdynamicmiddlewareapiendpointsauthvalidation

正しい形式：

|routing:{defining,dynamic,middleware} |api:{endpoints,auth,validation}

理由： 圧縮しすぎると、解析可能性が損なわれます。区切り文字（パイプ、ブレース、コロン）を使って論理的なグループ分けを保ちます。エージェントが特定のファイルやセクションにたどり着ける必要があります。

8. フレームワーク全体のインデックスは 8〜15KB を目標にする

フレームワークのドキュメント全体のインデックス（検索可能なドキュメントを指すファイルツリー）は、8〜15KB に圧縮します。次の条件を満たす、最適なサイズです。

• プロジェクト固有のコンテキストとともに AGENTS.md に無理なく収まる
• リクエストあたりのトークンコストが 2〜4K トークン未満に収まる
• フレームワーク固有のタスクで、エージェントの精度がほぼ完璧になる

圧縮後の出力が 15KB を超える場合は、プライマリーインデックス（よく使われる API）と、エージェントが必要に応じて読み込めるセカンダリーインデックスに分割します。

圧縮の手順

1. ソースを特定する - ドキュメントディレクトリ、API リファレンス、コーディングガイドライン、フレームワークのドキュメント
2. 実行可能な内容を抽出する - 文章、動機、経緯、ルールと重複する例を削除する
3. 形式を選ぶ - ファイルツリーにはパイプ区切りのインデックス、ルールには 1 行の指示、設定やスキーマには省略形のキーを使用する
4. 圧縮する - 省略形、ブレース展開、パスのプレフィックス、記号による略記を適用する
5. 検索指示を追加する - 出力が読み取り可能なファイルを参照する場合に追加する
6. 検証する - エージェントが特定の情報を引き続き見つけられることを確認する
7. 測定する - 圧縮前後のトークン数を比較し、70〜80% の削減を目指す

出力形式

ファイルインデックス（ドキュメントディレクトリ向け）

[Topic Index]|root: ./path |IMPORTANT: Prefer retrieval-led reasoning over pre-training-led
reasoning for [TOPIC] |section-a/subsection:{file1.md,file2.md,file3.md}
|section-b:{file1.md,file2.md}

ルール／標準（コーディングガイドライン向け）

[Standards] |naming: camelCase vars, PascalCase components, UPPER_SNAKE constants |imports:
builtin > external > internal > types |errors: always use Result<T,E>, never throw in library code
|tests: colocate with source, name: \*.test.ts, min coverage 80%

API リファレンス（エンドポイントのドキュメント用）

[API]|base: /api/v2 |GET /users?page,limit -> User[]|auth:bearer |POST /users {name,email,role?} ->
User|auth:admin |DELETE /users/:id -> void|auth:admin

設定／スキーマ（構造化メタデータ用）

[Config] |db: host=localhost port=5432 pool:5-20 timeout:30s |cache: redis ttl:5m max:1000
prefix:"app:" |auth: jwt secret=$JWT_SECRET exp:24h algo:HS256

アンチパターン

• エージェントがすでによく知っている内容（基本的な言語構文、標準ライブラリ）を圧縮する
• 一目ではわかりにくい API の使い方を示すコード例を削除する
• エラーメッセージやエッジケースのドキュメントを圧縮する（エージェントには原文どおりの情報が必要です）
• 人間が確認したり保守したりできないほど、過度に圧縮する
• ファイルへのインデックスではなく、ドキュメント全体を AGENTS.md に記載する
• 検索結果に基づく推論を指示する内容を忘れる