真实项目里的 AI 上下文工程：别只把需求丢给模型
很多人使用 AI 写代码时，会把重点放在 prompt 写得够不够详细。真实项目里，更关键的不是一句话怎么写得漂亮，而是你给 AI 的上下文是否能支撑它做出可验证的修改。
上下文工程不是把整个仓库塞给模型，也不是让 AI 自己漫无目的地读。它更像一次任务交接：这次要解决什么问题，哪些文件是事实来源，哪些边界不能碰，完成后用什么方式验收。
如果这些东西没有说清楚，AI 也许仍然能写出一段看起来合理的代码，但你很难判断它是不是改对了。更麻烦的是，它可能把局部问题扩大成重构，把临时现象解释成架构缺陷，或者在没有业务约束的地方替你做决定。
先定义任务边界
真实项目里的第一步不是“让 AI 看代码”，而是定义这次任务的边界。
边界至少包括四件事：
- 这次要改变的行为是什么。
- 哪些模块、页面、接口或测试可能相关。
- 哪些文件或层次不要动。
- 什么情况算完成，什么情况只是分析。
比如下面这种指令就太宽：
帮我优化一下用户权限。
它没有说明是权限展示、权限校验、权限缓存、角色绑定，还是菜单可见性。AI 会自己猜，而猜测会扩大改动范围。
更好的说法是：
检查用户列表页的导出按钮为什么对无权限账号仍然可见。
只分析前端可见性和已有权限工具的调用，不改后端权限模型。
如果需要修改，改页面组件和对应测试，并说明验证方式。
这类任务边界会把 AI 的注意力收窄到“按钮可见性”这个行为，而不是整个权限系统。
文件证据比背景故事重要
AI 很容易被自然语言背景带偏。你说“这个接口应该是追加角色”，它可能会按这个假设继续写；但真实代码里接口可能实际是替换角色。
所以在真实项目中，最好让 AI 先找文件证据，再给结论。不要只问“这个功能是不是正常”，而要要求它指出：
- 入口文件在哪里。
- 调用链经过哪些组件、service、controller、manager 或 mapper。
- 核心判断在哪个函数里发生。
- 数据读写用了哪些查询或缓存。
- 当前行为由哪几行代码决定。
文件证据的价值是降低幻觉空间。AI 的总结可以有理解和判断，但判断必须能回到代码。
如果你已经知道关键文件，也可以直接给它：
请从这几个文件开始读：
- app/users/page.tsx
- services/users.ts
- components/user-export-button.tsx
先解释现有调用链，不要马上改。
这不是限制 AI 的能力，而是让它从可信材料开始。后续如果它发现还有相关文件，可以继续扩展，但扩展应该有理由。
约束要写成工程规则
真实项目的约束通常不是模型能自动推出来的。
比如：
- 后端调用必须放在
services层。 - 页面 action 要靠近页面目录。
- 缺少权限绑定时必须拒绝，而不是默认通过。
- mutation 后只能刷新受影响的路径，不能全局刷新。
- 不要改已有数据库语义。
- 不要把本地配置、生成文件或别人改动混进来。
这些约束如果没有写出来，AI 可能会选择“看起来更简单”的实现。它未必是故意偷懒，而是它不知道你的项目为什么这样分层。
约束最好写成可执行规则：
约束：
- 只改 dashboard 用户列表相关文件。
- 网络请求逻辑放在 services，不放在 feature 组件里。
- 不新增依赖。
- 不修改数据库 schema。
- 不回退工作区里已有的其他改动。
这种写法比“注意代码质量”有用得多。后者是价值判断，前者是可检查边界。
验收方式要提前给
很多 AI 任务失败，不是因为代码完全错，而是因为没有明确验收。AI 写完会说“已实现”，但你不知道它到底跑了什么，没跑什么。
验收可以分几层：
- 静态检查：类型检查、lint、格式检查。
- 单元测试：覆盖核心函数或组件行为。
- 集成测试：覆盖接口、数据库、权限、缓存等跨层行为。
- 构建验证：确认 MDX、路由、bundle 或服务启动没有坏。
- 人工检查：查看 diff、打开页面、走一次关键流程。
不需要每个任务都全量验证。改一篇文章，可能构建通过就够了；改认证、支付、权限、缓存，就应该有更强的检查。
重要的是提前说清楚：
完成后运行 npm run build。
如果没有跑测试，必须说明原因，不要声称已经验证。
AI 很适合根据失败输出继续修。但前提是你让它进入真实反馈循环，而不是只让它生成代码。
上下文不是越多越好
把所有文件、所有日志、所有需求一次性塞给 AI，听起来保险，实际经常会变差。上下文太多时，模型会把重要信息和噪音混在一起，甚至抓住一个无关线索展开。
更好的方式是分阶段给上下文：
- 先给任务目标和限制。
- 让 AI 搜索并列出它认为相关的文件。
- 要求它解释当前行为和证据。
- 再决定是否允许修改。
- 修改后用 diff 和测试结果验收。
这和真实工程协作很像。你不会一开始就把整个公司文档丢给新人，而是先给任务、入口、规则和验收标准。
一个可复用的上下文模板
可以把下面这个模板当成日常起点：
目标：
修复/实现/分析什么行为。
范围：
可能相关的页面、服务、接口、测试或文档。
不做：
明确排除的重构、模块、配置、数据库或发布动作。
证据要求：
先说明调用链和关键文件，再给结论。
实现约束：
沿用现有模式，不新增依赖，不改无关文件。
验收：
运行哪些命令，或说明为什么不能运行。
交付：
列出改动文件、行为变化、验证结果和剩余风险。
这个模板不复杂，但它能让 AI 的工作从“生成答案”变成“完成一次可审查的工程任务”。
如果下一步涉及仓库安全边界，可以继续看：怎么让 AI agent 不把仓库改坏。如果代码已经准备合并，可以看：AI 代码 review 在合并前该看什么。
结论
真实项目里的 AI 上下文工程，本质上是把任务、证据、约束和验收说清楚。
任务边界决定 AI 该解决什么；文件证据决定结论能不能落地；工程约束决定它不会乱改；验收方式决定结果是否可信。
当这些东西清楚时，AI agent 会更像一个可协作的工程执行者。缺少这些上下文时，它可能仍然很快，但你得到的只是一个难以审查的改动包。