CLAUDE.md / AGENTS.mdの保守を機械的にチェックする ― 古いパス・重複見出し・肥大化を見つける

CLAUDE.mdやAGENTS.mdに、作業の進め方、参照するドキュメント、テストの実行方法を書いておく。運用を続けるうちに、そこに書かれたパスだけが古くなったり、追記の結果として同じ見出しが増えたり、ファイルが長くなったりすることがあります。

指示の意味や妥当性を確認するには、人間によるレビューが必要です。LLMによるレビューを補助に使う場合もあるでしょう。一方で、存在しないローカルパスや同名の見出しなど、決定論的に点検できる部分は別にあります。

この記事では、その機械的な点検を小さなCLIで行う方法を紹介します。使うのは、公開OSSのagent-rules-linterです。AIが指示を理解して正しさを保証するツールではありません。

目次

CLAUDE.md / AGENTS.mdの保守で、機械的に確認したいこと

たとえば、docs/guide.mdを移動しても、instruction fileの参照だけが以前のまま残ることがあります。別の作業でTesting節を追記すると、既存のTesting節と名前が重なるかもしれません。

どちらも人間が読めば気づける可能性がありますが、指示内容のレビューとは違う確認作業です。文字列として抽出できるパスの存在、同じファイル内の見出し名、行数や大きさの目安を機械で拾い、意味の判断に使うレビュー時間を残す、という分担ができます。

ただし、同名の見出しがあることと、指示内容が重複・矛盾していることは同じではありません。長いファイルが必ず悪いわけでもありません。検出結果は、保守する人が確認するための材料です。

agent-rules-linterでできる点検

agent-rules-linterは、ローカルのinstruction fileを読み、次の項目を確認するNode.js製CLIです。外部依存packageはなく、MITライセンスでソースを公開しています。

  • 抽出できたローカルパスが存在するか
  • 同じファイル内に、正規化後の名前が重複する見出しがあるか
  • 行数と概算token数が、設定した上限を超えるか

読み取ったファイルのbyte数も表示します。ただし、byte数に対する上限チェックはありません。file sizeの点検では、表示されるbyte数と、行数・概算token数の閾値判定を分けて読む必要があります。

導入方法：npm公開packageではなく、GitHubのソースから使う

repoが宣言するNode.js要件は18以上です。npm registryには公開していないsource-only releaseなので、検査するprojectのディレクトリで次のように実行します。

npx github:iwadjp/agent-rules-linter

引数がなければ、現在の作業ディレクトリ直下に存在するCLAUDE.mdとAGENTS.mdを対象にします。どちらもなければ、検査済みとしてPASSを返すのではなく、終了コード2で対象がないことを知らせます。サブディレクトリを再帰的に探す動作ではありません。

ファイルを明示することもできます。

npx github:iwadjp/agent-rules-linter CLAUDE.md AGENTS.md

cloneしたソースでは、bin/agent-rules-linter.jsをNode.jsで実行しても同じCLIを使えます。外部依存packageのinstallは不要です。次のコマンドは、clone先を実際のパスへ置き換え、検査するprojectのディレクトリから実行します。

node "<clone先>/bin/agent-rules-linter.js" CLAUDE.md

npxによるGitHubからの取得にはネットワーク接続が必要で、npmのキャッシュ等への書き込みもあります。これはツール取得時の動作です。取得済みCLIによる点検自体は、LLMやネットワークを使いません。

入力例：存在するパスと、存在しないパスを混ぜる

以下は記事用に作成した架空のサンプルです。実在する利用者のinstruction fileや不具合ではありません。docs/guide.mdだけを用意し、docs/missing.mdは作らないディレクトリで、次のCLAUDE.mdを点検しました。

# Project rules

## Testing
Run npm test.

## testing
Read docs/guide.md and docs/missing.md.

ファイルはUTF-8、LF改行で、最後にも改行を入れています。docs/guide.mdの内容は、末尾改行付きの「# Guide」の1行です。入力に書いたnpm testは、instruction fileに含まれる文字列であり、このCLIが実行するコマンドではありません。

実際の出力：パスはerror、重複見出しはwarning

2026年10月6日に、実装commit d7759e8、Node.js v24.15.0で、clone済みCLIを実行した結果です。出力を都合よく作り直さず、そのまま載せています。Node.js要件の下限を含む全バージョンで試したという意味ではありません。

Agent Rules Linter
Result: FAIL; 1 warning(s)
Failure threshold: error

Scanned files (1):
- CLAUDE.md: 94 bytes, 7 lines, ~24 tokens (estimate)

Findings (2):
- ERROR [broken-path] CLAUDE.md:7 — Local path does not exist: docs/missing.md
- WARNING [duplicate-heading] CLAUDE.md:6 — Duplicate heading: testing (first seen at line 3)

この実行の終了コードは1でした。存在するdocs/guide.mdはfindingにならず、存在しないdocs/missing.mdがerrorとして報告されています。Testingとtestingは正規化後に同名となり、後の見出しがwarningになります。

実行後に入力ファイルの内容が変わっていないことも確認しました。

各checkの意味と、結果を読むときの注意

broken-path：ローカルパスの存在をheuristicで確認する

相対パス、docs/やsrc/などのよくあるディレクトリ名、ファイルらしい表記を、文字列のパターンから抽出します。URLやoption表記、versionのような文字列は除外する処理があります。任意のMarkdownや自然言語を完全に解析するものではなく、抽出に漏れや誤検出があり得ます。

参照先は、現在の作業ディレクトリとinstruction file自身のディレクトリの両方から解決し、その範囲で存在すれば報告しません。たとえばpackages/app/CLAUDE.mdはファイルを明示して点検できます。その内部のdocs/guide.mdについては、project直下だけでなくpackages/app/docs/guide.mdも確認対象になり得ます。

作業ディレクトリの外へ解決される参照は検査しません。「外部への参照に問題がない」と確認した結果ではありません。また、パスが存在しても、内容が正しいこと、目的のファイルであること、リンク先の説明が最新であることまでは分かりません。

duplicate-heading：同じファイルの見出し名を比べる

#から######で始まる見出しについて、前後の空白を除き、連続する空白をまとめ、大文字小文字を正規化して比較します。末尾の飾りとしての#も取り除きます。階層の違いだけでは別の名前として扱いません。

同じファイル内の同名見出しが対象です。別ファイル間の重複、指示内容の重複、同じ意味の別表現を検出するものではありません。意図的に同名見出しを使っている場合もwarningになります。

max-lines / max-tokens：肥大化を確認する目安

既定値は、1ファイルあたり300行、概算3,000 tokensです。上限と同じ値ではなく、超えたときにfindingになります。どちらも既定のseverityはwarningで、閾値は任意に変更できます。

npx github:iwadjp/agent-rules-linter --max-lines 200 --max-tokens 2000 CLAUDE.md

token数は、JavaScriptの文字列長（UTF-16 code unit数）を4で割り、切り上げた概算です。providerやmodelのtokenizerを使った正確なtoken countではありません。特に日本語を含む文章についても、実際のtoken数やcontext使用量を保証しません。byte数から計算しているわけでもありません。

先ほどの短いサンプルでsize checkを確かめるため、上限を5行・10 tokensまで下げた実行も確認しました。これは動作確認用の値であり、日常運用に推奨する上限ではありません。

node "<clone先>/bin/agent-rules-linter.js" --max-lines 5 --max-tokens 10 CLAUDE.md

この実行では、元の2件に加えて次のwarningが報告されました。

- WARNING [max-lines] CLAUDE.md — 7 lines exceeds configured maximum of 5
- WARNING [max-tokens] CLAUDE.md — 24 approximate tokens exceeds configured maximum of 10

size findingをerrorにしたい場合は、--size-severity errorを使います。閾値は保守方針の目安であり、超えたから自動的に指示を削除すべきだ、という判定ではありません。

PASSでもwarningは残る：終了コードとCIでの使い方

既定の失敗条件は--fail-on errorです。warningだけなら、findingを表示したうえでPASS・終了コード0になります。

これを確認するため、別のディレクトリに次のAGENTS.mdを用意しました。UTF-8、LF、末尾改行付きです。

# Rules

## Testing
Use npm test.

## testing
Use npm test.

AGENTS.mdを指定して実行した出力は次のとおりで、終了コードは0でした。

Agent Rules Linter
Result: PASS; 1 warning(s)
Failure threshold: error

Scanned files (1):
- AGENTS.md: 60 bytes, 7 lines, ~15 tokens (estimate)

Findings (1):
- WARNING [duplicate-heading] AGENTS.md:6 — Duplicate heading: testing (first seen at line 3)

同じ入力に--fail-on warningを付けると、finding自体は同じまま、Result: FAIL、Failure threshold: warning、終了コード1になります。この違いも現在のCLIで確認しました。

終了コード 意味
0 設定した失敗条件以上のfindingがない。warningや未検査範囲がないことは保証しない。
1 設定した失敗条件以上のfindingがある。
2 引数不正、対象がない、読み書きの失敗など、CLIの処理を正常に完了できない。

GitHub Actionsでは、repositoryをcheckoutし、Node.jsとnpmが利用できる既存jobに、次のstepを追加できます。専用Marketplace Actionはありません。検査したいprojectを作業ディレクトリにしてください。

- name: Check agent instruction files
  run: npx --yes github:iwadjp/agent-rules-linter --fail-on warning

この例はwarningでもjobを失敗させる運用です。READMEのCI例に、非対話実行用の--yesを付けています。この記事ではGitHub Actionsのjob自体を実行したわけではなく、失敗条件と終了コードの動作をローカルで確認しています。

再現性が必要な運用では、GitHub参照を確認済みのcommitに固定する方法もあります。特定のinput fileを必須にしたい場合は、CLAUDE.mdやAGENTS.mdを引数に明示してください。無指定の自動検出では、片方だけ存在すればその1ファイルを検査します。

出力形式と、read-onlyの範囲

既定のterminal形式のほか、--format markdownでMarkdownをstdoutへ出せます。--outputを指定すると、形式指定にかかわらずMarkdownレポートをファイルへ書き出します。

npx github:iwadjp/agent-rules-linter --format markdown CLAUDE.md
npx github:iwadjp/agent-rules-linter --output report.md CLAUDE.md

Markdownには、結果・失敗条件・token概算方法・対象ファイルの表・findingの表が含まれます。両方の出力方法をサンプルで確認しました。error findingのあるサンプルでは、report.mdを書き出した場合も終了コードは1のままです。

通常のstdoutへの点検出力は、対象ファイルやrepoを変更しません。指示に書かれたコマンドを実行することもありません。ただし、--outputには書き込みがあります。別の既存レポートは上書きできるため、保存先を選んで使ってください。入力ファイルと同じ実体への上書きは拒否し、親ディレクトリがない場合は作成せず、エラーにします。

何を検査しないか：未対応を「問題なし」にしない

  • instructionの意味的な正しさ、有用性、最新性は判定しません。
  • instruction間の論理矛盾や、内容の重複を判定しません。
  • security scanningやsafety監査は行わず、安全性を保証しません。
  • token countはestimateであり、実際のmodelのtoken数ではありません。
  • local path検査はheuristicです。抽出できない表記や、作業ディレクトリの外へ解決される参照は確認済みになりません。
  • instruction fileを自動修正、分割、書き換えしません。LLM連携やhosted serviceもありません。

このCLIには、対象外の各記述についてNOT_CHECKEDと表示する仕組みはありません。PASSは、認識できた検査項目の結果が失敗条件に達しなかったという意味です。instruction file全体の正しさや、拾われなかった記述の妥当性を確認したものではありません。

どういう位置付けで使うか

instruction fileを変更したときにCLIを実行し、パスや見出し、肥大化のfindingを確認する。その後、人が指示の意味・必要性・矛盾・作業境界をレビューする。そうした保守手順の、最初の機械的な点検として使えます。

warningを出すだけにするか、CIを失敗させるかはprojectの運用に合わせて決めます。意図的な重複見出しや必要な長文まで、数値を満たすためだけに削除しないようにします。

まとめ

CLAUDE.md / AGENTS.mdの保守には、意味を読むレビューと、機械的に確認できる点検の両方があります。agent-rules-linterは、古いローカルパスの候補、重複見出し、行数・概算token数の上限超過を拾うための、小さなCLIです。

findingと未対応範囲を踏まえて、人間のレビューへつなげる使い方を想定しています。ソース、実行方法、tests、制約はGitHubのREADMEを参照してください。この記事の出力例はcommit d7759e8で確認しました。

プログラム開発CLI,CLAUDE.md,AGENTS.md,開発,Node.js

Posted by iwadjp