AGENTS.md 遵循規範

核心原則

AGENTS.md 是專案層級的 AI 工作指南，等同於人類開發者的 README.md，但對象是 AI Agent。

1. 開工必讀：開始任何開發任務前，必須先閱讀專案根目錄的 AGENTS.md。
2. 嚴格遵守：在整個任務週期中，所有產出和行為必須符合 AGENTS.md 中定義的規範。
3. 衝突提示：若使用者的要求與 AGENTS.md 中的內容產生衝突，必須立即提示使用者，並等待使用者決定。
4. 不可擅改：未經使用者明確同意，不得修改 AGENTS.md。若認為需要修改，應先說明修改原因和方向，取得使用者同意後才執行。

AGENTS.md 的用途

AGENTS.md 通常包含以下類型的資訊：

• 技術棧：專案使用的語言、框架和工具
• 資料夾架構：目錄結構與各目錄的用途
• 專案架構：模組設計、依賴關係
• 開發流程：分支策略、測試要求、部署流程
• 編碼規範：命名慣例、程式碼風格
• 禁止事項：不允許使用的套件、模式或做法

操作流程

1. 讀取 AGENTS.md

任務開始後，先確認 AGENTS.md 是否存在，並閱讀完整內容作為本次任務的基本約束。

2. 持續檢查合規性

在產出程式碼或進行任何修改時，持續檢查：

• 使用的技術棧是否符合規範？
• 檔案是否放在正確的目錄？
• 程式碼風格是否符合要求？
• 是否使用了被禁止的套件或模式？

3. 處理衝突

當使用者的要求與 AGENTS.md 衝突時：

⚠️ 衝突提示：
您要求的 [具體行為] 與 AGENTS.md 中 [具體規範] 有所衝突。

AGENTS.md 規定：[引用原文]
您的要求：[使用者要求摘要]

請問要如何處理？
1. 依照 AGENTS.md 的規範執行
2. 依照您的要求執行（本次例外）
3. 更新 AGENTS.md 的規範

4. Claude Code 相容性檢查

IF exists(".claude/") AND NOT exists("CLAUDE.md"):
    提示使用者：
    「偵測到 .claude/ 目錄但沒有 CLAUDE.md。
     建議執行：echo "@AGENTS.md" > CLAUDE.md
     讓 Claude Code 自動讀取 AGENTS.md 的內容。」

ELSE IF exists("CLAUDE.md") AND NOT contains("CLAUDE.md", "@AGENTS.md"):
    提示使用者：
    「偵測到 CLAUDE.md 但未引入 AGENTS.md。
     建議在 CLAUDE.md 中加入一行：@AGENTS.md
     讓 Claude Code 同步遵守 AGENTS.md 的規範。」

與 README.md 的分工

文件	對象	內容
README.md	人類開發者	專案簡介、安裝步驟、使用方式
AGENTS.md	AI Agent	技術棧、架構規範、開發流程、約束

兩份文件各司其職，不應互相取代。

參考

• 各 AI 工具支援狀況