我是张大鹏，有十多年 AI 人工智能项目的开发经验，带过不少项目。说实话，最难的不是写代码，是让 AI 真正理解你想要什么。最近给项目加了一份 CLAUDE.md，效果立竿见影——Claude Code 从"莽撞乱撞"变成了"精准出击"。今天聊聊为什么这么一小文件，能让 AI 编程效率提升至少一倍。

---

一、问题的本质：AI 编程的「盲人摸象」困境

大家有没有这种感觉：明明你花了很多时间描述需求，AI 写出来的代码却总是不对？

我举个例子。我的 InsMatrixAutomation 项目，用的是 Flask + Jinja2 + Bootstrap 5，但 Claude Code 第一次帮我写代码时，它居然想用 Vue.js！这就是问题所在——AI 不知道你项目的技术栈、不知道你的规范、不知道你的禁区。

没有 CLAUDE.md 的 AI，就像一个能力很强但不熟悉你业务的实习生：

• 不了解你的技术选型（可能引入禁止的技术）
• 不清楚代码风格（可能用 camelCase 破坏 snake_case 规范）
• 不知道哪些是红线（可能硬编码 API 密钥）
• 搞不懂日志规范（可能直接 print 而不是用装饰器）

这就是「盲人摸象」困境：AI 能力很强，但对你的项目一无所知。

---

二、CLAUDE.md 是什么？

CLAUDE.md 是什么？它是项目的「宪法」，是 AI 编程的行为准则。

当你用 Claude Code 打开项目时，它会自动读取项目根目录的 CLAUDE.md，然后根据这份文件来约束自己的行为。

InsMatrixAutomation/
├── CLAUDE.md          ← AI 的「工作手册」
├── application/       ← 业务代码
├── docs/
│   └── design/       ← 设计文档
└── tests/

就像新员工入职要先读员工手册一样，AI 也需要一份指南告诉它：什么该做，什么不该做。

---

三、CLAUDE.md 解决了什么问题？

3.1 告诉 AI 你的「技术栈清单」

## 技术栈（不可改变）

| 层级 | 技术 | 禁止 |
|------|------|------|
| 后端 | Flask 3.0+ | — |
| 前端 | Jinja2 + Bootstrap 5 | Vue / React / jQuery |
| 包管理 | **UV** | pip |

有了这个，Claude Code 再也不会引入 Vue.js 了——因为它知道这是禁区。

3.2 告诉 AI 你的「代码规范」

## 包管理
# ✅ 正确
uv add <package>
# ❌ 错误
pip install <package>

AI 知道要用 UV 而不是 pip，避免了依赖管理的混乱。

3.3 告诉 AI 你的「日志规范」

## 日志规范
- 关键业务操作必须使用 @log_operation 装饰器
- 敏感字段必须脱敏后记录

AI 不会在日志里打印 password 的原始值了。

3.4 告诉 AI 你的「12 条工作准则」

这是从 Mnimiy 实践总结出的核心规则，错误率从 41% 降到 3%：

规则	核心要点
思考后动手	明确假设，不确定就问
简单优先	最少代码解决问题
精准修改	只动必须动的地方
目标驱动	告诉成功什么样，不告诉步骤
先读代码再写	加代码前先读导出/调用方

---

四、CLAUDE.md 什么时候起作用？

场景 1：项目初始化

当你第一次把项目交给 Claude Code 时，它会读取 CLAUDE.md，然后说：「我看到这个项目用 Flask + Bootstrap 5，禁止使用 Vue/React，需要用 UV 管理依赖…」

场景 2：每次编程任务

当你让 Claude Code 实现一个新功能时：

• 它会先读 CLAUDE.md 了解规范
• 然后读相关的设计文档
• 最后才开始写代码

场景 3：代码审查

Claude Code 帮你审查代码时，会对照 CLAUDE.md 检查：

• 是否用了 UV 而不是 pip？
• 是否有硬编码的 API 密钥？
• 是否正确使用了日志装饰器？

场景 4：解决问题

当你问「为什么日志没记录」时，Claude Code 会根据 CLAUDE.md 的 FAQ 回答：「检查是否用了 @log_operation」。

---

五、CLAUDE.md 怎么写？

5.1 核心结构

一份实用的 CLAUDE.md 应该包含：

# 项目名

> AI Agent 编程准则

## 1. 设计文档优先
## 2. 技术栈（不可改变）
## 3. 核心规则（12 条）
## 4. 包管理规范
## 5. 日志规范
## 6. 安全红线
## 7. 常见问题

5.2 写作原则

原则	说明
克制	只写真正需要的规则，每条对应一个踩坑
精炼	不超过 200 行
实用	读完就知道「怎么做是对的」
具体	给出正面示例和反面示例

5.3 我的 CLAUDE.md 节选

## 包管理

```bash
# ✅ 正确
uv add <package>

# ❌ 错误
pip install <package>

安全红线

禁止	正确
硬编码 API 密钥	os.environ.get("API_KEY")
记录敏感字段原始值	先脱敏再记录
直接拼接 SQL	使用 ORM

---

六、效果对比

对比项	没有 CLAUDE.md	有 CLAUDE.md
技术选型	可能引入禁止的技术	严格遵守技术栈
代码风格	各写各的，风格混乱	匹配现有惯例
错误率	约 40%	约 3%
调试时间	长	短（规则清晰）
代码一致性	低	高

---

七、总结

维度	内容
核心思路	给 AI 一份「工作手册」，让它理解项目的规范和禁区
关键作用	自动读取、自动约束、提升效率、降低错误率
适用场景	任何需要 AI 编程的项目，尤其是团队协作
注意事项	保持精炼（<200行），每条规则对应真实踩坑

CLAUDE.md 不是技术文档，是行为准则。 它让 AI 从「盲目发挥」变成「精准执行」，从「总猜错」变成「一次对」。

---

参考资料：

• Anthropic 官方 Claude Code 指南
• CLAUDE.md 官方说明
• Mnimiy 12 条规则实践

---

作者：张大鹏
团队：大鹏 AI 教育
日期：2026-05-13
标签：AI 编程、Claude Code、工具使用

---

我是张大鹏，关注我，带你用 AI 编程提升开发效率。