企业官网建设流程全解析

Vibe Coding 这两年把编程变成了一件“嘴上说着话，手里没代码”的活，但很多人在 Claude Code 里越用越觉得 AI 像个金鱼——七秒记忆，刚说完要求转头就忘。折腾过几个项目之后我才真正意识到：CLAUDE.md 才是 Claude Code 的灵魂记忆。它不是普通的项目文档，而是每次会话都会自动加载进上下文的“项目世界观”。这篇文章就是想把 CLAUDE.md 怎么定位、写什么、怎么写、怎么避坑这件事讲透，适合已经在用 Claude Code 的人，也适合准备开始尝试 Vibe Coding、但对 AI 频繁“失忆”深恶痛绝的开发者。

1. Vibe Coding 的真相：不是失控，而是记忆管理

1.1 “Vibe”到底是在摸鱼，还是在建立新工作流

Vibe Coding 讲起来很玄，落到日常其实很朴素：你不再盯着每一行代码逐字审阅，而是用自然语言描述意图、约束和边界，把具体实现交给 Claude Code 这类 AI 编程助手。尤其在做原型、搭脚手架、做大规模重构时，这种工作流能把速度拉满。你只需要说“把支付状态机从订单模块里抽出来，旧调用方全部适配过去”，模型就会自己去翻文件、找引用、改导入，然后告诉你哪里可能还有隐患。

但真正把 Vibe Coding 用得舒服的人并不多。我见过不少开发者抱怨“AI 口口声声懂你，动手全是意外”：让它改 A 模块，它顺手把 B 模块的逻辑也改了；项目里明明用 pnpm，它偏要跑 npm install 然后留下一堆 lock 文件；上一轮刚强调过“这里不允许用全局单例”，下一轮它又给你写出来一个。

这些问题的根源不是模型智力不够，而是上下文管理出了问题。AI 每一轮对话都像新入职的员工，它不知道你的项目约定、历史决策和隐性规范。普通聊天式编程把这一切交给运气——有时候模型能从文件名猜出意图，有时候猜错；而 Vibe Coding 要做的事情，恰恰是把这些“项目世界观”显式地写进一个文件，让 AI 每次开局都在正确的上下文里干活。

这就是 CLAUDE.md 出现的原因。它承载的不只是“这个项目用了什么框架”这种显性信息，更多是“这个仓库里有些事情绝对不能碰”“这个模块的边界在哪里”“为什么当初没有用某套方案”这类隐性知识。等到这些信息都沉淀下来，Vibe Coding 才真正从“AI 乱写、人狂修”变成“AI 干活、人把关”。

1.2 AI 的失忆症，和一份文件的救场

Claude Code 本身并不会记住上一个会话聊了什么。默认情况下，一个新会话开始后，它只能看到命令行里传入的文件、当前目录的扫描结果，以及你在这个会话里新说的话。它没有“在这家公司干了一年所以知道别碰那个老模块”的长期记忆，也没有“上一周我们刚决定弃用某个库”的项目常识。

CLAUDE.md 正是为了解决这个失忆问题而存在的：它是项目根目录下的一个 Markdown 文件，每次新会话开始会自动被读入上下文。你不需要反复解释“这个项目是做什么的”“测试命令是什么”“哪几个目录是核心”，它在开局就全部知道。换句话说，CLAUDE.md 就是给 AI 准备的一份“入职交接文档”。

我用一个很生活化的类比：你被派到一个老项目组，第一天接手别人写了好几年的系统。同事如果丢给你一份写得清楚的交接文档，你会知道构建脚本在哪里、数据库迁移要怎么做、哪个模块是雷区；如果没有，你只能一遍遍找人问，问多了大家都烦。CLAUDE.md 承担的就是这份交接文档的角色，只不过它的读者是 AI。

从长期角度看，我会把 CLAUDE.md 理解成“可版本控制的外挂记忆”。当前会话里你随口说的要求，刷新一下可能就没了；但只要你把关键约定沉淀到文件里并提交进版本库，任何后续会话都能继承这份记忆。这也是为什么我认为它的重要程度高于一条精心构造的提示词——提示词只生效于“当前这个会话”，CLAUDE.md 却影响着“这个项目的所有未来会话”。你花半小时维护它，之后省下的是几十个小时的重复解释和改错返工。

2. CLAUDE.md 到底该存什么

2.1 四类必存信息：概述、命令、规范、坑

我复盘过十几个项目的 CLAUDE.md 之后，把真正值得写进去的内容归成了四类，每一类都有不可替代的作用。

第一类是项目概述。用它给 AI 建立最基本的上下文：这个系统解决什么问题，有哪些主要模块，模块之间大致怎么依赖，部署形态是什么。没有概述的 CLAUDE.md，就像开卷考试但发给你一本排版混乱的资料——AI 连目录都读不利索。概述别写长，三到五句话讲清楚“这个系统是谁在用、解决什么问题、分哪几层”就够了。举个例子，我的一个电商订单服务里只写了三句：处理订单状态流转；对外提供 REST API，消费方是商家后台；数据存储用 MySQL，缓存用 Redis。就这么简单，AI 后续读到“订单状态机”相关需求时，行为明显更贴题。

第二类是常用命令。构建、测试、启动、静态检查、数据库迁移这些命令必须有准确版本，而且要具体到目录。一个仓库里同时有前端和后端是常态，前端用 pnpm 而后端用 uv 也很常见，那就要写清楚“admin-web 目录下用 pnpm dev”“api-server 目录下用 uv run uvicorn”。否则 AI 很可能会随手用 npm 跑，导致一堆依赖错乱。命令要写到“可以直接复制粘贴执行”的精确程度，别写“安装依赖”这种模糊表述。

第三类是编码规范。包括命名风格、模块边界、错误处理约定、事务范围、是否允许魔法数字等。但规范不能写成“写高质量代码”这种正确的废话，必须写成 AI 能执行的动作指令。我常写的一条是“所有对外接口必须用 DTO 接收参数，禁止直接暴露 ORM 实体”，模型遇到相关任务时就会主动包裹一层 DTO。再比如“错误码统一使用 ErrorCode 枚举，禁止散落字符串”，这句话能避免 AI 在新增逻辑时随手return "invalid_param"。

第四类是易错提醒与已知坑。这是 CLAUDE.md 里最珍贵的部分。项目从 SQLite 迁到 PostgreSQL 之后方言变了；某个老接口内部有兼容逻辑，不能乱动；某个工具链升级后旧 flag 失效；某段支付金额逻辑里隐藏着精度陷阱……这些信息写在代码注释里容易被忽略，写在 CLAUDE.md 里则每次都会被 AI 主动读到，直接阻断它犯同样的错误。

我最近在维护一个支付服务，CLAUDE.md 里就写了这样一条：“所有金额字段使用最小货币单位整数存储，禁止浮点数；对外输出时统一格式化为两位小数。”如果没有这条，AI 用常规 decimal 写法处理金额时，虽然看着合理，但很容易在边界条件上出精度问题。写上之后，同样任务生成出来的代码几乎不需要再改。

2.2 不该往里放的东西

CLAUDE.md 不是越大越好，它是有“上下文预算”的。我见过有人把它当成剪贴板，把大量错误日志、调试记录、个人碎碎念全部塞进去，结果反而拖垮了会话质量。

不该放的东西大致有三类。一是会频繁变化的内容，比如当前 bug 修复进展、某个接口正在调试的临时参数、今天刚遇到还没结论的报错。这些信息过两天就失效，留在文件里只会制造噪音。二是 AI 用不上的团队事务信息，比如考勤制度、会议纪要、项目管理进度，AI 读了也不会对编码行为产生正面影响。三是与其他文档职责重叠的长篇说明，如果已经有 README 和独立架构文档，CLAUDE.md 就不要再复制一份，它只需要保留会影响 AI 行为的“行为约束”。

我给自己定了一条判断标准：如果一条规则在这轮会话里你反复用嘴强调，它就值得写进 CLAUDE.md；如果它只是偶然一次性的操作，甚至 AI 下次根本不应该继续执行，那就不该写。比如“这次把支付超时时间改成 30 秒方便测试”，这是临时参数，不该写；而“支付超时时间必须从配置中心读取，禁止硬编码”，这是长期约束，必须写。

一句话总结：CLAUDE.md 里只留那些“你不希望 AI 在接下来一百次会话里再猜一次”的信息。它不是一个记录发生过什么的日志，而是一份决定未来行为的规则集。

3. 如何写出好用的 CLAUDE.md

3.1 从“让 AI 写自己”开始

CLAUDE.md 最好的第一版，不是手敲出来的，而是让 Claude Code 根据现有代码自己总结出来的。当你在一个项目目录里首次启动 Claude Code 时，它会扫描当前目录，分析项目结构和关键配置文件，然后建议生成一份 CLAUDE.md 初稿。你可以在此基础上用自然语言补几句关键信息，它就会把内容整理好。

这个流程的好处是快。对大多数项目来说，一个合理的初稿比从零开始写容易太多。它会从 package.json 里读到scripts，从目录结构里分析出 src 和 tests 的职责，然后生成一份基础规则。这些自动总结算是“显性信息”，准确率不错，足够做第一版。

但你要清醒：AI 总结出来的无法覆盖隐性知识。它不知道“上一周我们决定不用 XX 方案”，也不知道“某模块是历史遗留代码，新功能不要扩展它”。所以第一版生成后，把它当草稿，不要当最终交付物。你在会话里补充的那些口头约定，才是让文件真正贴合项目的关键。

我个人的迭代路径是：先用初版 CLAUDE.md 跑一个简单任务，比如“给用户模块加一个导出功能”，观察 AI 的行为有没有明显偏差。如果它跑错了测试命令，或者用了团队不认可的校验库，我就把正确做法写进文件，然后重新开一个会话再验证。循环两三次之后，这份文件就会非常贴近团队的真实工作习惯。

3.2 一个可以直接抄的结构模板

下面是我反复调整之后比较顺手的结构，可以直接抄进项目里再做修改。

# 项目概述 一句话说明项目是什么，目标用户是谁，核心价值在哪里。 # 技术栈速览 - 语言 / 框架 / 版本 - 关键依赖（ORM、验证库、日志库等） - 包管理器与锁文件说明 # 常用命令 - 启动 / 构建 / 测试 / 静态检查 - 数据库迁移、初始化 - 特殊环境变量说明 # 目录结构与职责 - src/：业务代码 - tests/：测试 - scripts/：脚本，不要随意改动 - 哪个目录可以自由调整，哪个目录要谨慎修改 # 编码规范（项目专属） - 命名、接口风格、事务边界 - 禁止事项清单：不要全局单例、不要隐式依赖、不要魔法数字等 - 如果团队规范已经写在文档里，这里只写“请遵守团队文档X”，并补充本项目的例外 # 易错与经验 - 本项目特殊的坑 - 曾经踩过并确定不能再犯的点 - 迁移或重构期间的临时约束：某模块冻结改动等 # 非目标 - 明确告诉 AI 哪些事不要碰 - 遇到不确定时应该问，而不是擅自扩大改动范围

模板不是死规矩，不同项目类型要调整。微服务仓库里，“目录结构与职责”要细化到每个服务，最好能画一张纯文本的调用关系列表；单体应用里，“易错与经验”最值钱；脚手架类项目的核心是技术栈和命令。每一节都尽量做到“AI 读了就能执行，执行了就能验证”，不要把条目写成散文。

3.3 维护比初版更费心，但收益也更大

CLAUDE.md 写完提交到版本库之后，维护工作才算开始。我把它当源码来管理：每次重构、换依赖、改规范，同步更新对应条目；每次 AI 犯了重复错误，事后把纠正规则写入“易错与经验”；定期审查文件长度和条目有效性，删掉已经过时的内容。

有一个常见误区是等文件写“完美”才用。实际不可能完美。更合理的方式是“够用就上线，用烂再迭代”：第一天有一份能运行的草稿就行，之后随着项目演进和 AI 反馈把规则打磨成真正贴合项目的版本。

我还会把 CLAUDE.md 的改动纳入代码审查。比如这次重构改了模块边界，代码变更里同时改掉 CLAUDE.md 的“目录结构与职责”，评审人一眼就能看出规则是否跟着变化。这样文件就不会慢慢变成和代码脱节的“僵尸文档”。

另外，我还养成了一个习惯：每次会话结束，如果 AI 做对了一件我从未写进文件的事，我会立刻打开 CLAUDE.md 补上一行。一行就够，别写成长篇大论。比如“测试数据库连接串用 TEST_DATABASE_URL 环境变量，不要写死在代码里”，这行字的作用极其巨大。积少成多之后，你会发现口头纠正次数越来越少，因为 AI 已经通过文件自动继承了你每一次会话的智慧。

4. 我踩过的坑、排查方法与养成经验

4.1 写了 CLAUDE.md，AI 却像没读过

我一开始踩得最普通的坑，就是“文件写了、提交了，但下一轮 AI 还是照样犯错”。排查多了以后发现，绝大部分情况不是 AI 没读文件，而是文件本身写得有问题。

最常见的原因是规则表述太抽象。写“注意代码质量”等于没写，写“工具函数必须放在 src/utils/ 下并在测试中覆盖”才是有价值的指令。AI 对这种行为级指令的遵循度远高于价值观级口号。你也别写“谨慎处理金额”，要写“金额全部用最小货币单位整数存储”。

第二个原因是规则之间互相矛盾。比如你前面说“统一用 requests 库”，后面又说“遇到底层 IO 用 aiohttp”，AI 在具体场景里选择了 aiohttp，看起来像没遵守规则，其实是规则本身没定义清楚优先级。解决方法是给规则加上条件限定：“默认使用 requests；只有异步网关模块允许用 aiohttp，且必须经过评审。”有了条件和优先级，模型就不会左右为难。

第三个原因是上下文膨胀。CLAUDE.md 一旦超过上千行，关键规则就被淹没在大量次要内容里，模型读完后不会把注意力平均分配给每一条。我的经验值是项目级 CLAUDE.md 控制在 200 行以内，超出就要考虑精简或拆分。把详细的架构说明放到另外的文档里，CLAUDE.md 只留索引和核心约束。

还有一个认知偏差要纠正：用户的即时提示词与文件规则冲突时，AI 几乎总是优先听当前对话里的要求。比如文件里写了“禁止使用某个库”，但这轮需求里你说“用这个库实现导出”，它大概率会听你的。这不算文件失效，而是优先级本就如此。想避免就只能在下个会话时不要给出冲突指令，或者主动修改文件让两条规则对齐。

4.2 全局与项目：记忆放错地方最容易互相污染

Claude Code 支持全局记忆和项目记忆两层。全局文件放在用户主目录下，里面的内容对当前这台电脑上的所有项目生效；项目文件放在当前项目根目录里，只对这个仓库生效。我不止一次看到有人把项目专属规则写进全局文件，结果 AI 在另一个完全不相关的项目中也会执行那些规则。

举一个典型例子：Python 项目里我们约定“所有依赖版本锁定在 requirements.txt，禁止用 pip 安装最新版”，这条如果写进全局文件，那么处理 Java 项目时 AI 也会莫名其妙去找 requirements.txt，浪费改错时间。经验规则很粗暴：全局文件只放“你在任何项目中都不会变”的偏好，比如语言无关的代码风格底线、禁用某些声誉不佳的第三方库、通用安全要求；项目文件只放“只有这个仓库里成立”的约定。

我还发现 CLAUDE.md 能约束 AI 不碰某些目录。我经常会在一个存放接口文档和第三方私有包的目录里写上“此目录由团队脚本生成，禁止直接修改”。从此 AI 在这个目录下就不会自作主张生成多余文件。写清楚“哪些目录不要动”和写清楚“哪些目录可以动”同样重要。

4.3 一条实用的打磨流程与验证方法

CLAUDE.md 是持续调试出来的，我总结了一套四步验证流程，自用下来很顺手。

第一步，开局检查。新会话开始时，直接问 AI：“根据 CLAUDE.md，这个项目的测试命令是什么？有哪些禁止事项？”如果它能准确复述，说明文件被有效加载了；如果复述得不对，大概率是文件没放在正确目录或者格式有问题。

第二步，定向测试。给一个很小的修改任务，比如“在导出函数里补一个超时参数”，然后观察它是否严格遵守规范。如果它改了无关文件，说明规则覆盖不够或者有冲突。

第三步，回归测试。运行一次构建和测试，确认 AI 的改动没有破坏已有行为。这一步很关键，CLAUDE.md 写得再漂亮，最终产物还是要落到代码正确性上。

第四步，回写。如果这次会话里你反复口头纠正了同一个问题，会后就把它写进 CLAUDE.md。两周之后再回看，你会发现口头纠正次数越来越少，这才是这份文件真正的价值。

4.4 快查表：常见症状与对应解法

这张表我记在笔记里。每次有同事跟我抱怨“AI 记不住事”，我就会先让 TA 按表排查。排查完之后会发现，绝大多数问题不是模型太笨，而是记忆文件本身质量不过关。

经历过这些坑之后，我最大的体会是：CLAUDE.md 不是写给人看的文档，而是写给 AI 看的“灵魂记忆”。你愿不愿意花半小时把想法沉淀下来，直接决定未来一百次会话的质量。我现在很少在对话里反复解释项目背景，也很少纠正 AI 的重复错误，因为那些信息已经躺在文件里，每次开局就绪。最后再分享一个小技巧：把它当档案而不是便签来对待，认真维护版本，它回馈你的时间是几倍的。哪怕是个人玩具项目，只要你想让 AI 不“失忆”，CLAUDE.md 就是那个默认答案。