Vibe Coding的上限，在上下文工程

Vibe Coding的上限，在上下文工程。

AI coding工具的使用方式正在经历一次分层。

一批人还在调优prompt——怎么表达更清晰，怎么让AI第一次就写对。另一批人已经转移了注意力，开始在项目层面建立系统性的上下文基础设施。

这两条路线的效果差距正在拉开。

问题出在哪。

Vibe Coding的核心承诺是：用自然语言表达意图，AI负责翻译成代码。这个承诺在小任务上基本兑现了。在真实的工程项目里，它暴露了一个结构性缺陷：

AI没有项目记忆。

每次对话都是从零开始。它不知道这个代码库用什么异常规范，不知道前端API调用有没有统一封装层，不知道某个私域组件的正确用法应该参考哪个开源项目。你记得，但你不一定每次都说，说了也不一定说全。

结果是：AI生成的代码，局部看起来合理，放进项目里频繁出错。你花时间debug，发现问题根源不是AI写错了通用代码，而是AI不了解你项目的约定。

这不是prompt质量问题。这是上下文供给问题。

AGENTS.md：写给AI看的项目地图。

社区对这个问题的共识解法是AGENTS.md——一个放在项目根目录、专门供AI读取的上下文文件。

Sourcegraph AMP提出统一标准，OpenAI布局了agents.md域名，Cursor、GitHub Copilot等主流工具均已在实践层面支持项目级上下文文件。截至2026年初，GitHub上已有数万个项目在使用这类文件。

它不是README的替代品。README写给人看，讲的是"这个项目是什么、怎么用"。AGENTS.md写给AI看，讲的是"你在这个项目里工作时需要知道什么"。

两者的信息密度要求完全不同。

写什么？核心是五类信息：

项目概述——一句话说清技术栈和整体结构。

快速命令——构建、启动、测试怎么跑，AI生成代码后能立刻验证。

关键约定——违反会直接导致问题的规则。这是最重要的部分：不是所有规范都值得写进来，只写那些AI按默认行为去做会出错的。

验证流程——改动后怎么确认它是对的，而不只是看起来对。

参考项目——涉及私域组件或内部框架时，AI应该去参考哪个开源实现。

一个最小可行版本：

# AGENTS.md

## 项目概述
Spring Boot + React 管控系统，monorepo结构

## 快速命令
- 启动后端：./scripts/start-server.sh
- 启动前端：./scripts/start-web.sh
- 运行测试：make test

## 关键约定
- 异常用 BusinessException 抛出，禁止直接抛 RuntimeException
- 响应体由框架统一包装，禁止手动构造
- 前端 API 调用走 @/api 下的封装函数，禁止直接调用 axios

## 参考项目
- 组件用法：reference-projects/pro-components/
- 网关集成：reference-projects/higress/

长度控制在200行以内。超过500行，AI的注意力会被稀释，你精心写下的规则反而会被忽略。这是一份导航地图，不是项目文档全集。

需求澄清：Grill-me工作流。

AGENTS.md解决的是项目知识的持久化问题。但还有另一个上下文供给问题：需求本身的模糊性。

工程师向AI描述需求的方式，往往比自己意识到的更模糊。“写一个用户注册功能”——听起来清晰，但实际上没有指定邮箱还是手机号验证、重复注册怎么处理、密码规则是什么、是否需要风控。

Grill-me工作流的思路是反转提问方向：在让AI动手之前，先让AI来问你。

你在 prompt 里要求 AI 先澄清再动手，对话会变成这样：

你：帮我写一个用户注册功能
AI：
1. 注册时需要验证手机号还是邮箱？
2. 如果用户用已注册的邮箱再次注册，是直接提示"已注册"还是静默转为登录？
3. 密码规则允许连续重复字符吗？比如"111111"是否通过？
4. 同一IP在1分钟内尝试注册100个账号，是否要触发风控？
5. 注册成功后跳转首页还是停留当前页？

这些问题的答案，一部分是本次任务的输入，另一部分应该沉淀为AGENTS.md里的关键约定——它们描述了你项目的边界条件和决策偏好，下次遇到类似场景时不需要重新澄清。

风险分层：什么代码可以放手给AI。

Anthropic研究员Erik Schluntz在Code w/ Claude 2025演讲中分享了一个数据：他们最近将22,000行AI生成的代码合并进了生产环境的强化学习代码库（数据来自Code w/ Claude 2025公开演讲）。

这个数字的前提不是无限制地让AI写代码，而是一套清晰的风险分层策略。

把代码库按依赖关系分成两类：

叶子节点——零外部依赖的独立单元。纯函数、独立UI组件、无副作用的数据转换、一次性工具脚本。特征是修改影响范围可预测，出了问题容易定位和回滚。这类代码可以放心交给AI。

主干节点——多模块依赖的核心组件。数据库访问层、核心业务逻辑、公共工具类、框架配置。特征是修改可能引发连锁反应，且需要长期演进维护。这类代码需要人工主导，AI只能辅助。

22,000行都在叶子节点上产生。主干代码的改动至今仍然需要人工审核。

这种分层与微服务架构高度兼容——将AI生成的代码限制在特定服务或特定目录，由接口契约隔开影响范围。在单体应用里，等效的做法是按包名或模块边界划定AI可以自由操作的区域。

上下文是会变的。

这三个机制——AGENTS.md、Grill-me、风险分层——不是配置一次就不用管的。

Patrick Debois提出了"上下文开发生命周期"的框架：生成、评估、分发、观察，持续循环。AGENTS.md写完后，AI每次犯的错误都是一次更新机会——如果多一条规则能阻止这个错误，就把规则加进去。Grill-me发现的边界条件如果具有普遍性，就沉淀为约定。

这个维护成本比听起来低。一个运转中的项目，每两三周审视一次AGENTS.md，每次只需要增删几行，就能持续降低AI协作的摩擦。

如果你的项目已经积累了大量代码，建立AGENTS.md本身也可以借助AI：把项目根目录结构、package.json、几个核心文件作为输入，让AI反向提取技术栈和约定，生成初稿后人工校对精炼。通常20分钟以内可以完成一个够用的版本。

问题的本质。

Vibe Coding解决的是人机交互的自然语言化。它让不会写代码的人可以描述意图，让工程师可以用更高抽象层次表达需求。

但自然语言的问题是：它是单次的、无状态的。你今天告诉AI你的项目用什么规范，明天开一个新对话，它不记得。

上下文工程解决的是这个状态持久化问题。AGENTS.md把隐性的项目知识显式化，Grill-me把模糊的需求结构化，风险分层把AI的操作边界制度化。

三者的共同作用是把Vibe Coding从一个运气型活动，变成一个可以持续优化的工程过程。

Naval说的"对频率"，有了这套基础设施才真正可靠。否则只是恰好对上了。

诊断清单。

如果你的AI coding效果不稳定，按这个顺序检查：

项目根目录有没有AGENTS.md？如果没有，这是最高优先级的改进。

AGENTS.md有没有超过500行？如果有，删减到核心约定，其余内容改成索引指针。

你的需求输入有没有经过Grill-me？如果没有，在prompt末尾加一句"先提问澄清，再开始写代码"。

你有没有区分叶子节点和主干节点？如果没有，画出你的依赖图，标出哪些包或模块是零依赖的终端节点。

每个环节都可以独立改进，不需要全部到位才能看到效果。

新建一个AGENTS.md文件，把项目概述和三条最关键的约定写进去。这是你今天能做的最小行动，也是上下文工程的起点。