improve-agents-md

improve-agents-md

プロジェクトのエージェント指示ファイルを段階的に改善します（または、ゼロから作成します）。AGENTS.md（OpenAI Codex のベンダー中立な規約で、Cursor、Claude Code なども読み込みます）と CLAUDE.md（Claude 固有）の両方に対応しています。ディスク上に正規ファイルを 1 つだけ保持し、もう一方をシンボリックリンクにすることで、すべてのエージェントが同じ情報源を読み込めるようにします。

使用するタイミング

• ユーザーが /improve-agents-md（または、ここを指定して /improve-claude-md）を実行したとき
• ユーザーから CLAUDE.md／AGENTS.md を「整理する」「短くする」「監査する」「書き直す」よう求められたとき
• Claude（または別のエージェント）がプロジェクトのルールを無視し続けるとユーザーが不満を述べたとき
• ユーザーが新しいエージェントを導入しようとしていて、指示内容が適切か確認したいとき
• AGENTS.md／CLAUDE.md が存在せず、ユーザーが適切に作成したいとき

根本的な問題

Claude Code（およびほとんどの他のエージェント）は、プロジェクトのエージェントファイルを次のシステムリマインダーとともに読み込みます。

"this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task."

そのため、エージェントは無関係だと判断した部分を無視します。現在のタスクに当てはまらない内容が増えるほど、重要な内容も含めてファイル全体が無視される可能性が高くなります。長く、整理されていないエージェントファイルは逆効果です。

解決策は 2 つあります。

1. 徹底的に削る。 リンター、フォーマッター、またはコミット前フックで強制できる内容は、ここに記載する必要はありません。既存のコードパターンから把握できる内容（LLM はコンテキスト内で学習します）も不要です。曖昧な指示（「読みやすいコードを書く」「ベストプラクティスに従う」など）も不要です。
2. 条件付きで囲む。 ドメイン固有のガイダンスは、範囲を絞った具体的な条件を持つ <important if="..."> ブロックで囲みます。これにより、Claude Code が独自のシステムプロンプトで使うものと同じ XML タグのパターンを活用し、「関連するかもしれないし、しないかもしれない」という前置きを補う、明示的な関連性のシグナルをモデルに与えられます。

こうして、基本的なコンテキストは常に見える状態にし、ドメイン固有のガイダンスはタスクに合致したときだけ「有効になる」短いファイルに仕上げます。

ファイルの解決：どちらを正規ファイルにするか？

このスキルは Claude Code 内で実行されるため、ディスク上の正規ファイルは CLAUDE.md です。AGENTS.md は CLAUDE.md を指すシンボリックリンクとして作成し、ベンダー中立なエージェント（Codex、Cursor、Copilot workspace）が同じ情報源を読み込めるようにします。

各実行の開始時に、次の手順で解決します。

1. リポジトリのルートと、ユーザーがサブディレクトリから実行した場合はそのサブディレクトリで、CLAUDE.md と AGENTS.md を確認します。
2. 存在するファイルに応じて分岐します。
   • CLAUDE.md のみ存在する場合 → そのファイルを編集し、最後に AGENTS.md から CLAUDE.md へのシンボリックリンクを作成するか提案します。
   • AGENTS.md のみ存在する場合（実ファイルであり、シンボリックリンクではない）→ CLAUDE.md に名前を変更し、AGENTS.md から CLAUDE.md へのシンボリックリンクを作成するか提案します。ユーザーが名前の変更を断った場合は、AGENTS.md を直接編集します。
   • 両方存在し、一方がシンボリックリンクの場合 → 実ファイルを編集し、シンボリックリンクはそのままにします。
   • 両方存在し、どちらも実ファイルの場合 → これは内容の不一致による不具合です。AskUserQuestion を使って、どちらを正規ファイルにするか確認します。編集後、もう一方をシンボリックリンクに置き換えるか提案します。
   • どちらも存在しない場合 → AskUserQuestion を使って確認します。1. コードベースから新しい CLAUDE.md を作成する、2. 中止する。

シンボリックリンクを検出するには、必ず ls -la（または同等のコマンド）を使用してください。ファイル名だけで判断してはいけません。

対話フロー

このスキルは一度きりではなく、段階的に進めます。判断が必要な場面では AskUserQuestion を使い、ユーザーが主導権を保てるようにします。以下を標準のフローとし、入力ファイルがすでに整理されている場合や、ユーザーが迅速な進行を希望する場合は手順を省略します。

ステップ 1 — 対象ファイルを解決する

上記の解決手順に従います。どのファイルを編集するか、またその理由を明確に伝えます。

ステップ 2 — 読み込みと分類

ファイル全体を読みます。最上位のセクションをすべて、次のいずれかに分類します。

カテゴリー	例	処理
基礎情報（常に関連）	プロジェクトの概要（1 文）、プロジェクト構成（ディレクトリ一覧）、技術スタック（1〜2 行）	最上部にそのまま残します。
コマンド	ビルド／テスト／lint／開発用コマンド	1 つの <important if="you need to run commands to build, test, lint, or generate code"> ブロックで囲みます。すべてのコマンドを残します。
条件付きルール	「リクエストの検証には Zod を使う」、「API ルートは X に配置する」	条件を絞った <important if> ブロックで個別に囲みます。
ドメイン別セクション	テストの設定、状態管理、i18n、認証	セクションごとに 1 つの <important if> ブロックで囲みます。
lint／フォーマッターの範疇	camelCase、let より const、厳密等価演算子、JSDoc	削除します。 代わりに pre-commit フックを提案します。
曖昧な推奨事項	「ベストプラクティスに従う」、「X エージェントを活用する」、「慎重に考える」	削除します。
古くなったコードスニペット	コンポーネントの 20 行のサンプル	削除します。 ファイルパスへの参照（src/utils/example.ts を参照）に置き換えます。

ステップ 3 — 削除候補の提示

書き換える前に、意見が分かれそうな削除候補について、AskUserQuestion を使って確認します。すべての削除について尋ねる必要はありません。合理的な意見の相違がありそうなものだけを対象にします。複数選択できるリストを含む質問を 1 つにまとめます。

例：

「以下は lint の範疇にあるか、具体的な行動につながらないため、CLAUDE.md から削除したいと考えています。どれを削除してもよいですか？」

• camelCase／PascalCase のルール（lint の範疇）
• 「すべての公開関数に JSDoc を記述する」（lint で強制でき、さらに古くなっています）
• 「クリーンコードの原則に従う」（曖昧すぎます）
• どれも削除せず、すべて残す

意見が分かれそうな項目を削除しない場合は、このステップを省略します。

ステップ 4 — 新しい構成の提示

条件となる <important if> とともに、提案するセクション一覧をユーザーに提示します。ここでは全体を書き換えず、概要だけを示します。手間をかけずに、書き換え前に意見の食い違いを見つけられます。

AskUserQuestion を使って確認します。選択肢の例：

• 「問題ありません — 書き換える」
• 「条件を変更する」（変更内容を確認）
• 「不足しているセクションを追加する」（追加内容を確認）

ステップ 5 — 元のファイルをスナップショット

何かを書き込む前に、変更前後の指標を計算できるよう、またユーザーが元に戻せるよう、現在のファイルをコピーします。

cp CLAUDE.md /tmp/CLAUDE.md.before-$(date +%s)

スナップショットのパスを覚えておきます。ステップ 7 で必要になります。

ステップ 6 — 書き換えと差分の提示

新しいファイルを書き込みます。セクションの追加／削除／文言変更を簡潔にまとめてユーザーに提示します。ファイル全体をチャットに貼り付けないでください。ユーザーはディスク上で確認できます。

ステップ 7 — 指標の報告

変更前後を比較して提示します。重要な指標は次の 4 つです。

指標	計算方法
文字数	wc -c <file>
行数	wc -l <file>
KB	ls -lk <file>（または du -k <file>）
トークン数（推定）	chars / 4 — 英語の大まかな目安です。傾向を示すには十分なので、精度を追求しすぎないでください。

変更前（/tmp/... のスナップショット）と変更後（書き換えたファイル）の両方について実行します。コンパクトな表にまとめて提示します。

                  before      after       Δ
chars             8,412       3,104       −63%
lines               247          92       −63%
KB                  8.2         3.0       −63%
tokens (est.)     2,103         776       −63%

ワンショットの bash ヘルパー（パスは適宜調整してください）：

metrics() {
  local f=$1
  local chars=$(wc -c < "$f" | tr -d ' ')
  local lines=$(wc -l < "$f" | tr -d ' ')
  local kb=$(awk "BEGIN {printf \"%.1f\", $chars/1024}")
  local tokens=$((chars / 4))
  printf "%s\tchars=%s lines=%s kb=%s tokens~%s\n" "$f" "$chars" "$lines" "$kb" "$tokens"
}
metrics /tmp/CLAUDE.md.before-XXXXX
metrics CLAUDE.md

変更後のファイルが実質的に短くなっていない（たとえば削減率が 10% 未満）うえ、ユーザーが整理を希望していた場合は、削除が不十分だった可能性があります。確定前に、もう一度見直すことを検討してください。ファイルが長くなっていた場合は、独自のルールを追加してしまった可能性があります。「やってはいけないこと」のリストと照らし合わせて、出力を読み直してください。

判定のしきい値

after ファイルにラベルを付け、ユーザーが一言で把握できるようにします。主な指標はトークン数で、行数や文字数は補助的な指標です。

トークン数（推定）	判定	意味
< 500	Lean ✓	基礎的な内容と、対象を絞った <important if> ブロックが少数あります。ほとんどのプロジェクトで目指す水準です。
500 – 1,000	Good	中規模プロジェクトに適した分量です。モデルが引き続き十分に内容を参照できます。
1,000 – 2,000	Fat ⚠	リンターの対象となる内容、古くなったスニペット、またはトリガーを絞らずにグループ化されたルールが含まれている可能性が高いです。さらに削減してください。
> 2,000	Bloated ✗	「関連があるかもしれないし、ないかもしれない」と判断され、ほとんどが無視されます。大幅な書き直しが必要です。

機械的に適用せず、状況に応じて判断する注意点：

• モノレポのルートファイルは、パッケージごとのファイルより大きくなっても問題ありません。 多くの異なる領域を扱うルートファイルは、健全な内容でも「Fat」になることがあります。
• 適切にタグ付けされたファイルは、実質的な負荷が小さくなります。 内容の大半が対象を絞った <important if> トリガーで範囲指定されている1,500トークンのファイルは、条件のない文章だけで構成された900トークンのファイルより健全です。モデルが「注意を払う」のは、条件に一致したブロックだけです。
• 行数とセクション数の比率は、補助的な懸念材料です。 25個のブロックにまたがる300行なら問題ありませんが、3個のブロックにまたがる300行なら書き直しが必要です。

判定を変更前／変更後の表とともに報告し、方向性、変化の大きさ、ラベルがひと目で分かるようにします。

ステップ8 — シンボリックリンク

存在しない場合は、対応するシンボリックリンクの作成を提案します：

ln -s CLAUDE.md AGENTS.md   # from repo root

ls -la CLAUDE.md AGENTS.md で、シンボリックリンクが実在するファイルを指していることを確認します。

ステップ9 — 追加の対応を提案する

AskUserQuestion を使って、次の選択肢を提示します：

• 「file-review で結果を開いてコメントを残す」 (/file-review:file-review)
• 「このリポジトリのサブディレクトリにある CLAUDE.md ファイルもスキャンする」
• 「完了」

原則

1. 基礎的なコンテキストはそのままにし、領域固有のガイダンスは囲む

タスクの90％以上に関係する内容は、先頭にプレーンな Markdown として記載します。特定の種類の作業に関係する内容は、<important if> で囲みます。

2. 条件は具体的かつ対象を絞る

悪い例 — 広範な条件ひとつですべてを囲む：

<important if="you are writing or modifying any code">
- Use absolute imports
- Use functional components
- Use camelCase filenames
</important>

良い例 — ルールごとに対象を絞ったトリガーを設定する：

<important if="you are adding or modifying imports">
- Use `@/` absolute imports (see tsconfig.json for path aliases)
- Avoid default exports except in route files
</important>

<important if="you are creating new components">
- Use functional components with explicit prop interfaces
</important>

<important if="you are creating new files or directories">
- Use camelCase for file and directory names
</important>

この仕組みの目的は、精度を高めることです。「コードを書くときはいつでも」に一致する条件は、何のシグナルにもなりません。

3. インラインで保ち、段階的に分割しない

エージェントが見つけるために追加のツール呼び出しを必要とする、別ファイルへの分割や参照はしないでください。ただし、追加の内容が本当に長く（たとえば200行を超え）、関連する頻度が低い場合は除きます。<important if> ブロックが段階的な情報開示の仕組みです。すべてを表示しつつ、条件に応じて重み付けできます。

4. 少ないほど効果的

最先端のモデルは数百件の指示に確実に従えますが、Claude Code 自体のシステムプロンプトとツールで、その予算のうち約50件がすでに使われています。ファイルは簡潔に保ってください。

• リンター、フォーマッター、フックで強制できる内容は削除します。
• 既存のコードパターンからエージェントが把握できる内容は削除します。
• コードスニペットは古くなるため削除し、代わりにファイルパスを示します。
• 曖昧な激励文は削除します。

5. すべてのコマンドを残す

コマンドについては、簡潔さより網羅性を優先します。使用頻度が低くても、エージェントは利用可能なコマンドを把握する必要があります。元のコマンドはすべて残してください。重複した説明は削除しても構いませんが、コマンド自体は削除しないでください。

6. 自明でない内容には「理由」を説明する

ルールが自明でない場合は、短い理由を添えます。packages/db/test の prismaMock を使う、という指示は、「packages/db/test の prismaMock を使う — テストで実際の DB 接続を使うと CI で不安定になる」としたほうが明確です。理由があれば、エージェントは例外的な状況でより適切に判断できます。

出力構成

書き直すときの目標レイアウトです。ひな形として使用してください：

# CLAUDE.md

[one-line project identity — what it is, what it's built with]

## Project map

[directory listing with brief descriptions — keep bare]

<important if="you need to run commands to build, test, lint, or generate code">

[commands table — ALL commands from the original]

</important>

<important if="<specific trigger for rule 1>">

[rule 1]

</important>

<important if="<specific trigger for rule 2>">

[rule 2]

</important>

<important if="<specific trigger for domain area 1>">

[guidance for that domain]

</important>

... more sections, each with its own targeted condition ...

注：

• タイトル（# CLAUDE.md または # AGENTS.md）は、正式なファイル名と一致させます。
• 3行目のプロジェクトの概要は、段落ではなく1文にします。
• エージェントによっては表示時に問題が起きるため、<important if> ブロック内の空行は維持してください。

ブートストラップモード（グリーンフィールド）

既存のファイルがなく、ユーザーがブートストラップを選択した場合：

1. リポジトリのルートを確認します：ls、cat package.json / pyproject.toml / 該当するファイルを実行し、主要な言語とランタイムを特定します。
2. スクリプトを検出します：package.json のスクリプト、または Makefile / justfile / Taskfile のターゲット、あるいは pyproject.toml のツール設定を解析します。コマンドの表にまとめます。
3. ディレクトリツリーを1階層（モノレポの場合は2階層）たどり、プロジェクトマップを作成します。
4. 推測できないことがあれば、AskUserQuestion を使ってユーザーに確認します：
   • モノレポ、単一サービス、ライブラリのどれですか？
   • 分かりにくい規約（例：「ルートは X に配置する」）はありますか？
   • 使用しているテストフレームワークや、エージェントが把握しておくべきテストの設定はありますか？
5. 最小限のファイルを作成します。基礎情報とコマンドだけを記載します。ユーザーが提示していないルールを作り出さないでください。ルールを作り出すより、ルールの少ないエージェントファイルにするほうが適切です。

変換例

入力（変換前の CLAUDE.md）：

# CLAUDE.md

This is an Express API with a React frontend in a Turborepo monorepo.

## Commands

| Command | Description |
|---|---|
| `turbo build` | Build all packages |
| `turbo test` | Run all tests |
| `turbo lint` | Lint all packages |
| `turbo dev` | Start dev server |
| `turbo db:generate` | Generate Prisma client |
| `turbo db:migrate` | Run database migrations |

## Project Structure

- `apps/api/` - Express REST API
- `apps/web/` - React SPA
- `packages/db/` - Prisma schema and client
- `packages/ui/` - Shared component library

## Coding Standards

- Use named exports
- Use functional components with TypeScript interfaces for props
- Use camelCase for variables, PascalCase for components
- Prefer `const` over `let`
- Always use strict equality (`===`)
- Write JSDoc comments for all public functions

## API Development

- All routes go in `apps/api/src/routes/`
- Use Zod for request validation
- Use Prisma for database access
- Error responses follow RFC 7807 format
- Authentication via JWT middleware

## Testing

- Jest + Supertest for API tests
- Vitest + Testing Library for frontend
- Mock database with `prismaMock` from `packages/db/test`

出力（変換後の CLAUDE.md）：

# CLAUDE.md

Express API + React frontend in a Turborepo monorepo.

## Project map

- `apps/api/` — Express REST API
- `apps/web/` — React SPA
- `packages/db/` — Prisma schema and client
- `packages/ui/` — Shared component library

<important if="you need to run commands to build, test, lint, or generate code">

Run with `turbo` from the repo root.

| Command | What it does |
|---|---|
| `turbo build` | Build all packages |
| `turbo test` | Run all tests |
| `turbo lint` | Lint all packages |
| `turbo dev` | Start dev server |
| `turbo db:generate` | Regenerate Prisma client after schema changes |
| `turbo db:migrate` | Run database migrations |

</important>

<important if="you are adding or modifying imports or exports">
- Use named exports (no default exports).
</important>

<important if="you are creating new components">
- Functional components with TypeScript interfaces for props.
</important>

<important if="you are adding or modifying API routes">

- Routes live in `apps/api/src/routes/`.
- Use Zod for request validation.
- Use Prisma for database access.
- Error responses follow RFC 7807.
- Auth via JWT middleware — see `apps/api/src/middleware/auth.ts`.

</important>

<important if="you are writing or modifying tests">

- API: Jest + Supertest.
- Frontend: Vitest + Testing Library.
- Mock database with `prismaMock` from `packages/db/test` — real DB in tests flakes on CI.

</important>

削除した内容とその理由：

• camelCase/PascalCase、const と let の使い分け、厳密等価演算子、JSDoc → リンター／フォーマッターの範囲です。
• まとめられたセクションとしての「コーディング規約」 → 対象を絞った <important if> ブロックに分けました。
• 冗長な説明（「これは……です」） → 1行にまとめました。

残した内容：

• すべてのコマンド。
• プロジェクトマップ（簡潔で基礎的なもの）。
• 領域固有のルールはすべて残し、より限定された条件の下に再配置しました。

してはいけないこと

• ルールを作り出さないでください。 元の内容になく、ユーザーも確認していないルールは追加しないでください。
• コマンドを削除しないでください。 すべてのコマンドを残してください。
• 無関係なルールを1つの <important if> にまとめないでください。 要点は具体性です。
• 差分の要約をユーザーに先に見せずにファイルを置き換えないでください。
• 明示的な確認なしに、実ファイルをシンボリックリンクで上書きしないでください。
• ブートストラップ中に node_modules/、dist/、.git/、vendor/ を再帰的にたどらないでください。