同一个 AI，为什么到你项目里就开始自作主张——CLAUDE.md 到底该写什么

同一个 AI，为什么到你项目里就开始自作主张——CLAUDE.md 到底该写什么

1. 同一个 AI，到你项目里就开始自作主张

你有没有这种感觉——同一个 AI，在别人的演示里神乎其神，一到你自己的项目里，就开始自作主张、答非所问。

上周我让它给产品加个小改动。它顺手"送"了我三样没要的东西：

• 图省事用了 SQLite 数据库——可这个项目生产环境必须是 PostgreSQL。
• 把数据库密码直接写进了配置文件——本该走环境变量。
• 还自作主张补了一个登录模块——这功能我明确说过现在不做。

我一开始也以为是这次 Prompt 没写好。但这些坑反复出现，换什么措辞都拦不住。后来我想明白了：这不是 AI 变笨了，也不是它笨——是项目根目录那份 CLAUDE.md 还没写。

我把规则补进去之后，同类需求它再没踩过。模型对所有人都一样，差别就在根目录 CLAUDE.md 那一个文件。

单条 Prompt 管一次对话，CLAUDE.md 管整个项目。

2. 把 CLAUDE.md 写成 README，等于没写

大部分人第一次写 CLAUDE.md，会把它写成一份 README。

罗列一遍"这是什么项目、用了哪些技术栈、怎么本地跑起来"，然后觉得交差了。结果 AI 该踩的坑一个没少。

我自己早期就这么干过：CLAUDE.md 开头花了一大段介绍项目背景、贴了技术选型的来龙去脉，写得像一份产品文档。AI 读完照样我行我素——该顺手引入的新依赖一个没少。因为那一整段，对它全是已知信息。

问题出在：AI 根本不缺"是什么"的信息。它能读代码，能自己看出你用的是什么框架、数据流怎么走、Model怎么定义。你把这些再抄一遍给它，是冗余。冗余还有副作用——它会稀释真正重要的那几条规矩，让边界淹没在介绍里。

它缺的是另一类东西——边界和规矩：什么不能动、什么算做完、遇到模糊地带按什么原则来。这些东西代码里没写，AI 也猜不出来。

一句话区分：README 是写给新人的"介绍"，CLAUDE.md 是写给 AI 的"行为约束"。把 CLAUDE.md 写成介绍，等于没写。

那到底该写什么？

3. CLAUDE.md 就是项目级的"三要素"

第 1 篇讲过一个 Prompt 要稳定（点击此链接可以查看），结构上只要三件事：目标、约束、验收。

CLAUDE.md 不是什么新东西——它就是把这三要素从"一条 Prompt"放大到"整个项目"，再写一次、长期生效。一份好的 CLAUDE.md，章节基本能和三要素对上号：

关键差别在生效方式。Prompt 的三要素是每次手打、用完即弃；CLAUDE.md 是写一次、每次对话自动加载。它就放在项目根目录，Claude Code 这类工具每开一个新会话都会先读它一遍——你不用复制粘贴，不用反复提醒，它是 AI 一进门看到的第一份说明。

这正是第 3 篇"把重复的 Prompt 抽成模板" （点击此链接查看）那条思路的终点——模板是你主动调用的资产，CLAUDE.md 是 AI 默认就读的规则。前者还要你记得用，后者连记都不用记。换句话说，前三篇的方法论你得靠自觉执行，写进 CLAUDE.md 之后，执行这件事本身被自动化了。

4. 拆四段：一份真实产品的 CLAUDE.md 长什么样

光讲框架太虚。我把自己产品 ScoreMe 的 CLAUDE.md 公开了一份——删掉了所有密钥、域名和商业细节，只留结构和技术规则。下面拆的就是它的四个片段。

每段我都回答同一组问题：为什么这样写，以及不这样写会怎样。

4.1 边界：先写清楚"不做什么"

这份 CLAUDE.md 里有一节叫"暂不实现"，明明白白列着：手机号验证码登录、复杂会员系统、语音评分。

为什么要专门写"不做"？因为 AI 默认会"帮你想周到"。你让它加一个评分接口，它觉得"既然有用户，那得有登录吧"“既然有登录，那加个会员体系更完整吧”——一路给你脑补。

"暂不实现"这一节，就是给它画一条红线：到这儿为止，再往外不要碰。

不写会怎样？你让它做 A，它给你 A + B + C，每一项看着都合理，但 MVP 的范围像气球一样越吹越大，永远差最后一口气上不了线。写清楚"必须实现"只定了方向，写清楚"暂不实现"才真正刹得住车。

4.2 技术铁律：把 AI 最爱"图方便"的地方钉死

CLAUDE.md 里有一条数据库铁律，原话是：生产环境必须用 PostgreSQL，不允许用 SQLite，数据库连接信息必须来自环境变量，不允许写死在代码里。安全那一节还补了一条：API Key 不得出现在前端，DEBUG 必须为 False。

为什么要把这种"常识"白纸黑字写下来？因为这恰恰是 AI 最爱图方便违反的地方。本地开发时 SQLite 零配置、跑得飞快，AI 默认就奔它去；密钥直接写进配置文件，当下最省事。

把它写成铁律，AI 每次生成代码都会绕开这些坑。

不写会怎样？就是开篇那一幕——本地 SQLite 跑得欢，一上生产数据库直接炸；密钥硬编码进前端，等于公开挂出去。这类坑写一次 CLAUDE.md，之后一劳永逸；不写，就每个新对话陪它重踩一遍。

4.3 验收：给项目一个"做完了"的统一定义

这份 CLAUDE.md 有一节"上线标准"，列得很具体：能调用模型返回评分、能限制每日免费 3 次、Docker 能一键启动、PostgreSQL 数据可持久化。

这是第 1 篇"验收"概念放大到项目级的样子——给整个项目一个"完成的定义"。有了它，AI 和你对"做完了"才有同一把尺子，而且每一条都能机械判断，不靠感觉。

不写会怎样？AI 说"做完了"，你也以为做完了。结果上线一重启容器，数据全没——因为没人把"数据要可持久化"列进验收。验收缺失，最后都变成扯皮：它觉得交付了，你觉得没有，谁也说不清标准在哪。

4.4 价值观：替 AI 决定模糊地带怎么走

最后一节是"开发原则"，里面有两条我很看重：一是生产环境保持简单，不要过早引入复杂架构；二是所有模型输出必须可控，必须经过后端 JSON 校验，不能直接把原始输出丢给用户。

前三段管的是有明确答案的事。这一节管的是没有标准答案的模糊地带——也就是第 2 篇说的决策区。

CLAUDE.md 不可能穷举每个选择。当它没明说某件事该怎么办时，AI 要么按训练里的"行业最佳实践"自由发挥，要么按你写下的原则走。"开发原则"就是把你的判断标准提前交给它。

不写会怎样？你一个还在验证阶段的 MVP，AI 可能给你热心地塞进消息队列、缓存层、甚至拆成微服务——每一样都是"最佳实践"，合在一起就是过度工程。原则这一节，就是替它在岔路口提前选好方向。

5. 拿走就能用：一份最小 CLAUDE.md 骨架

5.1 7节骨架

不用一上来就写得多全。下面这份骨架是我现在的起手式，照着填就行：

1. 项目目标与定位 （50-150 字）一句话目标 + 核心定位 = 三要素的"目标" 2. MVP 边界：必须 / 暂不 （100-200 字）红线 = "约束" 3. 技术栈与技术铁律 （100-200 字）不可违反的硬规定：数据库 / 密钥 / 依赖 4. 目录结构与模块职责 （100-200 字）让 AI 知道东西放哪、各模块干什么 5. 上线 / 完成标准 （50-150 字）可机械判断的验收清单 = "验收" 6. 开发原则 （100-200 字）模糊地带的价值观 = "方法论" 7. 红区 / 禁止事项 （50-150 字）绝对不能做的事

用法很简单：先把这 7 节填个初版，跑两周，把这期间"AI 反复踩的坑"补进对应章节。补几轮之后，这份 CLAUDE.md 就活了。

5.2 什么时候该写，什么时候别写

CLAUDE.md 不是每个项目都需要。

不需要的场景：一次性脚本、几十行的小工具、单文件 Demo、只让 AI 碰一两次的代码。写 CLAUDE.md 的成本比收益高，纯属仪式感。

该写的场景：项目上了几百行、分了多个模块；你会反复让 AI 在上面改东西；开始出现"AI 老踩同一个坑"；多人或者多个 AI 会话一起协作；有几条不可违反的技术铁律。

最简单的判断信号，如果你发现每次开新对话都在重复同样的叮嘱，就该把那句叮嘱沉淀进 CLAUDE.md 了。重复的话，就是该抽出来的规则。

5.3 反面教材：别把"现状"写进 CLAUDE.md

见过不少人踩的一个反向坑：把快速变化的实现细节写进 CLAUDE.md。

比如"当前用户表有 17 个字段，分别是……"“OrderService 依赖 PaymentGateway 的 v2.3 接口”“现在用的是 Kafka 3.1”。

为什么错？因为 CLAUDE.md 不会随代码自动更新。这些细节一周就过期，而 AI 会拿着这份过期信息一本正经地误导你——过期的规则，比没有规则更危险。

正确做法是：CLAUDE.md 只写"慢变量"——目标、边界、原则、铁律、验收标准，这些几个月才变一次。具体的字段、接口签名、版本号，让 AI 自己去读代码，代码才是唯一的事实源。

一句话记住：CLAUDE.md 写原则，不写进度。

6. 收尾

把这个系列串一下：
第 1 篇三要素，管一条 Prompt（写 Prompt 的三要素：目标、约束、验收（附实战模板））；
第 2 篇四象限，管"该不该交给 AI" （AI 协作四象限：什么任务该交给 AI、什么自己来（附 30 秒决策清单））；
第 3 篇模板，把重复的 Prompt 抽成资产（
AI 编程常用 Prompt 模板：读项目 / 修 bug / 加功能 / 重构）；
这一篇 CLAUDE.md，把前面三篇沉淀成项目级、常驻的规则。它是前三篇的落地容器。

这套写 CLAUDE.md 的方法我自己每天在用——我用它搭了 ScoreMe，一个用 AI 帮你打磨面试和销售话术的工具，这篇拆的那份脱敏 CLAUDE.md 就是它的。如果你想看这套规则在一个真实付费产品里跑成什么样，点击此处跳转查看。

下一篇写我没立规矩时摔过的 5 个坑——这一篇讲怎么立规矩，下一篇讲不立规矩的代价。下一篇见。

关于作者

AI + 工程落地工程师，15 年系统工程经验，做过架构师 / Tech Lead / 独立 builder 三种角色。现在专注 ScoreMe（AI 评分官），用 AI 协作把想法快速变成可运行的付费产品。本系列分享我在这条路上沉淀的方法论与踩坑复盘。