AI 相關紀錄 v3｜Claude Code `.claude/` / Codex CLI 設定位置：全域與專案設定基本概要介紹

整理 Claude Code 與 Codex CLI 的使用者層級、專案層級設定位置，以及 rules、skills、agents 等目錄的用途。

發布於 2026.09.03W

前面兩篇整理了 Claude Code、Codex CLI，以及：

CLAUDE.md
AGENTS.md

這兩個檔案主要可以用來記錄：

AI 進入專案工作時，需要知道哪些規則？

但實際開始使用之後，還會陸續看到：

.claude/
.codex/
settings.json
config.toml
rules/
agents/
skills/

第一次看到很容易搞混：

這些東西到底要放哪裡？

而且同一個工具有時候還會同時看到：

~/.claude/

以及：

my-project/.claude/

所以這篇先整理一個更基本的問題：

Claude Code 與 Codex 的設定通常放在哪裡？全域設定與專案設定又有什麼差別？

先理解：使用者層級 vs 專案層級

在看 .claude/ 與 .codex/ 之前，我覺得先理解這個概念會比較容易。

Claude Code 與 Codex 都可能同時存在：

使用者層級（Global / 全域）

以及：

專案層級（Project）

簡單理解：

使用者層級
↓
自己的預設設定
可能套用到多個專案


專案層級
↓
只有目前這個專案使用
放專案特有的規則與設定

我會先把它記成：

全域設定 = 我的預設值

專案設定 = 這個專案的特殊需求

例如：

Claude Code

~/.claude/               ← 使用者層級

my-project/
├─ CLAUDE.md
└─ .claude/              ← 專案層級

Codex 則可能是：

Codex

~/.codex/
└─ config.toml           ← 使用者層級

my-project/
├─ AGENTS.md
└─ .codex/
   └─ config.toml        ← 專案層級

這樣之後看到同一個檔名出現在不同位置，就比較不容易混亂。

不同作業系統的使用者設定在哪裡？

前面一直看到：

~/.claude/
~/.codex/

這裡的 ~ 代表目前使用者的 Home 目錄。

所以實際位置會依作業系統不同。

Claude Code

Windows

C:\Users\你的使用者名稱\.claude\

也可以寫成：

%USERPROFILE%\.claude\

例如：

C:\Users\你的使用者名稱\.claude\
├─ settings.json
├─ CLAUDE.md
├─ agents/
└─ ...

macOS

/Users/你的使用者名稱/.claude/

也就是：

~/.claude/

例如：

/Users/你的使用者名稱/.claude/
├─ settings.json
├─ CLAUDE.md
├─ agents/
└─ ...

Linux

Linux 同樣使用：

~/.claude/

通常實際會是：

/home/你的使用者名稱/.claude/

Codex

Codex 的使用者層級設定也是放在 Home 目錄。

Windows

C:\Users\你的使用者名稱\.codex\

也可以表示成：

%USERPROFILE%\.codex\

主要設定檔：

%USERPROFILE%\.codex\config.toml

macOS

/Users/你的使用者名稱/.codex/

也就是：

~/.codex/

主要設定檔：

~/.codex/config.toml

Linux

/home/你的使用者名稱/.codex/

也可以寫成：

~/.codex/

所以看到：

~/.claude/

不用特別去尋找一個叫做 ~ 的資料夾。

它只是代表：

目前登入使用者的 Home 目錄

可以簡單記成：

工具	Windows	macOS / Linux
Claude Code	`%USERPROFILE%\.claude\`	`~/.claude/`
Codex	`%USERPROFILE%\.codex\`	`~/.codex/`

這些位置屬於使用者層級設定，通常會影響這個使用者所使用的多個專案。

而專案自己的設定則仍然放在專案目錄裡，例如：

my-project/
├─ .claude/
└─ .codex/

什麼適合放全域？什麼適合放專案？

假設有一個設定：

我平常使用 Codex 時，希望使用某個預設 Model。

如果這是自己大部分專案都會使用的習慣，就比較適合放在：

~/.codex/config.toml

但如果只有某一個專案需要特殊設定，例如：

不同的 Sandbox
特定 MCP
特定執行方式
專案專用 Agent

那就比較適合放在：

my-project/.codex/config.toml

Claude Code 也是類似概念。

可以先問自己：

這是「我自己的習慣」，還是「這個專案的要求」？

如果換一個完全不同的專案，我還是會想保留這項設定：

→ 比較偏向使用者層級

如果換一個專案就不一定需要：

→ 比較偏向專案層級

Claude Code：`.claude/`

Claude Code 的專案中可能會看到：

my-project/
├─ CLAUDE.md
│
└─ .claude/
   ├─ settings.json
   ├─ settings.local.json
   ├─ rules/
   ├─ agents/
   └─ skills/

不用一開始把所有資料夾全部建立出來。

有需要時再增加即可。

先簡單整理：

位置	用途
`CLAUDE.md`	專案工作規則
`.claude/settings.json`	專案共用設定
`.claude/settings.local.json`	自己在這個專案使用的 Local 設定
`.claude/rules/`	拆分較多的專案規則
`.claude/skills/`	可重複使用的工作流程或能力
`.claude/agents/`	自訂 Agent / Subagent

Claude Code 的使用者層級

除了專案裡面的：

my-project/.claude/

Claude Code 也有使用者自己的設定位置：

~/.claude/

Windows 的 ~ 可以理解為目前使用者的 Home 目錄。

例如大致會落在：

C:\Users\你的帳號\

所以：

~/.claude/

代表的是：

屬於目前使用者，而不是某一個特定專案的 Claude Code 設定。

這裡比較適合放自己跨專案使用的設定。

`.claude/settings.json`

專案中的：

.claude/settings.json

比較適合放：

希望這個專案共同使用的 Claude Code 設定。

例如：

Permission 設定
Plugin 設定
Hook
其他 Claude Code 行為設定

因為屬於專案設定，所以如果是團隊共同使用的內容，也可以跟著 Git 一起管理。

`.claude/settings.local.json`

另外還可能看到：

.claude/settings.local.json

這個比較偏向：

自己在目前這個專案使用的 Local 設定。

也就是說：

settings.json
→ 專案共同設定

settings.local.json
→ 個人在這個專案的設定

例如某個 Permission 只有自己本機開發時需要，就比較適合放在 Local 設定。

這類檔案通常也不適合提交到 Git。

`.claude/rules/`

如果 CLAUDE.md 開始越寫越長，可以把規則拆開。

例如：

.claude/
└─ rules/
   ├─ code-style.md
   ├─ testing.md
   ├─ api-design.md
   └─ security.md

這樣比全部塞進：

CLAUDE.md

更容易整理。

例如可以把：

程式風格
測試方式
API 規則
Security 規則

分開管理。

有些 Rule 也可以依照特定路徑套用，讓不同區域使用不同規範。

`.claude/skills/`

Skill 可以先簡單理解成：

可以重複使用的工作流程或能力。

例如：

.claude/
└─ skills/
   └─ review-code/
      └─ SKILL.md

可能用來處理：

Code Review
檢查 Git Diff
建立 Commit
部署流程
文件產生
專案特有流程

它跟 CLAUDE.md 的差別，可以先這樣理解：

CLAUDE.md
↓
平常工作時持續需要知道的規則


Skill
↓
要執行某種工作時才需要的流程與能力

Skill 的詳細寫法之後再另外整理。

`.claude/agents/`

如果需要建立特定用途的 Agent / Subagent，可以放在：

.claude/agents/

例如：

.claude/
└─ agents/
   ├─ code-reviewer.md
   └─ debugger.md

不同 Agent 可以負責不同工作。

例如：

code-reviewer
↓
只負責檢查問題，不修改程式


debugger
↓
專門調查 Bug

也可以替 Agent 設定不同的：

Prompt
Model
Tool
Permission
工作範圍

詳細用法之後再獨立整理。

`.claude/commands/` 呢？

如果以前有看過 Claude Code 的教學，可能還會看到：

.claude/commands/

例如：

.claude/commands/deploy.md

這種 Custom Command 的方式目前仍然可以使用。

不過現在 Claude Code 已經把這類能力逐漸整合到 Skills。

所以如果是現在才建立新的工作流程，我自己會優先考慮：

.claude/skills/deploy/SKILL.md

而不是特別再建立：

.claude/commands/

舊專案已經有的話不一定需要急著改，新功能則可以優先理解 Skills。

Codex CLI：`.codex/`

Codex 最常看到的使用者設定是：

~/.codex/
└─ config.toml

Windows 通常可以理解為：

%USERPROFILE%\.codex\
└─ config.toml

例如：

C:\Users\你的帳號\.codex\config.toml

config.toml 可以設定 Codex 的許多執行行為，例如：

Model
Reasoning
Sandbox
Approval
MCP
Agent
其他執行設定

Codex 也有專案層級 `.codex/`

這一點我一開始也很容易忽略。

Codex 不只有：

~/.codex/config.toml

也可以有專案層級的：

my-project/
├─ AGENTS.md
│
└─ .codex/
   └─ config.toml

所以可以理解成：

~/.codex/config.toml
↓
自己的 Codex 預設設定


my-project/.codex/config.toml
↓
這個專案的 Codex 設定

如果專案有自己的特殊需求，就不需要全部塞到使用者的全域設定裡。

專案設定可以覆蓋全域設定

假設：

~/.codex/config.toml

設定了自己的預設行為。

但某個專案又有：

my-project/.codex/config.toml

那麼更接近目前專案的設定，可以覆蓋對應的上層設定。

大致可以想像成：

使用者設定
~/.codex/config.toml
        ↓
專案設定
my-project/.codex/config.toml
        ↓
更靠近目前工作目錄的設定

越接近目前工作位置的專案設定，優先度越高。

不過基於安全考量，Codex 需要將專案視為 Trusted，才會載入專案層級的 .codex/ 設定。

`AGENTS.md` 跟 `.codex/config.toml` 有什麼差別？

這兩個也很容易混在一起。

可以先理解成：

AGENTS.md
↓
告訴 Codex「這個專案應該怎麼工作」


.codex/config.toml
↓
告訴 Codex「工具本身應該怎麼執行」

例如：

`AGENTS.md`

比較適合寫：

Coding Style
測試方式
專案架構
修改限制
驗證流程

`.codex/config.toml`

則比較偏向：

Model
Reasoning
Sandbox
Approval
MCP
Agent 設定

所以：

工作規則與工具設定，是兩件不同的事情。

Codex 的 Agent

Codex 目前也可以建立自己的 Agent。

例如：

my-project/
└─ .codex/
   ├─ config.toml
   └─ agents/
      ├─ code-mapper.toml
      └─ browser-debugger.toml

使用者自己的 Agent 也可以放在：

~/.codex/agents/

所以 Agent 同樣可能分成：

使用者 Agent
↓
跨專案使用


專案 Agent
↓
只提供這個專案使用

Codex 的 Rules

Codex 也有 Rules：

.codex/rules/

或使用者層級：

~/.codex/rules/

主要可以用來控制某些 Command 執行時應該：

Allow
Prompt
Forbidden

例如某些 Command 是否可以在 Sandbox 外執行。

不過目前 Rules 仍屬於比較容易隨版本調整的功能，因此如果之後要實際使用，我會再另外確認當下官方文件。

Codex 的 Skill 不在 `.codex/skills/`

這裡也是很容易因為 Claude Code 的結構而直覺猜錯的地方。

Claude Code 的專案 Skill 可以看到：

.claude/skills/

但 Codex 的專案 Skill 目前主要放在：

.agents/skills/

例如：

my-project/
├─ AGENTS.md
│
├─ .codex/
│  └─ config.toml
│
└─ .agents/
   └─ skills/
      └─ my-skill/
         └─ SKILL.md

使用者自己的 Skill 則可以放在：

~/.agents/skills/

所以不要因為：

.claude/skills/

就直覺認為 Codex 一定是：

.codex/skills/

兩邊的資料夾並不是完全一一對應。

Claude Code 與 Codex 簡單比較

到這裡，可以先整理成這樣。

Claude Code

使用者層級

~/.claude/

專案：

my-project/
├─ CLAUDE.md
│
└─ .claude/
   ├─ settings.json
   ├─ settings.local.json
   ├─ rules/
   ├─ agents/
   └─ skills/

Codex

使用者層級：

~/.codex/
├─ config.toml
├─ agents/
└─ rules/

Skill 則另外可能在：

~/.agents/skills/

專案：

my-project/
├─ AGENTS.md
│
├─ .codex/
│  ├─ config.toml
│  ├─ agents/
│  └─ rules/
│
└─ .agents/
   └─ skills/

最後怎麼記比較簡單？

如果一口氣看這麼多路徑有點亂，我自己會先只記兩個概念。

第一個：

使用者層級
= 我自己的預設設定

專案層級
= 這個專案自己的設定

第二個：

CLAUDE.md / AGENTS.md
↓
告訴 AI「這個專案怎麼工作」


.claude/ / .codex/
↓
工具設定與功能擴充

至於：

Agent
Skill
Rules
Permission
Sandbox
Approval

這些都不用在第一次看到時全部搞懂。

我自己也是實際使用到某個功能，再回頭理解它應該放在哪裡。

先把：

規則放哪、設定放哪、全域跟專案差在哪

搞清楚，後面的 Agent、Skill、Rules 就會比較容易理解。

分享這篇

X Facebook LINE Threads