如果你问我在实际项目里和 AI 结对编程最值得提前做的一件事我会说是写一份CLAUDE.md。这个看似不起眼的文件几乎能把 AI 助手从一个“话痨实习生”调教成“懂规矩的熟手”。它本质上是一份给 AI 看的项目说明书把那些不会写进 API 文档、也不会出现在代码注释里的“潜规则”一次说清楚接口怎么写、错误怎么抛、测试放哪、命令怎么跑、哪些东西碰都不能碰。最近我花了不少时间研究 Claude Code 的协作流程发现真正拉开体验差距的不是模型本身有多强而是你有没有在项目里把这个文件写好。这个内容适合所有正在使用 Claude Code、Cline 或者其他支持项目级上下文文件的 AI 编程工具的人也适合那些想把自己团队规范“塞进 AI 脑子里”的前后端工程师。文章里我会拆清楚设计思路、给出我实测有效的写法再拿一个真实项目做一轮前后对比最后把我踩过的坑和排查方法全部列出来。1. 为什么 CLAUDE.md 能成为项目的“第二个 README”1.1 一句话理解 CLAUDE.md 到底做了什么简单说Claude Code 这类 AI 编程工具运行项目时会主动读取项目根目录下的CLAUDE.md文件把它作为上下文的一部分“喂”给模型。这份文件可以包含你对这个项目的一切约束性描述技术栈版本、目录结构、代码风格、命令规范、架构决策、反复踩过的坑以及不想让 AI 做的危险操作。很多人第一次看到这个文件时会把它理解成“又一个 prompt 模板”其实差距很大。prompt 是你每次对话临时提供的上下文而CLAUDE.md是默认加载的持久记忆。只要你在项目根目录启动工具它就会被自动读取相当于每个新会话里 AI 都熟悉了你们的项目背景。这一点非常关键AI 再用不着从零猜你的工程思路。举一个非常直观的例子。同样是让 AI 添加一个用户注册接口在没有CLAUDE.md的情况下模型很可能按自己训练数据里最常见的“通用做法”写返回 200 状态码、用默认的 exception 直接往上传、顺手导入一个项目根本没装的依赖。但如果有文件提前说明“本项目的 API 统一使用{code, message, data}包装错误必须抛出AppError并由全局异常处理器捕获”AI 生成的代码就会明显向你的工程规范靠拢。1.2 没有 CLAUDE.md 时AI 为什么总“失忆”我最早用 AI 写业务代码时有个很深的痛点同一个仓库里上午让 AI 写了一个带分页的列表接口下午让它写另一个模块类似的接口结果它选了完全不同的翻页参数风格。这不是笨而是模型默认情况下只会根据当前对话的少量上下文做推理项目里大量的既有约定它根本看不到。大项目的代码通常超出上下文窗口AI 不可能读完全部文件再动手。它能看到的往往只有几个相关文件而仓库里沉淀的隐性知识比如错误码规则、日志字段格式、枚举命名方式、数据库 session 的获取方式大多散落在几十个文件里。没有CLAUDE.md做索引和摘要AI 就像一个刚入职的同事既没时间翻完所有代码又不好意思总来问你只能按自己的直觉开工。还有一个非常现实的问题AI 会带着“通用最佳实践”来写代码。这个“最佳实践”可能来自它训练时见过的海量开源项目但未必适配你手头这个技术栈版本。举个常见场景项目里用的是旧版本 ORMAI 却生成了新版本的 API 风格项目统一用单引号和分号结尾AI 却写成了双引号项目约定所有数据库访问必须走 Repository 层AI 却直接在路由函数里开起了 session。这些问题的根源都是“上下文缺失”而CLAUDE.md恰好是成本最低的补充手段。1.3 设计思路把“潜规则”显式化团队项目里很多规矩其实从来没有写进任何正式文档。PR 评审时大家会说“变量名别用缩写”“这类操作要加事务”但这些都是口头约定新成员要靠无数次 code review 才能慢慢领悟。AI 更惨它连 code review 的对话都看不到只能靠你一条一条告诉它或者祈祷它没漏。CLAUDE.md的核心理念就是把这些隐式知识显式化。它不是从零发明规则而是把散落在语音会议、评审意见、老板口头禅、Git 提交历史里的“真实约束”整理成文。这份文件的读者不是人类而是 AI所以写作方式和普通文档很不一样要具体到能执行最好给出正例和反例要明确优先级还要时刻提醒自己“这句话 AI 看完后会做出什么行为”。同样一句话写给人看和写给 AI 看的效果完全不同。比如“注意代码质量”这种话写进 README 没问题写进CLAUDE.md就几乎没有约束力因为 AI 不知道你的“质量”具体是什么。但如果你写“所有新增函数必须带 docstring复杂逻辑必须拆分为三个以内的辅助函数禁止出现超过 200 行的函数”模型就能直接照着执行。把规则从形容词翻译成动词和指标是这份文件最重要的设计方法。2. 写一个可落地的 CLAUDE.md核心细节与实操要点2.1 文件放哪、叫什么、何时加载要使用CLAUDE.md第一步的路径和命名绝对不能错。目前 Claude Code 约定项目根目录下的CLAUDE.md会被自动加载同时它也支持子目录里的CLAUDE.md当你让 AI 操作某个子目录中的文件时工具会把根目录文件与当前目录附近文件的内容合并作为上下文。这个机制非常适合大型 monorepo根文件放全仓通用规则子目录文件放该模块特有规则。另外还有个CLAUDE.local.md的约定它一般被.gitignore忽略用于存放本地私有的、不适合提交到共享仓库的个人配置。比如你本地有特殊的构建缓存命令、你个人不喜欢某个命名风格都可以放在这里。这样既不会污染团队共享的“标准操作规范”也能让你自己的 AI 协作体验更顺畅。加载时机上需要注意Claude Code 通常会在启动到项目目录、或每次进入新会话时重新读取文件。如果你中途改了CLAUDE.md最好新开一个会话或者明确要求 AI“重新读取项目根目录的 CLAUDE.md”否则它可能仍在使用旧版本上下文。这个细节我在实际使用中吃过好几次亏改完文件但发现 AI 继续按老规矩干活一问才知道它用的还是缓存。提示文件名大小写要严格注意是CLAUDE.md不是Claude.md或claude.md。不同操作系统的默认大小写敏感度不一样建议团队统一在项目根目录放一份别搞出多个变体来。2.2 我建议的通用内容结构一份高可用的CLAUDE.md不需要套用固定模板也不需要写成一本书。我见过的最理想状态是把文件控制在 200 到 500 行左右信息密度高但每条规则都很短。下面是我在多个项目里反复迭代后沉淀出的 8 个板块你可以按照项目现状删减。项目一句话定位说明这个服务到底干什么的面向什么用户。看似废话但 AI 生成代码时会因此更贴合业务语境比如不会给一个内部工具乱加用户注册功能。技术栈与版本清单把语言、框架、ORM、包管理器、关键库的版本写清楚。这里可以顺带注明“禁止引入新依赖”的约束在需要时放开。架构与目录结构说明用简短的目录树和若干箭头描述核心依赖方向。AI 看完后能判断新增文件应该放哪不该放哪。编码规范与风格约定命名、格式化、错误处理、日志规范。尽量给出正例和反例而不是只写“风格要统一”。常用命令启动、测试、lint、格式化、构建以及数据库迁移。这些命令会反复出现在 AI 生成的工作流中写全可以省掉大量试错。禁止事项凡是可能导致事故的指令比如“不得在业务逻辑中直接调用 println”“禁止关闭外键校验”“不要手动改 migration 文件”。这部分要谨慎但明确。数据模型与领域关键词列出常见实体、关键字段、状态枚举。AI 在生成业务代码时能少犯“拼错字段名”这种低级错误。工作流约定分支命名、提交信息格式、MR/PR 清单。如果团队有统一流程写在这里比让 AI 自由发挥稳得多。这个结构不是让你每项都长篇大论而是每项至少有一条“让 AI 可以立刻行动”的规则。比如“技术栈”可以写成一句话“Python 3.12 FastAPI 0.115 SQLAlchemy 2.0ORM 统一使用异步 Session禁止使用 Django ORM。”这样既说明事实又带了边界。2.3 写法技巧让 AI 更愿意“听话”写CLAUDE.md最大的坑是把它当 README 写。README 面向人讲究背景、动机、架构演进而CLAUDE.md面向 AI核心是“可执行约束”。我根据自己的试错经历总结出几个非常有效的写法原则。第一条是尽量使用祈使句和强烈的边界词。AI 对“必须”“务必”“禁止”“一律”这类表达的敏感度明显高于“建议”“最好”“通常”。当然不是说要写成一堆命令而是在关键规则上态度要清楚。比如“所有数据库操作必须走BaseRepository子类”就比“建议通过 Repository 访问数据库”约束力强很多。第二条是给出正例和反例。模型非常擅长模式匹配一个对比示例比十行说明更有效。比如你要规定时间字段统一使用 UTC可以写“正确created_at datetime.now(timezone.utc)错误datetime.now()”。AI 看到这种格式会更容易在生成代码时套用。第三条是控制规则之间的冲突。比如根目录写了“禁止使用 Redis”子目录文件又写了“缓存建议用 Redis”AI 会陷入混乱。解决方式是层级明确根文件管全局底线子目录文件只允许添加更细化的规则不能推翻上级。如果确实需要覆盖要在子目录文件中写明“本模块例外允许使用 Redis”。第四条是避免纯否定清单。如果你的CLAUDE.md写满了“不要这样做”模型可能会手足无措因为它并不知道“要怎样做”。更好的策略是把“不要”翻译成“应该”不说“不要用同步函数”而说“所有 IO 操作用async def和await”不说“不要在业务里打印日志”而说“业务日志统一用logger对象并带上 request_id”。3. 一个真实项目的实战我把 CLAUDE.md 从 0 写到 13.1 项目背景与选型为了让这套方法更具体我这里拿一个典型的 FastAPI 项目举例。假设它是一个给内部运营使用的数据查询服务Python 3.12、FastAPI、SQLAlchemy 2.0 异步模式、Alembic 做迁移、pytest 写测试、Ruff 负责格式检查、日志用 structlog。业务的典型场景是查询订单、导出报表、计算统计指标。在没有CLAUDE.md之前AI 在这个项目里经常犯几个固定错误路由函数直接session SessionLocal()而不是通过依赖注入时间字段返回本地时区而不是 UTC异常处理直接 return 一个裸字符串新增依赖时不复用项目已有的httpx而是自己选了 requests测试文件写成test_xxx.py却放在 app 代码目录里而不是放到tests/下。这些问题单看都不大但每次都要手工改累积起来非常痛。后来我开始整理CLAUDE.md思路是从“AI 最容易在哪些地方跑偏”反推规则。我先花了半小时把项目的技术栈、启动命令、目录结构写清楚再打开最近十次被 AI 写坏的代码把出问题的点逐个转化成语义明确的禁止/允许规则。这个过程比我想象中快而且随着文件一步步完善AI 的“听话程度”肉眼可见地提升。3.2 实战三步走我建议你第一次写CLAUDE.md时也按三步走不要试图一步到位。第一步是“写事实”只写那些客观存在的项目信息相当于给 AI 画一张地图。比如# CLAUDE.md ## 项目定位 内部订单数据查询服务主要提供订单检索、报表导出、指标统计接口。 ## 技术栈 - Python 3.12 - FastAPI 0.115 - SQLAlchemy 2.0 异步模式 asyncpg - Alembic 管理迁移 - pytest httpx 做测试 - Ruff 做 lint 和 format - structlog 日志 ## 常用命令 - 启动服务uvicorn app.main:app --reload - 运行测试pytest -x -q - lint 检查ruff check . - 格式化ruff format . - 生成迁移alembic revision --autogenerate -m describe change - 执行迁移alembic upgrade head第二步是“写约束”把 AI 容易踩的线画出来。比如“所有路由函数必须使用 FastAPI 依赖注入获取AsyncSession禁止自己创建 session”“所有接口响应格式统一为{code, message, data}错误由全局异常处理器返回”“所有时间字段默认返回 UTC ISO 8601 格式”“新增第三方依赖前必须和项目现有依赖对比优先复用已有能力”。这些约束不能太宽泛每条都要能直接变成代码行为。第三步是“写样例”把最常见的正确写法和错误写法放在一起。比如项目里统一用 Pydantic v2 的model_dump()AI 却经常写dict()那就直接给对比## 响应序列化 - 正确payload UserOut.model_validate(user).model_dump() - 错误payload dict(user)这三步走完后文件已经有可用性。后续再根据实际使用中发现的偏差持续补丁就像给 AI 建立一份“错误行为修正记录”。不要期待一版写完它更像一个持续演进的知识库。3.3 实际效果一个接口的“调教前 vs 调教后”我在同一台机器、同一个项目里做过一次对照实验。请求内容是“在app/routers/users.py中新增一个 POST /users 接口创建用户并返回用户详情”。在没有CLAUDE.md时AI 生成的大致代码是同步 def、直接SessionLocal()、获取当前时间用datetime.now()、response 直接返回 ORM 对象、异常直接抛HTTPException(status_code400, detailstr(e))。添加CLAUDE.md之后同样的请求AI 生成的代码变成了async def从依赖注入拿 session时间用datetime.now(timezone.utc)返回体包在统一的ApiResponse里业务校验抛自定义AppErrorORM 对象过了一层 Pydantic schema。最明显的变化是它还会主动把新增测试文件放到tests/test_users.py并且用pytest.mark.anyio标记异步测试。这个差异不是模型变聪明了而是我们给了它一张准确的项目地图。更重要的是这种一致性会扩散到后续所有同类任务。比如当我再让它写“删除用户”的接口时它不会再生成一套风格完全不同的代码。因为CLAUDE.md中的约束在每次会话中都生效相当于 AI 在你项目里的“全局印象分”被固定住了。这种稳定性的价值在代码量大的项目里尤其明显。3.4 额外在 CI 中强制校验 CLAUDE.md 存在并匹配项目大了之后团队成员不一定都会维护CLAUDE.md所以我还在 CI 里加了一个很轻量的校验用脚本保证根目录文件存在并且包含几个关键锚点词组比如禁止、依赖注入、pytest。如果关键规则被误删或文件名被改坏流水线会提示。这个检查不占用多少时间但能避免“规则悄悄失效”的尴尬。当然这种 CI 校验只能做很基础的兜底没法判断规则内容是否过期。更靠谱的办法是团队约定每次技术决策发生变化比如换 ORM、换日志库、调整目录结构提交代码时同步更新CLAUDE.md。把它当作 README 的等价物而不是一次性产物。只有持续维护AI 才能一直“记得”项目最新的潜规则。4. 常见问题与排查技巧实录4.1 我踩过的坑和修复记录任何配置文件都会遇到“失效”问题CLAUDE.md也不例外。下面是我实际遇到过的几个典型问题以及对应的解决思路。现象可能原因我的处理方式AI 完全不理会 CLAUDE.md文件名或路径不对或启动目录不在项目根目录重新确认CLAUDE.md在根目录、大小写正确并新开会话验证规则写了很多但 AI 执行时抓不住重点文件过长核心规则被淹没把最关键的 5 条规则提到文件头部次要规则移到子目录文件项目级规则和全局规则冲突~/.claude/CLAUDE.md里也定义了同名规则项目内规则优先于全局规则主动删掉全局文件中的冲突条款改了文件但 AI 还是按旧规矩干活模型使用了缓存上下文新开会话或明确说“请重新加载项目根目录的 CLAUDE.md”AI 生成的代码和 CLAUDE.md 里定义的风格不一致规则太抽象缺少正反例给每个关键约束补上“正确xxx错误xxx”的对比片段这些问题的共性在于文件本身没有成为模型上下文的一部分或者规则没有转化成模型能直接套用的模式。有时候只要你把文件精简一点、示例改具体一点问题就解决了一大半。4.2 排查思路用“AI 复盘”来定位规则失效当 AI 生成的代码明显违反规则时先别急着改 prompt。我习惯让 AI 自己复盘“我刚才让你写的代码符合项目根目录 CLAUDE.md 的规范吗请逐条对照并指出违规点。”这个命令会强制它重新读取并理解那份文件很多时候它能立刻意识到问题在哪然后自己修正。这背后的原因很简单模型在生成代码时是“局部注意力”模式但当你要求它反思时它会重新扫描上下文里的CLAUDE.md从而注意到之前忽略的约束。如果你在每次大任务结束后都加一句“最后检查一遍是否符合 CLAUDE.md 中的约定”其实相当于给输出流程加了一道自检闸门比事后人肉 review 高效得多。如果 AI 复盘后仍然无视规则那你需要怀疑是不是文件路径不对、内容没有进入上下文或者规则之间出现了逻辑冲突。此时可以先输入“请列出项目根目录 CLAUDE.md 的前 20 行内容”如果它列不出来说明这个文件根本没被加载。先解决加载问题再谈规则优化。4.3 我的避坑技巧最后分享几个我这几个月用下来的独家心得都是普通文档里不会写太细的实操经验。第一个技巧是不要把 README 直接复制成 CLAUDE.md。README 里有太多背景故事和架构演进AI 读完之后并不能直接转化成代码行为。你要做的是把 README 里的技术栈和命令摘出来再加上 README 里完全没写的“错误处理方式”“禁止事项”“团队代码风格偏好”而不是整篇搬过去。第二个技巧是每次迭代结束让 AI 帮你提炼新规则。比如你做完一个需求后可以问它“在这次对话中有哪些我没有明说但你应该记住的规则”它常常会总结出几条你很认可的点比如“用户 ID 一律用 UUID 字符串”“金额字段用 Decimal 而不是 float”。人工确认后追加到CLAUDE.md这就是一个螺旋上升的规则自进化过程。第三个技巧是给规则分级。根文件只放跨模块通用的硬约束子目录文件放局部偏好CLAUDE.local.md放私人偏好。这样做的好处是当 AI 在某处代码上表现异常时你能快速判断是哪一层规则出了问题而不是在几百行文件里大海捞针。项目越复杂这个分层的价值越大。我用CLAUDE.md一段时间后最大的一个改变是开工前先花 20 分钟更新这份文件再开始写功能。听起来像是在做额外工作但节省的返工时间远超投入。它已经从单纯的 AI 上下文配置变成了一个团队知识沉淀的地方让新人和 AI 都能站在同一条起跑线上。如果你也在和 AI 协作写代码我强烈建议从今天开始为你的项目补上这份“潜规则说明书”。
用 CLAUDE.md 调教 AI 编程助手：项目潜规则显式化实践指南
如果你问我在实际项目里和 AI 结对编程最值得提前做的一件事我会说是写一份CLAUDE.md。这个看似不起眼的文件几乎能把 AI 助手从一个“话痨实习生”调教成“懂规矩的熟手”。它本质上是一份给 AI 看的项目说明书把那些不会写进 API 文档、也不会出现在代码注释里的“潜规则”一次说清楚接口怎么写、错误怎么抛、测试放哪、命令怎么跑、哪些东西碰都不能碰。最近我花了不少时间研究 Claude Code 的协作流程发现真正拉开体验差距的不是模型本身有多强而是你有没有在项目里把这个文件写好。这个内容适合所有正在使用 Claude Code、Cline 或者其他支持项目级上下文文件的 AI 编程工具的人也适合那些想把自己团队规范“塞进 AI 脑子里”的前后端工程师。文章里我会拆清楚设计思路、给出我实测有效的写法再拿一个真实项目做一轮前后对比最后把我踩过的坑和排查方法全部列出来。1. 为什么 CLAUDE.md 能成为项目的“第二个 README”1.1 一句话理解 CLAUDE.md 到底做了什么简单说Claude Code 这类 AI 编程工具运行项目时会主动读取项目根目录下的CLAUDE.md文件把它作为上下文的一部分“喂”给模型。这份文件可以包含你对这个项目的一切约束性描述技术栈版本、目录结构、代码风格、命令规范、架构决策、反复踩过的坑以及不想让 AI 做的危险操作。很多人第一次看到这个文件时会把它理解成“又一个 prompt 模板”其实差距很大。prompt 是你每次对话临时提供的上下文而CLAUDE.md是默认加载的持久记忆。只要你在项目根目录启动工具它就会被自动读取相当于每个新会话里 AI 都熟悉了你们的项目背景。这一点非常关键AI 再用不着从零猜你的工程思路。举一个非常直观的例子。同样是让 AI 添加一个用户注册接口在没有CLAUDE.md的情况下模型很可能按自己训练数据里最常见的“通用做法”写返回 200 状态码、用默认的 exception 直接往上传、顺手导入一个项目根本没装的依赖。但如果有文件提前说明“本项目的 API 统一使用{code, message, data}包装错误必须抛出AppError并由全局异常处理器捕获”AI 生成的代码就会明显向你的工程规范靠拢。1.2 没有 CLAUDE.md 时AI 为什么总“失忆”我最早用 AI 写业务代码时有个很深的痛点同一个仓库里上午让 AI 写了一个带分页的列表接口下午让它写另一个模块类似的接口结果它选了完全不同的翻页参数风格。这不是笨而是模型默认情况下只会根据当前对话的少量上下文做推理项目里大量的既有约定它根本看不到。大项目的代码通常超出上下文窗口AI 不可能读完全部文件再动手。它能看到的往往只有几个相关文件而仓库里沉淀的隐性知识比如错误码规则、日志字段格式、枚举命名方式、数据库 session 的获取方式大多散落在几十个文件里。没有CLAUDE.md做索引和摘要AI 就像一个刚入职的同事既没时间翻完所有代码又不好意思总来问你只能按自己的直觉开工。还有一个非常现实的问题AI 会带着“通用最佳实践”来写代码。这个“最佳实践”可能来自它训练时见过的海量开源项目但未必适配你手头这个技术栈版本。举个常见场景项目里用的是旧版本 ORMAI 却生成了新版本的 API 风格项目统一用单引号和分号结尾AI 却写成了双引号项目约定所有数据库访问必须走 Repository 层AI 却直接在路由函数里开起了 session。这些问题的根源都是“上下文缺失”而CLAUDE.md恰好是成本最低的补充手段。1.3 设计思路把“潜规则”显式化团队项目里很多规矩其实从来没有写进任何正式文档。PR 评审时大家会说“变量名别用缩写”“这类操作要加事务”但这些都是口头约定新成员要靠无数次 code review 才能慢慢领悟。AI 更惨它连 code review 的对话都看不到只能靠你一条一条告诉它或者祈祷它没漏。CLAUDE.md的核心理念就是把这些隐式知识显式化。它不是从零发明规则而是把散落在语音会议、评审意见、老板口头禅、Git 提交历史里的“真实约束”整理成文。这份文件的读者不是人类而是 AI所以写作方式和普通文档很不一样要具体到能执行最好给出正例和反例要明确优先级还要时刻提醒自己“这句话 AI 看完后会做出什么行为”。同样一句话写给人看和写给 AI 看的效果完全不同。比如“注意代码质量”这种话写进 README 没问题写进CLAUDE.md就几乎没有约束力因为 AI 不知道你的“质量”具体是什么。但如果你写“所有新增函数必须带 docstring复杂逻辑必须拆分为三个以内的辅助函数禁止出现超过 200 行的函数”模型就能直接照着执行。把规则从形容词翻译成动词和指标是这份文件最重要的设计方法。2. 写一个可落地的 CLAUDE.md核心细节与实操要点2.1 文件放哪、叫什么、何时加载要使用CLAUDE.md第一步的路径和命名绝对不能错。目前 Claude Code 约定项目根目录下的CLAUDE.md会被自动加载同时它也支持子目录里的CLAUDE.md当你让 AI 操作某个子目录中的文件时工具会把根目录文件与当前目录附近文件的内容合并作为上下文。这个机制非常适合大型 monorepo根文件放全仓通用规则子目录文件放该模块特有规则。另外还有个CLAUDE.local.md的约定它一般被.gitignore忽略用于存放本地私有的、不适合提交到共享仓库的个人配置。比如你本地有特殊的构建缓存命令、你个人不喜欢某个命名风格都可以放在这里。这样既不会污染团队共享的“标准操作规范”也能让你自己的 AI 协作体验更顺畅。加载时机上需要注意Claude Code 通常会在启动到项目目录、或每次进入新会话时重新读取文件。如果你中途改了CLAUDE.md最好新开一个会话或者明确要求 AI“重新读取项目根目录的 CLAUDE.md”否则它可能仍在使用旧版本上下文。这个细节我在实际使用中吃过好几次亏改完文件但发现 AI 继续按老规矩干活一问才知道它用的还是缓存。提示文件名大小写要严格注意是CLAUDE.md不是Claude.md或claude.md。不同操作系统的默认大小写敏感度不一样建议团队统一在项目根目录放一份别搞出多个变体来。2.2 我建议的通用内容结构一份高可用的CLAUDE.md不需要套用固定模板也不需要写成一本书。我见过的最理想状态是把文件控制在 200 到 500 行左右信息密度高但每条规则都很短。下面是我在多个项目里反复迭代后沉淀出的 8 个板块你可以按照项目现状删减。项目一句话定位说明这个服务到底干什么的面向什么用户。看似废话但 AI 生成代码时会因此更贴合业务语境比如不会给一个内部工具乱加用户注册功能。技术栈与版本清单把语言、框架、ORM、包管理器、关键库的版本写清楚。这里可以顺带注明“禁止引入新依赖”的约束在需要时放开。架构与目录结构说明用简短的目录树和若干箭头描述核心依赖方向。AI 看完后能判断新增文件应该放哪不该放哪。编码规范与风格约定命名、格式化、错误处理、日志规范。尽量给出正例和反例而不是只写“风格要统一”。常用命令启动、测试、lint、格式化、构建以及数据库迁移。这些命令会反复出现在 AI 生成的工作流中写全可以省掉大量试错。禁止事项凡是可能导致事故的指令比如“不得在业务逻辑中直接调用 println”“禁止关闭外键校验”“不要手动改 migration 文件”。这部分要谨慎但明确。数据模型与领域关键词列出常见实体、关键字段、状态枚举。AI 在生成业务代码时能少犯“拼错字段名”这种低级错误。工作流约定分支命名、提交信息格式、MR/PR 清单。如果团队有统一流程写在这里比让 AI 自由发挥稳得多。这个结构不是让你每项都长篇大论而是每项至少有一条“让 AI 可以立刻行动”的规则。比如“技术栈”可以写成一句话“Python 3.12 FastAPI 0.115 SQLAlchemy 2.0ORM 统一使用异步 Session禁止使用 Django ORM。”这样既说明事实又带了边界。2.3 写法技巧让 AI 更愿意“听话”写CLAUDE.md最大的坑是把它当 README 写。README 面向人讲究背景、动机、架构演进而CLAUDE.md面向 AI核心是“可执行约束”。我根据自己的试错经历总结出几个非常有效的写法原则。第一条是尽量使用祈使句和强烈的边界词。AI 对“必须”“务必”“禁止”“一律”这类表达的敏感度明显高于“建议”“最好”“通常”。当然不是说要写成一堆命令而是在关键规则上态度要清楚。比如“所有数据库操作必须走BaseRepository子类”就比“建议通过 Repository 访问数据库”约束力强很多。第二条是给出正例和反例。模型非常擅长模式匹配一个对比示例比十行说明更有效。比如你要规定时间字段统一使用 UTC可以写“正确created_at datetime.now(timezone.utc)错误datetime.now()”。AI 看到这种格式会更容易在生成代码时套用。第三条是控制规则之间的冲突。比如根目录写了“禁止使用 Redis”子目录文件又写了“缓存建议用 Redis”AI 会陷入混乱。解决方式是层级明确根文件管全局底线子目录文件只允许添加更细化的规则不能推翻上级。如果确实需要覆盖要在子目录文件中写明“本模块例外允许使用 Redis”。第四条是避免纯否定清单。如果你的CLAUDE.md写满了“不要这样做”模型可能会手足无措因为它并不知道“要怎样做”。更好的策略是把“不要”翻译成“应该”不说“不要用同步函数”而说“所有 IO 操作用async def和await”不说“不要在业务里打印日志”而说“业务日志统一用logger对象并带上 request_id”。3. 一个真实项目的实战我把 CLAUDE.md 从 0 写到 13.1 项目背景与选型为了让这套方法更具体我这里拿一个典型的 FastAPI 项目举例。假设它是一个给内部运营使用的数据查询服务Python 3.12、FastAPI、SQLAlchemy 2.0 异步模式、Alembic 做迁移、pytest 写测试、Ruff 负责格式检查、日志用 structlog。业务的典型场景是查询订单、导出报表、计算统计指标。在没有CLAUDE.md之前AI 在这个项目里经常犯几个固定错误路由函数直接session SessionLocal()而不是通过依赖注入时间字段返回本地时区而不是 UTC异常处理直接 return 一个裸字符串新增依赖时不复用项目已有的httpx而是自己选了 requests测试文件写成test_xxx.py却放在 app 代码目录里而不是放到tests/下。这些问题单看都不大但每次都要手工改累积起来非常痛。后来我开始整理CLAUDE.md思路是从“AI 最容易在哪些地方跑偏”反推规则。我先花了半小时把项目的技术栈、启动命令、目录结构写清楚再打开最近十次被 AI 写坏的代码把出问题的点逐个转化成语义明确的禁止/允许规则。这个过程比我想象中快而且随着文件一步步完善AI 的“听话程度”肉眼可见地提升。3.2 实战三步走我建议你第一次写CLAUDE.md时也按三步走不要试图一步到位。第一步是“写事实”只写那些客观存在的项目信息相当于给 AI 画一张地图。比如# CLAUDE.md ## 项目定位 内部订单数据查询服务主要提供订单检索、报表导出、指标统计接口。 ## 技术栈 - Python 3.12 - FastAPI 0.115 - SQLAlchemy 2.0 异步模式 asyncpg - Alembic 管理迁移 - pytest httpx 做测试 - Ruff 做 lint 和 format - structlog 日志 ## 常用命令 - 启动服务uvicorn app.main:app --reload - 运行测试pytest -x -q - lint 检查ruff check . - 格式化ruff format . - 生成迁移alembic revision --autogenerate -m describe change - 执行迁移alembic upgrade head第二步是“写约束”把 AI 容易踩的线画出来。比如“所有路由函数必须使用 FastAPI 依赖注入获取AsyncSession禁止自己创建 session”“所有接口响应格式统一为{code, message, data}错误由全局异常处理器返回”“所有时间字段默认返回 UTC ISO 8601 格式”“新增第三方依赖前必须和项目现有依赖对比优先复用已有能力”。这些约束不能太宽泛每条都要能直接变成代码行为。第三步是“写样例”把最常见的正确写法和错误写法放在一起。比如项目里统一用 Pydantic v2 的model_dump()AI 却经常写dict()那就直接给对比## 响应序列化 - 正确payload UserOut.model_validate(user).model_dump() - 错误payload dict(user)这三步走完后文件已经有可用性。后续再根据实际使用中发现的偏差持续补丁就像给 AI 建立一份“错误行为修正记录”。不要期待一版写完它更像一个持续演进的知识库。3.3 实际效果一个接口的“调教前 vs 调教后”我在同一台机器、同一个项目里做过一次对照实验。请求内容是“在app/routers/users.py中新增一个 POST /users 接口创建用户并返回用户详情”。在没有CLAUDE.md时AI 生成的大致代码是同步 def、直接SessionLocal()、获取当前时间用datetime.now()、response 直接返回 ORM 对象、异常直接抛HTTPException(status_code400, detailstr(e))。添加CLAUDE.md之后同样的请求AI 生成的代码变成了async def从依赖注入拿 session时间用datetime.now(timezone.utc)返回体包在统一的ApiResponse里业务校验抛自定义AppErrorORM 对象过了一层 Pydantic schema。最明显的变化是它还会主动把新增测试文件放到tests/test_users.py并且用pytest.mark.anyio标记异步测试。这个差异不是模型变聪明了而是我们给了它一张准确的项目地图。更重要的是这种一致性会扩散到后续所有同类任务。比如当我再让它写“删除用户”的接口时它不会再生成一套风格完全不同的代码。因为CLAUDE.md中的约束在每次会话中都生效相当于 AI 在你项目里的“全局印象分”被固定住了。这种稳定性的价值在代码量大的项目里尤其明显。3.4 额外在 CI 中强制校验 CLAUDE.md 存在并匹配项目大了之后团队成员不一定都会维护CLAUDE.md所以我还在 CI 里加了一个很轻量的校验用脚本保证根目录文件存在并且包含几个关键锚点词组比如禁止、依赖注入、pytest。如果关键规则被误删或文件名被改坏流水线会提示。这个检查不占用多少时间但能避免“规则悄悄失效”的尴尬。当然这种 CI 校验只能做很基础的兜底没法判断规则内容是否过期。更靠谱的办法是团队约定每次技术决策发生变化比如换 ORM、换日志库、调整目录结构提交代码时同步更新CLAUDE.md。把它当作 README 的等价物而不是一次性产物。只有持续维护AI 才能一直“记得”项目最新的潜规则。4. 常见问题与排查技巧实录4.1 我踩过的坑和修复记录任何配置文件都会遇到“失效”问题CLAUDE.md也不例外。下面是我实际遇到过的几个典型问题以及对应的解决思路。现象可能原因我的处理方式AI 完全不理会 CLAUDE.md文件名或路径不对或启动目录不在项目根目录重新确认CLAUDE.md在根目录、大小写正确并新开会话验证规则写了很多但 AI 执行时抓不住重点文件过长核心规则被淹没把最关键的 5 条规则提到文件头部次要规则移到子目录文件项目级规则和全局规则冲突~/.claude/CLAUDE.md里也定义了同名规则项目内规则优先于全局规则主动删掉全局文件中的冲突条款改了文件但 AI 还是按旧规矩干活模型使用了缓存上下文新开会话或明确说“请重新加载项目根目录的 CLAUDE.md”AI 生成的代码和 CLAUDE.md 里定义的风格不一致规则太抽象缺少正反例给每个关键约束补上“正确xxx错误xxx”的对比片段这些问题的共性在于文件本身没有成为模型上下文的一部分或者规则没有转化成模型能直接套用的模式。有时候只要你把文件精简一点、示例改具体一点问题就解决了一大半。4.2 排查思路用“AI 复盘”来定位规则失效当 AI 生成的代码明显违反规则时先别急着改 prompt。我习惯让 AI 自己复盘“我刚才让你写的代码符合项目根目录 CLAUDE.md 的规范吗请逐条对照并指出违规点。”这个命令会强制它重新读取并理解那份文件很多时候它能立刻意识到问题在哪然后自己修正。这背后的原因很简单模型在生成代码时是“局部注意力”模式但当你要求它反思时它会重新扫描上下文里的CLAUDE.md从而注意到之前忽略的约束。如果你在每次大任务结束后都加一句“最后检查一遍是否符合 CLAUDE.md 中的约定”其实相当于给输出流程加了一道自检闸门比事后人肉 review 高效得多。如果 AI 复盘后仍然无视规则那你需要怀疑是不是文件路径不对、内容没有进入上下文或者规则之间出现了逻辑冲突。此时可以先输入“请列出项目根目录 CLAUDE.md 的前 20 行内容”如果它列不出来说明这个文件根本没被加载。先解决加载问题再谈规则优化。4.3 我的避坑技巧最后分享几个我这几个月用下来的独家心得都是普通文档里不会写太细的实操经验。第一个技巧是不要把 README 直接复制成 CLAUDE.md。README 里有太多背景故事和架构演进AI 读完之后并不能直接转化成代码行为。你要做的是把 README 里的技术栈和命令摘出来再加上 README 里完全没写的“错误处理方式”“禁止事项”“团队代码风格偏好”而不是整篇搬过去。第二个技巧是每次迭代结束让 AI 帮你提炼新规则。比如你做完一个需求后可以问它“在这次对话中有哪些我没有明说但你应该记住的规则”它常常会总结出几条你很认可的点比如“用户 ID 一律用 UUID 字符串”“金额字段用 Decimal 而不是 float”。人工确认后追加到CLAUDE.md这就是一个螺旋上升的规则自进化过程。第三个技巧是给规则分级。根文件只放跨模块通用的硬约束子目录文件放局部偏好CLAUDE.local.md放私人偏好。这样做的好处是当 AI 在某处代码上表现异常时你能快速判断是哪一层规则出了问题而不是在几百行文件里大海捞针。项目越复杂这个分层的价值越大。我用CLAUDE.md一段时间后最大的一个改变是开工前先花 20 分钟更新这份文件再开始写功能。听起来像是在做额外工作但节省的返工时间远超投入。它已经从单纯的 AI 上下文配置变成了一个团队知识沉淀的地方让新人和 AI 都能站在同一条起跑线上。如果你也在和 AI 协作写代码我强烈建议从今天开始为你的项目补上这份“潜规则说明书”。