optimize-agent-docs

エージェント向けナレッジ最適化

蓄積されたドキュメントを、検索に最適化されたナレッジシステムに変換します。

基本原則

ファイルの整理は人間にとって重要なことです。エージェントは閲覧するのではなく、検索して読み込みます。次の点を最適化します。

• 発見しやすさ：どのようなナレッジがあるか
• 関連性：このタスクで必要か
• 効率性：読み込む量を最小限にできるか

ワークフロー

フェーズ 1：ナレッジの抽出

エージェント向けドキュメントをすべて一覧化します。

# Find all agent doc sources
find . -maxdepth 2 -name "*.md" -path "*/.claude/*" -o \
       -name "*.md" -path "*/.codex/*" -o \
       -name "*.md" -path "*/.cursor/*" -o \
       -name "CLAUDE.md" -o -name "AGENTS.md" -o -name "INSTRUCTIONS.md"

各ファイルから、次の情報を抽出します。

• 個別の事実（実行可能な情報の単位）
• 指示（手順、ルール、制約）
• コンテキストのトリガー（このナレッジが必要になる状況）

フェーズ 2：チャンクの分析

内容を検索単位に分割します。検索単位とは、単独でも意味が通じる、自己完結した最小の情報単位です。

適切なチャンク：

## Adding API Endpoints
1. Create handler in src/handlers/
2. Register route in src/routes.rs
3. Add OpenAPI spec to docs/api.yaml

不適切なチャンク（結びつきが強すぎる）：

See the API section for endpoint patterns, but first read the auth docs,
which reference the middleware guide...

各チャンクを評価します。

• 自己完結しているか？ 追加情報を読み込まずに、エージェントがこの情報に基づいて行動できるか
• タスク固有か？ どのような場合に必要となるかが明確か
• 情報密度が高いか？ トークンあたりの有用な情報量が多いか

フェーズ 3：ナレッジマニフェストの作成

エージェントが最初に読む軽量なインデックス .claude/KNOWLEDGE.md を生成します。

# Knowledge Manifest

## Task → Knowledge Map

| When working on... | Load | Key terms |
|-------------------|------|-----------|
| API endpoints | references/api.md | route, handler, endpoint |
| Authentication | references/auth.md | token, session, login |
| Database changes | references/schema.md | migration, model, query |
| Testing | references/testing.md | spec, fixture, mock |
| Deployment | references/deploy.md | release, staging, prod |

## Quick Reference

### Build Commands
- `npm run dev` — Start dev server (port 3000)
- `npm test` — Run test suite
- `npm run build` — Production build

### Key Paths
- Handlers: `src/handlers/`
- Routes: `src/routes.ts`
- Tests: `tests/`

### Critical Rules
- Never commit .env files
- All PRs require tests
- Use conventional commits

マニフェストには、次の情報を含めます。

1. タスク→ナレッジの対応表：どのコンテキストで何を読み込むか
2. クイックリファレンス：頻繁に参照する事実（ファイルの読み込み不要）
3. 重要ルール：必ず把握すべき制約（常に関連するもの）

フェーズ 4：最適化された成果物の作成

冗長なソースドキュメントを、簡潔でエージェント向けに最適化された形式に変換します。

圧縮テクニック：

ソース（冗長）	コンパイル後（簡潔）
「新しいエンドポイントを追加する場合は、まずハンドラー関数を作成する必要があります……」	New endpoint: handler → route → spec
長い文章の段落	構造化された表
重複した情報	単一の信頼できる情報源
説明付きの例	パターンのみ

出力構成：

.claude/
├── CLAUDE.md              # Human-readable, can stay verbose
├── KNOWLEDGE.md           # Agent manifest (generated)
└── compiled/              # Agent-optimized versions (generated)
    ├── api.md             # Dense API reference
    ├── patterns.md        # Code patterns as templates
    └── rules.md           # All constraints in one place

フェーズ 5：検索ヒントの生成

コンパイル後のドキュメント全体に、grep で見つけやすいマーカーを追加します。

## Adding Endpoints


## Authentication Flow


## Test Patterns

これらのマーカーにより、次のことが可能になります。

# Find relevant sections for a task
grep -l "@task:new-endpoint" .claude/compiled/*.md

フェーズ 6：検証

最適化されたシステムをテストします。

1. 網羅性の確認：ソースにあるすべての事実が、コンパイル後の出力に含まれているか
2. 検索テスト：一般的なタスクに対し、読み込みを最小限に抑えて対応できるか
3. 密度の確認：コンパイル後のドキュメントはソースより小さいか

# Compare sizes
wc -l .claude/references/*.md    # Source
wc -l .claude/compiled/*.md       # Compiled (should be smaller)

マニフェストの形式

KNOWLEDGE.md マニフェストは、次の構成に従います。

# Knowledge Manifest


## Task Context Map


| Context | Load | Search |
|---------|------|--------|
| [task description] | [file path] | [grep terms] |

## Always-Loaded Facts


### Commands
[Most-used commands as a table]

### Paths
[Key directories and their purposes]

### Rules
[Critical constraints that always apply]

## Chunk Index


| Topic | Location | Lines | Summary |
|-------|----------|-------|---------|
| [topic] | [file:line-range] | [count] | [one-line summary] |

情報密度の原則

文章を構造化する

変換前：

「認証システムでは、httpOnly Cookie に保存された JWT トークンを使用します。 ユーザーがログインすると、サーバーはデータベースに照らして認証情報を検証し、 有効期限が 24 時間のトークンを生成して、Cookie として設定します……」

変換後：

## Auth Flow
- Method: JWT in httpOnly cookie
- Expiry: 24h
- Flow: credentials → DB validate → token → cookie

冗長性を排除する

同じ情報が複数の場所にある場合は、正規の情報源を 1 つ作成し、そこを参照するようにします。

## Token Handling
See: [Auth Flow](#auth-flow) — tokens section

リストより表を優先する

変換前：

- The API endpoint for users is /api/users
- The API endpoint for posts is /api/posts
- The API endpoint for comments is /api/comments

変換後：

| Resource | Endpoint |
|----------|----------|
| Users | /api/users |
| Posts | /api/posts |
| Comments | /api/comments |

例よりパターンを使う

変換前：

To create a user handler:
```javascript
export async function createUser(req, res) {
  const { name, email } = req.body;
  const user = await db.users.create({ name, email });
  res.json(user);
}

変換後：

Handler pattern: `export async function {action}{Resource}(req, res)`
Body: Extract params → DB operation → Return result

出力チェックリスト

最適化後に、次の点を確認します。

• KNOWLEDGE.md が存在し、100 行未満である
• タスク→ナレッジの対応表が、一般的なワークフローを網羅している
• クイックリファレンスに、最もよく使われる事実が含まれている
• コンパイル後のドキュメントがソースより簡潔である
• 孤立したナレッジがない（すべてインデックス化されている）
• 検索ヒントによって grep ベースで情報を見つけられる
• 元のソースドキュメントが変更されていない（人間向けの参照用）