AI 相關紀錄 v2｜CLAUDE.md / AGENTS.md 怎麼寫？專案規範與實際範例

上一篇整理了 Claude Code、Codex CLI 與 /init 的一些基本使用方式。

實際開始讓 AI 參與專案開發後，我發現另一個很重要的問題：

每次開新的 Session，都要重新跟 AI 說一次專案規則嗎？

例如：

• 這個專案使用 npm
• 使用 Nuxt 4 + TypeScript
• 不要隨意增加新的套件
• 修改完成後要執行 lint / test
• 某些檔案不能直接修改

如果每次重新開啟 Claude Code 或 Codex 都要再說一次，其實很麻煩。

這時候就可以把這些「AI 長期需要知道的專案規則」整理到 CLAUDE.md 或 AGENTS.md。

CLAUDE.md / AGENTS.md 是什麼？

簡單來說，可以把它們理解成：

寫給 AI Coding Agent 看的專案工作說明。

例如專案：

my-project/
├─ CLAUDE.md
├─ AGENTS.md
├─ package.json
├─ nuxt.config.ts
└─ ...

兩者的用途很接近，但主要使用的工具不同。

它們不是用來取代 README 或完整技術文件，而是整理：

AI 每次進入這個專案工作時，都應該知道什麼？

CLAUDE.md

CLAUDE.md 是 Claude Code 使用的專案指示文件。

例如可以記錄：

• Coding Style
• Build / Test 指令
• 專案架構上的特殊規則
• 套件管理方式
• 工作流程
• AI 經常弄錯的地方

可以使用：

/init

讓 Claude Code分析目前的專案並產生一份初始的 CLAUDE.md，之後再依照自己的需求調整。

不過我不太建議產生後就完全不管它。

真正重要的通常不是「AI 可以從程式碼自己看出來的事情」，而是：

AI 看程式碼不一定能知道，但實際開發時必須遵守的規則。

例如：

## Package Manager

- 本專案統一使用 npm。
- 不要使用 pnpm 或 yarn。

## 開發規範

- 新增程式碼使用 TypeScript。
- 優先沿用現有元件。
- 不要為了簡單功能額外安裝套件。

這類資訊就很適合放進去。

另外，CLAUDE.md 會佔用 Context，所以也不是寫得越多越好。

官方目前建議單份 CLAUDE.md 盡量保持精簡，以 200 行內為目標。如果內容開始變得很多，可以再考慮拆分規則。

AGENTS.md

AGENTS.md 則可以提供 Codex 專案相關的工作指示。

例如：

# Project Guidelines

## Stack

- Nuxt 4
- Vue 3
- TypeScript
- Tailwind CSS
- npm

## Commands

- Development: `npm dev`
- Lint: `npm lint`
- Test: `npm test`
- Build: `npm build`

## Coding Rules

- 使用 Composition API。
- 新增程式碼使用 TypeScript。
- 優先沿用現有元件。
- 不任意增加新的 dependency。

## Validation

完成修改後：

1. 執行 lint。
2. 執行相關測試。
3. 確認 build 正常。
4. 檢查 git diff，避免修改到無關檔案。

除了 Coding Style 以外，也可以告訴 Codex：

• Codebase 怎麼組成
• 哪些目錄負責什麼
• 要怎麼執行測試
• 修改完成後要驗證什麼
• 哪些檔案不能修改
• 特殊的 Business Rule

另外，AGENTS.md 還可以放在不同目錄。

例如：

my-project/
├─ AGENTS.md
├─ frontend/
│  ├─ AGENTS.md
│  └─ ...
└─ backend/
   ├─ AGENTS.md
   └─ ...

根目錄可以放整個專案共同的規則，而子目錄再補上該區域特有的規範。

例如前端要求：

- Vue Component 使用 Composition API。
- Component 使用 `<script setup lang="ts">`。

後端則可能是：

- API 必須使用統一 Response 格式。
- 新增 Endpoint 時需要補上測試。

這樣不需要把所有規則全部擠在同一份文件裡。

到底該寫什麼？

我自己目前會先整理幾種 AI 每次工作都可能需要知道的資訊。

技術

專案使用什麼技術。

例如：

## 技術

- Nuxt 4
- Vue 3
- TypeScript
- Tailwind CSS
- npm

常用指令

例如：

## 常用指令

- 開發：`npm dev`
- Lint：`npm lint`
- Test：`npm test`
- Build：`npm build`

Coding Style

例如：

## Coding Style

- 使用 Composition API。
- 新增程式碼使用 TypeScript。
- 優先使用既有元件。
- 命名方式沿用目前專案風格。

專案規範

一些 AI 單純閱讀程式碼不一定能理解的規則。

例如：

## 專案規範

- API Response 統一使用既有格式。
- 共用元件放在 `components/common`。
- API 型別統一放在 `types/api`。

限制

直接告訴 AI 哪些事情不要做。

例如：

## 限制

- 不要任意增加新的套件。
- 不要修改自動產生的檔案。
- 不要修改與目前任務無關的程式碼。

驗證方式

這也是我覺得很值得寫的一塊。

不要只告訴 AI「要改什麼」，也可以告訴它：

改完之後，要怎麼證明自己沒有改壞？

例如：

## 完成條件

修改完成後：

1. 執行 `npm lint`
2. 執行相關 Test
3. 執行 `npm build`
4. 檢查 git diff
5. 確認沒有修改到與任務無關的內容

怎麼判斷一條規則要不要寫進去？

我自己目前會用一個很簡單的方法判斷：

下一次開新的 Claude Code / Codex Session 時，我還會希望 AI 知道這件事情嗎？

如果答案是「會」，就可以考慮寫進去。

另外還有幾種情況：

• AI 已經不只一次犯同樣的錯
• 每次開新 Session 都要重新提醒
• Code Review 時常出現相同問題
• 新加入專案的人也需要知道
• 這是專案特有規則，AI 無法只靠閱讀程式碼判斷

這些通常都很適合留下來。

不需要一開始就把規則寫到完美

一開始我也會覺得：

那我要不要先把所有規則整理完整？

但後來覺得其實不用。

因為剛開始根本不知道 AI 會在哪些地方出問題。

我現在比較傾向：

先放基本規則
    ↓
實際跟 AI 開發
    ↓
發現問題
    ↓
修正 AI
    ↓
同樣問題可能再次發生
    ↓
補進 CLAUDE.md / AGENTS.md

這樣文件會隨著實際開發慢慢成長，而不是一開始先想像幾十條可能根本用不到的規則。

我的使用方式：任務完成後跟 AI 覆盤

這是我最近自己比較常使用的方式。

有時候跟 AI 完成一個比較大的功能後，我會再問它：

• 這次合作有什麼地方可以改善？
• 有沒有什麼資訊我一直重複提醒？
• 哪些規則值得下一次繼續保留？
• 應該整理到哪一份文件？

雖然這樣會再消耗一些 Token，但對比較長期的專案，我覺得還滿有幫助。

例如今天 AI 使用了：

npm install

但我的專案其實一直都是：

npm

第一次發生時，我可能只會直接糾正它。

但如果同樣的問題一直出現，就可以把它整理成：

## Package Manager

本專案統一使用 npm。

- 不要使用 pnpm。
- 不要使用 yarn。
- 安裝套件使用 `npm add`。

下一個 Session 就不用再重新說一次。

這也是我目前對 CLAUDE.md / AGENTS.md 最大的理解：

它不是一份要一次寫完的文件，而是一份跟著 AI 協作經驗慢慢累積的專案工作規範。

Claude Code 和 Codex 都有用怎麼辦？

如果同一個專案同時使用 Claude Code 與 Codex，很容易遇到另一個問題：

難道 CLAUDE.md 和 AGENTS.md 要維護兩份一模一樣的內容？

目前 Claude Code 本身主要讀取 CLAUDE.md，不會直接把 AGENTS.md 當成自己的專案指示文件。

不過 CLAUDE.md 支援匯入其他文件。

所以如果專案已經把共通規範整理在 AGENTS.md，可以寫：

@AGENTS.md

再另外補充 Claude Code 專用的規則：

@AGENTS.md

## Claude Code

- 大型修改先規劃再實作。
- 修改完成後檢查 git diff。

這樣共通規範只需要維護一份。

例如：

my-project/
├─ AGENTS.md       ← 共通專案規範
├─ CLAUDE.md       ← 匯入 AGENTS.md + Claude 專用規則
├─ package.json
└─ ...

對同時使用多個 AI Coding Agent 的專案來說，我覺得會比較容易維護。

不建議放什麼？

有些內容反而不適合寫進這些文件。

例如：

• API Key
• Password
• Access Token
• .env 實際內容
• 私密憑證
• 單次任務內容
• 與 AI 工作無關的大量文件

尤其 CLAUDE.md / AGENTS.md 很可能會跟著專案一起進入 Git，因此不要把敏感資訊直接寫進去。

Secret 還是應該使用環境變數或適合的 Secret Management 機制處理。

另外，單次任務也不需要留下來。

例如：

今天幫我修改登入頁按鈕顏色。

這種下一個 Session 就沒有意義的事情，直接留在當次 Prompt 即可。

一份簡單的範例

如果是 Nuxt 專案，我可能會先從這樣開始：

# 專案

Nuxt 4 + Vue 3 + TypeScript 專案。

## 技術

- Nuxt 4
- Vue 3
- TypeScript
- Tailwind CSS
- npm

## 開發規範

- 使用 Composition API。
- 新增程式碼使用 TypeScript。
- 優先沿用現有元件。
- 不任意增加新的套件。
- 修改前先理解既有實作方式。

## 常用指令

- 開發：`npm dev`
- Lint：`npm lint`
- Test：`npm test`
- Build：`npm build`

## 限制

- 不要修改自動產生的檔案。
- 不要提交 `.env`。
- 不要修改與目前任務無關的程式碼。

## 驗證

完成修改後：

1. 執行 Lint。
2. 執行相關 Test。
3. 確認 Build 正常。
4. 檢查 git diff。

其實一開始這樣就已經很夠用了。

之後遇到問題，再慢慢補。

小結

目前我會把 CLAUDE.md / AGENTS.md 理解成：

給 AI Coding Agent 的專案工作手冊。

不用一開始就寫得非常完整，也不需要把 README、API 文件、架構文件全部複製進去。

真正值得留下來的是：

• 每個 Session 都需要知道的規則
• AI 無法單靠程式碼推測的資訊
• 經常需要重新提醒的事情
• Coding Convention
• 開發與測試流程
• 專案限制
• 修改後的驗證方式

而我自己目前比較喜歡的做法，是先從一份很小的規則開始。

實際跟 AI 合作 → 發現問題 → 覆盤 → 再把真正值得保留的內容補進去。

比起一開始試著寫出一份「完美的 AI 規範」，這樣反而比較符合實際開發的使用方式。