精選 Configuration Troubleshooting CLAUDE.md Best Practices

CLAUDE.md 反模式：12 個扼殺生產力的常見錯誤

避免最常見的 CLAUDE.md 錯誤，這些錯誤會讓開發者感到沮喪並浪費時間。學習讓 Claude Code 重回正軌的故障排除技巧。

2026年1月14日 • 12 min read • 作者：Claude World

一個糟糕的 CLAUDE.md 比沒有 CLAUDE.md 更糟糕。當你的配置與你對抗而非協助時，每次互動都會變得令人沮喪。

本指南涵蓋我們見過的 12 個最常見的反模式、它們發生的原因，以及如何修復。我們還會介紹當出問題時的故障排除技巧。

第一部分：12 個反模式

反模式 1：長篇大論

症狀： 你的 CLAUDE.md 超過 500 行，包含你想到的每一條規則。

表現形式：

# CLAUDE.md (847 行)

## 程式碼風格 (217 行)
- 變數使用 camelCase
- 類別使用 PascalCase
- 常數使用 SCREAMING_SNAKE_CASE
- 檔案名稱使用 kebab-case
- 使用 2 個空格縮排，不用 tab
- 每行最多 100 個字元
- 永遠使用分號
- 優先使用 const 而非 let
- 絕對不用 var
... (還有 200 多行)

為什麼有問題： Claude 每次 session 都要處理這些內容。大部分是 Claude 已經知道的通用建議。你在浪費 token，而且可能讓 Claude 錯過重要的內容。

修正方式：

# 程式碼標準
遵循標準 TypeScript 慣例。特定覆寫：
- 使用 4 個空格縮排（不是 2 個）
- 不使用分號（Prettier 會處理）
- 每行最多 80 個字元

詳見 @.eslintrc.js 和 @.prettierrc。

經驗法則： 如果你的 linter/formatter 配置已經涵蓋，就不要在 CLAUDE.md 重複。

反模式 2：過度保護的家長

症狀： 每個動作都需要確認。Claude 不斷請求許可。

表現形式：

# 權限
- 讀取任何檔案前要詢問
- 寫入任何檔案前要詢問
- 執行任何命令前要詢問
- 做任何改變前要詢問
- 絕不假設 - 永遠詢問

為什麼有問題： 這會毀掉生產力。你花在批准動作上的時間比實際工作還多。

修正方式：

# 自主操作（不需確認）
- 讀取專案中的任何檔案
- 在 src/、tests/、docs/ 中建立/修改檔案
- 執行：npm test、npm run lint、npm run build
- 建立本地 git 分支
- 安裝 devDependencies

# 需要確認
- 安裝生產依賴
- 修改 .env 或配置檔
- 推送到遠端
- 刪除檔案
- 執行資料庫遷移

使用 settings.json 進行精細控制：

{
  "permissions": {
    "allow": ["Read", "Write(src/**)", "Bash(npm run:*)"],
    "deny": ["Write(.env*)", "Bash(rm -rf:*)"]
  }
}

反模式 3：空城計

症狀： CLAUDE.md 存在但幾乎沒說什麼有用的。

表現形式：

# CLAUDE.md

這是一個 React 專案。

為什麼有問題： Claude 必須猜測一切 - 你的慣例、技術棧、偏好。每個 session 都從零開始。

修正方式： 至少包含：

# 專案概述
使用 Next.js 14 App Router、PostgreSQL 和 Stripe 的電商平台。

# 技術棧
- Next.js 14（App Router）
- TypeScript（嚴格模式）
- Prisma + PostgreSQL
- Tailwind CSS
- Vitest 測試

# 指令
- npm run dev     # 啟動開發伺服器（port 3000）
- npm test        # 執行測試
- npm run lint    # 檢查程式碼品質

# 目錄結構
src/
├── app/          # Next.js 路由和頁面
├── components/   # 共用 React 元件
├── lib/          # 工具函式
└── services/     # 業務邏輯

反模式 4：複製貼上特餐

症狀： 你複製了別人的 CLAUDE.md 卻沒有理解或調整。

表現形式：

# 來自某個教學
- 使用 Rust 的所有權模型
- 遵循 Elm 架構
- 用 pytest 測試

# 你的實際專案：React + TypeScript

為什麼有問題： 衝突或不相關的指示會讓 Claude 困惑。它可能套用不適合你專案的規則。

修正方式： 從頭開始。回答這些問題：

  1. 這個專案做什麼？
  2. 技術棧是什麼？
  3. 必要的指令有哪些？
  4. 我的具體慣例是什麼？
  5. 哪些操作需要保護？

根據你的答案建立 CLAUDE.md，而不是別人的模板。

反模式 5：時間膠囊

症狀： CLAUDE.md 已經好幾個月沒更新了。它參考了已棄用的模式或舊技術。

表現形式：

# 最後更新：2024-03-15

## 資料庫
使用 MongoDB 和 Mongoose 模型。

# （你在 6 個月前已經遷移到 PostgreSQL）

為什麼有問題： Claude 遵循過時的指示，產生不符合當前架構的程式碼。

修正方式： 排程審查：

# CLAUDE.md
最後更新：2026-01-14
版本：3.2

## 審查觸發條件
- [ ] 主要功能完成後
- [ ] 技術棧變更時
- [ ] 團隊成員加入/離開時
- [ ] 每月審查（每月 1 日）

## 近期變更
- 3.2：從 MongoDB 遷移到 PostgreSQL
- 3.1：新增 API 驗證要求
- 3.0：為 Claude Code v2.0 重構

反模式 6：矛盾製造機

症狀： CLAUDE.md 的不同部分給出衝突的指示。

表現形式：

# 測試
所有功能都必須有單元測試。
目標 90% 覆蓋率。

...

# 快速迭代
跳過測試以進行快速原型開發。
不要讓測試拖慢你。

為什麼有問題： Claude 不知道該遵循哪個指示。行為變得不可預測。

修正方式： 使用明確的優先級和例外：

# 測試（不可協商）
所有功能都必須有單元測試。
新程式碼至少 80% 覆蓋率。

**例外：**
- 以 `_experimental` 為前綴的檔案
- `scripts/` 目錄中的腳本
- 明確指示跳過測試時

反模式 7：術語叢林

症狀： CLAUDE.md 使用 Claude 不知道的內部術語或縮寫。

表現形式：

# 規則
- 所有 PFR 必須通過 QG3
- 服務遵循 BATS 模式
- 對 gateway 層使用 DTO
- 確保 ACME 端點的 FE/BE 一致性

為什麼有問題： Claude 會不可預測地解釋未知術語或完全忽略它們。

修正方式： 定義你的術語：

# 術語表
- PFR：Pull Feature Request（我們對功能分支的稱呼）
- QG3：Quality Gate 3（測試通過、覆蓋率 >80%、無 lint 錯誤）
- BATS：Business-API-Transform-Store（我們的服務層模式）
- DTO：Data Transfer Object（API 邊界的型別介面）

# 規則
- 所有功能分支（PFR）必須在合併前通過 QG3
- 服務遵循 BATS 模式：見 @docs/bats-pattern.md

反模式 8：安全劇場

症狀： 聽起來很厲害但實際上沒有保護任何有意義內容的安全規則。

表現形式：

# 安全
- 絕不使用 eval()
- 不用 innerHTML
- 清理所有輸入
- 使用參數化查詢

為什麼有問題： 這些是 Claude 已經遵循的通用規則。你程式碼庫中的真正安全風險沒有被解決。

修正方式： 專注於你的實際風險：

# 安全（專案特定）

## 支付處理（src/services/payment/）
- 所有 Stripe API 呼叫必須使用 lib/stripe.ts 中的包裝器
- 絕不記錄完整卡號（只記錄最後 4 位）
- PCI 合規：錯誤訊息中不能有卡片資料

## 認證（src/services/auth/）
- JWT 密鑰只能來自環境變數
- Token 有效期：15 分鐘（存取）、7 天（重新整理）
- 速率限制：5 次失敗嘗試 = 15 分鐘鎖定

## 資料處理
- PII 欄位（email、name、address）必須靜態加密
- 對使用者輸入使用 lib/security.ts 中的 sanitize() 輔助函式

反模式 9：微管理者

症狀： 指示太具體，導致 Claude 無法適應邊緣情況。

表現形式：

# 錯誤處理
1. 首先檢查是否為網路錯誤
2. 如果是網路錯誤，顯示「發生網路錯誤」
3. 如果不是網路錯誤，檢查是否為驗證錯誤
4. 如果是驗證錯誤，顯示欄位特定訊息
5. 如果不是驗證錯誤，檢查是否為認證錯誤
6. 如果是認證錯誤，重定向到 /login
7. 否則顯示「發生錯誤」

為什麼有問題： 真實錯誤更混亂。這個僵硬的流程圖在第一個意外情況就會失效。

修正方式： 給原則，而非程序：

# 錯誤處理原則
- 面向使用者的錯誤：友善訊息，不含技術細節
- 開發者錯誤：開發模式下顯示完整堆疊追蹤
- 網路錯誤：建議重試，如果可用則提供離線模式
- 認證錯誤：重定向到登入，保留返回 URL
- 使用 ErrorBoundary 元件處理 React 錯誤
- 將所有錯誤記錄到監控（見 lib/monitoring.ts）

## 錯誤回應格式
{ error: string, code: string, details?: object }
完整型別定義見 @src/types/errors.ts。

反模式 10：一廂情願的思考者

症狀： CLAUDE.md 描述你希望事情如何運作，而不是它們實際如何運作。

表現形式：

# 架構
我們遵循乾淨架構，有清晰的分離：
- Domain 層：純業務邏輯
- Application 層：使用案例
- Infrastructure 層：外部服務
- Presentation 層：UI 元件

# （現實：所有東西都在 components/ 中，沒有分離）

為什麼有問題： Claude 為你理想的架構寫程式碼，而不是你真實的程式碼庫。新程式碼無法融入。

修正方式： 誠實面對當前狀態：

# 架構（當前狀態）
大部分邏輯在 React 元件中。我們正在逐步提取：
- 業務邏輯 → src/services/（進行中）
- API 呼叫 → src/lib/api.ts（完成）
- 共用型別 → src/types/（完成）

# 架構（目標狀態）
最終目標見 @docs/target-architecture.md。

# 遷移規則
- 新功能：使用 services 層
- Bug 修復：可以修改現有元件邏輯
- 重構：修改檔案時提取到 services

反模式 11：一體適用

症狀： 相同的規則應用於所有內容，不考慮上下文。

表現形式：

# 標準
- 100% 測試覆蓋率
- 完整 JSDoc 文件
- 完善的錯誤處理
- 效能優化

為什麼有問題： 不是所有東西都需要相同的嚴格程度。原型程式碼和生產程式碼有不同的需求。

修正方式： 使用上下文感知規則：

# 依上下文的標準

## 生產程式碼（src/services/、src/lib/）
- 至少 90% 測試覆蓋率
- 所有公開 API 都要 JSDoc
- 完整錯誤處理，使用型別化錯誤
- 熱點路徑進行效能分析

## UI 元件（src/components/）
- 70% 測試覆蓋率
- 需要 Props 文件
- 頁面層級的 Error boundaries

## 腳本與工具（scripts/、tools/）
- 測試可選
- 最少文件
- 專注於正常流程

## 實驗（src/_experimental/）
- 無覆蓋率要求
- 2 週內刪除或升級

反模式 12：孤島效應

症狀： 團隊成員各自有不同的 CLAUDE.md 檔案，標準相互衝突。

表現形式：

# Alice 的 CLAUDE.md：「使用 Redux 管理狀態」
# Bob 的 CLAUDE.md：  「使用 Zustand 管理狀態」
# Carol 的 CLAUDE.md：「使用 React Query 管理狀態」

為什麼有問題： 程式碼變得不一致。PR 有風格衝突。新人入職很困惑。

修正方式： 正確使用層級結構：

.claude/CLAUDE.md          # 共享團隊標準（已提交）
CLAUDE.local.md            # 個人偏好（已 gitignore）
~/.claude/CLAUDE.md        # 全域個人設定

團隊協議：

# .claude/CLAUDE.md（團隊版本）
## 狀態管理
- 伺服器狀態：React Query
- 客戶端狀態：Zustand
- 表單狀態：React Hook Form

## 個人偏好
使用 CLAUDE.local.md 進行個人覆寫。
未經團隊討論，請勿修改共享的 CLAUDE.md。

第二部分：故障排除指南

問題：Claude 忽略我的 CLAUDE.md

檢查 1：檔案位置

# 正確位置：
./CLAUDE.md              # 專案根目錄
./.claude/CLAUDE.md      # 隱藏目錄

檢查 2：檔案正在被讀取 詢問 Claude：「你正在遵循 CLAUDE.md 中的哪些指示？」

檢查 3：優先級衝突

優先級：CLAUDE.local.md > ./CLAUDE.md > ~/.claude/CLAUDE.md

本地覆寫可能隱藏了你的專案規則。

問題：Claude 一直請求許可

檢查 1：權限設定

// .claude/settings.json
{
  "permissions": {
    "allow": ["Read", "Write", "Edit", "Bash(npm:*)"]
  }
}

檢查 2：CLAUDE.md 中的衝突指示 尋找「永遠詢問」或「確認之前」等短語並移除。

檢查 3：企業限制 如果你在組織中，檢查 /etc/claude-code/settings.json 中的企業政策。

問題：Claude 使用錯誤的慣例

檢查 1：慣例是明確的

# 不要：
使用標準 React 模式。

# 要：
## React 模式
- 只使用函式元件
- 使用具名匯出（不是 default）
- Props 介面命名為 [ComponentName]Props
- 共用的 Hooks 放在單獨檔案

檢查 2：提供範例

## 元件模板
我們的標準結構見 @src/components/_template.tsx。

問題：Claude 不記得之前的 Session

檢查 1：Memory MCP 已配置

claude mcp add --scope project memory \
  -e MEMORY_FILE_PATH=./.claude/memory.json \
  -- npx -y @modelcontextprotocol/server-memory

檢查 2：Memory 檔案存在且可讀

cat .claude/memory.json

檢查 3：你正在使用 memory 指令

  • /memory-save 儲存重要上下文
  • /memory-search 回憶之前的決定

問題：settings.json 不起作用

檢查 1：JSON 有效

cat .claude/settings.json | jq .

檢查 2：正確的屬性名稱

{
  "permissions": {
    "allow": [...],      // 小寫
    "deny": [...]        // 小寫
  },
  "enableAllProjectMcpServers": true,
  "ignorePatterns": [...]
}

檢查 3：MCP 伺服器權限

claude mcp list
claude mcp reset-project-choices

問題：Rules 目錄不載入

檢查 1：正確的結構

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    └── testing.md

檢查 2：Claude Code 版本 路徑特定規則需要 v2.0.20+：

claude --version

檢查 3：Frontmatter 語法

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

API 檔案的規則...

快速參考：CLAUDE.md 健康檢查

每月執行這個檢查表：

## CLAUDE.md 健康檢查

### 長度
- [ ] 少於 200 行
- [ ] 沒有冗餘資訊
- [ ] 細節已提取到 rules/

### 清晰度
- [ ] 沒有未定義的術語
- [ ] 具體、可執行的規則
- [ ] 有需要時提供範例

### 準確性
- [ ] 符合當前技術棧
- [ ] 反映實際架構
- [ ] 沒有矛盾

### 權限
- [ ] 已定義自主操作
- [ ] 只有真正有風險的操作需要確認
- [ ] settings.json 已正確配置

### 維護
- [ ] 有最後更新日期
- [ ] 維護變更日誌
- [ ] 設定審查排程

總結

最好的 CLAUDE.md 檔案有這些特質：

  • 簡潔： 少於 200 行，專注於獨特的內容
  • 誠實： 描述現實，而非願望
  • 具體： 可執行的規則，而非模糊的原則
  • 分層： 使用層級結構（全域、專案、本地）
  • 維護： 隨專案演進定期更新

故障排除時，總是檢查：

  1. 檔案在正確的位置嗎？
  2. 有優先級衝突嗎？
  3. 指示夠明確嗎？
  4. 有版本不匹配嗎？

優秀的 CLAUDE.md 不會試圖控制一切 - 它只提供足夠的指導讓 Claude 做出好的決定。

來源：Claude Code 文件、Claude Code GitHub