【要約】AGENTS.md を共有したつもりが、Claude Code だけ古い指示を読んでいた [Qiita_Trend] | Summary by TechDistill
> Source: Qiita_Trend
Execute Primary Source
// Problem
開発者が共通の指示ファイル
AGENTS.mdを利用しようとした際、Claude Codeがこれを認識しない問題が発生する。公式の回避策に従っても、環境によっては指示が更新されないリスクがある。- ・Claude Codeは
AGENTS.mdを直接読み込まない。 - ・WindowsのGit Bashで
ln -sを実行すると、リンクではなくコピーが作成される。 - ・コピーの場合、
AGENTS.mdを更新してもCLAUDE.mdの内容が古いままとなる。 - ・エラーが発生しないため、指示の不一致に気づきにくい。
// Approach
筆者はWindowsでのリンク挙動を検証した。安全な回避策として「インポート方式」を推奨している。
- ・
CLAUDE.md内に@AGENTS.mdと記述するインポート方式を採用する。 - ・この方式は実ファイルへの参照として機能し、常に最新の指示が反映される。
- ・
CLAUDE.md内にClaude Code専用の指示を追記することも可能である。 - ・Windows環境では、管理者権限を要するシンボリックリンクを避ける。
// Result
検証の結果、インポート方式で
AGENTS.mdの更新が即座に反映されることを確認した。- ・インポート方式により、指示の二重管理を防ぎつつ同期を実現した。
- ・Windowsでの「静かな失敗」を回避する明確な基準を示した。
- ・
ls -lによるリンク状態の確認方法を提示し、トラブルシューティングを容易にした。
Senior Engineer Insight
> AIエージェントの指示管理は、開発自動化において極めて重要だ。本件のような「エラーが出ない不具合」は、AIの挙動を予測不能にし、深刻なデバッグコストを招く。Windows環境における
ln -sの挙動の違いは、環境構築の自動化において見落としやすい罠である。プラットフォームに依存しない堅牢な手法の選択が、開発体験（DX）の維持には不可欠だ。