# Agents Md Improver

> CLAUDE.md / AGENTS.md / GEMINI.md などエージェント指示ファイル（プロジェクトメモリ）の監査・改善。 「CLAUDE.md を監査して」「AGENTS.md が最新か確認して」「指示ファイルを改善して」「プロジェクトメモリを最適化して」で起動。 リポジトリ内の指示ファイルを走査して品質レポートを提示し、ユーザー承認後に的を絞った更新を適用する。 コードベースの現状との整合を確認する定期メンテナンス向け（セッションで得た学びの取り込みは agents-md-revise を使う）。

- Skill: `mjcreativelab/agents-md-improver` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add mjcreativelab/agents-md-improver`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mjcreativelab/agents-md-improver/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: mjcreativelab (https://skillmd.com/u/mjcreativelab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mjcreativelab/agents-md-improver

---


# Agents MD Improver（エージェント指示ファイルの監査・改善）

リポジトリ内のエージェント指示ファイル（CLAUDE.md / AGENTS.md / GEMINI.md 等）を監査・評価・改善し、コーディングエージェントが最適なプロジェクトコンテキストを持てる状態を保つ。

**このスキルは指示ファイルへ書き込みうる。** ただし必ず品質レポートを提示し、ユーザー承認を得てから的を絞った更新のみを適用する。

## 対象ファイル

| 種別 | 場所 | 用途 |
|------|------|------|
| プロジェクトルート | `./CLAUDE.md` / `./AGENTS.md` / `./GEMINI.md` | プロジェクトの一次コンテキスト（git 管理・チーム共有） |
| ローカル上書き | `./.claude.local.md` | 個人・ローカル限定設定（gitignore 対象。Claude Code 固有） |
| パッケージ単位 | `./packages/*/CLAUDE.md` 等 | monorepo のモジュール単位コンテキスト |
| サブディレクトリ | 任意のネスト位置 | 機能・ドメイン固有コンテキスト |
| グローバル | `~/.claude/CLAUDE.md`（Claude Code）/ `~/.codex/AGENTS.md`（Codex）/ `~/.gemini/GEMINI.md`（Gemini CLI） | ユーザー全体のデフォルト。**明示的に依頼されたときのみ対象にする** |

多くのエージェントは親ディレクトリの指示ファイルを自動発見するため、monorepo 構成でもネスト配置が機能する。

## Phase 1: Discovery（走査）

リポジトリ内の指示ファイルをすべて洗い出す:

```bash
find . \( -name "CLAUDE.md" -o -name "AGENTS.md" -o -name "GEMINI.md" -o -name ".claude.local.md" \) -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | head -50
```

**symlink の扱い（重要）:**

- 各ファイルが symlink かを確認する（`ls -l <path>`）。`AGENTS.md → CLAUDE.md` のような symlink は実体と合わせて **1 エンティティ**として扱い、評価・編集は実体側に対して行う（二重カウント・二重編集しない）
- 同名役割のファイルが**別実体**として複数存在する場合（例: CLAUDE.md と AGENTS.md が独立ファイル）、内容の乖離（drift）を確認し、乖離があれば問題として報告する

## Phase 2: 品質評価

各ファイルを品質基準に照らして評価する。詳細ルーブリックは [references/quality-criteria.md](references/quality-criteria.md) を参照。

**クイックチェックリスト:**

| 基準 | 重み | 確認内容 |
|------|------|---------|
| コマンド・ワークフローの文書化 | 高 | build / test / deploy コマンドがあるか |
| アーキテクチャの明瞭さ | 高 | コードベース構造をエージェントが理解できるか |
| 非自明なパターン | 中 | 落とし穴・癖が記録されているか |
| 簡潔さ | 中 | 冗長な説明・自明な情報がないか |
| 鮮度 | 高 | 現在のコードベースの状態を反映しているか |
| 実行可能性 | 高 | 指示が曖昧でなく実行可能か |

**品質スコア:**

- **A (90-100)**: 網羅的・最新・実行可能
- **B (70-89)**: 良好、軽微なギャップあり
- **C (50-69)**: 基本情報のみ、主要セクション欠落
- **D (30-49)**: 希薄または陳腐化
- **F (0-29)**: 欠落または深刻に陳腐化

## Phase 3: 品質レポート出力

**更新前に必ず品質レポートを出力する。**

フォーマット:

```
## エージェント指示ファイル品質レポート

### サマリ
- 検出ファイル数: X（symlink 統合後）
- 平均スコア: X/100
- 更新が必要なファイル: X

### ファイル別評価

#### 1. ./CLAUDE.md（プロジェクトルート。AGENTS.md は symlink）
**スコア: XX/100（グレード: X）**

| 基準 | スコア | 備考 |
|------|-------|------|
| コマンド・ワークフロー | X/20 | ... |
| アーキテクチャの明瞭さ | X/20 | ... |
| 非自明なパターン | X/15 | ... |
| 簡潔さ | X/15 | ... |
| 鮮度 | X/15 | ... |
| 実行可能性 | X/15 | ... |

**問題点:**
- [具体的な問題を列挙]

**推奨追記:**
- [追加すべき内容を列挙]
```

## Phase 4: 的を絞った更新提案

品質レポート出力後、更新前にユーザーへ確認を取る。詳細は [references/update-guidelines.md](references/update-guidelines.md) を参照。

**更新ガイドライン（重要):**

1. **的を絞った追記のみ提案する** — 分析中に発見したコマンド・ワークフロー、コードから読み取った落とし穴・非自明パターン、不明瞭だったパッケージ関係、機能するテストアプローチ、設定の癖
2. **最小限に保つ** — コードから自明な情報の再掲、一般論のベストプラクティス、再発しない一回限りの修正、一行で済む内容の冗長説明は避ける
3. **diff を見せる** — 変更ごとに、対象ファイル・追記内容（diff または引用ブロック）・将来セッションに役立つ理由を示す

**diff フォーマット:**

```markdown
### 更新: ./CLAUDE.md

**理由:** ビルドコマンドが未記載で、プロジェクトの起動方法が分からなかったため。

```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev  # 開発サーバー起動（port 3000）
+ ```
```
```

## Phase 5: 承認後の適用

ユーザー承認後、Edit ツールで変更を適用する。既存の構成・スタイルを保持する。symlink の場合は実体ファイルを編集する。

## テンプレート

プロジェクト種別ごとのテンプレートは [references/templates.md](references/templates.md) を参照。

## よくある問題（フラグを立てる対象）

1. **陳腐化したコマンド**: もう動かないビルドコマンド
2. **依存の欠落**: 必要なツールが未記載
3. **古いアーキテクチャ**: 変更済みのファイル構造
4. **環境セットアップの欠落**: 必要な環境変数・設定
5. **壊れたテストコマンド**: 変更されたテストスクリプト
6. **未記録の落とし穴**: 非自明なパターンの取りこぼし
7. **指示ファイル間の乖離**: 別実体の CLAUDE.md / AGENTS.md 間の内容 drift・重複

## ユーザーへ共有する Tips

推奨を提示する際、**実行中のエージェントに該当するもののみ**添える:

- **簡潔に保つ**: 指示ファイルは人間が読めるもの。冗長より高密度
- **実行可能なコマンド**: 記載コマンドはすべてコピペで動くこと
- Claude Code: セッション中に `#` キーで学びを CLAUDE.md へ自動取り込みできる。個人設定は `.claude.local.md`（gitignore 追加）、ユーザー全体のデフォルトは `~/.claude/CLAUDE.md`
- Codex: ユーザー全体のデフォルトは `~/.codex/AGENTS.md`
- Gemini CLI: ユーザー全体のデフォルトは `~/.gemini/GEMINI.md`

## 良い指示ファイルの条件

**原則:**

- 簡潔で人間が読める
- コピペ可能な実行可能コマンド
- 一般論ではなくプロジェクト固有のパターン
- 非自明な落とし穴・警告

**推奨セクション**（関連するものだけ使う）: Commands（build / test / dev / lint）、Architecture（ディレクトリ構造）、Key Files（エントリポイント・設定）、Code Style（プロジェクト規約）、Environment（必須変数・セットアップ）、Testing（コマンド・パターン）、Gotchas（癖・よくあるミス)、Workflow（いつ何をするか）

---

移植元: Anthropic 公式プラグイン [claude-md-management](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/claude-md-management) の `claude-md-improver` skill（Apache-2.0）。CLAUDE.md 専用だった対象を AGENTS.md / GEMINI.md を含むクロスツール向けに一般化。