用 Claude Code 一段時(shí)間后，會(huì)發(fā)現(xiàn)真正決定它"好不好用"的，不是模型本身，而是 .claude/ 目錄里那幾個(gè)文件

01 兩個(gè) .claude/ 目錄

.claude/ 不是一個(gè)目錄，是兩個(gè)，作用域和職責(zé)完全不同

1.1 用戶級(jí)~/.claude/

跟著登錄用戶走，所有項(xiàng)目共享。放全局偏好——模型默認(rèn)值、個(gè)人快捷指令、跨項(xiàng)目的記憶

典型目錄結(jié)構(gòu)：

~/.claude/
├── settings.json          # 全局配置（model / theme / env / permissions）
├── CLAUDE.md              # 全局指令（所有項(xiàng)目都會(huì)加載）
├── commands/              # 全局 slash 命令
├── agents/                # 全局 subagent
├── skills/                # 全局 skill
└── projects/<sanitized-cwd>/
    ├── *.jsonl            # 會(huì)話 transcript
    └── memory/            # 自動(dòng)記憶系統(tǒng)

projects/ 下面那一坨是 Claude Code 自動(dòng)維護(hù)的"賬本"，不需要手動(dòng)碰，但知道它在哪能解決很多奇怪問題——比如想看上次那次會(huì)話到底發(fā)了什么，直接讀 jsonl 就行

1.2 項(xiàng)目級(jí).claude/

放在項(xiàng)目根目錄，只在這個(gè)項(xiàng)目里生效。是給團(tuán)隊(duì)成員或這個(gè)倉庫定制專屬行為的地方

<project>/.claude/
├── settings.json          # 項(xiàng)目共享配置（建議提交到 git）
├── settings.local.json    # 個(gè)人覆蓋（應(yīng)該 gitignore）
├── commands/              # 項(xiàng)目專屬 slash 命令
├── agents/                # 項(xiàng)目專屬 subagent
├── skills/                # 項(xiàng)目專屬 skill
└── rules/                 # 按主題拆分的規(guī)則模塊

加載優(yōu)先級(jí)：用戶級(jí) → 項(xiàng)目級(jí) settings.json → 項(xiàng)目級(jí) settings.local.json

git 提交建議：

一個(gè)常見誤區(qū)：把所有自己的偏好都堆到項(xiàng)目 settings.json 里，結(jié)果跟同事發(fā)生 git 沖突。個(gè)人偏好走 settings.local.json，團(tuán)隊(duì)約定才走 settings.json。

02 配置文件

2.1 settings.json

常用頂層 key：model / theme / env / permissions / hooks。重點(diǎn)說 permissions，它的語法變體最多也最容易寫錯(cuò)：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-opus-4-8",
  "permissions": {
    "allow": [
      "Bash(pnpm *)",                    // pnpm 全部子命令（空格 + 通配）
      "Bash(git add:*)",                 // git add 任意參數(shù)（冒號(hào) + 通配）
      "Read", "Edit", "Grep", "Glob",    // 工具名直寫 = 全放行
      "WebFetch(domain:github.com)",     // 僅放行指定域名
      "Skill(commit)",                   // 放行某個(gè) skill
      "mcp__ide__getDiagnostics"         // 放行某個(gè) MCP 工具
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

加 $schema 后，VS Code、Cursor 這類編輯器會(huì)給字段補(bǔ)全和拼寫校驗(yàn)——權(quán)限規(guī)則寫錯(cuò)比代碼寫錯(cuò)更難察覺，寫一次就值回票價(jià)

幾條原則：

• 最小權(quán)限：只放行項(xiàng)目實(shí)際用到的命令，不要寫 "Bash(*)" 一把梭
• 不放行任意代碼執(zhí)行類：python、bash、npm run * 這種，收益小、安全代價(jià)大
• 危險(xiǎn)命令顯式 deny：rm -rf、git push --force、git reset --hard，讓 Claude 每次都彈確認(rèn)

一個(gè)常見的安全盲區(qū)：Read(./.env) 阻止內(nèi)置 Read 工具讀 .env，但同時(shí)放行了 Bash 的話，cat .env 照樣能讀到——Read/Edit 的 deny 規(guī)則只約束內(nèi)置文件工具，不約束 Bash 子進(jìn)程。要做嚴(yán)格的路徑隔離，需要啟用 sandbox

2.2 settings.local.json

跟 settings.json 同結(jié)構(gòu)，用法差異只在一條：它必須進(jìn) .gitignore。Claude Code 自動(dòng)創(chuàng)建它時(shí)已經(jīng)做了這件事，你只要?jiǎng)e去掉就行

適合放：本地路徑的環(huán)境變量、個(gè)人調(diào)試用的臨時(shí)權(quán)限、個(gè)人偏好的 model 切換

2.3 CLAUDE.md

.claude/ 目錄之外但跟它密切相關(guān)的文件——它會(huì)被自動(dòng)注入到每次對(duì)話的 system prompt

項(xiàng)目級(jí) CLAUDE.md 建議按五塊來組織（參考京東內(nèi)部一位同事的歸納）：

• 項(xiàng)目結(jié)構(gòu)：核心目錄在哪、源碼軟鏈指向哪、自動(dòng)生成的文件在哪。不告訴 AI 這個(gè)，它會(huì)反復(fù) find，浪費(fèi)時(shí)間也浪費(fèi) token
• 參考項(xiàng)目：本倉庫借鑒或?qū)φ盏钠渌?xiàng)目放在哪個(gè)本地路徑，讓 AI 直接對(duì)照源碼，而不是憑印象生成
• 架構(gòu)骨架：幾句話講清楚這個(gè)項(xiàng)目要干什么、關(guān)鍵模塊的職責(zé)，讓生成的代碼符合整體規(guī)劃
• 編碼規(guī)則：注釋語言、命名風(fēng)格、空行處理、特定語言的 idioms——AI 在不同模型間風(fēng)格漂移很大，靠這一節(jié)穩(wěn)住
• 編譯與調(diào)試：構(gòu)建命令、運(yùn)行環(huán)境差異（如 Docker 容器內(nèi) vs IDE 終端的路徑不一致）、是否允許 AI 自動(dòng)跑編譯

不要放：

• 通用工程實(shí)踐（“寫注釋”、“加單元測(cè)試”——模型已經(jīng)知道）
• 文件目錄樹（模型可以自己 ls）
• 會(huì)過時(shí)的臨時(shí)狀態(tài)（“目前我們正在重構(gòu) X”）

經(jīng)驗(yàn)：CLAUDE.md 越短越好用。150 行以內(nèi)能 hold 住，超過 200 行有效信息會(huì)被稀釋，遵循度明顯下降

還有一條比"寫什么"更重要的建議——寫"不要做什么"比"要做什么"更重要。模型默認(rèn)行為已經(jīng)夠好，CLAUDE.md 真正的價(jià)值在糾偏：明確禁止用 npm、明確禁止 any 類型、明確禁止改某個(gè)配置文件，這類硬約束比"請(qǐng)遵循 SOLID 原則"有用一萬倍

03 擴(kuò)展能力

.claude/ 下真正能改變 Claude Code 行為的幾類對(duì)象，按使用頻率排序：

3.1 commands/ — 自定義 slash 命令

每個(gè)文件是一條 /foo 命令：

• 路徑：<scope>/.claude/commands/<name>.md
• 子目錄變成命名空間：commands/git/commit.md → /git:commit
• 文件正文是 prompt 模板
• 可選 YAML frontmatter：description、argument-hint、allowed-tools、model 等
• 模板里可用 $ARGUMENTS 占位用戶傳入的參數(shù)
• !some-shell-command 前綴會(huì)先執(zhí)行 shell 命令，輸出內(nèi)容嵌進(jìn) prompt
• @path/to/file 引用文件內(nèi)容

適合"重復(fù)性強(qiáng)、模板化、自己每次說一段長 prompt 嫌煩"的場(chǎng)景，比如 /new-post 思考 標(biāo)題 直接生成草稿

3.2 agents/ — Subagents

帶獨(dú)立上下文的"子 Claude"：

• 路徑：<scope>/.claude/agents/<name>.md
• frontmatter 必填 name、description；可選 tools（工具白名單，缺省繼承全部）、model
• 文件正文是這個(gè) agent 的 system prompt
• 主對(duì)話可顯式 Agent(...) 調(diào)用，也可基于 description 自動(dòng)委派
• 每次調(diào)用是全新上下文，主對(duì)話只看到 agent 的最終回復(fù)

什么時(shí)候用：

• 任務(wù)讀大量文件，但你不想這些 token 占主對(duì)話上下文
• 任務(wù)有專門的 system prompt（安全審查、性能分析），跟主對(duì)話調(diào)性不同
• 想并行——一次發(fā)出多個(gè) subagent 同時(shí)跑

3.3 skills/ — 漸進(jìn)披露的能力包

看起來跟 subagent 像，機(jī)制完全不同：

• 路徑：<scope>/.claude/skills/<name>/SKILL.md——注意是目錄，可以帶腳本、模板、參考資料等附屬文件
• SKILL.md frontmatter 至少 name 和 description
• 漸進(jìn)披露：會(huì)話開始時(shí)只注入 frontmatter；正文在 description 匹配用戶意圖時(shí)才被讀入。這跟 subagent 的"全文進(jìn)系統(tǒng)提示"完全不同
• 跟 subagent 的本質(zhì)區(qū)別：skill 在主對(duì)話上下文里展開執(zhí)行；subagent 是另起隔離會(huì)話

適合定義"按部就班的流程"——比如"發(fā) PR 前的 review 步驟"、“生成某類規(guī)范文檔”

3.4 rules/ — 把規(guī)范拆成可維護(hù)的模塊

CLAUDE.md 寫到幾百行就開始失控——信息被稀釋，模型遵循度下降。這時(shí)把內(nèi)容遷到 .claude/rules/ 下，一個(gè)主題一份 markdown，遞歸發(fā)現(xiàn)，多人維護(hù)互不干擾

兩種加載模式：

• 無 frontmatter（或沒有 paths 字段）：?jiǎn)?dòng)時(shí)加載，行為類似 CLAUDE.md
• 帶 paths frontmatter：只在 Claude 處理匹配路徑的文件時(shí)觸發(fā)

例如 .claude/rules/api.md：

---
paths:
  - "src/server/api/**/*.ts"
---

# API 約定
- 所有 handler 必須做輸入校驗(yàn)
- 對(duì)外錯(cuò)誤返回統(tǒng)一結(jié)構(gòu) { data, error }
- 禁止把內(nèi)部堆棧直接返回給客戶端

API 約定只在改 src/server/api/ 文件時(shí)進(jìn)上下文，前端組件改動(dòng)不會(huì)被無關(guān)規(guī)則污染

加載順序：用戶級(jí) ~/.claude/rules/ 先加載，項(xiàng)目級(jí) .claude/rules/ 后加載——后者優(yōu)先，項(xiàng)目規(guī)則不會(huì)被個(gè)人偏好覆蓋

和 CLAUDE.md 的分工：

• CLAUDE.md：項(xiàng)目級(jí)"必備命令 + 關(guān)鍵約定 + 容易踩的坑"，控制在 200 行內(nèi)
• rules/：按主題拆分的模塊化規(guī)范，按需觸發(fā)

模型遵循度的差距來自信息密度——一份 200 行的 CLAUDE.md 加上若干 paths 觸發(fā)的 rules，比一份 1000 行什么都塞的 CLAUDE.md 靠譜得多

3.5 plugins/ — 能力打包

把 commands / agents / skills / hooks 打成一組分發(fā)的形式。本身不在 .claude/<dir> 下展開，而是通過 settings 的 enabledPlugins 字段啟用、或經(jīng)由 plugin marketplace 安裝。適合給團(tuán)隊(duì)下發(fā)一套配套能力，避免每個(gè)倉庫都重新拷貝

3.6 output-styles/ — 主對(duì)話人格

<scope>/.claude/output-styles/<name>.md 定義一份替換主對(duì)話 system prompt 的"風(fēng)格"。通過 /output-style 命令切換。適合在不同場(chǎng)景間切人格——比如代碼評(píng)審模式 vs 教學(xué)講解模式。日常用得不多，了解為主

04 自動(dòng)狀態(tài)

這一節(jié)講的是你不需要手動(dòng)維護(hù)、但應(yīng)該知道存在的部分

4.1 projects/

~/.claude/projects/<sanitized-cwd>/ 下每個(gè) *.jsonl 是一次會(huì)話的完整 transcript。每行一個(gè) JSON，記錄了所有 user/assistant/tool 消息

什么時(shí)候它有用：

• 想分析自己最常用什么命令（參見我之前那篇 fewer-permission-prompts 的例子）
• 想看上次某個(gè) bug 是怎么 debug 出來的
• 想給同事演示"那次操作的全過程"——直接發(fā) jsonl

4.2 memory/

自動(dòng)記憶系統(tǒng)住在 ~/.claude/projects/<sanitized-cwd>/memory/。結(jié)構(gòu)是：

• MEMORY.md：索引文件（每條一行，自動(dòng)加載到上下文）
• <slug>.md：每個(gè)獨(dú)立記憶一個(gè)文件，有 frontmatter

它存的是跨會(huì)話需要保留的、且不能從代碼或 git 推出的事實(shí)——你的角色背景、反復(fù)糾正過的偏好、項(xiàng)目里的非顯性約定

不該存的：代碼片段、文件路徑、git 歷史、臨時(shí)狀態(tài)

05 最小配置

如果你剛開始整理自己的 .claude/，從下面這套起步就夠：

~/.claude/settings.json     # 全局 model + 主題 + 跨項(xiàng)目高頻權(quán)限
~/.claude/CLAUDE.md         # 你的工作風(fēng)格偏好（< 50 行）

<project>/.claude/settings.json        # 項(xiàng)目高頻只讀命令權(quán)限
<project>/.claude/settings.local.json  # 個(gè)人本地覆蓋
<project>/CLAUDE.md                    # 項(xiàng)目命令 + 架構(gòu)骨架 + 隱性約定

commands/ agents/ skills/ rules/ 都不是必備，等你發(fā)現(xiàn)自己反復(fù)在做某件事時(shí)再加。過早配置等于過早優(yōu)化

5.1 完整工作流示例

配好 commands 之后，日常迭代會(huì)變成這樣的鏈條：

Input：實(shí)現(xiàn) X 功能
Claude：（讀 CLAUDE.md 了解項(xiàng)目規(guī)范，按規(guī)范寫代碼）

Input：/review
Claude：（按 review.md 的維度做代碼審查，輸出問題列表）

Input：/lint
Claude：（運(yùn)行 pnpm lint，修復(fù)發(fā)現(xiàn)的問題）

Input：/commit
Claude：（分析改動(dòng)，生成規(guī)范提交信息，執(zhí)行 git commit）

每一步都是可被打斷、可被回滾的小動(dòng)作。比直接說"幫我搞定這個(gè) feature 并提交"靠譜得多，因?yàn)槟Ｐ驮诿恳徊蕉寄玫搅四氵@一刻明確的意圖，不會(huì)"自作主張"地連貫執(zhí)行十幾個(gè)不該連貫執(zhí)行的動(dòng)作

這是 .claude/ 配置的最大價(jià)值——把含混的"AI 幫我寫代碼"拆成一連串明確的、可觀察的、可控制的步驟

06 實(shí)踐經(jīng)驗(yàn)

.claude/ 配好了不等于用得好。下面這幾條，是踩過的坑里能轉(zhuǎn)化為 rule / hook / prompt 習(xí)慣的：

6.1 先注釋再刪代碼

讓 AI 重構(gòu)時(shí)，rule 里默認(rèn)要求用注釋替代刪除，刪除由工程師確認(rèn)后再做。AI 一旦"自信地"刪錯(cuò)文件，回滾成本遠(yuǎn)高于多看一眼注釋行

6.2 環(huán)境差異寫進(jìn) rule

如果開發(fā)、編譯、測(cè)試環(huán)境路徑不一致（典型：Docker 容器內(nèi) /code/... 對(duì) IDE 終端 /data/home/.../code/...），把這個(gè)映射寫進(jìn) CLAUDE.md。貼一段編譯錯(cuò)誤時(shí) AI 能自動(dòng)換算到 IDE 路徑，不用人工對(duì)照

6.3 用腳本而不是裸命令

rule 里告訴 AI 跑測(cè)試用 scripts/test.sh，而不是讓它每次自己拼 pytest --cov=...。腳本化的好處是統(tǒng)一入口，AI 一看就知道系統(tǒng)怎么跑，失敗時(shí)也好定位是流程問題還是代碼問題

6.4 明確"何時(shí)可以編譯"

大型項(xiàng)目編譯幾分鐘到幾十分鐘，讓 AI 寫一點(diǎn)編譯一次會(huì)拖死節(jié)奏。rule 里寫明：只有顯式說"編譯"時(shí)才執(zhí)行——日常生成代碼先攢著，攢完一組任務(wù)再統(tǒng)一編譯

6.5 單測(cè)是反偷懶的杠桿

AI 寫實(shí)現(xiàn)代碼很快，寫單測(cè)時(shí)卻最愛 mock 一切——主分支根本沒被覆蓋。兩條配套習(xí)慣：rule 里要求優(yōu)先覆蓋核心調(diào)用鏈，少 mock；review 單測(cè)時(shí)優(yōu)先看斷言充不充分，而不是看是否通過

6.6 讓 AI 自證

AI 給的方案和代碼不一定對(duì)。懷疑某處不對(duì)勁又說不清時(shí)，直接問"這里是不是不優(yōu)雅？“或"再 review 一下這份設(shè)計(jì)”。模型被反問時(shí)往往會(huì)主動(dòng)承認(rèn)問題，比你自己挑錯(cuò)快。這條不需要寫進(jìn) rule，寫進(jìn)自己的 prompt 習(xí)慣就行

07 結(jié)語

.claude/ 的所有這些文件、目錄、配置項(xiàng)，本質(zhì)上都是在做同一件事：把你和 agent 之間反復(fù)重復(fù)的對(duì)話固化下來

第一次讓它做某件事時(shí)，多說幾句無所謂；第二次還要重復(fù)同樣的話，就該想想是不是該寫成一條 rule、一個(gè) command、一份 skill。用 Claude Code 這類 agent 的核心實(shí)踐原理就一句話：使用過程中不斷增加配置調(diào)教 agent

不要追求一次性配齊完美的 .claude/，那是過早優(yōu)化，等你發(fā)現(xiàn)自己反復(fù)在做某件事時(shí)再加。讓配置跟著真實(shí)使用一起長大，每一條新增的規(guī)則背后都該有一次"我又重復(fù)說了"的不耐煩——那才是它該被沉淀下來的信號(hào)

到此這篇關(guān)于Claude Code 的 .claude 目錄詳解的文章就介紹到這了,更多相關(guān)Claude .claude 目錄內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論