optimize-agents-md

AGENTS.md を最適化する

Boris Cherny の圧縮原則を AGENTS.md とルールファイルに適用します。

目標：約 2.5k トークン（多くは不必要に 10k 以上あります）

使用する場面

• AGENTS.md または CLAUDE.md を改善したい場合
• エージェントへの指示が冗長、または重複している場合
• ルールはあるものの、検証パターンがない場合
• 新しいプロジェクトのエージェント設定を行う場合

修正するアンチパターン

アンチパターン	問題	修正
コンテキストの詰め込み	エージェントがすでに知っている情報の繰り返し	明白な指示を削除する
静的なメモリ	学びを記録するセクションがない	日付付きの ## Learnings を追加する
形式のばらつき	構成が一貫していない	一貫した見出しを使用する
検証の欠如	作業を確認する方法がない	ルールに *Verify:* パターンを追加する
冗長なルール	パターンではなく段落になっている	パターン + 検証 + 修正に圧縮する

ワークフロー

フェーズ 1：現在の状態を分析する

# Count tokens (rough estimate: words × 1.3)
wc -w AGENTS.md

# Find redundancy with project files
grep -l "bun test" AGENTS.md package.json

以下を確認します：

• package.json のスクリプトと重複する指示
• 一般的なツール（git、npm、bun）の説明
• 表にできる冗長な説明
• 検証パターンのないルール

フェーズ 2：AGENTS.md を圧縮する

目標とする構成：

# AGENTS.md

## Overview
[1-2 sentences: what this project is]

## Capabilities  
[Bullet list of key features/commands]

## Structure
[Brief file tree of key paths]

## Commands
[Essential commands only - not everything in package.json]

## Verification
[How to check work is correct]

## Workflow
[Key constraints: plan first, verify incrementally]

## Rules
[Links to rule files or inline compressed rules]

## Learnings
[Dated entries from actual issues encountered]

圧縮のテクニック：

• 段落より表を使う
• 文より箇条書きを使う
• package.json に書かれている内容はすべて削除する
• ツールの説明を削除する（エージェントは git、npm、bun を知っています）
• 関連するセクションを統合する

フェーズ 3：ルールを最適化する

冗長なルールを検証パターンに変換します：

変換前（冗長）：

## Type Aliases Over Interfaces

In this codebase, we prefer using TypeScript type aliases 
instead of interfaces. This provides better consistency 
and flexibility when working with unions and intersections.

Example:
// Good
type User = { name: string }

// Bad  
interface User { name: string }

変換後（検証付きに圧縮）：

**Type over interface** - `type User = {` instead of `interface User {`
*Verify:* `grep 'interface [A-Z]' src/`
*Fix:* Replace `interface X {` with `type X = {`

パターン形式：

**Rule name** - Brief description with example
*Verify:* Command or tool to check compliance
*Fix:* How to resolve violations

フェーズ 4：更新され続けるドキュメントの要素を追加する

学びのセクション：

## Learnings
- 2024-01-15: Skills use CLI tools, never duplicate logic
- 2024-01-20: Rules need verification patterns for self-checking

更新するタイミング： 以下の場合に学びを追加します：

• ミスの修正が必要になった
• パターンが見つかった
• 制約が明確になった

検証

最適化後、以下を確認します：

1. トークン数：wc -w AGENTS.md × 1.3 ≈ トークン数（目標：<2.5k）
2. 重複がないこと：package.json と重複する情報を grep で確認する
3. パターンのあるルール：各ルールに *Verify:* の行がある
4. 学びがあること：## Learnings セクションが存在する

変換例

コマンドのセクション

変換前（340 語）：

## Development Commands

To install dependencies, run the following command...
[lengthy explanation of bun install]

To run tests, you can use...
[explanation of test runner]

変換後（40 語）：

## Commands
```bash
bun install    # Setup
bun run check  # Lint/format
bun test       # Unit tests

### Capability Description

**Before:**
```markdown
This package provides TypeScript Language Server Protocol 
integration that allows you to get type information, find 
symbols across your workspace, locate references to symbols,
and perform batch analysis of files.

変換後：

**LSP** (`lsp-*`): Type-aware hover, symbol search, references, batch analysis

関連するスキル

• scaffold-rules - 検証パターンを備えた最適化済みルールをインストールする
• validate-skill - スキルの構成を検証する