一、CLAUDE.md 配置原則

核心原則：保持簡短

• 控制在 60 行以內(nèi)
• ，硬上限 300 行
• LLM 能可靠遵循約 150-200 條指令，Claude Code 系統(tǒng)提示已占用約 50 條
• 只放 Claude 可能忽略的信息
• ：構(gòu)建命令、測試命令、分支命名規(guī)范、項目特定架構(gòu)決策
• 能從代碼推斷的內(nèi)容不要寫進去
• 規(guī)則太多？拆分到 .claude/rules/ 目錄下按需加載
• 關鍵規(guī)則用標簽包裹
• 防止被忽略
• 運行 /doctor 可檢查 CLAUDE.md 中有哪些內(nèi)容 Claude 其實能自行推導，把冗余指令刪掉

示例：好的 CLAUDE.md 結(jié)構(gòu)

## 工作流
-?每次代碼變更后運行?`npm test`
-?每個任務創(chuàng)建新分支，絕不直接提交到 main
-?使用 Conventional Commits（feat:, fix:, refactor:, docs:）
-?每次提交前運行?`eslint . --fix`
-?完成后通過?`gh pr create`?創(chuàng)建 PR
## 技術(shù)棧
-?Node.js 18+, Express 4.x, PostgreSQL 16
-?測試：Jest + React Testing Library
-?認證：JWT + bcrypt

二、工作流最佳實踐

1. 復雜任務用 Plan Mode

• 按 Shift+Tab 兩次進入計劃模式
• Claude 只研究和規(guī)劃，不寫代碼
• 確認計劃后再切換回正常模式執(zhí)行
• 官方推薦流程
• ：探索 → 規(guī)劃 → 實現(xiàn) → 提交

2. 讓 Claude 先采訪你

• 給出簡單需求描述，讓 Claude 用 AskUserQuestion 工具采訪你
• 它能發(fā)現(xiàn)你忽略的邊緣情況
• 采訪后開新會話執(zhí)行
• （采訪對話會污染上下文）

3. 分階段工作流

• 理解代碼庫 → 修改
• 先規(guī)劃 → 再實現(xiàn)
• 生成 → 驗證
• 不要把所有步驟壓縮到一個大提示詞里

4. 小任務別用復雜工作流

• 3-5 分鐘能完成的事，直接用原生 Claude Code
• 復雜工作流（Superpowers、Workflows 等）適用于多文件、多步驟的大任務
• 重命名變量這種小事，一句話就行

5. 善用 ! 命令的自動響應

• Bash 模式下執(zhí)行命令后，Claude 會自動分析輸出并判斷是否需要行動，不需要額外指示
• 如果你需要聚焦自己讀輸出，可以在 settings.json 中設置 "respondToBashCommands": false

6. 用大模型做大活，用小模型做小活

• 日常編碼
• 用 Sonnet 5（默認模型，1M 上下文窗口，性價比最高）
• 復雜架構(gòu)設計
• 切 Opus 4.8（更高精度）
• 極限推理任務
• 切 Fable 5（最強推理能力）
• 臨時切換：/model claude-fable-5
• 備用模型配置：設置 fallbackModel 防止主模型不可用時卡住

7. 重復性監(jiān)控用 /loop

• /loop
•  讓 Claude 按固定間隔反復執(zhí)行一個任務，適用于：
  • 監(jiān)控部署狀態(tài)：/loop 5m 檢查 staging 部署是否完成
  • 等待外部依賴：/loop 30s 看看 CI 跑完了沒有
  • 定時檢查告警：/loop 10m 檢查日志中有沒有新增的 error
• /loop <間隔> <提示詞>
• ，間隔支持 5m（分鐘）、30s（秒）、1h（小時）
• /proactive
•  是 /loop 的別名，兩者功能相同
• 按 Esc 取消等待中的下一次喚醒
• 注意
• ：/loop 在遠程會話中不會被持續(xù)喚醒，遠程環(huán)境建議用替代方案

8. 輸出復雜結(jié)果用 Artifacts 發(fā)布頁面

• 依賴 project-artifact 插件
• 當終端文字不夠直觀時，讓 Claude 發(fā)布一個交互頁面（Artifact），發(fā)布到 claude.ai 的私有鏈接
• 適用場景：
• PR 走查
  • ：讓 Claude 把 diff 逐行標注發(fā)布為可交互頁面，比看終端輸出直觀得多
• 數(shù)據(jù)儀表盤
  • ：從會話數(shù)據(jù)生成圖表、儀表盤發(fā)布為網(wǎng)頁
• 文檔輸出
  • ：復雜的技術(shù)文檔直接渲染為 HTML 頁面
• 用法：做一個 artifact，用 diff 逐行標注的方式走查這個 PR
  • Claude 會先創(chuàng)建內(nèi)容，然后請求你批準發(fā)布
  • Artifact 會隨著會話更新實時刷新，不需要重復發(fā)布
• 注意
  • ：Artifacts 目前在 Team 和 Enterprise 計劃上 beta 可用

三、調(diào)試與糾錯

1. 粘貼 bug，說"fix"

• 把錯誤信息粘貼給 Claude，說一個字：“fix”
• 不要指導怎么修
• ，不要猜測原因，不要指定解決方案
• Claude 的調(diào)試能力比想象中強，管得越多越容易帶偏
• 直接讓 Claude 修的成功率 80%+

2. 兩次失敗 = /clear

• 同一個問題修正超過兩次，/clear 重新開始
• 上下文污染會降低性能
• 官方建議：修正超過兩次就重啟
• 如果清空后又想找回歷史，可以用 /rewind 回退到 /clear 之前的對話

3. 走偏了？Esc Esc 回滾

• 按兩次 Esc（或 /rewind）直接回滾到上一個檢查點
• 在同一上下文中糾正偏差往往更糟
• 同一個問題偏差兩次？/clear 重啟

4. 要求重寫平庸方案

• 當 Claude 給出能工作但不優(yōu)雅的解決方案時，不要修補
• 說：“知道你現(xiàn)在知道的一切，拋棄這個，實現(xiàn)優(yōu)雅的解決方案”
• 重寫版本通常比修補版本好得多

5. 用 /doctor 做定期健康檢查

• 每隔一段時間運行 /doctor，它會檢查：安裝健康度、未使用的 Skills/MCP/插件、重復的 CLAUDE.md、慢速 Hooks
• 把不用的東西清掉，既省上下文也省 token

6. 配置出問題時用 --safe-mode

• 如果懷疑自定義配置（CLAUDE.md、插件、Hooks 等）導致 Claude 行為異常，用 --safe-mode 啟動
• 所有自定義配置被禁用，能快速定位問題源

四、上下文管理

1. 50% 時手動壓縮

• 上下文使用超過 60-70% 時，性能明顯下降
• 在 50% 時手動執(zhí)行 /compact
  • ，不要等自動壓縮
• 用 /statusline 實時監(jiān)控使用情況
• 或使用 /clear 開新會話
• Sonnet 5 擁有 100 萬 token 窗口，長上下文會話更需要主動管理，不要等到快滿了才壓縮

2. /compact 可指定壓縮策略

# 聚焦 API 變更壓縮
/compact focusing on API changes
# 保留測試相關歷史
/compact keep test-related?history
# 保留錯誤解決歷史
/compact keep error resolution

3. 切換目錄用 /cd 不要用 /clear

• 需要切到項目另一個子目錄繼續(xù)工作時，用 /cd <新路徑>
• 不會破壞提示緩存，上下文窗口不受影響
• 比 /clear + 重新啟動效率高得多

4. Checkpoints（檢查點）

• 每次 Claude 操作自動創(chuàng)建
• 可獨立回滾對話或代碼
• 跨會話持久化
• 不是 git 的替代品

五、Subagents（子智能體）

1. 什么時候該用子智能體

• 當任務可以自然拆分為多個獨立單元時，在提示詞中加 “use subagents”
• 典型場景：代碼審查、大規(guī)模重構(gòu)、多模塊并行開發(fā)
• 子智能體有獨立的上下文窗口，研究、驗證、審查隔離進行，防止污染和偏見

2. 專用子智能體 > 通用 mega-agent

• 創(chuàng)建功能特定的子智能體（如"前端組件智能體"），而不是通用的（如"QA 智能體"）
• 功能越具體，上下文越精準，效果越好
• 子智能體可嵌套最多 5 層，復雜任務可以逐層抽象，但日常使用 1-2 層就夠了

3. 后臺子智能體可以在重啟后自動恢復

• 長時間運行的任務放到后臺執(zhí)行（/bg 或 ←←）
• daemon 升級或重啟后，后臺子智能體會自動恢復，不再丟失進度
• 通過 claude agents 列表查看和管理所有運行中的會話

4. 子智能體有獨立上下文窗口

• 研究、驗證、審查隔離在獨立上下文中
• 防止污染和偏見
• 不污染主上下文

5. 典型用法

# 讓 Claude 自動拆分任務并行處理
> 審查用戶認證模塊，use subagents
# 跨文件批量修改
> 重命名所有文件中的 User 為 Account，use subagents

六、Skills（技能）管理

1. 技能應該是文件夾結(jié)構(gòu)

skills/
? api-design/
? ? SKILL.md ? ? ? ? ?# 主文件：核心規(guī)則和索引
? ? references/ ? ? ? # 語料庫、參考資料
? ? scripts/ ? ? ? ? ?# 輔助腳本
? ? examples/ ? ? ? ? # 示例代碼

• 主文件只包含核心規(guī)則和索引
• 語料庫、檢查表放在 references/
• 漸進式披露
• ：Claude 只在需要時讀取子目錄內(nèi)容

2. 嵌套 Skills 自動按路徑加載

• 把技能放在 .claude/skills/ 的子目錄中，在該目錄下工作時會自動加載
• 名稱沖突時顯示為 <目錄名>:<技能名>，兩者都可訪問
• 最佳實踐：按模塊/領域組織技能目錄，不用把所有技能塞在一個平鋪目錄里

3. 堆疊調(diào)用多個技能

• 一行調(diào)用多個技能：/skill-a /skill-b do XYZ（最多 5 個）
• 適合組合多種專業(yè)技能的復雜任務，不用分多次對話

4. 添加 Gotchas（坑點記錄）部分

這是長期最有價值的技術(shù)：每次 Claude 犯錯時記錄失敗模式，長期積累成為信噪比最高的內(nèi)容。

Gotchas 結(jié)構(gòu)示例

# SKILL.md
## Gotchas（坑點記錄）
### 2026-04-15: API 分頁參數(shù)遺漏
-?**問題**：生成 API 時忘記添加分頁參數(shù)
-?**表現(xiàn)**：返回所有數(shù)據(jù)導致性能問題
-?**修復**：在 SKILL.md 中添加分頁規(guī)則
-?**預防**：檢查清單中增加"是否包含分頁"

Gotchas 維護原則

• 每次犯錯必記錄
• ：不要等，立即記錄
• 包含四個要素
• ：問題描述、表現(xiàn)形式、修復方法、預防措施
• 定期回顧
• ：每周回顧一次，識別重復出現(xiàn)的模式
• 轉(zhuǎn)化為規(guī)則
• ：如果某個坑點出現(xiàn) 3 次以上，轉(zhuǎn)化為正式規(guī)則
• 歸檔已解決的
• ：超過 30 天未出現(xiàn)的問題，移到歸檔區(qū)

七、Superpowers 使用詳解

1. 什么是 Superpowers？

Superpowers 是由 Jesse Vincent 和 Prime Radiant 團隊開發(fā)的 Claude Code 插件，解決工程紀律問題。

核心功能：

• 強制結(jié)構(gòu)化工作流：頭腦風暴 → 分支隔離 → 詳細計劃 → 執(zhí)行
• TDD（測試驅(qū)動開發(fā)）
• 代碼審查
• 系統(tǒng)調(diào)試
• 驗證完成

2. 安裝與配置

# 在 Claude Code 會話中安裝
/plugin install superpowers@claude-plugins-official
# 下次啟動時看到"You have Superpowers"即表示成功

3. 技能激活方式

## Superpowers 工作流規(guī)則
### 新功能開發(fā)
-?使用 /opsx:propose 開始（路由到 OpenSpec）
-?跳過 brainstorming/writing-plans（避免重復）
### 編碼紀律
-?使用 /opsx:apply 時，始終遵循 TDD：先寫失敗的測試，再實現(xiàn)代碼
-?遇到 bug 時，使用 systematic-debugging 技能
-?完成主要實現(xiàn)后，自動觸發(fā) code-reviewer
### 驗證規(guī)則
-?聲稱工作完成前，必須通過 verification-before-completion
-?所有測試必須通過，無跳過測試

5. 四步強制序列

• 頭腦風暴
• ：解決重大架構(gòu)決策（比寫代碼便宜）
• 分支隔離
• ：每個功能在獨立分支上開發(fā)
• 詳細計劃
• ：編寫可審查的計劃文檔
• 執(zhí)行
• ：按計劃實施，每步都有檢查點

6. 管理已安裝的插件

• /plugin list
•  查看所有插件，用 --enabled/--disabled 過濾
• 長時間未用的插件會被提示清理，節(jié)省上下文
• 插件鉤子的標識符匹配規(guī)則：含連字符的鉤子名（如 code-reviewer）現(xiàn)在精確匹配，不會誤觸

八、Spec Kit（OpenSpec）使用詳解

1. 什么是 OpenSpec？

OpenSpec 是 Fission AI 開發(fā)的開源框架，解決需求不匹配問題。將一句話需求擴展為四個結(jié)構(gòu)化文檔。

核心功能：

• proposal.md：為什么、范圍、不在范圍內(nèi)什么（防止 AI 添加未請求的功能）
• specs/：使用 GIVEN/WHEN/THEN 場景的行為規(guī)范
• design.md：技術(shù)決策及推理
• tasks.md：實現(xiàn)清單，每個任務 2-5 分鐘可完成

2. 安裝與配置

# 需要 Node.js 20.19.0+
npm install -g @fission-ai/openspec@latest
cd?your-project
openspec init ?# 選擇 Claude Code
# 創(chuàng)建 openspec/ 目錄，包含 specs/、changes/archive/、AGENTS.md

3. 與 Claude Code 集成

// .claude/settings.json
{
??"mcpServers":?{
? ??"openspec":?{
? ? ??"command":?"npx",
? ? ??"args":?["-y",?"@fission-ai/openspec-mcp"]
? ??}
??},
??"permissions":?{
? ??"allow":?["Bash:openspec:*",?"Bash:npm:*",?"Bash:git:*"]
??}
}

4. 工作流程

# 會話 1：需求 → 規(guī)范
> /opsx:propose 用戶認證 API，Express + MongoDB + JWT
# 生成：
# - openspec/changes/YYYY-MM-DD--proposal.md
# - openspec/changes/YYYY-MM-DD--specs/
# - openspec/changes/YYYY-MM-DD--design.md
# - openspec/changes/YYYY-MM-DD--tasks.md
# 會話 2：規(guī)范 → 實現(xiàn)
> /opsx:apply
# 會話 3：獨立驗證
> /opsx:archive ?# 歸檔當前迭代

5. Delta/Archive 機制

• Delta
• ：每次迭代保留決策歷史
• Archive
• ：歸檔已完成的迭代，保留審計追蹤
• 解決設計決策在迭代中丟失的問題

6. 五大常見陷阱

九、權(quán)限與安全

1. Hooks vs CLAUDE.md

2. Allowlist 減少審批疲勞

{
??"permissions":?{
? ??"allow":?[
? ? ??"Bash(npm run lint:*)",
? ? ??"Bash(npm run test:*)",
? ? ??"Bash(git status)",
? ? ??"Read",
? ? ??"Glob",
? ? ??"Grep"
? ??]
??}
}

3. deny 比 Hooks 更安全

{
??"permissions":?{
? ??"deny":?[
? ? ??"Read(./.env)",
? ? ??"Read(./.env.*)",
? ? ??"Read(./secrets/**)",
? ? ??"Bash(curl:*)"
? ??]
??}
}

• 權(quán)限評估順序：deny → ask → allow
• 設為 deny 后文件對 Claude"不可見"

4. 權(quán)限規(guī)則進階用法

• 參數(shù)化匹配
• ：Agent(model:opus) 可精確禁止 Opus 子智能體
• Glob 模式
• ："*" 在 deny 規(guī)則中匹配所有工具
• 安全強化
• ：破壞性 git 命令（git reset --hard、git checkout -- . 等）自動模式已默認阻止，除非你明確要求
• rm -rf
•  在自動模式下也需要確認

5. --dangerously-skip-permissions 正確使用

重要：應在無互聯(lián)網(wǎng)的隔離環(huán)境中使用。企業(yè)可設置 disableBypassPermissionsMode: true 全局禁用。

十、規(guī)格與實現(xiàn)分離

推薦流程

• Session 1
• ：通過采訪創(chuàng)建規(guī)格
• Session 2
• ：基于規(guī)格實現(xiàn)
• Session 3
• ：獨立驗證

為什么分離？

• 采訪和規(guī)格討論污染上下文
• 新會話有干凈的上下文窗口
• 規(guī)格文檔作為實現(xiàn)依據(jù)
• 驗證會話獨立于實現(xiàn)偏見

十一、Claude Code 常見陷阱（Gotchas）

8 大陷阱

陷阱 1：過早放棄

表現(xiàn)：

我已實現(xiàn)大部分功能。功能在 XX 情況下工作正常。
但 YY 情況下不工作。代碼已充分測試，這是好的開始。

緩解：

• 拆分任務為更小、更隔離的單元
• 即使人類認為可以分組，Claude Code 也需要分離
• 示例：兩個相似表 → 分兩個 PR，每個 10 分鐘完成

陷阱 2：上下文壓縮后變笨

表現(xiàn)：

• 不知道之前看的文件
• 重復之前糾正的錯誤
• 性能明顯下降

緩解：

• 50% 時手動 /compact
• 指定壓縮策略（保留什么）
• 必要時 /clear + git reset --hard
• 如果已經(jīng) /clear 了又想找回之前的對話，用 /rewind

陷阱 3 & 4：測試問題

表現(xiàn)：

• 生成看起來對但失敗的測試
• 修改測試匹配錯誤代碼
• 降低測試標準

緩解：

• TDD 模式：先寫測試
• 仔細審查生成的測試
• 嚴格審查測試變更（比代碼變更更嚴格）

陷阱 5：忘記編譯

表現(xiàn)：

• 測試循環(huán)失敗因為未編譯
• 依賴變更后忘記重新編譯

緩解：

• CLAUDE.md 中明確編譯步驟
• 測試前強制編譯
• 注意：編譯語言 vs 解釋語言混合時特別容易出錯

陷阱 6 & 7：工作目錄和 Git

表現(xiàn)：

• 留下測試腳本、數(shù)據(jù)庫文件
• Git 操作錯誤導致 PR 混亂

緩解：

• 每次完成后 git status 檢查
• 人工執(zhí)行 Git 操作
• （分支、提交、推送）
• Claude Code 只修改文件，不操作 Git

陷阱 8：重寫但不刪除

表現(xiàn)：

• 創(chuàng)建新文件但不刪除舊文件
• 新舊代碼共存導致混淆

緩解：

• 審查 diff 確認刪除
• 明確指示"刪除舊實現(xiàn)"
• 檢查文件列表確認清理

新陷阱：后臺會話意外中斷

表現(xiàn)：

• 后臺會話在 daemon 重啟后消失
• 狀態(tài)顯示異常（一直"Working"或空白）

緩解：

• 更新到最新版本，后臺會話已支持自動恢復
• 如果后臺卡住，在 claude agents 中檢查狀態(tài)
• 通過 claude agents 的過濾功能按狀態(tài)定位問題會話

十二、工具組合策略

Claude Code + OpenSpec + Superpowers 三重棧

解決三個核心問題：

分工明確

OpenSpec 負責：思考 WHAT（構(gòu)建什么、為什么）
Superpowers 負責：確保 HOW（如何構(gòu)建好）
Claude Code 負責：執(zhí)行（編輯文件、運行測試、處理 Git）

配置協(xié)作

# CLAUDE.md 中的路由規(guī)則
## 規(guī)劃階段
-?任何新功能：從 /opsx:propose 開始
-?跳過 brainstorming/writing-plans（避免重復）
## 編碼階段
-?使用 /opsx:apply 時：始終遵循 TDD
-?遇到 bug：使用 systematic-debugging
-?完成實現(xiàn)：觸發(fā) code-reviewer
-?聲稱完成：通過 verification-before-completion

十三、核心原則總結(jié)

上下文是寶貴資源

• 保持簡潔、及時壓縮、污染就重置
• 50% 時手動 /compact
• 兩次失敗 = /clear
• /cd
•  切目錄不破壞緩存
• /rewind
•  可找回 /clear 之前的對話

系統(tǒng)約束 > 提示詞約束

• 用 Hooks 和權(quán)限配置代替"希望 Claude 記住"
• deny
•  比 Hooks 更安全
• 關鍵規(guī)則用標簽包裹
• 定期運行 /doctor 清理冗余

分而治之

• 子智能體、分階段工作流、規(guī)格與實現(xiàn)分離
• 專用子智能體 > 通用 mega-agent
• Skills 按目錄組織、可嵌套加載和堆疊調(diào)用

不要過度工程

• 3-5 分鐘能完成的事，直接用原生 Claude Code
• 復雜工作流適用于多文件、多步驟的大任務
• 重命名變量這種小事，一句話就行

持續(xù)改進

• 每次犯錯必記錄 Gotchas
• 定期回顧，識別重復模式
• 將高頻問題轉(zhuǎn)化為正式規(guī)則
• 用 /doctor 定期清理不用的插件和配置

參考資料

• Claude Code 官方文檔：https://code.claude.com/docs/en
• Claude Code 發(fā)布日志：https://github.com/anthropics/claude-code/releases
• Superpowers 插件：https://github.com/obra/superpowers
• OpenSpec 框架：https://openspec.dev/
• 10 個必備最佳實踐：https://discuss.huggingface.co/t/10-essential-claude-code-best-practices-you-need-to-know/174731
• Claude Code Gotchas：https://www.dolthub.com/blog/2025-06-30-claude-code-gotchas/
• Superpowers 插件詳解：https://www.builder.io/blog/claude-code-superpowers-plugin
• OpenSpec + Superpowers 三重棧：https://www.heyuan110.com/posts/ai/2026-04-09-claude-code-openspec-superpowers/

到此這篇關于Claude Code 最佳實踐完整指南(最新更新)的文章就介紹到這了,更多相關Claude Code最佳實踐內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章，希望大家以后多多支持腳本之家！

最新評論