我写了 3 版 CLAUDE.md，AI Agent 的代码通过率从 30% 跳到了 85%
我写了 3 版 CLAUDE.md，AI Agent 的代码通过率从 30% 跳到了 85%
上个月我用 Claude Code 重构一个 Python 项目，每次让 AI 改代码，改完就跑不通——不是 import 路径错，就是 API 签名对不上，要么直接用了项目里根本不存在的函数。30% 的改动能一次跑通，剩下 70% 我得手动修。我一度觉得 AI 编程也就这样了——直到我认真写了一版 CLAUDE.md。
三个月过去，我的 CLAUDE.md 迭代了三版，代码一次通过率从 30% 爬到了 85%。这篇文章把每一版改了什么、为什么改、效果差在哪，全拆开给你看。
第一版：什么都没写（通过率 ~30%）
第一周我根本没写 CLAUDE.md——Claude Code 装好就直接用。结果是灾难性的。
最典型的场景：我让它「给 user_service.py 加一个分页查询接口」。它写出来的代码用了paginate()函数——这个函数在我项目里根本不存在。因为项目用的是 SQLAlchemy 的limit().offset()模式，但它不知道。
还有一次让它写单元测试，它用unittest框架写了 10 个测试用例。但我的项目用的是pytest，测试文件放在tests/目录下。结果它把测试文件写到了项目根目录，文件名也不对。
这一版的教训：AI 对你的项目一无所知。你不告诉它项目结构、技术栈、代码规范，它就只能猜——猜错的概率远大于猜对。
第二版：基本信息填上（通过率 ~55%）
意识到问题后，我写了第一版 CLAUDE.md，大概 30 行：
# 项目概述 这是一个 FastAPI 后端服务，使用 SQLAlchemy ORM，PostgreSQL 数据库。 # 项目结构 - `app/` — 主应用代码 - `models/` — SQLAlchemy 模型 - `services/` — 业务逻辑层 - `routers/` — FastAPI 路由 - `tests/` — pytest 测试文件 - `alembic/` — 数据库迁移 # 技术栈 - Python 3.11+ - FastAPI 0.100+ - SQLAlchemy 2.0+ - pytest + pytest-asyncio - PostgreSQL 15 # 代码风格 - 使用 type hints - 函数命名：snake_case - 类命名：PascalCase效果立竿见影。AI 终于知道项目用 FastAPI 而不是 Flask，知道测试放tests/而不是根目录，知道数据库是 PostgreSQL 不是 MySQL。import 路径错误大幅减少，测试框架不会再跑偏。
但新问题出现了：AI 写的代码风格跟项目已有代码不搭。比如项目里错误处理统一返回{"error": "...", "code": 400}，AI 却直接raise HTTPException；项目里数据库查询统一用asyncsession，AI 写的全是同步调用。
这一版的教训：只告诉 AI「项目有什么」不够，还得告诉它「代码怎么写算对」。
第三版：加上规则和反例（通过率 ~85%）
第三版我把 CLAUDE.md 扩展到了 60 行，核心变化是加了规则（Rules）和反例（Anti-patterns）：
# 必须遵守的规则 1. 所有数据库操作必须使用 async session —— 从 `app.db` 导入 `get_db`，不要自己创建 session 2. 错误响应统一格式： return JSONResponse( content={"error": "描述", "code": 错误码}, status_code=状态码 ) —— 不要直接 raise HTTPException 3. 分页查询使用 SQLAlchemy 的 .limit().offset() —— 项目里没有 paginate() 这个函数，不要用 4. 新增路由必须在 app/routers/__init__.py 里注册 5. 测试文件命名：tests/test_{模块名}.py —— 不是 test_{模块名}.py，tests 目录下必须带 test_ 前缀 # 禁止做的事 - 不要使用项目中不存在的第三方库（用前先检查 requirements.txt） - 不要在测试里创建真实数据库记录（用 fixtures 和 mock） - 不要修改 alembic/ 目录下的迁移文件（除非明确要求）这版上去之后，变化是质的。AI 终于写出了「看起来像这个项目自己人写的」代码。
举一个真实的例子：我让它「给 articles 表加一个status字段，写迁移、更新 model、加查询接口」。三件事，一次完成。迁移文件放在alembic/versions/，model 加了 type hint，接口用了统一的错误格式——全部跑通，零手动修改。
为什么「反例」这么重要？因为 AI 的默认行为往往是你项目里不需要的。你说「不要用 paginate()」，它才知道那个函数不存在。你不说，它会反复踩同一个坑。反例 = 提前排雷。
我的 CLAUDE.md 模板
如果你也想从零开始写，直接套这个骨架：
# 项目概述 一句话描述 + 核心技术 # 项目结构（带路径） 列出关键目录和用途 # 技术栈（带版本） Python/Node/Java 版本 + 框架 + 数据库 + 测试工具 # 代码规范（5-8 条） 具体到你项目中「AI 最容易犯的错」 # 禁止事项（3-5 条） 碰都不能碰的事两个关键原则：
具体到文件名和函数名。不要写「使用统一的错误处理」，要写「用
app.utils.errors.json_error(code, msg)」。AI 需要的是可执行指令，不是原则性指导。每次 AI 犯低级错误后，立刻更新 CLAUDE.md。把错误写成一条规则或反例。AI 的犯错模式高度重复——同一个坑它会反复踩，除非你明确告诉它「这里有个坑」。
三个月前我还在手动修 AI 写的代码，现在大部分任务改完直接跑。不是 AI 变聪明了——是我终于学会了怎么告诉它「在我的项目里，什么是对的」。
你在用 AI Agent 写代码时踩过什么坑？有没有什么奇葩的错误 AI 反复犯？评论区聊聊，说不定你的经验能救我一命。
📌 作者：Aliaoo
🚀 专注 AI 工具实战、云部署、自动化脚本。每篇都是亲测可跑的教程。
🖥️需要云服务器跑项目？👉 CSDN 开发云常年折扣，新用户首单特惠
📬 觉得有用就点个赞，想追更就点个关注——下次搜到我不靠缘分。