很多开发者第一次使用 AI Agent 时，会有一个明显感受：

新项目里AI表现很好，接手旧项目以后却经常理解错误。

同样是让AI完成一个功能：

新项目：

• 文件结构简单；
• 命名统一；
• 代码关系清晰。

AI往往很快找到位置。

但到了真实业务项目：

• 文件很多；
• 模块关系复杂；
• 历史代码长期存在；
• 很多规则没有写出来。

这时候AI容易出现：

• 修改了错误文件；
• 选择了不符合项目习惯的实现；
• 没发现已有工具；
• 重复造轮子；
• 改完代码影响其他模块。

问题并不是AI不会写代码。

而是：

它缺少理解这个项目所需要的上下文。

---

一、代码只是项目的一部分信息

很多人认为：

只要把代码给AI，它就能理解项目。

但真实项目中，代码只是其中一部分。

一个成熟项目通常还包含：

• 架构设计；
• 命名规则；
• 数据流程；
• 业务约束；
• 部署方式；
• 测试要求；
• 历史原因。

例如：

一个函数看起来可以删除。

但项目文档可能说明：

这个函数用于兼容旧版本客户端。

如果AI只看代码，很容易认为：

“这里没有调用，可以清理。”

结果导致隐藏问题。

---

二、为什么旧项目更容易让AI误判？

新项目通常：

需求
↓
代码
↓
测试

关系比较直接。

但长期维护项目可能：

当前代码
+
历史需求
+
兼容逻辑
+
临时方案
+
业务规则

很多东西没有明显写在代码里。

例如：

一个判断：

if(user.type === "old")

AI可能认为：

这是重复逻辑，可以优化。

但真实原因可能是：

• 老用户数据结构不同；
• 历史迁移没有完成；
• 某个客户依赖特殊行为。

这种信息通常不会出现在当前文件。

---

三、项目规则文件会影响AI质量

如果每次都让AI自己猜：

• 代码风格；
• 文件位置；
• 测试方式；
• 修改边界。

它只能根据已有代码推测。

但如果项目提前提供规则：

例如：

项目规则：

1. 所有API放在service目录；
2. 不直接修改数据库模型；
3. 新功能必须添加测试；
4. 公共组件禁止重复创建。

AI执行任务时，就多了一层判断标准。

这相当于告诉AI：

这个项目希望代码怎样变化。

---

四、代码地图为什么越来越重要？

随着项目规模增加，单个文件的重要性降低。

真正重要的是：

文件之间的关系。

例如一个用户登录功能：

登录页面
↓
Auth组件
↓
用户Service
↓
Token模块
↓
权限系统
↓
数据库

如果AI只修改其中一个文件，很可能不知道：

后面还有哪些影响。

所以大型项目越来越需要：

• 模块说明；
• 目录结构介绍；
• 关键调用链；
• 核心流程图。

这些内容本质上是在给AI建立：

项目地图。

---

五、为什么文档质量会直接影响Agent表现？

很多团队过去认为：

代码才是最重要的。

文档可以慢慢补。

但AI Agent进入开发流程以后，这个情况会变化。

因为AI不像老员工：

它不会参加会议。

不会记得：

“这个地方以前为什么这么设计。”

如果信息没有留下：

AI只能猜。

所以：

好的文档不只是给新人看的。

也是给AI理解项目使用的。

---

六、哪些上下文最值得提供给AI？

并不是所有文档都需要。

优先级比较高的是：

1. 项目结构说明

告诉AI：

哪些目录负责什么。

例如：

src/api
接口层

src/service
业务逻辑

src/repository
数据库访问

---

2. 核心业务流程

例如：

订单创建：

创建订单
↓
锁库存
↓
支付
↓
发送通知

---

3. 开发规则

例如：

• 不允许直接调用数据库；
• 必须通过Service层；
• 修改接口需要同步测试。

---

4. 常见坑

例如：

• 某字段不能直接删除；
• 某模块依赖旧版本逻辑；
• 某接口存在兼容要求。

这些信息对Agent非常有价值。

---

七、为什么“给AI更多代码”不一定更好？

很多人遇到AI理解错误，会选择：

把整个项目全部上传给AI。

但代码数量增加，不一定代表理解增加。

因为上下文太大以后：

AI可能反而难以抓住重点。

更有效的方法是：

提供：

相关代码 + 项目规则 + 关键背景。

让AI知道：

• 任务是什么；
• 哪些地方重要；
• 哪些地方不能动。

---

八、Agent执行任务前应该先做什么？

对于复杂任务，不建议直接：

帮我实现这个功能。

更好的流程：

第一步：

让AI分析项目。

例如：

请先说明这个功能涉及哪些模块，以及可能影响哪些地方。

第二步：

确认方案。

第三步：

再开始修改。

这样可以减少：

直接修改错误位置。

---

九、未来项目可能需要“Agent说明文件”

类似现在很多项目有：

README。

未来可能会出现更专门给Agent看的规则。

例如：

AGENT.md

项目结构：
核心模块：
禁止修改：
测试方式：
代码规范：
常见风险：

它的作用不是替代开发文档。

而是帮助AI快速建立项目认知。

---

十、项目越复杂，上下文管理越重要

简单项目：

AI只需要知道：

“我要改哪个文件。”

复杂项目：

AI需要知道：

• 为什么这么设计；
• 哪些模块有关联；
• 哪些代码不能动；
• 哪些行为必须保持。

所以未来开发效率的提升，不只是依靠更强模型。

还依赖：

项目是否容易被AI理解。

---

十一、可以建立一个AI友好的项目结构

如果希望Agent长期参与开发，可以逐步优化：

清晰目录

减少隐藏关系。

明确命名

降低猜测成本。

保留文档

记录关键规则。

完善测试

提供行为参考。

固定开发流程

减少随机修改。

这些实际上是在建设：

Agent-ready代码库。

---

最后

AI Agent越来越强以后，真正影响效果的因素，不只是模型能力。

还有：

它是否真正理解你的项目。

没有上下文时：

AI只能根据代码猜。

有完整项目地图、规则和文档时：

AI才更接近一个熟悉项目的新成员。

未来的软件开发可能不只是：

让AI写更多代码。

而是：

让项目变得更容易被AI理解。

因为对于Agent来说：

代码是语言。

上下文才是含义。

---

持续更新 Codex、Claude Code、AI Agent 与大模型开发工作流实战内容，也会整理 AI 工具使用技巧与相关经验。更多深度内容和稳定订阅渠道欢迎搜索关注「孤狼GPT」。