很多人第一次用 AI 写代码时，都会有一种很强的感觉：

单独给它一个文件，写得挺准。

比如：

• 改一个函数；

• 修一个报错；

• 增加一个字段；

• 优化一段逻辑；

• 写一个小工具。

往往几分钟就能给出不错的结果。

但一旦把任务换成：

帮我修改整个项目里的登录逻辑。

体验就可能完全不一样。

AI开始出现：

• 改错文件；

• 漏掉调用方；

• 改了后端却忘了前端；

• 忽略配置；

• 单个文件逻辑正确，项目整体却跑不起来；

• 修好一个Bug，又引出另外一个问题。

为什么会这样？

真正的原因并不是AI突然“不会写代码”了。

而是：

单文件编程和项目级编程，本来就是两种完全不同的任务。

---

一、单文件任务为什么容易做准？

假设你把下面一个函数完整交给AI：

def get_user_age(user):
    return user["age"]

然后告诉它：

如果age不存在，不要报错，默认返回0。

这个任务非常简单。

AI需要理解的信息只有：

输入是什么 → 当前代码是什么 → 你想改成什么。

上下文几乎全部集中在一个地方。

它不需要知道：

这个函数从哪里被调用；

用户数据从哪里来；

数据库怎么设计；

项目里有没有另一个同名函数。

所以这类任务天然就比较容易。

可以把它理解成：

问题边界非常清楚。

AI只需要在一个小盒子里解决问题。

---

二、整个项目里真正难的是“相关代码到底在哪里”

把任务换成：

用户退出登录以后，页面仍然显示旧用户名，帮我修。

这时候就完全不一样了。

问题可能出现在：

前端状态管理
↓
本地缓存
↓
退出接口
↓
用户信息接口
↓
页面组件

表面看是一个“退出登录Bug”。

真正原因却可能藏在5个不同文件里。

AI首先需要完成的已经不是“写代码”，而是：

找到真正相关的代码。

如果它只看到：

LogoutButton.tsx

就开始改，那么很可能只是处理表面现象。

真正的问题可能其实在：

store/user.ts

或者：

hooks/useCurrentUser.ts

所以大型项目的第一道难题不是生成代码。

而是：

代码检索。

---

三、项目越大，“上下文”就越不等于“把代码全部塞进去”

很多人会自然想到：

既然AI不了解项目，那就把更多代码交给它。

但问题在于：

代码越多，不一定越容易理解。

例如一个项目有10万行代码。

真正和当前Bug有关的可能只有：

800行

如果把整个项目都放进去，AI面对的不是：

更多有用信息。

而是：

有用信息 + 大量无关信息。

真正重要的是：

能不能从大量代码里找到当前任务真正相关的那部分？

这和人类开发其实很像。

一个程序员接手大型项目，也不会从第一行读到第10万行。

通常会从：

报错位置；

路由；

函数调用；

关键字；

测试；

Git历史；

逐步往外扩。

AI Agent真正需要的也不是无限上下文。

而是：

正确检索上下文。

---

四、调用链才是项目级编程真正难的地方

一个文件里的代码通常只是整个系统的一小段。

比如：

Controller
↓
Service
↓
Repository
↓
Database

你修改了Service里的返回结构。

单看这个文件可能完全正确。

但是Controller还按照旧结构读取。

结果项目就报错了。

这就是调用链。

再比如前端：

API
↓
Store
↓
Hook
↓
Component

AI只改了API。

但Store没有同步调整。

最后出现：

每个单文件都“看起来没问题”，整个系统却错了。

所以项目开发真正要求AI理解的是：

这个文件和其他文件是什么关系。

而不是只判断：

这一段代码本身有没有语法错误。

---

五、配置文件经常是最容易被忽略的一层

还有一种情况特别常见。

代码逻辑全部正确。

项目还是跑不起来。

最后发现问题在：

.env
package.json
tsconfig.json
vite.config.ts
docker-compose.yml

也就是说：

项目行为不只由业务代码决定。

还受到：

• 依赖版本；

• 环境变量；

• 构建配置；

• 运行时环境；

• 数据库配置；

• 权限；

影响。

单文件任务通常不需要考虑这些。

项目级任务却经常必须同时理解：

代码 + 配置 + 环境。

这就是为什么：

“帮我写这个函数”

和：

“帮我把这个功能在项目里真正跑起来”

难度差距非常大。

---

六、隐藏规则也是AI很容易踩坑的地方

真实项目里通常还有很多“代码里不一定写出来的规则”。

例如团队默认：

• 不能直接调用数据库；

• 所有接口必须经过Service层；

• 不允许在组件里请求API；

• 所有错误必须统一处理；

• 新功能必须补测试；

• 某几个目录禁止修改。

开发者在项目里待久以后，会默认知道这些规则。

但AI第一次进入项目并不知道。

如果没有明确项目规范，它很可能写出：

语法正确、功能能跑，但不符合项目架构的代码。

所以现在很多 Coding Agent 都开始强调：

项目说明；

仓库规则；

开发规范；

长期上下文。

本质上都是在解决同一个问题：

让AI不仅看到代码，还要知道“这个项目平时是怎么写代码的”。

---

七、测试为什么对项目级AI编程特别重要？

单文件任务里，你自己看一眼通常就能判断大概有没有问题。

大型项目不行。

因为一次修改可能影响：

A模块
↓
B模块
↓
C模块

人工很难一次看全。

这时候测试就是一种非常重要的反馈机制。

例如AI修改以后：

120 tests passed
3 tests failed

至少说明：

修改影响到了另外3个已有行为。

于是AI可以继续根据测试结果排查。

所以一个真正比较完整的项目级AI工作流应该是：

理解任务
↓
搜索相关代码
↓
分析调用链
↓
修改
↓
运行测试
↓
根据结果继续修

而不是：

打开文件
↓
改代码
↓
结束

---

八、为什么有时候AI会“改得越来越偏”？

这也是大型项目很常见的现象。

第一轮它找错了根因。

然后开始修改。

第二轮新的报错出现以后，它又继续沿着第一次的错误假设修。

于是：

第一次误判
↓
第一次错误修改
↓
产生次生问题
↓
继续针对次生问题修改
↓
项目越来越乱

最终看起来就是：

AI越改越偏。

真正正确的方式应该是：

当连续两三轮没有解决时，暂停修改。

重新问：

当前Bug的真实调用链是什么？

最初问题在哪里第一次出现？

哪些假设已经被测试排除了？

这相当于重新建立项目上下文。

很多时候比继续堆代码更有效。

---

九、同样一个模型，在“聊天”和“Agent”里的表现为什么可能差很多？

这也解释了一个很多人容易忽略的问题。

同一个大模型：

放在普通聊天窗口里；

和放在真正的 Coding Agent 里；

实际开发体验可能完全不同。

因为 Coding Agent 往往还具备：

• 文件搜索；

• 项目读取；

• 终端执行；

• Git Diff；

• 测试运行；

• 多文件修改；

这些能力。

所以项目级编程最终比的并不只是：

模型会不会写代码。

还包括：

它能不能自己找到上下文。

这就是为什么现在越来越多AI编程工具开始从“代码聊天框”走向“Agent”。

---

十、判断AI是否真正理解项目，可以先别让它写代码

有一个很简单的测试方法。

给AI一个项目问题以后，不要马上说：

帮我修。

先让它回答：

先不要修改代码。

找出和这个问题最相关的5个文件，并解释它们之间的调用关系。

如果它能够正确找到：

入口；

核心逻辑；

下游依赖；

测试；

配置；

说明它至少已经开始建立项目地图。

如果连相关文件都没找对，直接开始修改，风险通常就很高。

所以项目级AI编程里，一个很重要的习惯就是：

先验证理解，再允许修改。

---

十一、一个更稳定的项目任务写法

以后遇到大型项目问题，可以把Prompt从：

帮我修复登录Bug。

改成：

任务：
修复退出登录后仍显示旧用户信息的问题。

要求：

1. 先不要修改代码；
2. 找到用户状态完整调用链；
3. 列出与问题最相关的文件；
4. 判断根因最可能出现在哪一层；
5. 确认后再进行最小范围修改；
6. 不做无关重构；
7. 修改完成后运行相关测试；
8. 最后列出所有变更文件。

这样任务的重点就从：

“快点写代码”

变成：

“先把项目理解清楚”。

这通常会稳定很多。

---

十二、项目越大，真正重要的能力越不是“代码生成”

可以把AI编程能力简单拆成四层。

第一层：代码生成

能不能写一个函数？

现在大多数模型都不错。

第二层：代码理解

能不能解释一个文件？

难度开始提高。

第三层：项目理解

能不能找到相关文件和调用链？

差距开始明显。

第四层：任务执行

能不能修改、测试、根据反馈继续推进？

这才是真正的 Coding Agent 场景。

所以当AI“单文件很准，整个项目容易出错”时，并不是出现了矛盾。

只是任务已经从：

代码生成

升级成了：

软件工程。

---

最后

AI写单文件代码很准，但到了整个项目里容易出错，真正差的往往不是“写代码能力”。

而是项目级任务还多了很多隐藏难题：

哪些文件真正相关；

它们之间怎么调用；

项目有哪些配置；

团队有哪些规则；

修改以后怎么验证。

所以大型项目里，真正重要的不只是给AI更多代码。

而是让它：

找到正确上下文 → 理解调用链 → 控制修改范围 → 用测试验证结果。

当AI编程从单文件走向真实项目以后，竞争的也就不再只是：

谁能写出更漂亮的代码。

而是：

谁能真正理解一个项目是怎么运行的。

---

持续更新 Codex、Claude Code 与大模型开发实战内容，更多深度内容欢迎搜索关注「孤狼GPT」。