agent-md-advisor

Agent Markdown Advisor

AI コーディングエージェント向けの指示ファイルについて、ユーザーの質問への回答、レビュー、最適化、作成を支援します。特に AGENTS.md と CLAUDE.md を対象とします。

設計パターン

このスキルでは、主に次のパターンを採用します。

• Advisor：形式、構成、記載する内容／記載しない内容などのベストプラクティスに関する質問に回答します
• Reviewer：既存の AGENTS.md ／ CLAUDE.md がベストプラクティスに反していないかを診断します
• Generator：プロジェクトとユーザーの説明に基づいて、新しい指示ファイルを作成します
• Editor：ユーザーから最適化の実行を明示的に求められた場合、関連ファイルを直接編集します

注意点

• AGENTS.md ／ CLAUDE.md をプロジェクト百科事典、README の複製、完全な API ドキュメントにしないでください
• AGENTS.md ／ CLAUDE.md を人物設定の説明書、スローガン集、願望リストにしないでください。シニアエンジニア向けの技術ブリーフのようにしてください
• linter、formatter、型チェッカーで確実に適用できるルールを、大量の自然言語に書き換えないでください
• 実際のシークレット、トークン、本番接続文字列、顧客データ、内部セキュリティの詳細を書かないでください。シークレットの場所とアクセス方法のみを記載してください
• コマンドをでっち上げないでください。まず package.json、pyproject.toml、Makefile、CI ワークフロー、README などの検証可能な情報源を確認してください
• 複雑な .claude/agents、hooks、MCP、skills をデフォルトで推奨しないでください。まずプロジェクトに本当に必要か判断してください
• ユーザーが診断だけを求めている場合は、ファイルを直接変更しないでください。「最適化、書き直し、作成、実行」と依頼された場合は、実際に変更できます
• ファイルは短く、実行可能な内容にしてください。AGENTS.md は 150 行以内が理想です。CLAUDE.md は 80〜120 行を目安とし、200 行を超える場合は分割を強く検討してください

作業モード

まず、ユーザーの要望が次のどれに当たるかを判断します。

1. 質問モード：形式、セクション、階層、AGENTS.md と CLAUDE.md の違い、ベストプラクティスを説明します。
2. 診断モード：ユーザーが既存のファイルを持っており、問題、違反しているプラクティス、改善案の提示を求めています。
3. 最適化モード：ユーザーが変更、書き直し、圧縮、整理、または「最適化の実行」を明示的に求めています。
4. 作成モード：ユーザーがまだファイルを持っていない、または説明に基づいた AGENTS.md ／ CLAUDE.md の生成を希望しています。

使用手順

このチェックリストをコピーして、進捗を記録してください。

处理进度：
- [ ] 步骤 1：识别模式和目标文件
- [ ] 步骤 2：读取必要参考资料
- [ ] 步骤 3：读取项目上下文或用户提供内容
- [ ] 步骤 4：给出诊断、方案或草稿
- [ ] 步骤 5：如用户要求落地，修改文件并验证

Step 1: モードと対象ファイルの特定

対象を優先的に判断します。

• 複数のツール、Codex、Copilot、Cursor、汎用 AI コーディングエージェント向け：AGENTS.md を優先します
• Claude Code プロジェクトのメモリ、Claude 固有のルール：CLAUDE.md を優先します
• どのプロジェクトでも共通する作業上の好み：global/user レベルの設定に入れることを優先します
• 現在のプロジェクト、技術スタック、アーキテクチャ、コマンド：リポジトリ内の AGENTS.md ／ CLAUDE.md に入れることを優先します
• 個人のローカルな好み：CLAUDE.local.md またはユーザーレベルの memory を優先し、チーム共有ファイルにはコミットしないでください
• Monorepo または複数の技術スタック：ルートディレクトリのファイルと、サブディレクトリにネストしたファイルの組み合わせを検討します

ユーザーがファイル名を指定していない場合：

• 汎用的な標準を求めている場合：AGENTS.md を提案します
• 主に Claude Code を使用している場合：CLAUDE.md を提案します
• 複数のツールを使用している場合：AGENTS.md を基本とし、ツールの対応状況に応じて CLAUDE.md またはシンボリックリンクで互換性を確保することを提案します

Step 2: 必要な参考資料の確認

• ベストプラクティスに関する質問への回答：references/best-practices.md を読みます
• 既存ファイルのレビューまたは評価：references/review-rubric.md を読みます
• ファイルの作成または書き直し：references/templates.md を読みます
• 根拠資料を追跡する必要がある場合：references/source-notes.md を読みます

Step 3: プロジェクトのコンテキストを確認

ファイルの診断または作成を始める前に、必要最小限のコンテキストを確認します。

• 対象ファイル：AGENTS.md、CLAUDE.md、CLAUDE.local.md
• プロジェクト概要：README.md
• 技術スタックとコマンド：package.json、pyproject.toml、Makefile、justfile、Taskfile.yml、pnpm-workspace.yaml
• テストと CI：.github/workflows/、pytest.ini、vitest.config.*、tsconfig.json
• 既存の AI 設定：.claude/、.cursor/rules/、.github/copilot-instructions.md

判断に関係するファイルだけを読みます。指示ファイルを書くために、リポジトリ全体をスキャンしないでください。

Step 4: 出力方法

質問モード

簡潔な日本語で回答し、実際に適用できる判断基準を示します。

结论：...

推荐结构：
- ...

注意事项：
- ...

診断モード

結論と優先度を明確に示す必要があります。

# Agent 指令文件诊断

结论：优秀 / 基本可用 / 需要重构 / 风险较高
成熟度：L0-L6 中的某一级

## 主要问题
1. [P1] ...
2. [P2] ...

## 做得好的地方
- ...

## 优化建议
1. ...
2. ...

## 建议改法
- 保留：...
- 删除：...
- 拆分：...
- 新增：...

具体的な行を特定できる場合は、ファイルパスと行番号を引用します。問題は単なる文章の推敲ではなく、「エージェントの信頼性向上につながるか」という観点で評価してください。

最適化モード

まず簡潔に診断してから、直接編集します。編集の原則：

• 実際にあり、安定していて、全体に適用できる情報を残す
• 抽象的、重複している、古い、細かすぎる、コードから推測しやすい情報を削除する
• 長い SOP、API ドキュメント、スタイルガイドは、「Read when」付きの参照に置き換える
• コマンドはコピーして実行できる実際のコマンドにする
• 厳守ルールは、具体的な間違いを防げるチェックリストにまとめ、MUST ／ MUST NOT は重要な制約のみに使う
• セキュリティ上の境界とリスクの高い操作を明確にする

完了後、変更内容を説明し、よくあるタスクを実際に一度実行して検証するようユーザーに提案します。

作成モード

ユーザーの説明とプロジェクトのコンテキストに基づいてファイルを生成します。情報が足りない場合は、複雑なルールをでっち上げず、控えめで最小限の実用的なバージョンを作成します。

作成時には、次の内容を優先して含めます。

• プロジェクトの簡潔な説明
• 技術スタック
• よく使うコマンド
• アーキテクチャマップ／コードの配置ルール
• 厳守ルールとデフォルトとは異なる慣例
• テストと完了の基準
• セキュリティと権限の境界
• 参考ドキュメントと「Read when」の条件

レビューの原則

• すべての行について、「この行を削除したら、エージェントが間違いを犯しやすくなるか」と考えます
• プロジェクト固有で、自明ではなく、実行可能なルールを書きます
• 「テストを実行する」「通常のビルドを行う」のような曖昧な表現ではなく、正確なコマンドを使います
• ファイルパスと、実際のコードパターンを示す良い例／悪い例を使います
• 段階的な開示で長い内容を扱います。ルートファイルにはルーティング情報と重要な制約だけを記載します
• Global ／ Project ／ Local の 3 層を分け、個人の習慣とプロジェクトの事実を同じ共有ファイルに混在させないようにします
• エージェントが同じ間違いを繰り返した後にルールを追加し、最初から巨大な説明書にならないようにします
• 確実に判定できるチェックはツールに任せ、方針、境界、例外はエージェント向けに記述します
• 指示ファイルをコードとして扱います：プロジェクトの変化に合わせてレビュー、整理し、コミットします