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。我最常写的是要不要问我、哪些事不能做、文章怎么放，这些都不需要懂代码。