CLAUDE.md 怎麼寫？一個多語內容網站的實際規則與寫法

CLAUDE.md 是 Claude Code 每次開工都會先讀的說明檔。Jason Finance 從 2026 年 10 月 2 日第一個 commit 起就有一份，到 10 月 11 日已經改了 42 次，現在 106 行，管文章放哪裡、哪些事 AI 可以直接做、哪些要先問我。講 CLAUDE.md 怎麼寫的文章，我很少看到拿一份真的在用的檔案出來拆解，這篇就用這個網站的 CLAUDE.md 當實例。

先說結論：CLAUDE.md 寫的是「每次對話都要記得的事」：指令、專案結構、不能違反的規則，以及什麼情況要先問人。我覺得最有用的寫法有三個：規則寫成「誰在哪一天做的決定」；AI 要不要先問我，看這件事的影響，不看它用什麼工具；重要的規則再寫成測試，違反就建置失敗。文末有一份可以直接複製的骨架。

本文是 Jason Finance 的實際做法，不是 Anthropic 的官方教學。Claude Code 的功能以官方文件為準（2026 年 10 月 12 日查閱），功能和限制可能調整。文中引用的 CLAUDE.md 片段是 2026 年 10 月 12 日的版本，有刪節。

CLAUDE.md 是什麼：官方文件的重點

Claude Code 每次開新對話都是空白的上下文。官方文件說，有兩種東西會帶到下一次對話：CLAUDE.md 是你寫的指示，自動記憶（auto memory）是 Claude 自己記的筆記。兩者每次開工都會載入，但 Claude 把它們當成上下文，不是強制設定。

官方建議在這些情況把東西寫進 CLAUDE.md：Claude 第二次犯同一個錯、code review 抓到它本來應該知道的事、你在對話裡打了上次打過的同一句修正，或是新同事也需要知道的背景。多步驟的流程、只跟某一部分程式有關的規則，官方建議改放 skill 或依路徑載入的規則檔。

放在哪裡：四種範圍

載入順序從範圍最大的到最小的，專案的指示排在個人指示後面。Claude Code 會讀工作目錄和它上面每一層目錄的 CLAUDE.md，全部串在一起，不會互相覆蓋；子目錄裡的 CLAUDE.md 要等 Claude 讀寫那個子目錄的檔案時才載入。

用 @ 匯入其他檔案

CLAUDE.md 裡可以寫 @路徑 匯入其他檔案，相對路徑以寫匯入的那個檔案為準，最多遞迴四層。用反引號包起來的路徑只是文字，不會匯入。要注意的是，被匯入的檔案在啟動時就一起載入，拆成多個檔案方便管理，但不會減少佔用的上下文。

另外兩個常用指令：/init 會分析程式碼，產生一份起始的 CLAUDE.md；/memory 列出目前所有的 CLAUDE.md 和自動記憶的位置，也可以直接打開編輯。

官方建議怎麼寫

• 具體到可以檢查：寫「commit 前跑 npm test」，不寫「記得測試」。
• 長度：每個 CLAUDE.md 目標在 200 行以內，太長會佔用上下文、降低遵守程度。
• 結構：用 Markdown 標題和清單分組，比一大段文字好讀。
• 一致：兩條規則互相矛盾時，Claude 可能隨便挑一條，要定期清掉過時的規則。

官方也明講，要不論 Claude 怎麼判斷都擋下某個動作，要用 PreToolUse hook，不是寫在 CLAUDE.md。這句話影響了我後面把規則寫成測試的做法。

Jason Finance 的 CLAUDE.md 長什麼樣

Jason Finance 是一個四種語言的理財內容網站，文章是 GitHub 裡的 Markdown 檔，整套架構寫在〈Jason Finance 從零到一〉。它的 CLAUDE.md 放在 repo 根目錄，用英文寫。我看不懂程式碼，裡面的規則多半是我用中文做的決定，再由 Claude Code 整理寫進去。

這七段的順序有用意：先告訴 Claude 去哪裡找答案，再講規則，最後才是指令和程式結構。

實際寫法：逐段拆解

權威文件：告訴 Claude 去哪裡找答案

第一段只列文件和它管的範圍，細節不放在 CLAUDE.md。例如架構：

TECH-STACK.md is authoritative for architecture. Do not substitute a different architecture because another approach is more conventional. Proposed changes go to the user first.

後半句是寫給 AI 看的。AI 容易因為「另一種做法比較常見」就改掉原本的設計，這句話先把這條路堵住。其他像主題分類、文章版面、SEO 自查清單也是同樣寫法：一句話指出檔案和範圍，內容留在那份文件裡。

這一段還有兩個值得抄的做法：

• 交接清單：docs/TODO.md is the hand-off list between sessions. Read it at the start of every session. 每次對話開始都讀待辦清單，做完、新增、改變都要更新，換一次對話也接得上。
• 用 @ 匯入另一個專案維護的文件：SEO 監控是另一個專案，它的工作指南每週同步到這個 repo，CLAUDE.md 只寫一行 @seo/CLAUDE-SEO.md 匯入，並註明這份檔案不要在這裡改。

內容規則：Git 是 CMS、slug 不改、一篇一個主題

內容規則是 CLAUDE.md 裡最長的一段，因為網站本身就是內容。最基本的幾條：

Git is the CMS and the source of truth for published content. Posts live in src/content/posts/{slug}/{lang}.md

Slugs are immutable once published. If a slug must change, add a 301 in public/_redirects.

Every article belongs to exactly one pillar (pillar frontmatter). Pillars are the directory names under src/content/pillars/; do not hard-code a second list.

A language version exists only if its Markdown file exists. Never substitute another language.

最後一條是多語網站特有的。網站有繁中、簡中、英文，西班牙文只做加密貨幣主題；某個語言沒有檔案就不產生那一頁，不拿英文頂替。翻譯流程也寫在這一段：我確認繁中定稿後，Claude Code 不用再問我，直接產生其他語言版本，而且翻譯不能加入原文沒有的說法。

這一段還有一條很長的「金融內容的法遵規則」，規定理財和加密貨幣文章能怎麼寫、不能怎麼寫。細節和這篇主題無關，這裡不展開；有一個寫法可以參考：這種有法律風險的規則，每一條都附上我做決定的日期，後面會講為什麼。

安全規則：四條技術底線

安全規則只有四條，而且寫得很死：

No production secrets in Git — no .env, keys, tokens, connection strings or credentials.

Never disable Supabase RLS, not even temporarily as a troubleshooting shortcut. Fix missing data access with policies or grants.

Never introduce service-role credentials into the application. Admin queries run with the signed-in user’s JWT; RLS decides.

/admin* must fail closed (src/middleware.ts).

第二條特別寫了「not even temporarily」。AI 遇到資料讀不到，最省事的除錯方法就是暫時關掉資料庫的權限保護（RLS），這句話把這個捷徑先排除，並說明應該怎麼修。第四條的「fail closed」意思是後台遇到任何異常，例如沒有登入、不是管理員、資料庫連不上，都一律拒絕，不會因為出錯就放行。

工作約定：看影響，不看工具

我看不懂指令，不可能逐一核准 AI 跑的每個步驟，所以規則從這句開始：

Approval depends on the effect of an operation, not on the tool that performs it (Bash, SSH, Git, npm, Wrangler/Cloudflare, Supabase, database clients, deployment tooling). Never ask the user to approve command syntax.

接著分成幾層：

還有一句讓整套規則可以運作：

An explicit user request is approval for the routine steps needed to implement it.

我交代一件事，就等於同意完成它需要的例行步驟；只有做到一半遇到我沒授權的後果，才停下來問。實際上這套規則也真的會讓 AI 停下來，經過寫在〈看不懂程式也能架網站〉和〈看不懂 SSH 也能維運 WordPress〉。

溝通語言、指令和程式結構

最後三段很短：

• 溝通語言：Always communicate with the user in Traditional Chinese. 後面補一句：這不影響網站內容的語言、程式碼、commit 訊息和檔案內容。用意是把界線劃清楚：跟我說話用中文，其他照各自的慣例。
• 指令：npm test、npm run check、npm run build、npm run verify 各一行，後面註明做什麼。
• 程式結構：共用邏輯放 src/lib/，要寫成 Node 也能直接執行的 TypeScript；公開頁面只能有哪幾種 JavaScript，一條一條列出來。

寫 CLAUDE.md 的四個原則

規則寫成決定：誰、哪一天

這份 CLAUDE.md 裡很多規則後面都有括號，例如 (owner decision 2026-10-11)、(standing approval, 2026-10-03)。這樣寫有三個用處：

• Claude 知道這是我做的決定，不是它可以順手「優化」的慣例。
• 規則改了，舊規則有出處可查。例如寫作潤稿工具那一條寫明它取代 10 月 5 日的舊工具，Claude 就不會兩套都用。
• 我自己回頭看，知道當時為什麼這樣決定，配合 Git 紀錄就能找到那天的修改。

看影響，不看工具

依工具分權限，例如「Git 可以、SSH 要問我」，很快就會失效：同一個 SSH 可以只是看日誌，也可以刪掉正式資料。依影響分，規則就不用跟著工具一起改。對看不懂指令的人來說，這也是唯一能做的判斷，我看得懂「要刪除哪些資料」，看不懂指令本身。

重要的規則寫成測試

官方說 CLAUDE.md 是上下文，不是強制設定。另一篇〈一台主機跑多個 Remote Control〉也提到，只靠 CLAUDE.md 寫規則不是存取控制。所以我把重要的規則再寫一次，寫成程式：

規則會長大，要定期整理

42 次修改裡，大部分是加規則。目前 106 行，在官方建議的 200 行以內，但金融內容的法遵規則那一條一行就超過 2,600 個字元，長度不能只看行數。我的整理方式是把細節搬到 docs/ 下的專門文件，CLAUDE.md 只留一句話加連結，例如文章版面規範、SEO 自查清單都是這樣拆出去的。

可以直接複製的 CLAUDE.md 範本

下面是照這個網站的結構整理的骨架，路徑和指令換成你自己的。英文寫規則、中文跟你溝通，是我的習慣，不是必要條件。

# CLAUDE.md — your-project

## Authoritative documents
- `docs/architecture.md` is authoritative for architecture. Do not substitute
  a different approach because it is more conventional. Proposed changes go to the owner first.
- `docs/TODO.md` is the hand-off list between sessions. Read it at the start of
  every session; update it when an item is done, added or changed.

## Content rules
- Git is the source of truth for published content: `content/{slug}/{lang}.md`.
- Slugs are immutable once published. A rename needs a 301 redirect.
- A language version exists only if its file exists. Never substitute another language.
- <rule> (owner decision YYYY-MM-DD; enforced by `tests/<name>.test.ts`)

## Security rules
- No secrets in Git: no `.env`, keys, tokens or credentials.
- Never disable database row-level security, not even temporarily.
- No admin or service-role keys in the application.
- `/admin*` must fail closed.

## Communication language
- Always reply to the owner in Traditional Chinese. Code, commit messages
  and file contents follow their own conventions.

## Working agreement
Approval depends on the effect of an operation, not on the tool that performs it.
Never ask the owner to approve command syntax.
An explicit request is approval for the routine steps needed to implement it.

### Autonomous
- Reading, searching, tests, builds, normal commits and non-force pushes.

### Tell the owner in plain language
- Content direction, design and layout choices.

### Ask for a decision
- Publishing content the owner has not approved, production settings, DNS,
  payments, anything costly or irreversible. Explain: what changes, why,
  impact, main risk, recommended implementation.

### Never without a decision
- Rewriting Git history, force pushes, destructive operations outside the task.

## Commands
- `npm test`: unit tests
- `npm run build`: production build

## Code layout
- `src/lib/`: shared logic

用這份骨架時，我建議先寫「Working agreement」和「Security rules」，這兩段決定 AI 會不會做出你沒想到的事；其他段落可以等 Claude 第二次犯同一個錯時再補。

CLAUDE.md 做不到的事

• 它不是權限控制：Claude 可能沒照做。真正要擋的事，用 hook、測試、資料庫權限，或分開 Linux 使用者和憑證。
• 它不會自己更新：規則變了要記得改，舊規則留著會互相矛盾。
• 它不能放祕密：CLAUDE.md 跟著 Git 走，金鑰和密碼放在 Git 以外的地方。
• 它不能取代判斷：要不要發佈、要不要承擔某個風險，還是我自己決定，CLAUDE.md 只是把「什麼時候該問我」寫清楚。

整套架構見〈Jason Finance 從零到一〉，每個服務的費用和權限設計見〈看不懂程式也能架網站〉。更多文章在 AI 創業主題頁。

常見問題

CLAUDE.md 是什麼？

CLAUDE.md 是給 Claude Code 讀的 Markdown 檔，寫專案的長期指示，例如建置指令、程式慣例、專案結構和「一定要這樣做」的規則。Claude Code 每次開新對話都會讀它。

CLAUDE.md 要放在哪裡？

官方文件列出四種範圍：組織管理的政策檔、個人的 ~/.claude/CLAUDE.md、專案根目錄的 ./CLAUDE.md 或 ./.claude/CLAUDE.md，以及不進版本控制的 ./CLAUDE.local.md。專案規則放在 repo 根目錄，跟著 Git 和團隊共用。

CLAUDE.md 可以引用其他檔案嗎？

可以，用 @路徑 的語法，例如 @docs/git-instructions.md。相對路徑以寫匯入的那個檔案為準，最多遞迴四層。被匯入的檔案在啟動時一起載入，所以拆檔案不會減少佔用的上下文。

CLAUDE.md 要寫多長？

官方建議每個 CLAUDE.md 控制在 200 行以內，太長會佔用上下文、降低遵守程度。Jason Finance 的 CLAUDE.md 是 106 行，但有幾條規則一行就很長，長度不能只看行數。

寫進 CLAUDE.md 的規則，Claude 一定會遵守嗎？

不一定。官方說明 Claude 把 CLAUDE.md 當成上下文，不是強制設定；要不論如何都擋下某個動作，要用 PreToolUse hook。我的做法是把重要的規則再寫成測試或資料格式檢查，違反時建置失敗。

看不懂程式的人可以自己寫 CLAUDE.md 嗎？

可以。我看不懂程式碼，Jason Finance 的規則多半是我用中文做的決定，再由 Claude Code 整理寫進 CLAUDE.md。我最常寫的是要不要問我、哪些事不能做、文章怎麼放，這些不需要懂程式。