agentsfile

agentsfile

エージェント指示ファイルは、いつの間にか古くなります。このツールは、説明対象のリポジトリと照合して確認します。

AGENTS.md と CLAUDE.md には、リポジトリの仕組みが記されています。どのファイルが重要か、どのコマンドを実行するか、プロジェクトがどのように構成されているかなどです。リポジトリの変化は、指示ファイルの更新より速く進みます。ディレクトリ名が変更されたり、スクリプトが削除されたり、ガイドが最初から単なるひな形だったりすると、そのファイルに従うエージェントは実行を無駄にするか、ファイルの誤りをでっち上げてしまいます。ファイルとリポジトリを照合する仕組みがないため、こうした問題は表面化しません。

agentsfile はその照合を行います。リポジトリのルートにある AGENTS.md と CLAUDE.md を読み取り、バッククォートで囲まれたパスと、npm、yarn、pnpm のスクリプト参照を抽出して、それぞれを実際のファイルツリーと実際の package.json に照らして確認します。各検出結果には、ファイル名、行番号、該当する正確なテキストが含まれます。出力は決定論的です。検出結果はソートされ、タイムスタンプはなく、同じリポジトリからは常に同じレポートが生成されます。

チェック内容

ルール	深刻度	意味
NO-FILE	高	リポジトリのルートに AGENTS.md も CLAUDE.md もありません。
PATH-MISSING	中	相対パスのように見えるバッククォートで囲まれた文字列が、ファイルとしてもディレクトリとしてもリポジトリ内に存在しません。
SCRIPT-MISSING	中	参照されているスクリプト（npm run <name>、npm test、yarn <name>、pnpm <name> など）が、package.json の scripts に定義されていません。
STUB	低	エージェントファイルは存在しますが、空であるか、5 行未満です。
NO-PACKAGE-JSON	情報	リポジトリのルートに package.json がない（または解析できない）ため、スクリプト参照はチェックされませんでした。

判定ルール：

• VALID：中または高の検出結果はありません。低および情報の検出結果が含まれる場合があります。終了コードは 0 です。
• DRIFT：中または高の検出結果が 1 件以上あります。エージェントファイルの内容がリポジトリと一致していません。終了コードは 1 です。
• MISSING：リポジトリのルートに AGENTS.md も CLAUDE.md もありません。終了コードは 1 です。
• 使用方法のエラーでは終了コード 2 で終了します。読み取り側が出力パイプを早期に閉じた場合、プロセスは 0 ではなく 141 で終了します。

スクリプト参照の詳細：npm run <name> は <name> を直接チェックします。慣例的な短縮形である npm test と npm start（および stop、restart）は、同じ名前のスクリプトに対応します。yarn と pnpm では、<manager> <name> と <manager> run <name> が <name> をチェックします。また、パッケージマネージャー独自の組み込みサブコマンド（install、add、publish など）はスクリプトとして扱われません。

使い方

CLI

# Check the current repo
npx @reneturcios/agentsfile check

# Check another repo, machine readable
npx @reneturcios/agentsfile check ~/src/my-repo --json

# Print the version
npx @reneturcios/agentsfile --version

出力例：

agentsfile check .: DRIFT
  files: 2, findings: 2 (high: 0, medium: 2, low: 0, info: 0)
  summary: 2 agent file(s) checked; 2 finding(s): 0 high, 2 medium, 0 low, 0 info. Verdict: DRIFT.

AGENTS.md:
  [MEDIUM] line 4 PATH-MISSING `src/gone.ts` Referenced path does not exist in the repo: src/gone.ts
  [MEDIUM] line 5 SCRIPT-MISSING `npm run deploy` Script referenced but not defined in package.json scripts: deploy

DRIFT: at least one medium or high finding; the agent files disagree with the repo.

--json を指定すると、ツール、バージョン、対象、判定、件数（ファイル数、検出結果数、深刻度ごとの合計）、検出結果の配列、1 行の要約を含む完全なレポートが JSON として出力されます。チェックに認証情報やネットワークは不要で、対象リポジトリ内のものが実行されることもありません。

対象にはディレクトリの代わりに、単一のエージェント指示ファイルを指定することもできます。この場合、そのファイルのディレクトリがリポジトリのルートとして扱われ、そのファイルだけがチェックされます。

MCP サーバー

npx @reneturcios/agentsfile mcp

MCP クライアントの設定に追加します：

{
  "mcpServers": {
    "agentsfile": {
      "command": "npx",
      "args": ["-y", "@reneturcios/agentsfile", "mcp"]
    }
  }
}

ツール：check_agents_file(path) は、path に指定したリポジトリ（または単一ファイル）のチェックレポート全体を JSON として返します。

制限事項を明確に説明します

• リポジトリのルートにある AGENTS.md と CLAUDE.md のみを読み取ります。このバージョンでは、サブディレクトリ内のエージェントファイルは確認しません。
• 確認する参照は、バッククォートで囲まれた箇所と、npm、yarn、pnpm のスクリプトパターンの 2 種類のみです。フェンス付きコードブロック内のコマンドはスクリプトパターンで検出されますが、バッククォートで囲まれていないフェンス付きブロック内のパスは確認しません。また、リンク、本文中の言及、その他のツールチェーン（make、cargo、go など）のコマンドも対象外です。
• パスの検出は、誠実に説明するとヒューリスティックです。バッククォートで囲まれた箇所は、空白を含まず、http で始まらず、スラッシュを含むか、既知の一覧にあるファイル拡張子らしいドット付きの部分で終わる場合（.env など、既知のドットファイルの一部も含みます）、パスとして扱われます。@、:、*、=、引用符などの文字を含むトークンはパスとして扱われないため、スコープ付きパッケージ名やアクション参照は警告されません。一方で、実際には、珍しいファイル名が見落とされることも、パスのように見える変わったトークンが警告されることもあります。検出結果には常に該当箇所がそのまま引用されるため、人が一目で判断できます。
• 確認するのは存在するかどうかだけです。存在するパスについて、それが正しいファイルかどうかは確認しません。また、存在するスクリプトについて、ガイドに記載された動作をするかどうかも確認しません。
• スタブの判定基準は行数（5 行未満）であり、品質の評価ではありません。短くても実際には完全なファイルは、引き続き低重大度として報告されますが、それだけで判定が変わることはありません。