我写了 3 版 CLAUDE.mdAI 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 ORMPostgreSQL 数据库。 # 项目结构 - 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项目里数据库查询统一用asyncsessionAI 写的全是同步调用。这一版的教训只告诉 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_{模块名}.pytests 目录下必须带 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 开发云常年折扣新用户首单特惠 觉得有用就点个赞想追更就点个关注——下次搜到我不靠缘分。