agents-md-lint

agents-md-lint

コード検索だけで文書化された各事実を再発見しようとするブラインドのサブエージェントを起動して、AI エージェント向けの指示ファイルを監査します。説明的な事実について、実際に発見するためのコストを検証します。コード内に準拠例が見つかっても、規範的な指示は保持します。

これは、コードベースに関するコンテキストを AI エージェントに提供することを目的としたあらゆるファイルで機能します。AGENTS.md、CLAUDE.md、CONVENTIONS.md、.cursorrules などが該当します。このワークフローでは、これらを総称して「指示ファイル」と呼びます。

モード

デフォルト（書き換え）： レポートを作成し、残すべき事実のみを含むよう指示ファイルを書き換えます。

ドライラン： レポートを作成しますが、ファイルは変更しません。ユーザーがコミット前に変更内容を確認したい場合や、「表示するだけでよい」「レポートのみ」「冗長な箇所はどこか」といったことを言った場合に使用します。モードが曖昧な場合は、ステップ 1 の追加・除外ファイルの確認と同じ質問の中で、ユーザーが希望するモードを尋ねます。

ワークフロー

1. 指示ファイルを検出して正規化する

リポジトリ内の指示ファイルをスキャンします。一般的なファイル名：AGENTS.md、CLAUDE.md、CONVENTIONS.md、.cursorrules、.github/copilot-instructions.md。ほかに該当するファイルがあるか、除外するファイルがあるかをユーザーに尋ねます。モードが曖昧な場合は、ユーザーが一度で回答できるよう、モードについての質問とまとめて尋ねます。

指示ファイルの名前変更やシンボリックリンクの作成は、別途依頼された場合にのみ行います。内容を削減しても、検出パスは変わりません。

2. 事実を抽出する

必須の規約、禁止事項、受け入れ条件と、説明的な事実を分けます。前者は、明示的に置き換えられていない限り保持します。コード例は、規則が不要であることの証明にはなりません。説明的な事実はすべて番号付き項目にし、ファイルごとにまとめて列挙します。「事実」とは、単一の主張、規約、指示、または背景情報を指します。たとえば、「テストには vitest を使う」「ブランチ名は feature/JIRA-123 形式にする」「統合テストではデータベースを決してモックしない」などです。

3. 検証用に事実を分割する

一度に多くの質問を与えると、サブエージェントの信頼性が低下します。ファイルに事実が 25 件を超える場合は、20～25 件ずつのバッチに分割し、各バッチに個別のサブエージェントを起動します。各バッチは自己完結させ、ほかのバッチを見なくてもサブエージェントが分野を理解できるだけのコンテキストを含めます。ファイルごとにではなく、すべての指示ファイルのバッチを並列で一度に起動します。

4. ブラインドレビュアーを起動する

説明的な事実の各バッチについて、会話や指示のコンテキストを引き継がない隔離されたサブエージェントを起動し、次のタスクテンプレートを使用します。ここで重要なのは、サブエージェントが指示ファイルにアクセスできず、コード検索で見つけた情報だけを頼りにすることです。問題が発生した場合のデータ損失を避けるため、ファイルの名前変更や移動はせず、無視するファイルをサブエージェントに明示的に伝えます。

You are reviewing the codebase at <REPO_PATH> to test what facts are easily
discoverable from code alone — without any documentation.

IMPORTANT: Do NOT read or search inside these files, as they are the
documentation being audited:
<list of instruction file paths to exclude>

For EACH question below, try to answer using code searches (grep, glob,
reading config/source files). Use up to 3-4 searches per question — check
multiple locations if the first search doesn't find it (e.g., config files,
source code, test files, CI configs). Answer briefly and rate your confidence:

- HIGH: Found clear, unambiguous evidence
- MEDIUM: Found partial or indirect evidence (e.g., an example exists but
  the convention isn't stated, or the fact is buried in a non-obvious place)
- LOW: Could not find evidence, or only found it after extensive digging

For MEDIUM answers, note WHERE you found the evidence and how many searches
it took. This helps distinguish "technically findable but practically buried"
from "right there in the config."

QUESTIONS:
<numbered list of questions, one per extracted fact>

選択したランタイムモデルまたは明示的なレビュアー設定を使用します。検索内容と調査にかかった時間を記録し、指示の自動読み込みによってブラインドレビューが妨げられた場合は、そのことを明記します。

5. 結果を採点する

各サブエージェントの回答を元の事実と比較します。採点では、正確性と実際の発見しやすさの両方を考慮します。コード内に技術的には存在していても、見つけるのに内部事情の知識が必要な事実は、文書化する価値があります。

エージェントの確信度	エージェントの回答は正しいか？	判定
HIGH	Yes	削除候補 — 将来の検索コストが、短い参照先を保持するコストより低い場合に限る
HIGH	Partially	保持 — 不足している詳細のみ
MEDIUM	Yes	保持 — 見つけることはできるが埋もれている。ドキュメントのないエージェントは見落とすか、検索に時間を浪費する可能性が高い
MEDIUM	Partially	保持 — 確実には見つけられない
LOW	—	保持 — 発見できない

6. 結果を提示する

概要表を表示します。

| # | Fact | Confidence | Correct? | Verdict |
|---|------|-----------|----------|---------|
| 1 | Uses vitest for testing | HIGH | Yes | Remove |
| 2 | Branch naming: feature/JIRA-### | LOW | No | Keep |
| 3 | Auth middleware in src/middleware/auth.ts | MEDIUM | Yes | Keep (buried) |

根拠、保持した規約、削除候補、行数の削減、検索コストを報告します。コンテキストの節約だけでは、全体的な効率性を示したことにはなりません。

ドライランモードの場合： ここで終了します。ファイルは変更しないでください。

7. ファイルを書き換える（デフォルトモードのみ）

各指示ファイルを、残す事実だけを含む内容に書き換えます。原則：

• すべての行で、トークンを使う価値を示すこと
• 箇条書きが1つだけの見出しやセクションは作らない（内容を1行にまとめる）
• CONTRIBUTING.md、README.md、設定ファイルに記載されている内容を繰り返さない
• 関連する事実を自然にまとめる
• 可能な限り、元のファイルの文体と構成を保つ — ゼロからの書き直しではなく、不要な部分を削る

ヒント

• 複数の指示ファイルがあるモノレポでは、ファイルごとに個別にテストします。あるサブプロジェクトのコンテキストでは事実を見つけられても、別のサブプロジェクトでは見つけられない場合があります
• 規約（命名規則、ブランチのパターンなど）に関する事実は、Git の履歴に例があっても、通常は発見できません — 残してください
• 認証メカニズムに関する事実は、ミドルウェアの中に埋もれていることがよくあります — 通常は残す価値があります
• 既知の注意点（例：「--forceExit を使う」「DB をモックしない」）は、ほとんど発見できません — 残してください
• ファイルの場所（「テストは tests/ にあります」など）は、ディレクトリ構造から簡単に見つけられることがよくあります — 削除候補として適しています
• 迷った場合は、事実を残してください。指示が欠けてエージェントが誤った動作をするコストは、コンテキストトークンが少し増えるコストよりも高くなります