agents-md-optimizer

Agents-MD オプティマイザー

発見可能性フィルターを適用して、エージェントのコンテキストファイル（CLAUDE.md、AGENTS.md、.cursorrules など）を最適化します。エージェントがコードから見つけられる情報を削除し、発見できない運用上の知識（注意点、落とし穴、標準外の規約）のみを残し、ソースコードから文書化されていない注意点を洗い出します。

調査によると、冗長なコンテキスト（ディレクトリツリー、データフロー図）はエージェントのパフォーマンスを15～20％低下させる一方、人間が作成した運用上の知識は実行時間を約28％短縮します。

フラグの解析

省略可能なフラグを $ARGUMENTS から解析します。

フラグ	効果
--dry-run	ファイルを変更せずに分析し、差分を表示します
--report-only	統計情報と分類表のみを出力します
--path <path>	対象ファイルのパス（下記の自動検出を参照）
--help	使い方を表示して終了します

--help が指定されている場合は、使用可能なフラグとワークフローの簡単な説明を表示して終了します。

ワークフロー

フェーズ0：セットアップ

言語の検出：会話履歴からユーザーの言語を検出します。分析結果とメッセージはすべてユーザーの言語で提示します。

対象ファイルの解決（--path が指定されていない場合）：

次の優先順位で、最初に見つかったファイルを対象にします。

1. AGENTS.md
2. CLAUDE.md
3. .cursorrules
4. CURSOR.md
5. .github/copilot-instructions.md
6. .windsurfrules
7. codex.md

いずれも見つからない場合は、対象ファイルのパスをユーザーに指定してもらいます。

小さなファイルの確認：対象ファイルが20行未満の場合、すでに最小限の内容であり、最適化は不要であることをユーザーに伝えます。ユーザーが明示的に続行を希望しない限り、終了します。

ステップ1：ベースライン分析

対象ファイルを読み込み、行数の統計情報を収集します。

スクリプトの場所：検索して行数カウントのスクリプトを見つけます。

# Search in common skill installation paths
SCRIPT_PATH=$(find ~/.claude/skills ~/.codex/skills ~/.cursor/skills ~/skills 2>/dev/null -path "*/agents-md-optimizer/scripts/line-count.mjs" | head -1)
if [ -z "$SCRIPT_PATH" ]; then
  # Fallback: search in current directory
  SCRIPT_PATH=$(find . -path "*/agents-md-optimizer/scripts/line-count.mjs" 2>/dev/null | head -1)
fi

見つかった場合はスクリプトを実行します。

node "$SCRIPT_PATH" '<TARGET_PATH>'

フォールバック（スクリプトが見つからない場合）：Bash を使って手動で行数をカウントします。

wc -l '<TARGET_PATH>'
grep -c '^##' '<TARGET_PATH>'

次に、各 ##／### セクションを次の3つのカテゴリに分類します。

カテゴリ	意味	対応
discoverable	エージェントが10秒以内に Glob／Grep／Read で見つけられる	削除
operational	発見できず、運用上重要	残す
verbose	運用上の知識だが詳細すぎる	簡潔にする

分類するには、各セクションで参照されているソースファイルを実際に読み込んでください。情報が本当に発見可能かどうかを確認します。詳細な分類基準については、references/methodology.md を参照してください。

次の形式で結果を提示します。

## Baseline Analysis — <filename>

Total: XXX lines (YY sections)

| Section | Lines | Category | Rationale |
|---------|-------|----------|-----------|
| Directory Structure | 63 | discoverable | Glob **/* reveals this instantly |
| Design Rules | 8 | operational | Non-standard constraints, not in code |
| Config & State | 24 | verbose | Operational but compressible to ~6 lines |

Removal candidates: XX lines (XX%)

--report-only が指定されている場合は、ここで終了します。

ステップ2：注意点の洗い出し

プロジェクトのソースコードをスキャンして、対象ファイルに記載されていない、直感的に分かりにくい運用上の知識を見つけます。references/gotcha-mining.md にある体系的なチェックリストを使用します。

コードベースで実行する主要な Grep パターン：

MUST|WARNING|HACK|TODO|FIXME          → developer-flagged gotchas
catch.*exit\(0\)|process\.exit        → error exit policies
setTimeout|setInterval|deadline       → timing constraints
=== null|== null|delete result        → implicit semantics
process\.platform|/proc/version       → platform detection quirks
cooldown|throttle|lastNotified        → rate limiting scope

調査結果を提示します。

## Discovered Gotchas

| # | Category | Description | Source | Already documented? |
|---|----------|-------------|--------|---------------------|
| 1 | Timing | 5s→4s→2s budget | _common.mjs:21,52 | No → Add |
| 2 | Implicit | null = key deletion | config.mjs:157 | No → Add |

ステップ3：最適化されたファイルの生成

変更する前に、AskUserQuestion を使って確認します。

分析結果：

• 削除：発見可能な内容 X 行（Y セクション）
• 簡潔化：X 行 → 約 Y 行（Z セクション）
• 追加：新しい注意点 X 項目

選択肢：

1. すべて適用 — 発見可能な内容を削除し、詳細な内容を簡潔にし、注意点を追加
2. 項目ごと — 各変更を個別に確認
3. キャンセル — 変更しない

Edit を使って選択された変更を適用します（ファイル全体を書き換えるより、必要な箇所のみを編集することを優先してください）。

--dry-run が指定されている場合は、差分を表示しますが、書き込みは行いません。

最適化されたファイルの構成（推奨されるセクション順）：

1. プロジェクトの説明（1～2行）
2. 開発コマンド
3. 設計ルール（必ず守る制約）
4. 注意点と落とし穴（カテゴリ別のサブセクション）
5. 規約（プロジェクト固有の標準外パターン）
6. バージョン／リリース管理
7. テスト

変更前と変更後を示す詳細なアンチパターンの例については、references/anti-patterns.md を参照してください。

ステップ 4：検証

統計を再計算し（ステップ 1 と同じスクリプトまたは代替方法を使用）、変更前後の比較を提示します。

## Optimization Results

| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Total lines | 182 | 90 | -51% |
| Discoverable lines | 80 | 0 | Removed |
| Operational lines | 60 | 55 | Kept |
| Gotcha items | 0 | 25 | Added |

Discoverability filter: all remaining lines pass "not discoverable from code" check.

参考ファイル

• references/methodology.md — 発見可能性フィルターの判断ツリー、カテゴリ分類基準、圧縮手法、効率性に関する調査データ
• references/anti-patterns.md — 実際の変更前後の例を含む、6 つのアンチパターンのカタログ
• references/gotcha-mining.md — Grep パターンとソースコード分析手法を含む、8 カテゴリのマイニングチェックリスト