AGENTS.md リンタを118リポジトリに当てたら、記事に書いたフラグが一度も動いていなかった

AGENTS.mdやCLAUDE.mdは時間とともに静かに腐る。「セットアップは npm run build」「エントリは src/index.ts」と書いたまま、リネームや削除でその一文が嘘になる。エージェントやAIアシスタントがそれを信じて手順を実行すると事故る。参照が実在するかだけを検査するリンタ「reflint」を作り、依存ゼロで公開した。バッククォートで書かれたパス、markdownリンク、npm runのスクリプト名を、実際のファイル・package.jsonと突き合わせるツールだ。

興味深いのは公開後の話だ。リポジトリ118本に当てたところ、自分が記事で「使えます」と書いたオプションフラグが一度も機能していなかった。テストは全て緑だったのに、である。原因は、フェンス内かどうかの判定を見ていたのは4つのスキャナのうち1つだけ。残り3つは素通りしていた。さらに、pnpmのワークスペースフラグを「存在しないスクリプト」と報告していたり、コードフェンスの開閉判定が1つずれた瞬間から下全体を「フェンス内」と誤認していたり、禁止文（「このファイルを実行するな」など）をそのまま指摘していたりと、想定外の壊れ方が3つ出現した。自分で書いたテストは自分が想定した壊れ方しか見ない。他人が実際に書いたドキュメント118本が初めて、予期しない使われ方を暴露したのだ。

中小企業でセットアップ手順や技術ドキュメントを書く際、最大のリスクは「書いた時点では正しい」が「半年後には嘘」になることだ。新入社員がそれを信じて半日浪費する。修正も気づかれない。reflint のような参照検査を、社内ドキュメントを扱うCIに組み込むだけで、腐ったドキュメントが本番に行く前に引っかかる。人間の目だけでは限界がある領域である。