Claude Code 與 Codex 共用專案規則：CLAUDE.md、AGENTS.md 與設定檔

Codex 和 Claude Code 雙修第 3 / 7 篇

本篇是「Codex 和 Claude Code 雙修」系列的第 3 / 7 篇。你可以從系列總覽開始閱讀，也可以直接接著看本文。

同一個 repo 同時用 Claude Code 和 Codex，很容易遇到這種狀況：建置指令改在 CLAUDE.md，測試要求補在 AGENTS.md，過一陣子，兩份規則就對不起來了。

我的解法是先把資訊分成三類：

repo 規則：兩邊都該遵守的事。
client 設定：權限、hooks、MCP、介面行為。
可重用流程：有步驟、腳本和參考資料的 Skills。

三類分開後，大部分內容只需要一份正本。

這是系列第 3 篇。上一篇是Claude Code 與 Codex 功能對照。

共用核心：讓 `CLAUDE.md` 匯入 `AGENTS.md`

兩邊的 instruction file 概念相近，但載入規則不同。與其維護兩份完整副本，我會把跨工具規則放在 repo root 的 AGENTS.md：

# Repository Guidelines

## Commands

- Install: `npm ci`
- Check: `npm run check`
- Build: `npm run build`

## Working agreements

- Preserve unrelated user changes.
- Use existing design tokens; do not hardcode colors.
- Run check and build before handing off.
- Never commit secrets or local environment files.

接著在 CLAUDE.md 匯入它：

@AGENTS.md

# Claude Code notes

- Use project Skills for release and content workflows.
- Ask before running commands that change external services.

@AGENTS.md 是 Claude Code 文件支援的 import 語法。相較於把兩個檔案做成 symlink，這個做法有兩個好處：

CLAUDE.md 可以保留 Claude Code 專屬附註；
對 Windows、壓縮檔和某些 Git 設定比較友善。

Symlink 仍可用，但適合個人且環境一致的 repo。團隊專案應先確認每個開發環境都能正確保留連結。

官方載入規則可參考 Claude Code memory 與 Codex AGENTS.md。

Instruction file 不是安全機制

AGENTS.md 或 CLAUDE.md 裡寫「不要刪資料」，本質上仍是給模型的上下文，不是作業系統層級的禁止規則。

我會把限制分成兩層：

指引層：架構、流程、風格、該跑哪些檢查，寫在 instruction file。
強制層：檔案寫入、網路、指令、credentials，交給 permission rules、sandbox、容器和 CI 權限。

所以我會在規則裡交代原因，再用權限設定和沙箱限制實際能做的操作。只寫一句「不要刪資料」，還不夠放心。

大型 repo：把局部規則放近一點

如果 frontend、API 和 infra 的指令不同，不要把所有細節塞進根目錄。Codex 會依目錄層級讀取 AGENTS.md，較接近目前工作目錄的內容可以補充或覆寫上層規則。

AGENTS.md
apps/
  web/
    AGENTS.md
services/
  api/
    AGENTS.md

根目錄只放全 repo 共識，局部檔案再寫專屬測試、產生碼或部署限制。Claude Code 也支援分層的 memory；實際搜尋與優先順序仍以各自官方文件為準，不要假設兩邊完全相同。

Client 設定：接受兩份格式，不要硬合併

工具執行設定本來就不同，強迫共用只會讓結構更難懂。

設定範圍	Claude Code	Codex
專案	`.claude/settings.json`	`.codex/config.toml`
使用者	`~/.claude/settings.json`	`~/.codex/config.toml`
常見內容	permissions、hooks、plugins	sandbox、approval、MCP、features

Codex 支援受信任專案裡的 .codex/config.toml，並且會與使用者設定和 CLI 參數依優先順序疊加。需要多套個人設定時，Codex 的 profile 會載入 $CODEX_HOME/<name>.config.toml，再用 codex --profile <name> 選取；不要沿用舊文章裡的 [profiles.name] 寫法。

這些檔案只放 client 行為。像「PR 前要跑哪些測試」仍應寫在共用規則，否則換工具後就消失了。

不要再用舊式 prompt 目錄共用工作流

過去常見的對照是：

.claude/commands/
~/.codex/prompts/

這不再是適合新專案的長期方案。Claude Code 已把 commands 的能力併入 Skills；Codex custom prompts 也已標示為 deprecated，官方建議改用 Skills。

如果一段流程需要被反覆呼叫，例如：

發版前檢查；
依專案格式寫部落格；
產生 migration 並驗證；
review 未提交 diff；

就把它寫成 SKILL.md，附上需要的 scripts 和 references。下一篇會處理如何讓同一份 Skill 被兩邊找到。

整理成圖，就是下面這個分法。下一節再看實際的目錄：

flowchart TD
    INFO["repo 裡要記下來的一件事"] --> Q{"這是哪一類資訊？"}
    Q -->|"repo 規則"| AG["AGENTS.md<br/>跨工具規則的一份正本"]
    Q -->|"client 設定"| CFG[".claude/settings.json<br/>.codex/config.toml<br/>兩份格式，不硬合併"]
    Q -->|"可重用流程"| SK["SKILL.md<br/>附上 scripts 和 references"]
    AG -->|"@AGENTS.md 匯入"| CM["CLAUDE.md<br/>再加 Claude Code 專屬附註"]
    AG -->|"依目錄層級讀取"| CX["Codex"]
    CM --> CC["Claude Code"]
    AG -.->|"寫在這裡管不到"| ENF["強制層<br/>permission rules、sandbox<br/>容器和 CI 權限"]
    CM -.-> ENF

共用規則改 AGENTS.md 就好：Claude Code 透過匯入讀到它，Codex 則直接讀取。權限和工具設定還是分開維護；Skills 也能共用一份，兩邊怎麼找到它，下一篇再說。

圖中的虛線提醒的是前面提過的限制：規則檔能交代要求，實際禁止哪些操作，還是要靠 permission rules 和 sandbox。

一個可維護的 repo 結構

最後的目錄大致會長這樣：

repo/
├── AGENTS.md                 # 跨工具 repo 規則
├── CLAUDE.md                 # @AGENTS.md + Claude 專屬附註
├── .claude/
│   ├── settings.json         # Claude client 設定
│   └── skills/               # Claude 的 skill discovery 路徑
├── .codex/
│   └── config.toml           # Codex client 設定
└── .agents/
    └── skills/               # Codex 的 skill discovery 路徑