🧹 技術調査 - agents-lint（AGENTS.md 参照整合性リンタ）

hyuga611/agents-lint は、AGENTS.md / llms.txt / CLAUDE.md などの AI エージェント向け設定ファイルの 参照整合性（reference integrity） を CI で検証するリンタです。文体や表記ではなく、「もう存在しないコマンド・スクリプト・パスを指していないか」という 事実 だけを検査します。本記事は、起点記事（Zenn: agents-lint-reference-integrity）とリポジトリのソースコード（src/check.mjs ほか）を一次情報として構造・データ・構築・利用・運用を整理します。

同名の別ツールに注意: npm レジストリで公開されている agents-lint（giacomo/agents-lint、TypeScript 製）は本記事の対象とは 別物 です。本記事の対象は hyuga611/agents-lint（JavaScript, 依存ゼロ, 132 行）です。両者は名前が同じでも実装・配布経路が異なります（後述）。

調査時点: 2026-07-19 / 対象 commit 0bf2938（main）。本文の行数・出力例・ソース引用はこの時点のものです。main は更新されるため、厳密に再現するときは同 commit を参照してください。

この記事で独自に検証して分かった注意点が 2 つあります。本文の該当箇所で詳述します。

• npm の agents-lint は別プロジェクト（giacomo/agents-lint）。npx agents-lint と打つと調査対象ではない別ツールが動きます。
• bin symlink 経由の起動では何も検査せず exit 0（サイレント成功）。CI ゲートを謳うツールなのに沈黙して通るため、git clone 直実行か GitHub Action での運用が確実です。

概要

agents-lint とは

hyuga611/agents-lint は、AI コーディングエージェント向け設定ファイルを検査するリンタです。

GitHub 上の説明文は次のとおりです。

Reference-integrity linter for AGENTS.md and llms.txt. Catch commands, scripts, and paths that no longer exist. Runs in CI.

何を解決するツールか

AI コーディングエージェントは、AGENTS.md に書かれたコマンドやパスの記述を そのまま信じて実行 します。しかし、リポジトリは変化し続けます。

• npm script をリネームする
• ファイルを移動・削除する
• ディレクトリ構成を変える

この結果、AGENTS.md の記述だけが古いまま取り残されます。この状態を「参照腐敗（stale reference）」と呼びます。参照腐敗が起きると、エージェントは古い指示を信じて 正しいコードに対して誤った操作を再現可能に実行 します。

agents-lint は、この参照腐敗を CI で機械的に検出します。

• npm run build のような記述 → package.json の scripts に実在するか検査
• `src/parser.ts` のようなパス記述 → ファイルシステム上に実在するか検査

存在しない参照が 1 件でもあれば、exit code 1 で CI を失敗させます。

設計思想: 「事実」を検査し、「文体」は見ない

agents-lint の設計思想は一貫しています。

• 検査対象は 事実（参照先が実在するか）のみ
• 表記ゆれ・文法・語調・読みやすさは検査しない

この割り切りにより、実装は依存ゼロ・132 行という小さなコードで完結しています。言語非依存であり、英語で記述が密になりがちなリポジトリでもそのまま機能します。

裏を返すと、次のような「意味的腐敗」は検知できません。

• コマンドやパスは実在するが、指す内容が変わってしまった 場合
• 例: npm run build は今も存在するが、ビルド対象が変わり実際には lint しか走らない

agents-lint が検知できるのは、あくまで 構文的な存在確認（syntactic existence check） に限られます（深掘り論点は「ベストプラクティス」参照）。

AGENTS.md 標準と agents-lint の位置づけ

AGENTS.md は、AI コーディングエージェント向けの指示を書くための、Markdown ベースのオープンフォーマットです。特定の必須構造を持たず、実質的に「エージェント向けの README」として機能します。公式サイト（agents.md）によれば、現在は Linux Foundation 傘下の Agentic AI Foundation が stewarding し、6 万以上の OSS プロジェクトで使われています。読み込み対象とするエージェントには OpenAI Codex、Cursor、Gemini CLI、GitHub Copilot、Jules、Aider などがあります。

Claude Code は AGENTS.md を既定では読みません。 Claude Code が読むのは CLAUDE.md です（AGENTS.md を使う場合は CLAUDE.md からの @AGENTS.md import か symlink が必要）。agents-lint は AGENTS.md / llms.txt に加えて CLAUDE.md も検査対象に含むため、Claude Code 系の運用でも参照整合性チェックの恩恵を受けられます。

ファイル自体が持つ制約は緩いため、記述内容の正しさを保証する仕組みは別途必要になります。agents-lint は、この「記述内容の正しさ」のうち 参照の実在性 だけを担う専用ツールです。

既存の Markdown 系リンタは、いずれも「参照が実在するか」を主目的にしていません。

markdown-link-check は「リンク切れ」を見る点で agents-lint に近い発想です。ただし対象が URL / Markdown リンクに限られ、npm run <script> のようなコマンド参照や、バッククォート中のファイルパス参照までは検査しません。agents-lint は、この隙間（コマンド参照・パス参照の実在性）を埋めるツールです。

他ツールとの比較表

ユースケース別の推奨

特徴

構造

hyuga611/agents-lint の構造を C4 model の 3 段階で整理します。

システムコンテキスト図

agents-lint を中心に、利用者と外部システムとの関係を示します。

コンテナ図

agents-lint 内部を構成要素単位に分解します。

コンポーネント図

scan 関数内部の検査フローと、呼び出し元 main の出力フローを詳細化します。scan は行走査で findings を生成し、main がその findings をファイル単位で出力します。

scan 純粋関数

main 出力処理

データ

agents-lint が src/check.mjs の scan() / main() 内で扱うエンティティを、コード（正規表現・データ構造・分岐条件）から抽出してモデル化します。

概念モデル

検査対象ドキュメント（TargetFile）が保持する行（Line）から、2 種類の参照（ScriptRef / PathRef）を抽出します。各参照は、実行時コンテキスト（ScanOptions が保持する PackageScripts）や定数（ReservedSet / CodeExtPattern）と照合され、不整合があれば Finding を生みます。ScriptRef の不整合には近傍名の Suggestion が付くことがあります。

情報モデル

属性の意味（NULL / 空許容の区別）

構築方法

前提条件

• Node.js（ESM .mjs 実行に対応するバージョン）
• 依存ライブラリはゼロです。node:fs / node:path / node:url の組み込みモジュールのみで動作します。npm install によるパッケージ導入は不要です。

導入手段

配布経路は 3 つの実行パターンに整理して理解すると混乱しません。

hyuga611 版を npm bin 経由で起動すると何も検査せず exit 0 になります（サイレント成功）。 src/check.mjs 末尾の CLI 起動ガードは import.meta.url === pathToFileURL(process.argv[1]).href で「直接実行かどうか」を判定します。npm の bin（agents-lint → src/check.mjs）は symlink で作られるため、symlink 越しに起動すると process.argv[1]（symlink パス）と import.meta.url（実体パス）が一致せず、main() が呼ばれません。手元の検証（macOS / Node v22 / npm bin symlink）では、symlink 経由 = 出力なし・exit 0、node <file> 直接実行 = 検出あり・exit 1 でした。参照整合性を保証するはずのツールが「沈黙して成功」する重大な運用リスクなので、git clone + node src/check.mjs か GitHub Action（node "$GITHUB_ACTION_PATH/src/check.mjs" の直接パス実行）を使ってください。

なお同名で npm 公開されている agents-lint（npx agents-lint で解決される名前）は別プロジェクト giacomo/agents-lint です。両者を取り違えないよう注意してください。

リポジトリを直接使う場合の手順です。

git clone https://github.com/hyuga611/agents-lint.git
cd agents-lint
node src/check.mjs

ビルドステップはありません。src/check.mjs 単体がソースの全体（132 行）であり、コンパイル・バンドルは行いません。

利用方法

入力・挙動

引数はファイルパスのみです。 フラグ（--fix 等のオプション）は存在しません。設定ファイルも持ちません。

CLI

# 引数省略: AGENTS.md / llms.txt / CLAUDE.md を自動検出
node src/check.mjs

# ファイルを明示指定（複数可）
node src/check.mjs docs/AGENTS.md llms.txt

hyuga611 版を npm bin 経由で起動すると前述の symlink 問題で何も検査せず exit 0 になります。ローカル実行は node src/check.mjs の直接パス実行を使ってください（npx agents-lint は別プロジェクト giacomo/agents-lint が動きます）。

GitHub Action

action.yml（composite action）の全文です。

name: 'agents-lint'
description: 'Fail CI when your AGENTS.md / llms.txt points at commands, scripts, or paths that no longer exist.'
author: 'agents-lint'
branding:
  icon: 'check-circle'
  color: 'green'
inputs:
  files:
    description: 'Space-separated files to check. Default: auto-detect AGENTS.md / llms.txt / CLAUDE.md at the repo root.'
    required: false
    default: ''
runs:
  using: 'composite'
  steps:
    - name: Run agents-lint
      shell: bash
      # Pass the caller input via env (NOT ${{ }} expanded into the script) to avoid
      # GitHub Actions template/shell injection. $FILES is intentionally unquoted so
      # multiple space-separated filenames split into separate argv.
      env:
        FILES: ${{ inputs.files }}
      run: node "$GITHUB_ACTION_PATH/src/check.mjs" $FILES

呼び出し側のワークフロー例です（README 一次）。

name: agents-lint
on: [push, pull_request]
jobs:
  agents-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: <you>/agents-lint@v1

inputs.files の使い方です。

• 省略時（デフォルト ''）: CLI 同様に AGENTS.md / llms.txt / CLAUDE.md を自動検出します。
• 指定時: スペース区切りで複数ファイルを渡せます。例: files: 'docs/AGENTS.md llms.txt'。

$FILES を env 経由で渡しテンプレート展開せず unquoted で使う設計は、GitHub Actions のテンプレート / シェルインジェクション対策です。

exit code

検出例

examples/AGENTS.sample.md は、意図的に不整合を含むデモ用サンプルです。要点は次の 3 箇所です。

- ビルド: `npm run build`
- パーサ: `src/parser.ts`
- テスト: `test/run.mjs`

npm run poc（package.json の script、実体は node src/check.mjs examples/AGENTS.sample.md）を実行すると、次の結果になります。

✗ examples/AGENTS.sample.md — 3 件
  examples/AGENTS.sample.md:8	`npm run build` — package.json に script "build" がありません
  examples/AGENTS.sample.md:14	参照 `src/parser.ts` が存在しません
  examples/AGENTS.sample.md:15	参照 `test/run.mjs` が存在しません

agents-lint: 3 件の参照エラー

exit code は 1 です。src/parser.ts と test/run.mjs は、この検出デモのための架空のパスです。リポジトリの実ファイルではありません。

近傍提案（Levenshtein 距離 2 以内で似た script 名をヒント表示する機能）は、この build / poc の組では距離が 2 を超えるため表示されません。この機能自体は実在し、例えば package.json に scripts.poc があり本文に npm run pcs のような 1〜2 文字違いの参照があった場合、次のように近傍候補を提示します。

`npm run pcs` — package.json に script "pcs" がありません（"poc" では？）

GITHUB_ACTIONS=true 環境で実行すると、上記の stderr 出力に加えて、findings ごとに次の workflow command が stdout に追加されます。

::error file=examples/AGENTS.sample.md,line=8::`npm run build` — package.json に script "build" がありません

これが GitHub Actions の PR 上でのインライン注釈（該当行への赤い ✗ アノテーション）になります。

自リポジトリの AGENTS.md を検査すると、参照はすべて実在するため次のようになります。

node src/check.mjs
# => ✓ AGENTS.md — 参照整合OK
# => agents-lint: すべてOK
# exit code: 0

運用

CI での継続運用

agents-lint は GitHub Action として組み込み、PR ごとに自動実行します。

name: agents-lint
on: [push, pull_request]
jobs:
  agents-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: <you>/agents-lint@v1

• on: [push, pull_request] で全 push / PR に反応します。
• 検査対象は既定で AGENTS.md / llms.txt / CLAUDE.md を cwd から自動検出します。
• inputs.files（スペース区切り）を指定すると、検査対象ファイルを追加・変更できます。

      - uses: <you>/agents-lint@v1
        with:
          files: 'AGENTS.md docs/AGENTS.md'

参照エラーがあると exit 1 でジョブが失敗します。ブランチ保護でこの check を必須化しておけば、結果としてマージがブロックされます。PR 上ではインライン注釈で該当行が示されます。この注釈は GITHUB_ACTIONS === 'true' のときだけ出力されます。ローカル実行や他 CI では stderr のみです。

self-CI パターン

agents-lint 自身のリポジトリは、自身の AGENTS.md を自身の Action で検査する self-CI 構成を採っています。

jobs:
  agents-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./          # 自分自身を uses: に指定
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: node --test

• uses: ./ でリポジトリ直下の action.yml を参照します。ローカルの composite action をそのまま CI で使う最小の動作確認になります。
• agents-lint job（自己検査）と test job（node --test によるユニットテスト）は分離して実行されます。
• 導入先リポジトリでも、この self-CI パターン（自リポの AGENTS.md を自 Action で検査）をそのまま踏襲できます。

監視観点

ベストプラクティス

• AGENTS.md の変更とコード変更は同じ PR でレビューする。 指示（AGENTS.md）と実装（コード）が別 PR に分かれると、レビュー時点でのドリフト検知が遅れます。agents-lint は「存在するかどうか」しか見ないため、レビューでの整合性確認と併用が前提です。

• パス参照はバッククォートで囲む。 scan はバッククォート `...` で囲まれたトークンのみを走査対象にします。囲まないプレーンテキストのパスは検査されません。

  誤: 設定ファイルは src/config.yml を参照してください。
  正: 設定ファイルは `src/config.yml` を参照してください。
  

• npm script 参照は npm run <name> 形式で書く。 npm run / pnpm run / yarn run / bun run / pnpm <script> / yarn <script> の各表記に対応しています。install・ci・exec などの組み込みサブコマンド（RESERVED）は package.json に定義がなくても finding になりません。

• monorepo / workspace 構成には限界がある。 loadScripts は cwd 直下の package.json の scripts しか読みません。サブパッケージ（packages/*/package.json）の script 参照は検証対象外です。ルート以外のパッケージを扱う AGENTS.md では、この限界を運用上の前提として明記しておきます。

• 「意味的腐敗」は本ツールのスコープ外と理解して運用する。 agents-lint が検査するのは「参照先が存在するか」だけです。パスやコマンドが実在していても、実装変更で意味・挙動が変わった（例: npm run build の中身が別処理に差し替わった）ケースは検出できません。この種のドリフトは以下の補完策を併用で検討します。

  • テストによる挙動の担保
  • 人間レビューでの指示内容の再確認
  • リンク先ドキュメントの内容検証（remark AST によるコードブロック内 commands/paths 抽出、llms.txt のリンク 404 チェックは README Roadmap に記載があるが 未実装）

• 他リンタと役割分担して併用する。 agents-lint は「参照整合性（事実）」のみを見ます。「文体・表記」は textlint や markdownlint、Markdown 内リンクの死活は markdown-link-check が担当領域です。これらは agents-lint と競合しないため、同じ CI ワークフロー内に別 step として並べる配置が自然です。

  jobs:
    lint:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: <you>/agents-lint@v1
        - run: npx markdownlint '**/*.md'
        - run: npx markdown-link-check AGENTS.md
  

Roadmap（README 一次）

現時点で実装済みの機能と、未実装の計画を区別して把握しておきます。

トラブルシューティング

まとめ

agents-lint は、AGENTS.md / llms.txt / CLAUDE.md が参照する npm script とファイルパスの実在性だけを CI で検査し、参照腐敗した「嘘の指示」をマージ前に落とす依存ゼロのリンタです。文体や意味的腐敗は対象外という割り切りで 132 行に収まる一方、npm 名前空間の別ツールとの混同や、bin symlink 経由起動で何も検査せず exit 0 になる挙動には注意が必要で、git clone 直実行か GitHub Action での運用が確実です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 概要 / 標準
  • agents-lint（GitHub, hyuga611）
  • Zenn: あなたの AGENTS.md、もう存在しないコマンドやパスを指してませんか？（起点記事）
  • AGENTS.md（公式サイト）
• 構造 / データ（ソース）
  • src/check.mjs（本体）
  • action.yml（GitHub Action 定義）
  • test/check.test.mjs（ユニットテスト）
  • package.json
  • examples/AGENTS.sample.md
• 併用ツール
  • textlint
  • markdownlint
  • markdown-link-check
• 同名の別ツール（区別のため）
  • giacomo/agents-lint（TypeScript, npm agents-lint の実体, 別プロジェクト）