AI 上下文工程实践：让工具读懂项目而不是只回答问题

AI 编程工具的效果，很多时候不是由模型本身单独决定，而是由它拿到的上下文决定。同一个需求，如果只给一句“帮我修一下登录问题”，输出往往会很泛；如果补充项目结构、复现步骤、日志、约束和验证命令，AI 就更容易给出可落地的修改。

上下文工程不是写更长的提示词，而是把项目里真正影响判断的信息组织好，让 AI 在开始动手之前就知道边界、目标和验收方式。对个人项目和团队项目来说，这比临时追问更稳定，也更容易复用。

一、上下文不是越多越好

很多人第一次使用 AI 工具时，会把大量代码、报错和背景一次性贴进去，希望模型“自己理解”。这样做看似充分，实际容易带来两个问题：

重要信息被噪声淹没。
AI 难以判断哪些约束必须遵守。
输出内容变长，但可执行性变差。
后续对话里旧信息和新信息互相冲突。

有效上下文应该像一次代码审查的材料：少而准确，能支持判断。比如修复一个 Android 页面崩溃，不需要把整个项目都贴进去，但需要包含崩溃堆栈、相关 Activity 或 Fragment、生命周期代码、复现路径和预期行为。

如果上下文太少，AI 会猜；如果上下文太乱，AI 会误判。工程上的目标，是让它少猜、少发挥、少修改无关内容。

二、先给稳定约束

每个项目都有一批长期稳定的信息，适合沉淀成固定上下文。

以一个 Hexo 博客仓库为例，稳定约束可能包括：

文章目录：source/_posts/
封面目录：source/img/covers/
文章格式：YAML front matter + 正文 + <!-- more -->
构建命令：npm run build
禁止事项：不要覆盖已有文章，不要自动提交源码

以一个 Android 项目为例，则可能包括：

语言：Kotlin
架构：MVVM
异步：Coroutine + Flow
依赖注入：Hilt
验证命令：./gradlew testDebugUnitTest assembleDebug
约束：不要在 View 层直接访问数据库或网络

这些信息不应该每次临时回忆。可以放在项目说明、AI 协作指南、任务模板或仓库内的文档里。AI 每次接任务前先读取这些约束，输出会更接近项目习惯。

三、任务上下文要围绕“目标”组织

一次具体任务还需要补充动态上下文。比较实用的组织方式是按“目标、现象、范围、约束、验收”来写。

例如：

目标：修复设置页点击保存后偶发重复提交。
现象：快速点击保存按钮两次，会发出两个相同请求。
范围：SettingsViewModel、SettingsRepository、相关单元测试。
约束：不要改接口协议，不要引入新依赖。
验收：重复点击只产生一次提交，失败后按钮能恢复，单元测试通过。

这段上下文比“按钮重复提交，帮我改一下”更有价值。它提前说明了不该改什么、哪里是重点、完成后怎么判断结果。

上下文工程的关键不是把需求写得文学化，而是把工程决策需要的信息补齐。

四、让 AI 先读再写

在代码仓库里，AI 最容易出错的场景之一，是没读现有实现就直接给方案。它可能写出语法正确但风格不一致的代码，也可能绕过项目已有的工具类和错误处理方式。

更稳定的流程是：

先定位入口文件。
阅读调用链和相邻实现。
总结现有模式。
再提出修改点。
最后执行最小改动。

例如修改日志轮转逻辑时，应该先看现有日志路径、配置加载方式、systemd 服务文件和部署脚本，而不是直接生成一个新的 shell 脚本。很多问题不是“代码不会写”，而是“写到项目里不合适”。

在提示中可以明确要求：

1
2
3

请先阅读相关文件，说明你看到的现有模式，再做修改。
只改完成任务所需的文件。
不要重排无关代码。

这会让 AI 的行为更接近一个谨慎的维护者，而不是一个只会生成片段的补全器。

五、把验证命令也当作上下文

验证命令不是任务结束时才需要的信息，而是设计方案时就要考虑的约束。

如果项目要求最终通过：

1	npm run build

那么 AI 在新增文章时就会更注意 front matter、资源路径和 Markdown 语法。如果 Android 项目要求通过：

1 2	./gradlew testDebugUnitTest ./gradlew assembleDebug

它就会更关注依赖、导入、可测试性和编译边界。

很多“生成出来不能跑”的问题，本质上是验收标准太晚出现。把验证命令提前放进上下文，AI 的方案会自然向可验证结果收敛。

六、上下文需要分层

一个项目的上下文可以分成三层：

全局上下文：项目技术栈、目录结构、代码风格、禁止事项。
模块上下文：某个功能域的架构、数据流、接口约定、错误处理。
任务上下文：本次要解决的问题、复现方式、改动范围和验收命令。

不要把三层混在一起。全局上下文适合长期保存，模块上下文适合随功能沉淀，任务上下文适合每次单独描述。

这样做的好处是复用成本低。下一次修同一个模块时，不需要重新解释整套项目，只要补充本次问题即可。

七、警惕过期上下文

上下文也会失效。项目迁移了构建工具、接口协议改了、目录结构重排了、测试命令换了，如果 AI 仍然拿旧信息做判断，结果会比没有上下文更危险。

因此固定上下文需要维护。可以在以下场景主动更新：

升级框架或构建系统。
调整目录结构。
替换网络、数据库、日志或依赖注入方案。
修改发布流程和验证命令。
形成新的代码审查规则。

对 AI 来说，错误上下文比缺失上下文更难处理。缺失时它可能会询问或搜索，错误时它会带着错误前提继续执行。

八、一个轻量模板

日常使用时，可以准备一个简短模板：

请在当前仓库中完成任务。

目标：
现象或输入：
相关范围：
必须遵守：
完成后验证：
最后说明：

填充后的例子：

目标：新增一篇技术博客。
现象或输入：主题为 AI 工具工程实践，日期为指定时间。
相关范围：source/_posts/，可使用已有封面。
必须遵守：不要覆盖旧文章，不要提交代码，正文包含 <!-- more -->。
完成后验证：npm run build。
最后说明：新增文件和构建结果。

这个模板很短，但已经覆盖了 AI 执行任务最需要的几个判断点。比起临时一句话，它更能减少返工。

九、总结

AI 协作的质量，取决于它能否在正确上下文里工作。好的上下文应该帮助它回答五个问题：

这个项目是什么样的。
本次任务要完成什么。
哪些范围不能碰。
现有代码采用什么模式。
结果应该如何验证。

当这些信息被稳定地组织起来，AI 工具就不只是“回答问题”，而是能更可靠地参与维护、修复、验证和交付。上下文工程的价值，也正是在这里体现出来：少一点猜测，多一点可控的工程结果。