AI 读完仓库还是不懂业务？4 层项目上下文让 Agent 少猜
“明明已经让 AI 读了大量代码和文档，为什么给出的方案还是不够靠谱？”这几乎是很多团队把 Agent 引入真实项目后，最常见的疑问之一。
归根结底，读过代码并不等于真正理解项目。代码能够告诉 AI 的，通常只是“当前系统是怎么实现的”；但“为什么要这样设计”“哪些业务红线绝不能碰”“当多个事实冲突时应该优先相信谁”——这些关键背景信息，代码本身并不会主动说明。如果缺少清晰的项目上下文结构，模型就容易用通用知识去补空白，最后看似逻辑完整，实际上却和真实业务场景偏差很大。
AI 最常见的三类误判
- 用通用经验覆盖项目事实：例如把行业常见做法，直接当成当前业务里的固定规则或强约束。
- 只看单仓库：忽略前端、网关、异步任务、数据脚本、公共组件等“看不见但很关键”的上下游系统。
- 相信过期文档：文档描述的是旧方案，而实际运行的代码、接口契约和业务流程早已发生变化。
因此，真正的问题不是给 AI 输入更多文件，而是要建立一个清晰的项目入口，让 AI 能判断“哪些信息更可信、哪些内容只是参考”。
可靠上下文至少有四层
1. 业务语义
包括核心对象、状态流转、计费规则、权限规则、异常路径以及领域术语。这一层解决的是“字段、动作和状态到底代表什么”的基础问题，也是 AI 理解业务逻辑的前提。
2. 仓库与系统地图
包括仓库职责、服务边界、关键入口、上下游依赖以及数据流向。这一层重点回答“一个改动可能会影响到哪些模块、服务或系统”。
3. 协作规则
例如需求如何分级、哪些修改必须经过评审、哪些目录禁止直接改动、测试和发布材料如何交付。这一层明确的是“当前任务应该遵循什么流程和规范”。
4. 事实优先级
建议明确一条核心原则：运行行为和代码契约优先，其次是接口定义、数据库结构和最近的评审结论，最后才参考历史文档。这一层解决的是“当信息冲突时，到底应该信哪一份”。
用“现状先行三步法”减少猜测
在让 Agent 正式处理需求之前，可以固定要求它先完成三步检查：
- 查代码：定位系统入口、调用链和当前实现方式。
- 查契约：确认接口、消息、数据库和权限相关约束。
- 查文档：补充业务目标、历史决策和明确的非目标。
输出结果时也不要只给结论，而要写明证据来源、受影响模块以及仍待确认的问题。这样，评审者就能快速判断：AI 到底是在基于项目事实做推理，还是只是“说得像那么回事”。
上下文要有入口，也要按需加载
实践中最有效的方法，不是维护一篇无限增长的项目说明书，而是整理一份清晰的工作区入口。它可以统一指向业务术语表、系统架构图、协作规则、关键目录以及事实优先级。具体任务再根据场景按需加载相关资料。
例如，只是修改页面文案时，并不需要把整个代码仓库都塞进上下文；但如果任务涉及订单状态、库存扣减、权限控制等核心流程，就必须补充对应的业务流程、接口契约和风险规则。上下文越精准，模型越不容易凭空猜测，成本也更容易控制。
一页项目入口应该怎么写
项目入口不一定要做成几十页的架构文档。更重要的是，保证新成员或新接入的 Agent 能在几分钟内找到关键事实。下面是一种常见且实用的结构：
复制代码项目目标：解决什么业务问题，当前阶段是什么。
核心术语：订单、履约、结算等概念的项目内定义。
系统地图：仓库、服务、前端、消息和数据库各自负责什么。
关键目录：入口代码、接口定义、迁移脚本、测试与发布资料的位置。
协作规则：需求如何分轨，哪些修改必须评审，怎样交接。
事实优先级：代码、契约、数据库、近期决策、历史文档的取信顺序。
需要注意的是，项目入口的职责是导航，而不是复制全部内容。每一个链接、目录说明或文档指引，都应该指向仍在持续维护的真实资产。把过期内容堆在入口里，比没有入口更危险——因为它会让 AI 带着错误的自信继续推理和生成方案。
让 AI 先“陈述理解”，再开始改动
对于中高风险任务，可以把第一轮输出固定为一份“理解确认”，而不是直接生成代码。建议要求 Agent 先写出：
- 它理解的业务目标与非目标。
- 涉及的服务、接口、数据表、事件以及调用方。
- 已经查到的证据路径，例如具体模块、文件或接口名称。
- 尚未确定、需要人工确认的假设。
- 建议进入的风险轨道及对应原因。
如果它把“我猜测”表述成“系统当前就是这样”，就应该在这一步及时打回。这个动作看起来比直接让 AI 写代码更慢，但它能在成本最低的阶段暴露错误，也为后续方案设计、测试准备和技术评审提供可复用的事实依据。
上下文需要设定更新触发器
项目知识不会在第一次整理完成后就永久有效。至少在以下情况发生时，应该及时更新项目入口或相关资料：核心术语发生变化；接口或事件契约调整；仓库拆分或合并；权限、发布、回滚流程变更；以及某次线上事故暴露出此前未被记录的关键规则。
同时，也要避免让所有人都能随意修改“事实定义”。更稳妥的做法是：普通成员先提交更新建议，再由负责人或代码所有者确认后合入；每条重要结论尽量附上来源和更新时间。这样，AI 读到的就不是零散、不可追溯的聊天记录，而是一份可验证、可维护的项目知识资产。
上下文统一，模型接入也要统一
项目入口解决的是知识一致性，而调用入口解决的是配置一致性。如果团队在 Codex、Claude Code 和脚本工具中分别维护base_url、模型名称和 Key，就很容易出现“同一个任务、不同客户端、不同结果”的配置漂移问题。
提供一个 OpenAI 兼容的统一接入方式，可以帮助团队集中管理配置入口，并统一查看可用模型、Key 和调用记录。它本身不能替代你读取仓库或维护项目知识库，但能让排查模型配置、权限问题以及请求失败原因变得更直接。模型名称和权限范围也不要靠手写猜测，而应以后台提供的模型列表为准。
验证 AI 是否真的理解项目
不要只问“你理解了吗”，而应该让它完成三项更可验证的测试：
- 用自己的话解释三个关键业务术语。
- 说明一次改动会影响哪些系统，并给出对应证据。
- 列出本次结论依赖的事实来源和仍存在的不确定项。
如果这三项都回答不稳，就先补齐项目入口和上下文资料，不要急着让 AI 直接生成大范围改动。对 Agent 来说，理解项目并不是一次性的“读完仓库”动作，而是一套可更新、可验证、可追溯的项目上下文机制。