agents-md-setup
讓 AGENTS.md 成為代理與專案說明的唯一真相來源，並透過符號連結（symlink） 讓每個工具都指向同一份檔案。一個檔案，所有代理皆可讀取——無重複，無資訊漂移。
為什麼採用這種佈局
AGENTS.md是跨工具的新興標準（Cursor、Codex 等工具都會讀取它）。- Claude Code 讀取的是
CLAUDE.md。你無法透過提示詞或技能讓其改讀AGENTS.md——但符號連結CLAUDE.md → AGENTS.md可以讓 Claude 打開CLAUDE.md時實際取得AGENTS.md的內容。這便是運作機制；無需其他設定。 - 結果：只需編輯
AGENTS.md；所有代理都會保持同步。
決策：目前已存在哪些檔案？
- 兩者皆不存在 → 根據下方範本建立
AGENTS.md。 - 僅有
CLAUDE.md（真實檔案） → 將其設為真相來源：git mv CLAUDE.md AGENTS.md # 保留歷史記錄（若未追蹤則用 mv） - 僅有
AGENTS.md→ 保持原樣（很好）。 - 兩者皆為真實檔案 → 不要盲目覆寫。比較它們，合併至
AGENTS.md（以它作為正式檔案），若內容不同則先與使用者確認，然後刪除獨立的CLAUDE.md。 CLAUDE.md已經是AGENTS.md的符號連結 → 已完成；停止。
建立符號連結
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md # git 會以真正的符號連結儲存（模式 120000）
確認它以符號連結而非副本的方式提交：
git ls-files -s CLAUDE.md # 模式應為 120000
可選擇性地將其他工具指向同一檔案：
ln -s AGENTS.md GEMINI.md
mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md
Monorepo（Turborepo / workspaces）
在根目錄保留 AGENTS.md 存放倉庫層級的慣例（並如上建立 CLAUDE.md 符號連結），然後在每個需要獨立規範的工作區中分別加入有範圍的 AGENTS.md——例如 apps/<app>/AGENTS.md、packages/<pkg>/AGENTS.md——每個皆附帶自己的同層級符號連結，且需從該目錄內部建立，以使目標為相對路徑：
cd apps/web && ln -s AGENTS.md CLAUDE.md # CLAUDE.md -> ./AGENTS.md（同一目錄）
- Claude Code 會讀取其正在處理檔案最靠近的那個
CLAUDE.md，因此嵌套檔案補充而非取代根目錄。將倉庫層級的事項放在根目錄；只在每個工作區中放置該套件的特定差異——不要重複根目錄的內容。 - 務必讓每個符號連結相對於其自身資料夾（
cd到該工作區後執行ln -s AGENTS.md CLAUDE.md），絕對不要指向回根目錄——相對的同目錄符號連結在簽出或搬移時仍能正常運作。 - Turborepo 本身不會讀取這些檔案（它們是給代理用的），因此無需修改
turbo.json。如果你希望它們能被看見，仍可在根目錄的AGENTS.md中提及此慣例。
README
如果沒有 README.md，請建立一個精簡的（專案名稱、一行描述、設定/執行指令）。將給人類看的文件放在 README.md，代理說明則放在 AGENTS.md——不要將兩者合併。
Windows / CI 注意事項（重要）
Git 符號連結需要 core.symlinks=true，且可能在 Windows 簽出或某些 CI 執行環境中損壞（符號連結會變成一個包含 AGENTS.md 字串的文字檔案）。如果專案目標平台包含 Windows，建議採用備案：一個極小的真實 CLAUDE.md，其完整內容只是一個指標——
See [AGENTS.md](./AGENTS.md) for project + agent instructions.
——並接受它必須手動同步（或透過檢查）。在所有符號連結可靠的環境中，符號連結仍是更好的選擇。
之後不要復原
如果你看到 CLAUDE.md 是 AGENTS.md 的符號連結，那是刻意的——請編輯 AGENTS.md，永遠不要將符號連結替換成副本。
AGENTS.md 範本
# AGENTS.md
提供給在此倉庫中工作的 AI 代理與人類的說明。
`CLAUDE.md` 是此檔案的符號連結；此檔案是唯一真相來源。
## 專案概覽
<這是什麼，1–3 句話>
## 指令
- install: `…`
- dev: `…`
- build: `…`
- test / lint / format: `…`
## 慣例
- <程式碼風格、語言/執行環境、格式化>
- 提交訊息：<例如 Conventional Commits>
- <代理不得做的事，或必須做的事>
## 目錄結構
<主要目錄及其各自存放的內容>