CLAUDE.md 是一个位于项目根目录的普通 Markdown 文件。Claude 会在每个会话中自动读取它。项目级别：./CLAUDE.md。全局（所有项目）：~/.claude/CLAUDE.md。项目文件会覆盖全局文件：全局文件包含你的默认设置，项目文件包含该仓库的特定设置。
把它想象成你交给一个对你的项目一无所知但技能高超的承包商的入职文档。没有它，每个会话开始时 Claude 都会猜测你的技术栈、命名约定和过去的决策。猜测会变成代码，代码会变成 bug。CLAUDE.md 能够缩短这个链条。一个文件胜过一个巧妙的提示，因为它无论你是否记住都能起作用。
五个发挥作用的部分。 每个部分三到六行要点：
1. 技术栈 (Stack)： 框架、数据库、认证、邮件，以及版本。“Next.js 16，Neon 上的 Postgres，使用 Resend 发送邮件，Stripe 处理支付，Supabase 进行认证。”
2. 路由 (Routes)： 文件存放位置。“应用在 /app 中，服务器操作在 /actions 中，API 在 /app/api/v2 下，共享组件在 /components/ui 中。”
3. 约定 (Conventions)： 对你来说显而易见，对 Claude 来说却不可见的规则。“金额以美分（整数）存储，日期为 UTC，文件名采用 kebab-case，ID 为 UUID v4。”
4. 安全规则 (Security Rules)： 绝不能发生的事情。“绝不记录 API 密钥。所有 SQL 都参数化。所有公共端点都进行速率限制。”
5. 禁止事项 (Don't Do This)： 你已经踩过的坑。“未经询问，不要添加依赖。不要从本地对生产环境运行迁移。”
一个已完成的模板。替换为你的真实项目细节：
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth with Google OAuth
## Routes
- App in /app, actions in /actions, API under /app/api/v2
## Conventions
- Money in cents (int), dates UTC, filenames kebab-case
- IDs: UUID v4. Boolean columns: is_ or has_ prefix
## Security Rules
- Never log secrets, parameterize SQL
- Rate-limit all POST/PUT/DELETE endpoints (10/min per IP)
- New Supabase tables ship with RLS policies in same commit
## Don't Do This
- Don't add deps without asking
- Don't run migrations from local against prod
- Don't use select(*)注意其具体性。“每 IP 每分钟 10 次”是可操作的。“使用速率限制”则不是。
最昂贵的错误：听起来具体但实则模糊的规则。
弱：“小心处理金钱。” Claude 会以它认为最好的方式处理金钱，这可能与你的系统不符。
强：“所有货币金额均为整数美分。绝不能是浮点数。绝不能显示原始美分；除以 100 并用货币符号格式化。” 存储类型、处理规则、显示规则。没有歧义。
第二个错误：写愿望而不是约束。“我们重视干净、可读的代码”是一个愿望。“超过 200 行的文件应拆分为模块”是一个约束。愿望需要判断；约束产生一致的行为。用约束填充你的 CLAUDE.md。
CLAUDE.md 是一个活文档。 三个信号表明它需要更新：
你第二次将相同的上下文粘贴到提示中。如果你再次提及，它就属于 CLAUDE.md。
Claude 犯了一个本可以被规则阻止的错误。这个错误就是规则。在下一次会话之前写下它。
你向同事解释一个约定。如果值得大声说出来，就值得自动加载。
长度规范： 每个部分三到六个要点；超过八个，就拆分该部分。一个太长而无法快速浏览的 CLAUDE.md 会失效，因为重要的规则会被埋没。六行正确的规则胜过六十行填充内容。
扩展到大约 300 行以上： 使用 @filename 包含拆分为主题文件：
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.md每个主题文件保持专注；根文件保持简短。
将 CLAUDE.md 提交到版本控制。 规则可以在 PR 中进行审查，新队友克隆仓库时 Claude 已配置好。在修复 bug 的同一提交中添加每条“禁止事项”规则。一个注意事项：在提交之前，将机器特定的路径通用化。
什么属于 CLAUDE.md，什么属于提示？ 影响范围。如果一条规则可以防止需要一小时或更长时间才能修复的错误，它就属于 CLAUDE.md。会话特定的指令保留在提示中。
十分钟内创建你的第一个 CLAUDE.md。 给 Claude 这个提示：
“我正在为一个项目设置 Claude Code，技术栈是：[技术栈]。新来的人不会知道的关键约定：[约定]。绝不能违反的安全规则：[规则]。以前导致过 bug 的事情：[陷阱]。起草一个包含五个部分的 CLAUDE.md：技术栈、路由、约定、安全规则、禁止事项。”
初稿能给你 80% 的内容。根据 Claude 遗漏的部分进行完善；剩下的 20% 是你对项目实际经验的特定内容。
项目根目录下的 CLAUDE.md 会将你的技术栈、路由、约定、安全规则和陷阱加载到每个会话中。全局文件用于跨项目默认设置，项目文件用于覆盖。约束而非愿望。六行正确的规则胜过六十行。每当 Claude 犯了一个本可以被书面规则阻止的错误时，就更新它。