AI 读完仓库还是不懂业务？4 层项目上下文让 Agent 少猜

AI 读完仓库还是不懂业务？4 层项目上下文让 Agent 少猜

“已经让 AI 读了很多文件，为什么方案还是不靠谱？”这大概是团队把 Agent 用到项目里后，最常听到的抱怨之一。

说到底，读过代码不等于理解项目。代码能告诉AI的是“现在怎么做的”，但“为什么这么做”、“哪些红线不能碰”、“事实冲突时听谁的”——这些，代码自己不会说。如果缺了上下文结构，模型往往会用通用经验来填补空白，结果看起来逻辑通顺，实则离项目实际十万八千里。

AI 最常见的三类误判

• 用通用经验覆盖项目事实
  ：比如把行业里的通用做法，直接当成当前业务的硬性规则。

• 只看单仓库
  ：忽略了前端、网关、异步任务、数据脚本或者公共组件这些“隐形邻居”。

• 相信过期文档
  ：文档里写的是旧设计，而运行中的代码和接口契约早就变了天。

所以，问题的关键不是给AI喂更多文件，而是要建立一个让AI能判断“什么信息更可信”的项目入口。

可靠上下文至少有四层

1. 业务语义

核心对象、状态、计费/权限规则、异常路径，还有领域术语。这一层解决的是“字段和动作到底代表什么”这个根本问题。

2. 仓库与系统地图

仓库职责、服务边界、关键入口、上下游依赖和数据流向。这一层要回答的是“改动可能波及到哪里”。

3. 协作规则

需求怎么分级？什么改动必须评审？哪些目录不能直接改？如何交付测试和发布材料？这一层明确了“这次应该按什么流程走”。

4. 事实优先级

建议明确一条铁律：运行行为和代码契约优先，其次是接口、数据库和最近的评审结论，最后才是历史文档。这一层解决的是“信息冲突时，到底该信谁”。

用“现状先行三步法”减少猜测

让Agent处理需求前，可以固定要求它先完成三步：

1. 查代码：找到入口、调用链和现有实现。
2. 查契约：确认接口、消息、数据库和权限约束。
3. 查文档：补足业务意图、历史决策和非目标。

输出时也别只给结论，要写清楚证据来源、受影响模块和仍待确认的问题。这样一来，评审者就能快速判断：AI是基于事实推理，还是只是在“讲得像”。

上下文要有入口，也要按需加载

最实用的做法，不是建一篇无限长的说明书，而是维护一份工作区入口。它指向业务词表、架构地图、规则、关键目录和事实优先级。具体任务再按需加载相关资料。

举个例子，改页面文案，不需要把全库都塞进上下文；但涉及订单状态、库存扣减或权限时，就必须加载对应流程、接口和风险规则。上下文越精准，模型越少凭空补全，成本也越可控。

一页项目入口应该怎么写

项目入口不必是几十页的架构文档。先保证新成员或新Agent在几分钟内能找到关键事实即可。下面是一种实用结构：

 复制代码项目目标：解决什么业务问题，当前阶段是什么。
核心术语：订单、履约、结算等概念的项目内定义。
系统地图：仓库、服务、前端、消息和数据库各自负责什么。
关键目录：入口代码、接口定义、迁移脚本、测试与发布资料的位置。
协作规则：需求如何分轨，哪些修改必须评审，怎样交接。
事实优先级：代码、契约、数据库、近期决策、历史文档的取信顺序。

注意，项目入口只负责导航，不负责复制所有内容。每一个链接或目录说明，都应指向仍在维护的真实资产。把过期内容堆进入口，比没有入口更危险——它会让AI带着错误自信继续推理。

让 AI 先“陈述理解”，再开始改动

对于中高风险任务，可以把第一轮输出固定成一份理解确认，而不是代码。建议要求Agent写出：

• 它理解的业务目标与非目标。
• 涉及的服务、接口、表、事件和调用方。
• 已查到的证据路径，例如具体模块或接口名称。
• 尚未确定、需要人确认的假设。
• 建议进入的风险轨道与原因。

如果它把“我猜测”写成“当前系统就是这样”，应在这一步打回。这个动作看起来比直接生成代码慢，但它把错误暴露在成本最低的阶段，也为后续方案、测试和评审提供了可复用的事实基础。

上下文需要设定更新触发器

项目知识不会一次建好后永远有效。至少在这些事件发生时，需要更新入口或相关资料：核心术语变化；接口或事件契约变更；仓库拆分/合并；权限、发布和回滚流程调整；一次线上事故暴露出过去未记录的规则。

同时，要避免让所有人都能随意改“事实”。更稳妥的方式是：普通成员提交更新建议，负责人或代码所有者确认后合入；每条重要结论附上来源和更新时间。这样，AI读到的不是无边的聊天沉淀，而是可追溯的项目记忆。

上下文统一，模型接入也要统一

项目入口解决知识一致性，调用入口解决配置一致性。如果团队在Codex、Claude Code和脚本中分别维护base_url、模型名与Key，极易出现“同一任务、不同客户端、不同结果”的配置漂移。

提供一个OpenAI兼容的接入方式，可以用来统一配置入口，并集中查看可用模型、Key和调用记录。它不会替你读取仓库或维护项目知识库，但能让排查模型配置、权限和请求失败更直接。模型名和权限不要手写猜测，应以后台模型列表为准。

验证 AI 是否真的理解项目

不要只问“你理解了吗”，而应让它完成三项测试：

• 用自己的话解释三个关键业务术语。
• 说明一个改动会影响哪些系统，并给出证据。
• 列出本次结论依赖的事实来源和不确定项。

如果这三项答不稳，就先补项目入口，不要急着让AI生成大改动。对Agent来说，理解项目不是一次性的“阅读动作”，而是一套可更新、可验证、可追溯的上下文机制。