# 策展 · X (Twitter) 🔥🔥

> 作者：darkzodchi (@zodchiii) · 平台：X (Twitter) · 日期：2026-04-27

> 原始來源：https://x.com/zodchiii/status/2048683276194185640

## 中文摘要

# 讓我的產出提升 10 倍的 CLAUDE.md 檔案（附完整檔案內容）

每一個 Claude Code 的對話階段都是從讀取一個檔案開始的：CLAUDE.md。在你輸入第一個 Prompt 之前、在任何程式碼執行之前、在發生任何事情之前，Claude 都會先讀取這個檔案，並將其視為整個對話階段的「事實依據 (ground truth)」。

大多數人要麼沒有這個檔案，要麼裡面寫了 300 行關於「個性設定」的指令。

一個好的 CLAUDE.md 和一個糟糕的 CLAUDE.md 之間的差別，就像是「帶著明確簡報引導資深工程師入職」與「把新人直接丟進一個毫無文件說明的程式庫」之間的差別。

以下是如何寫出一個真正有效的 CLAUDE.md 👇

在我們深入探討之前，我會在我的 Telegram 頻道分享關於 AI 與 vibe coding 的每日筆記：https://t.me/zodchixquant🧠

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1777307070204-iaHG5WmPwa8AEJAU6jpg.jpg)

## 為什麼大多數的 CLAUDE.md 檔案沒用？

原因有三：

太長了。模型大約只能可靠地遵循 150-200 條指令。Claude Code 的系統 Prompt 已經佔用了大約 50 條。這意味著在 Claude 開始遺漏指令之前，你的 CLAUDE.md 最多只能容納 100-150 條指令。如果你的檔案超過 200 行，Claude 並不是故意忽略你的規則，而是它已經記不住了。

內容錯誤。大多數人會在 CLAUDE.md 中填入 Claude 自己就能搞定的事情。例如「成為一名資深工程師」或「一步步思考」這類個性化指令，這些通用建議並不會改變 Claude 的行為。每一行不能防止特定錯誤的指令，都是在浪費額度。

沒有層級。CLAUDE.md 並不是唯一可以放置指令的地方。指令分為三個層級，但大多數人把所有東西都塞進同一個檔案裡：

```
~/.claude/CLAUDE.md       → 全域（適用於每個專案）
.claude/CLAUDE.md         → 專案（與團隊共享，包含在 git 中）  
./CLAUDE.local.md         → 本地（個人覆寫設定，已加入 gitignore）
```

全域設定適用於你在每個專案都會重複的規則。專案設定適用於團隊需要的技術堆疊相關背景資訊。本地設定則適用於你個人的偏好。

善用這三種層級可以讓每個檔案保持簡短且聚焦。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1777307070209-iaHG5W2GZaAAAvpagjpg.jpg)

## 真正重要的 5 個區塊

在瀏覽了數十個來自開源專案、Anthropic 官方文件以及社群最佳實踐庫的生產環境 CLAUDE.md 檔案後，我發現每個有效的檔案都涵蓋了這 5 個重點：

## 1. 關鍵指令 (Critical commands)

Claude 不知道如何建置、測試或檢查你的專案，所以你必須告訴它。

```
## Commands
- Build: `npm run build`
- Dev: `npm run dev`  
- Test single file: `npm test -- path/to/file`
- Lint + fix: `npm run lint:fix`
- Type check: `npx tsc --noEmit`
```

要簡短且具體。Claude 會執行這些指令，而不是自己瞎猜。如果沒有這個區塊，當你的專案使用 pnpm vitest 時，Claude 可能會嘗試執行 npm test，然後浪費 3 次對話機會去除錯一個根本無法運作的指令。

## 2. 架構地圖 (Architecture map)

Claude 在開始每個對話階段時，對你的程式庫一無所知。給它一張地圖。

```
## Architecture  
- src/lib/services/ → all business logic
- src/components/ → stateless UI components only
- src/lib/store/ → global state (Zustand)
- src/app/api/ → API routes, no business logic here
- Database access only through Server Actions or API routes
```

不需要完整的目錄清單，只要讓 Claude 知道東西放在哪裡、什麼東西該放哪裡即可。

## 3. 硬性規則 (Hard rules)

這是最重要的區塊。這裡的每一條規則都應該回答這個問題：「如果刪除這一行，會不會導致 Claude 犯錯？」

```
## Rules
- NEVER commit .env files or secrets
- All async calls must use try/catch
- Use functional components only, no class components
- Prefix commits: feat:, fix:, docs:, refactor:
- All PRs must pass `npm run verify` before merge
- Static export only, no SSR (deployed to S3)
- IMPORTANT: run type check after every code change
```

注意兩點：
1. 負面規則（例如「永遠不要提交 .env」）和正面規則一樣重要。

2. 像「IMPORTANT」這樣的強調標記確實有效。

Anthropic 的官方文件證實，加入「IMPORTANT」或「YOU MUST」可以提高模型對指令的遵循程度。

將此區塊的規則控制在 15 條以內。

## 4. 工作流程偏好 (Workflow preferences)

你希望 Claude 如何工作？這能防止「當你只要求修改一行程式碼時，Claude 卻重寫了整個檔案」的問題。

```
## Workflow
- Ask clarifying questions before starting complex tasks
- Make minimal changes, don't refactor unrelated code
- Run tests after every change, fix failures before moving on
- Create separate commits per logical change, not one giant commit
- When unsure between two approaches, explain both and let me choose
```

## 5. 不要包含什麼 (What NOT to include)

同樣重要的是你要捨棄的東西：

```
## Don't include:
- Personality instructions ("be a senior engineer")
- Code formatting rules your linter already handles  
- @-imports that embed entire docs into every session
- Duplicate rules (if global says "run tests," project doesn't repeat it)
- Anything Claude will learn on its own via auto memory
```

這裡的「自動記憶 (auto memory)」常被低估。Claude 會在 `~/.claude/projects/<project>/memory/` 維護它自己的筆記。執行 `/memory` 即可查看 Claude 已經學到了關於你專案的哪些資訊。

不要浪費 CLAUDE.md 的行數在那些 Claude 經過一次對話就能學會的事情上。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1777307070190-iaHG5XtuXbUAAprGSjpg.jpg)

## 完整模板（直接複製）

這是一個可直接用於生產環境的 CLAUDE.md，你可以複製並根據需求調整。不到 60 行，涵蓋了 Claude 需要的一切，且沒有多餘的廢話。

```
# CLAUDE.md

## Project
[One line: what this project does and who uses it]

## Stack  
[Framework, language, database, deployment target]

## Commands
- Dev: `[command]`
- Build: `[command]`
- Test single: `[command] -- [path]`
- Test all: `[command]`
- Lint: `[command]`
- Type check: `[command]`

## Architecture
- [folder] → [what lives here]
- [folder] → [what lives here]
- [folder] → [what lives here]
- [file] → [what this file does]

## Rules
- [Rule that prevents a specific mistake]
- [Rule that prevents a specific mistake]
- [Rule that prevents a specific mistake]
- IMPORTANT: [The one rule Claude keeps breaking]

## Workflow
- [How you want Claude to approach tasks]
- [Commit conventions]
- [Testing expectations]
- [When to ask vs when to act]

## Out of scope
- [Things Claude should not touch]
- [Files that are manually maintained]
- [Integrations Claude shouldn't modify]

```

刪除不適用的區塊即可。

## 改變一切的規則

在測試了數十種 CLAUDE.md 設定後，以下這些行數對產出品質的影響最大：

```
# The lines with highest impact:

- IMPORTANT: run type check after every code change
  (prevents Claude from shipping broken types)

- Make minimal changes, don't refactor unrelated code  
  (prevents Claude from rewriting your entire file)

- Create separate commits per logical change
  (prevents the 47-file monster commit)

- When unsure, explain both approaches and let me choose
  (prevents Claude from making architectural decisions for you)

- Static export only, no SSR
  (prevents Claude from adding server-side code to a static site)

```

每一條規則都能防止一個特定的常見錯誤。

這就是你 CLAUDE.md 中每一行的檢驗標準：刪除它，會不會導致 Claude 做錯事？

## 每個人都會犯的錯誤

人們把 CLAUDE.md 當成許願清單。

你的 CLAUDE.md 應該是一份技術簡報，而不是勵志演講。堆疊、指令、架構、規則、工作流程，這些才是重點。其他所有東西都是在與真正重要的指令競爭 Claude 的注意力。

保持在 80 行以內。當 Claude 犯錯時，就去審視並更新它。

這個檔案會隨著時間累積價值。一個好的 CLAUDE.md 在第一個月就能讓你省下重複叮嚀的時間。

到了第六個月，它已經記錄了 Claude 在你專案中犯過的所有錯誤，並自動防止它們再次發生。

我會在我的 Telegram 頻道分享關於 AI、金融與 vibe coding 的每日筆記：https://t.me/zodchixquant

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1777307070235-iaHG5ZOZGaIAAQqrJjpg.jpg)

## 標籤

Claude Code, Skills, 教學資源, Anthropic, Claude