同一个 AI 助手，让它写一个日期格式化函数，稳定得让人放心；让它在仓库里把「下单」改成「先锁库存再扣款」，补丁看着完整，跑起来把两个不相关的流程一起改了。函数级任务里需求就是全部输入，项目级任务里需求只占一小部分，剩下的是这个仓库的约定。差距就出在这部分。
差距不在写代码，在读代码
目录怎么分、状态放在哪、错误怎么抛、哪些接口不能动，这些信息不在需求描述里，只在代码和人的脑子里。所以项目级理解的第一层能力是找得到：给它一个改动目标，它能不能定位到相关的文件、函数、配置和测试。找不到就无从谈起，找到一半，改出来就是半对。
定位靠检索，检索靠关键词。你的仓库里如果同一件事有三种叫法，它按一种去搜，就会漏掉另外两处。这也是为什么老项目里改动特别容易出事：命名不统一的年代越久，能靠字面匹配找到的比例越低。
四层理解，能做与不能做的分界
| 理解层次 | 能做 | 不能做 | 为什么 |
|---|---|---|---|
| 文件内 | 按现有风格改一个函数、补分支、加日志 | 判断这个函数还该不该存在 | 只看得到当前文件，缺调用方信息 |
| 模块内 | 顺着引用找到相关类，把一条调用链改通 | 判断改动会不会破坏对外契约 | 契约散在文档、测试和口头约定里 |
| 跨模块 | 列出可能受影响的文件清单，给出改动顺序 | 覆盖全部受影响的地方 | 依赖靠检索推断，动态调用和配置注入看不到 |
| 系统级 | 提示风险点、给出验证清单 | 替代架构判断和上线决策 | 缺运行时状态，也缺历史决策的背景 |
四层的分界不在难度，在信息存在哪。前两层的信息在代码里，它能读到；后两层的信息一部分在代码里，一部分在工单、监控和人的经验里，它读不到。项目越大，后两层占的比重越高，它能覆盖的比例就越低。
影响范围为什么总会漏
静态检索能找到显式调用，找不到隐式依赖：字符串拼出来的路由、靠配置注入的实现类、事件总线上松耦合的订阅者、定时任务里按名字取的服务。这些在代码里没有一条直接的引用线，工具搜不出来，模型自然也搜不出来。
漏一个的代价不对称。多改一个文件，测试多半能拦住；漏改一个文件，可能要到某个冷门入口被触发才暴露。所以它给的清单要当下限用，不能当上限，剩下的靠全局搜索和类型检查补。
风格一致比正确更难
让它写一段新逻辑，语法和结构通常没问题；让它融进现有代码，问题就来了：异常用自定义类还是标准异常、日志走哪个封装、返回值用包装对象还是裸数据、注释写中文还是英文。这些约定没有写在任何地方，但评审时会一条条被指出来。
风格不一致的代码合并进去，短期没故障，长期是维护成本。它每次生成都按最常见写法来，而你的项目可能恰好是最不常见的那一种。给它两三个同目录的现有文件当范例，比写一段风格要求有效得多。
用一个小改动就能测出深浅
测法不需要造场景，拿真实仓库做两件事。第一，让它加一个字段，从数据库到接口到页面走一遍，看它会不会漏掉序列化、校验、前端展示中的某一环。第二，让它修一个已知的 bug，看它改在症状处还是改在成因处。
还有一个观察点：它有没有主动去读别的文件。上来就写、不检索的，理解深度基本为零；先列文件清单、再问你要不要看某个目录的，通常能走得更远。多步任务怎么拆给智能体讲的是同一件事：先规划再执行，比一口气生成可靠。
给范围，比给自由更能拿到能合并的代码
把改动约束在三五个文件内，附上相关文件内容，说清不许动的部分，产出质量会明显不同。范围给得越窄，它需要猜的东西越少。反过来，一句帮我优化这个项目，它只能回一堆泛泛的建议。
上下文长度是硬约束。仓库大到一个程度，相关代码塞不进去，就要靠检索先筛，上下文窗口塞满之后会怎样决定了这个策略的上限。检索做得粗，塞进去的是无关文件，反而干扰判断。检索做得准，等于替它补上了一半的项目级理解，按需取回相关片段再回答就是这个思路在问答里的版本。
改完必须跑测试，并且专门翻 diff 看有没有意外改动。项目级改动的风险不在改错，在改多了。
什么项目值得指望它
脚本、原型、一次性数据处理，单文件能力就够，项目级理解用不上。长期维护的业务系统，项目级理解直接决定它能不能参与，因为这类系统的成本大头在改动的影响面，不在打字速度。
有个很朴素的试法：在这个仓库里，改一处要翻几个文件才能确认没漏？翻得越多，越依赖它对全局的理解，也越需要你把范围收窄、把验证做足。
速查：测一次项目级理解
- 给它一个加字段的活，看漏不漏序列化、校验、前端展示
- 给它一个已知 bug，看改症状还是改成因
- 看它有没有先检索再动手，还是直接生成
- 翻 diff 看有没有顺手改到无关文件
