AGENTS.md × CLAUDE.md:讓 Claude Code 與 VS Code 共用行為規範的實務做法

前篇文章:〈VS Code 專案中如何設置 AGENTS.md 作為 Agent 協作的行為規範〉提及,在 VS Code 生態中,我們可以透過 AGENTS.md 來定義 Agent 的行為規範。雖然 AGENTS.md 已經是多數 AI 開發工具共同採用的標準(由 AAIF 所制定),但 Claude Code 目前仍相當「自成一格」,所有規範都以官方定義為準,社群其實已有多位成員提出改善建議,但目前尚未看到官方回應。😏

目前 Claude Code 並未將 AGENTS.md 視為自動載入的標準檔案。這意味著即便 AGENTS.md 位於儲存庫(Repository)根目錄,Claude Code 也不會因其檔名而主動將其納入推理的上下文(Context)之中。

在 Claude Code 的生態系中,CLAUDE.md(或位於 .claude/CLAUDE.md)才是定義 Agent 行為與技術規範的標準入口。其核心價值在於提供「專案持久化記憶」(Project Memory)—— 這是一份專為 AI 撰寫的「專案說明書」。

一個問題的主要思考:如果這個專案可能會交叉應用 VS Code Copilot 以及 Claude Code 作為 AI 輔助開發的工具,那麼是否可以共用原來 Copilot 所定義好的 AGENTS.md + copilot-instructions.md 行為與技術規格?

👉 先給解決方案:使用 模組化映射(Modular Mapping)

行為與技術規範的模組化映射

VS Code 所使用標準化的 AGENTS.md(以及 copilot-instructions.md),可以透過 Claude Code 的模組化映射(Modular Mapping)方式,以達成相同的效果:

  • 行為中樞:CLAUDE.md ↔ 對應並載入 AGENTS.md(定義 Agent 如何行動)。
  • 技術約束:.claude/rules/ 模組 ↔ 對應並導入 copilot-instructions.md(定義專案技術規格與規則)。

一個基本 Claude Code 的專案規範的目錄結構:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

CLAUDE.md 與 .claude/rules/ 檔案設置

在 ./.claude/CLAUDE.md 中可以使用(@path)導入方式引用 AGENTS.md 檔案。

# Claude Code 專案記憶入口
## Agent 行為規範
@AGENTS.md

此外在 .claude/rules/ 目錄(該目錄所有 .md 檔案會自動載入)下可以有多個技術規範檔案以作為模組化映射。

這裡簡化為只有一個技術規格檔:tech-stack.md,並且讓其映射 copilot-instructions.md 所記載的技術堆疊。

# Tech Stack & Coding Conventions
> 本檔案定義專案的技術約束與開發慣例。
## 核心技術規範
為了維持與專案全域開發標準的一致性,請完整遵循:
- **技術棧與架構約束**:@.github/copilot-instructions.md

驗證 CLAUDE.md 與 rules 的規範設置

利用 VS Code 開啟終端機並執行 Claude Code(CLI)後,在對話欄內輸入:

- 本專案的核心技術規範紀錄在哪一個檔案內?

- 本專案在修改程式碼時需遵循的行為原則?

如果回覆內容確實對應並記載於 .claude/ 資料夾內的 CLAUDE.mdrules/tech-stack.md,即表示以上設置步驟正確,且規範已成功載入。

透過上述配置,我們能完美實現 Claude Code AGENTS.md 的檔案映射,讓專案管理更加自動化。

補充說明

為了方便進一步對照與理解,我已將本文提到的 AGENTS.md、copilot-instructions.md、CLAUDE.md 、tech-stack.md 等相關檔案,整理成一份 Gist,並附上四個實際範例檔案,說明它們在 VS Code Copilot 與 Claude Code 中的角色分工與關係。

留下第一條留言