CLAUDE.md 到底该写什么？7 个能直接复制的模板 + 禁止事项写法

“CLAUDE.md 嘛，把技术栈写上不就行了？”

我一开始也是这么想的。Astro、TypeScript、Tailwind，写完，齐活。然后心满意足地把活儿交给 Claude Code——结果同一个错误它给我犯了三遍。每次都跳过测试。手伸向那个绝对不能删的配置文件。嘴上说着”修好了！“，可构建根本没过。

只写技术栈的 CLAUDE.md，就像跟新人说一句”我们是家 Java 公司”，然后就把人扔进项目里。他知道你用什么了，可”该怎么干活”这件事，一个字都没传达到。

这篇文章里，我把自己在真实项目里直接拿来用的 7 个 CLAUDE.md 模板,以能复制粘贴的形式放出来。重点不是讲技术栈，而是彻底押在”做事的顺序”和”绝对不能碰的事”上。

本文要点

• CLAUDE.md 真正起作用的不是技术栈，而是两样东西：作业流程（Working Rules）和禁止事项（Do Not）。
• 我按用途准备了 7 个模板：个人开发／内容站／API／团队／遗留代码／自动化／Monorepo。挑一个最像你仓库的,直接贴进去就行。
• 不管贴哪个模板，贴完之后都必须再补三行你自己的 Do Not。这三行才是真正挡事故的东西。
• “写得越长越好”是个误解。CLAUDE.md 不是说明书，而是一份运维文件。简短的行为规则才赢。
• 如果 Claude Code 把同一个错犯了三遍，别先怪 AI，先怀疑你 CLAUDE.md 的颗粒度。

这一篇，我是当成一本”实物目录”来写的，正好填补 Claude Code 新手入门完整指南 和 CLAUDE.md 写法完整指南 之间的空白。道理在那两篇里看，到了这儿,你直接把实物搬回家就好。

一份好的 CLAUDE.md，默默在做的事

强的 CLAUDE.md 并不是写了什么聪明话。它只是不动声色地把下面这三种”老毛病事故”给堵死了：

• 改的位置是对的，却把这个项目特有的规矩给丢了
• 改是改对了，可该跑的测试、该做的确认全跳过了
• 自己的活儿边界在哪儿不清楚,结果探索范围越铺越大，时间就这么耗没了

为了防住这三样，文件里最起码得有这几项：

项目	作用	效果
技术栈和主要命令	对齐前提	中
目录职责	收窄探索范围	中
项目特有规则	守住规矩	大
作业流程（顺序）	防止漏掉确认	大
禁止事项（Do Not）	直接挡事故	特大

上面两项是搭头，真正管用的是下面三项。尤其是一旦把作业流程和禁止事项写进去，Claude Code 整个人都安静了下来，像换了个人。“怎么往前推”加上”什么别做”——说到底，这跟你递给人类新人的那本手册,是一回事。

往下都是实物。把代码块里的内容，直接贴进你自己的 CLAUDE.md 就行。

1. 给个人开发的 Web 应用

如果你是一个人在运营一个小服务，先用这个。

# Project Overview

Customer-facing Astro site with a small Node API.

## Tech Stack

- Frontend: Astro 5 + TypeScript
- Styling: Tailwind CSS
- Backend: Node.js 22
- Tests: Vitest

## Key Directories

- `site/src/pages/` route entrypoints
- `site/src/components/` reusable UI
- `site/src/content/` blog and docs content
- `scripts/` operational scripts

## Common Commands

- Build: `cd site && npm run build`
- Test: `npm run test`
- Search content: `rg "keyword" site/src/content`

## Working Rules

- Prefer minimal diffs over wide refactors
- Keep copy changes aligned with existing brand tone
- When editing UI, verify mobile width before calling the task done

## Do Not

- Do not rename routes unless required
- Do not delete analytics or SEO fields
- Do not claim deploy success without checking the public URL

这里最管用的不是技术栈说明,而是 Working Rules 和 Do Not 的最后那几行。“没确认移动端宽度之前，不许说完成""没看公开 URL 之前，不许说部署成功”。在加这两行之前，我有好几次都是:PC 屏幕上 UI 好端端的，一掏出手机看，全溢出去了。把成功的条件用一句话锁死，这种事就没了。

2. 给有文章、PDF、商品引流的内容站

这个博客本身就是这样——带变现链路的站点，用通用工程模板实在太弱了。

# Project Overview

Multilingual Claude Code content site with free PDF lead magnet, Gumroad products, and consultation funnel.

## Business Goal

- Priority 1: free PDF registration
- Priority 2: Gumroad product clicks and purchases
- Priority 3: consultation inquiries

## Content Rules

- Every new article must include internal links
- Every article must include free PDF, product, and consultation CTA paths
- Use the same slug across all locales when publishing multilingual posts

## Verification Workflow

1. Build the site
2. Deploy the site
3. Open the public URL
4. Check mobile layout
5. Confirm CTA destination links

## Do Not

- Do not publish only one locale when the article requires all locales
- Do not treat build success as release success
- Do not prioritize pageviews over conversion path quality

关键在 Do Not 的最后一句:明明白白写着”别拿 PV 压转化链路的质量”。不写这句,Claude Code 就会一个劲往”看起来会被人读的文章”那边偏,然后批量产出一堆 CTA 稀薄、不顶用的页面。只是给业务目标排个优先级、放到最前面,产出方向就整个掉头了。

3. 给后端 API

对一致性就是命门的 API，要强制做到”动手前先读""改完用人话说清楚”。

# Project Overview

Internal TypeScript API for billing and account management.

## Tech Stack

- Node.js 22
- Fastify
- PostgreSQL + Prisma
- Zod
- Vitest

## Directory Map

- `src/routes/` HTTP handlers
- `src/services/` business logic
- `src/repositories/` DB access
- `src/lib/` shared utilities

## Required Workflow

1. Read the route or service first
2. Check for existing schema and tests
3. Make the smallest safe change
4. Run unit tests or type checks
5. Summarize risk in plain English

## Do Not

- Do not bypass Zod validation
- Do not edit migrations casually
- Do not touch billing logic without tests

这里头我最喜欢的是 Summarize risk in plain English 这一行——“用大白话把风险讲清楚”。加上这句，Claude Code 就不会一句”改好了”完事，而是会自己补一句:“这次改动离计费逻辑的边界很近，有可能波及月结批处理。“它会主动把影响范围讲出来,评审的第一步一下子轻松多了。

4. 给团队开发

团队里真正让人头疼的，不是产出不够多，而是没法评审的 diff。这个模板就是提前堵住它。

# Team Workflow

- Work on the current branch only
- Do not revert changes you did not make
- Call out uncertainty before making broad edits
- Prefer review-friendly patches over large rewrites

## Pull Request Expectations

- Mention user-facing behavior changes
- Mention test coverage gaps
- Flag security, permissions, and deploy risks first

## Approval Boundaries

- Ask before deploy commands
- Ask before editing CI, infra, or secrets-related files
- Ask before changing lockfiles unless required

Do not revert changes you did not make（不许擅自回滚不是你改的东西），看着不起眼，却很顶用。AI 经常会”顺手”把旁边的代码”收拾干净”,结果把别人有意为之的写法给倒退回去。关于审批边界怎么切分，我在 审批 / 沙箱设置指南 里写得很细，团队运营的话可以一起看。

5. 给遗留代码

改老代码的时候，“漂不漂亮”得让位给”别弄坏”，后者才是正义。

# Legacy Repo Notes

- This codebase has inconsistent patterns
- Prefer compatibility over elegance
- Preserve behavior unless the task explicitly allows change

## Investigation First

1. Explain current behavior
2. Locate the smallest responsible file set
3. Identify risks before editing

## Do Not

- Do not rename public methods casually
- Do not introduce new frameworks
- Do not rewrite files only to match modern style

Prefer compatibility over elegance（兼容性优先于美观）。在遗留项目里，这句往往是最要紧的。你不管它，Claude Code 就会一片好心地说”我帮你按最新风格重写一下哈”,可在遗留代码里，这恰恰是事故的入口。把 Do not rewrite files only to match modern style 放进禁止事项,就是给这份好心盖上盖子。

6. 给自动化、运维脚本

发邮件、部署、往外部 API 写数据——只要是带副作用的脚本，第一个该考虑的就是它。

# Automation Rules

- Dry-run whenever the script supports it
- Log intended side effects before executing
- Prefer idempotent operations
- Keep secrets out of logs and generated files

## Required Checks

- Confirm environment variables used
- Confirm target environment
- Confirm output path or destination service

## Do Not

- Do not send emails, deploy, or publish without explicit approval
- Do not delete generated assets unless cleanup is requested

Log intended side effects before executing（执行前，先把你打算搞出什么动静写出来）就是那道安全阀。让它先声明”接下来我要往生产环境发 120 封邮件”,人就有机会喊一声”等等”。再配上 Dry-run whenever the script supports it,那些覆水难收的操作前面,必定多一道缓冲。

7. 给 Monorepo

如果多个应用和共享包挤在一个仓库里，那就先把”哪个包负责什么”写清楚。

# Monorepo Map

- `apps/web/` customer app
- `apps/admin/` internal admin tool
- `packages/ui/` shared UI
- `packages/config/` lint and tsconfig presets

## Ownership Rules

- Web UI work should stay inside `apps/web/` unless the task clearly needs a shared component change
- Shared package edits require checking downstream usage
- Avoid version or config churn unless necessary

## Verification

- Run the narrowest relevant build or test command first
- Describe cross-package impact before editing shared code

光是写上 Ownership Rules，跨包改动的事故就能少一大截。本来应该是 apps/web/ 里一处小修改，不知不觉手就伸进了 packages/ui/ 的共享组件，最后连 apps/admin/ 一起带崩——这就是 Monorepo 的典型事故。让它一上来先声明负责范围,再加一句”碰共享代码之前先把对下游的影响讲清楚”。

这 7 个模板，到底该挑哪个

一口气摆出 7 个,挑起来容易犯晕,所以我用一句话一条把选法列出来。

• 以 UI 和产品为主 → 个人开发模板
• 有文章、PDF、Gumroad 引流 → 内容站模板
• 一致性就是命 → API 模板
• 协作成本高 → 团队 或 Monorepo 模板
• 出错代价高 → 遗留代码 或 自动化模板

没必要把 7 个全揉成一份。揉到一起反而又臭又长，效果还掉。拿一个当底子,只补那些会真正改变你现场行为的规则——这才是正解。

CLAUDE.md 上最容易踩的 4 个坑

我自己实打实踩过的雷，原样分享给你。

坑 1：像写公司 Wiki 一样长篇大论。 “解释得越详细越好”完全是个误解。CLAUDE.md 不是说明书,是运维文件。比起大段的背景介绍,短短的行为规则要顶用好几倍。读它的不是人,是 AI——这个前提特别容易忘。

坑 2：只写命令，不写流程。 光写一句 npm run test，远不如写”碰了 billing 就必须跑 test”来得强。命令只告诉你”它存在”,流程还能告诉你”什么时候用”。

坑 3：没有禁止事项。 这是最可惜的。“别碰 .env""没确认公开 URL 不许说部署成功""别 force push”。就这么一句话,能挡掉一整晚的事故。Do Not 不是摆设,是保险。

坑 4：从来不更新。 如果 Claude Code 把同一个错犯了三遍,多半不是 AI 的锅,而是 CLAUDE.md 那边颗粒度不够。这时候别去骂它,补一行规则进去就好。CLAUDE.md 不是写完就完事,是一份要慢慢养的文件。

常见问题

Q. CLAUDE.md 该放在项目的哪儿？ A. 放在仓库根目录、取名 CLAUDE.md，Claude Code 启动时就会自动读取。Monorepo 的话，每个包根目录下也能各放一份，离得近的优先级更高。实际怎么放、有没有生效，就靠下面这两条命令确认。

# 放在项目根目录就行，Claude Code 启动时会自动加载
cat > CLAUDE.md <<'EOF'
# Project
（把上面的模板原样贴进来）
EOF

# 确认是否生效：让它把规则复述一遍
claude -p "把这个项目 CLAUDE.md 里的 Do Not 列举三条"

更详细的放置规则，请查阅官方的 Claude Code documentation。

Q. 用中文写也照样管用吗？ A. 管用。我有时候也用中文写禁止事项和流程。不过模板本身用英文写，跟海外同事、官方示例都更好对齐，所以这篇文章里我以英文为底。只要意思能传到位,用哪种语言都没问题。

Q. 长的 CLAUDE.md 和短的，哪个好？ A. 短的好。一个参考标准是:一屏放得下。一旦开始变长,那就是该把内容拆到单独文档里的信号。CLAUDE.md 里只留”会改变行为的规则”就行。

Q. 贴完模板，第一步该补什么？ A. 补三行你这个项目专属的 Do Not。“被碰了会出事的文件""被执行了会出事的操作""被说了会出事的谎（比如:没确认就报成功）“,各写一行。这是回报最高的一笔追加。

Q. CLAUDE.md 和 permissions（权限设置）有什么区别？ A. CLAUDE.md 是”请求和方针”，permissions 是”有强制力的许可清单”。要是真想让禁止事项被严格执行,两个一起用。权限怎么切分,我在 Claude Code 新手入门完整指南 里也提到了。

我实际试下来的结果

CLAUDE.md 里只写技术栈那阵子，我每次看 Claude Code 的产出都提心吊胆,心里念叨”这回它能好好跑测试不”。

加上 Working Rules 和 Do Not 之后，这份不安基本消失了。尤其是”没看公开 URL 不许说部署成功”这一行,效果直接体现在数字上。在那之前,“部署好啦”说完结果实际是 404,这种事一个月要来好几回;加上之后,归零了。

结论很简单:CLAUDE.md 不是用来让 AI 变聪明的文件，而是用来让 AI 别出事故的文件。比起加技术栈，补三行禁止事项的体感效果要强上十倍。先挑一个最像你仓库的模板贴进去,再补三行 Do Not,就这么试试看。

想把 CLAUDE.md 的设计思路再往深挖的，可以看 CLAUDE.md 写法完整指南;想搞懂”怎么把活儿安全交给 AI”这整套”足架”的话，去看 对 AI 说”剩下你全搞定”就是事故的开端。要是想把模板集和配置示例攒在手边随时取用，免费的 Claude Code Quick Reference Cheatsheet,以及连 hooks、permissions 都讲透的 The Complete Claude Code Setup & Configuration Guide,都会派上用场。想把教材整体过一遍的,从 教材一览 进;想连团队标准化一起敲定的,去 导入咨询。