写代码前先给 Claude 一张项目地图：让 AI 更靠谱的技巧

一个简单的技巧正在程序员中流传：在让 Claude 或任何 AI 编程助手写代码之前，先给它一张项目"地图"——一份带注释的目录树，说明文档放在哪里、代码放进哪里、计划在哪里跟踪。听起来理所当然，但正是这一步，让 AI 的回答从"瞎猜"变为"精准"。

为什么 AI 写代码前需要"地图"

像 Claude Code 这样的 AI 编程助手看不到你的整台电脑。它只能处理你提供的内容：打开的文件、粘贴的代码片段，或你授权它读取的目录。在这个限制范围内，如果没有参照点，AI 就会按照互联网上常见项目的惯例来操作——而你的项目恰恰并不常见。

"把 AI 放进一个信息盲区项目"的后果，各个团队都屡见不鲜：

• 文件放错位置： AI 把新文件创建在根目录，而你的项目早有专门的 src/services 目录。
• 制造重复代码： 明明已有一个处理日期的函数，AI 因为不知道旧版本的存在，又写了一个新的。
• 违反团队规范： 变量命名、目录结构、导入方式与代码库其余部分大相径庭。
• 丢失需求： 你曾在某个文件里记下业务需求，但 AI 读不到，于是自造了一套不同的逻辑。

项目地图从根源上解决了这个问题：它告诉 AI 去哪里找指引、结构如何理解、按什么计划推进——这正是一个新入职程序员也需要被交代的三件事。

项目地图是什么

最简单的形式，就是一棵目录树（Directory Tree），为每个重要组成部分附上一行简短注释。你不需要画得多精美——只要 AI（和人）一眼就能看出每样东西归属何处即可。一个极简示例：

my-project/
├── CLAUDE.md            # AI 必须遵守的工作规则
├── docs/
│   ├── requirements.md  # 业务需求、用户故事
│   └── plan.md          # 正在执行的分步计划
├── src/
│   ├── api/             # 端点、控制器
│   ├── services/        # 业务逻辑
│   └── models/          # 数据类型、schema
├── tests/               # 测试，与 src/ 结构保持一致
└── .env.example         # 环境变量模板

地图中最值得投资的三类信息：

1. 需求文档和计划的位置： AI 改代码前需要回读原始需求，避免偏离最初目标。
2. 按职责划分的目录结构： 精确知道新文件该进哪个目录、测试写在哪里。
3. 项目的专属规范： 命名规则、已选定的库，以及那些"别碰"的东西。

如何创建和维护这张地图

• 自动生成目录树： tree -L 2（Linux/macOS）或 find . -maxdepth 2 命令几秒钟就能给出基本框架；把结果粘贴进项目的指引文件即可。
• 写进 AI 最先读取的文件： 对 Claude Code 来说是项目根目录的 CLAUDE.md；其他工具通常读取 README.md 或各自的配置文件。
• 用一行短注释说明： 每个目录一行职责描述——足以让 AI 定位方向，又不至于长到占用上下文窗口（Context Window）。
• 随项目演进更新： 等真正需要时再添加新条目，不要一开始就试图设计全部。这种渐进式做法（start small, extend later，从小处起步、后续扩展）正是原始分享的精髓。
• 人也能复用： 这张地图同时也是新成员的入职文档——一箭双雕。

交给 AI 任务前的检查清单

敲下大型需求之前，快速过一遍以下 6 点：

1. AI 是否已读过项目的目录结构？
2. 原始业务需求在哪个文件里，AI 是否知道该路径？
3. 工作计划（todo、plan）是否有固定的存放处？
4. 是否明确说明了 AI 必须遵守的命名和结构规范？
5. 是否已向 AI 指出与任务直接相关的文件？
6. 是否已明确圈定不许擅自修改的区域？

如果 6 个答案全是"是"，那么每次 AI 写完代码后清理"战场残骸"的概率将大幅下降。

给越南企业的启示

对于正在将 AI 引入软件开发流程的越南中小技术团队来说，这个技巧的实施成本几乎为零，收益却能不断累积：

• 多人协作标准化： 所有人共用一张地图，AI 生成的代码风格统一，而不是一人一个样。
• 降低监督成本： 管理者不必逐行审读 AI 写的代码，只需按既定结构抽查。
• 快速入职： 新工程师（以及新加入的 AI）几分钟就能摸清项目，而不是花上几天。

花一个小时绘制项目地图，可能省下几十个用来修复 AI"自作主张"组织代码所引发问题的小时。

结语

AI 读不懂你的心思——它只能读懂你给出的上下文。一棵带注释的目录树、一个位置明确的需求文件、一份记录在案的计划，正是"碰运气"的 AI 编程助手与真正理解项目的助手之间的分水岭。下次给 Claude 派活之前，花几分钟画张地图吧：你的项目会因此感谢你。

资料来源：整理自 Facebook 技术分享，由 Wotech Electronics 编辑。

如果您的企业希望规范 AI 辅助的软件开发流程，Wotech Electronics 团队随时愿与您同行，为您的团队设计合适的流程。