CLAUDE.md 详解：防止AI犯错的那个文件

CLAUDE.md 详解：这个文件能防止约90%的AI编程错误。它是什么，里面确切该写什么，以及如何只用5条规则就开始写出你自己的那一份文件。

分类Build with AI

阅读时长1 分钟

已发布2026年8月5日

作者Luis Goncalves

CLAUDE.md 详解：它是放在项目根目录的纯文本文件，你的AI编程工具在每次回答之前都会读它——能防止AI在你的代码库里约90%的错误。它不是代码。它是规则手册：你项目的模式、你的底线、AI绝不能重犯的错误。

大多数用AI做产品的人根本不知道它的存在。下面讲讲它是什么、为什么它能改变一切，以及你的那份该写些什么。

CLAUDE.md 详解：员工手册的类比

想象你雇了一位才华横溢的外包人员，但他每次开完会就彻底失忆。每天早晨他到岗时，对你公司的运作一无所知——你的标准、你的归档系统、你过去的决定。每天早晨你都得重新解释一切，而在你解释之前，每天早晨他都会犯同样的错误。

现在想象你递给他一本员工手册，他在每次会议开始时重读一遍。突然间，他一到岗就已经知道你的规则。

这就是CLAUDE.md。AI编程工具每次对话都从零开始——它们不记得昨天你的纠正。CLAUDE.md就是它们在回应任何内容之前自动阅读的手册。把它看作你代码库的宪法：AI必须遵守的规则、必须使用的模式、绝不能犯的错误。

这是我的亲身经历。我当时在为我的平台构建一个申请评审系统——复杂的评分逻辑、多步骤工作流、几十张数据库表。我对Claude说：“构建申请评审服务。”

Claude生成了代码。能跑。而且在五个地方是错的：

我手动修好了一切。然后我要的下一个文件呢？同样的错误。又来了。我在每一个文件上都在跟Claude较劲——不是因为Claude不好，而是因为它对我项目的规则失忆了。没有CLAUDE.md，你每次对话都是在从零重新训练你的AI。

一份好的CLAUDE.md有七个部分。没有一个需要你写代码——它们需要你陈述决定，而这正是架构师的工作：

部分	它告诉AI什么	示例（用大白话）
项目性质	这个产品是什么，规模多大	“一款用于项目管理的多租户SaaS”
关键规则	底线，写成“始终/绝不”的语句	“每个查询都必须始终标注客户所属的组织”
架构模式	这里的代码如何组织	“所有数据库访问都经过服务层”
技术栈	正在使用的确切工具	“数据库用Supabase，部署在Cloudflare上”
文件位置	各类东西该放在哪里	“服务放在一个文件夹，界面放在另一个”
示例	你项目里做对了的真实代码	AI应当模仿的一个可运行功能
反模式	不该做什么，并展示错误与正确的做法	“绝不要在没有客户标签的情况下获取数据”

最有威力的是最后两部分。AI是一台模式匹配机器：给它看一个做对了的真实代码示例，它就会到处模仿。给它看它上周犯的那个确切错误，标上“绝不要这样做”，这个错误就会消失。

同样的请求——“构建申请评审服务”——加上CLAUDE.md之后。Claude先读了规则，然后生成的代码遵循了我的结构，与我的数据库完全匹配，每个查询都为多租户做了标注，用我的方式处理错误，并把每个文件放在正确的位置。一次通过。零修改。

我知道它是魔法的那一刻：我需要一个导师匹配功能——复杂逻辑，多张表。在有CLAUDE.md之前，这意味着花几个小时修AI的输出。之后，我只说了“用与申请评审相同的模式来构建导师匹配”。Claude读了规则手册，研究了之前的功能，并按每一个模式构建了整个东西。花了15分钟，运行完美。

没有这个文件的话，预计每个生成的文件都要花大约30分钟修复——错误的模式、缺失的保护措施、放错位置的文件。乘以几百个文件，CLAUDE.md就是能交付与被淹没之间的区别。

不用写成杰作。从五条规则开始——你的AI在你的项目里一再犯的五个错误——外加一行描述你在做什么以及你的技术栈。就这样。

然后把它当作一份活的文档。每当AI犯了新错误，就加一条规则。每当它生成了很棒的东西，就把那段代码复制到示例部分。最佳区间是200–400行：不到100行上下文太少，超过500行AI就会被淹没。

有一条值得了解的界线：CLAUDE.md放的是你全局的、始终成立的规则。对于大型的一次性功能，你还需要一份针对任务的说明，写明该功能的确切需求和背景——那是另一种工具，即PRP方法，两者配合使用：每天用宪法，每次构建用蓝图。

放在项目根目录的一个Markdown（纯文本）文件，Claude Code在每次回答之前都会读取它。它包含你项目的规则、模式、技术栈、真实代码示例和反模式——这样AI从第一次就遵循你的标准，而不是每次对话都被重新训练。

不需要。文件用大白话写：产品是什么，必须始终成立的规则，绝不能发生的事。至于示例部分，你把AI自己某次做对时生成的代码粘贴进去即可。陈述决定是创始人的工作；实现它们是AI的工作。

今天先从五条规则开始。逐步增长到200–400行——长到足以承载你的模式，短到AI真的会用上全部内容。不到100行太单薄；超过500行就要精简。每周回顾一次：加入新模式，删掉过时的规则。

它涵盖的是全局规则——否则会在每个文件上重复出现的错误。对于复杂功能，你还需要一份针对任务的规格说明，写明该功能的确切需求、数据和验证步骤。那就是PRP方法；CLAUDE.md加上PRP，就是一次把功能做对的方式。

继续阅读

完成职场窒息指数——这项免费测评告诉你是否已准备好成为独立创业者。