Vibe Coding 任务上下文包：开工前把目标、边界与证据装在一起

“把登录页修一下”足以启动一段对话，却不足以启动一次工程改动。AI 不知道“修”指视觉、跳转还是会话恢复，不知道哪些文件是用户正在编辑的，也不知道通过构建是否就是完成。它仍可能很快给出 diff，但速度来自替你补全假设，而不是理解了任务。

任务上下文包解决的不是上下文窗口大小，而是开工输入是否闭合。编程 Agent 的上下文预算讨论如何分配有限窗口，编程 Agent 的仓库地图描述全局结构；上下文包只针对一次任务，回答“这次要改变什么、不能碰什么、拿什么证明完成”。它应足够短，且每个仓库事实都能回到文件、命令或用户确认。

先固定任务身份与代码基线

包的第一段不是长背景，而是任务身份：一句目标、用户可见结果、明确非目标和风险等级。随后记录仓库根目录、当前分支、HEAD、工作树状态采集时间，以及是否存在未提交修改。Git 的对象名只代表已提交基线；如果工作树不干净，还要附上已暂存、未暂存和未跟踪文件清单，不能用一个 commit 假装代表当前现场。

task: restore-login-return-path
goal: 登录成功后回到发起登录前的站内页面
nonGoals:
  - 不更换认证库
  - 不修改会话有效期
baseline:
  head: 8d31c2f
  branch: fix/login-return
  statusCapturedAt: 2026-07-30T10:15:00+08:00
  worktree: dirty

这里不要粘贴秘密、完整环境文件或无关 diff。敏感事实用“变量名存在、值由哪个环境提供、验证方式是什么”表达。若仓库状态无法确认，字段应写 unknown，而不是让 AI 从目录名推断。

把需求改写成可判定的接受边界

目标说明动机，验收条件决定何时停止。每条验收都写成可观察结果，并指出观察层：单元测试、浏览器交互、HTTP 响应、数据库状态或人工审阅。例如“优化跳转”不可判定；“匿名用户访问 /settings，登录后回到 /settings，外站 URL 被拒绝”才给出了正向、负向和安全边界。

同时列出非目标。Vibe Coding 容易因为 AI 看见邻近问题而扩大范围；非目标不是消极声明，而是 reviewer 判断越界 diff 的依据。Vibe Coding 实践中的小步迭代只有在停止条件清楚时才成立。

文件不是上下文，选择理由才是

上下文包可列“已知相关文件”，但每个路径都要带理由和证据：路由入口由框架配置指向，认证回调由搜索结果和调用方共同证明，测试文件覆盖对应行为。不要把猜测写进同一列表。把材料分为四类更实用：必须遵守的规则、当前实现证据、接受测试、仍待探索的未知项。

evidence:
  - path: src/auth/callback.ts
    reason: 登录成功回调的实际写入点
    verifiedBy: "rg 'returnTo' src/auth"
unknowns:
  - 外站 URL 当前在哪一层被规范化
allowedPaths:
  - src/auth/**
  - src/auth/**/*.test.ts

allowedPaths 是初始调查范围，不应伪装成永远完整的依赖闭包。若探索发现必须修改公共路由工具，AI 先报告新证据和影响，再扩大范围。这样约束不会逼它偷偷绕路，也不会变成无限授权。

在编辑前确定验证命令

把项目认可的命令、运行目录、所需服务和成功判据写入包。不要只写“跑测试”；同一个仓库可能有单包测试、全量测试、生成检查和真实浏览器检查。还要列出本机无法运行的门禁及原因，防止 AI 把“未运行”措辞成“通过”。编程 Agent 的改动验证门可用于组织分层检查，上下文包则负责把本任务选择的那一组冻结下来。

验证项应和验收条件一一对应。类型检查能证明类型关系，不能证明登录跳转；一个页面返回 200，也不能证明客户端导航保留了目标地址。高风险条件如果没有可执行验证，就应标为需要人工确认，而不是删除。

用来源和时效管理事实

上下文包不是永久规范。给每条易变化事实记录来源与有效条件：源码事实绑定 HEAD 加工作树快照，依赖行为绑定锁文件版本，用户决定绑定消息或 issue，外部文档绑定版本和访问日期。W3C PROV 的核心思想是区分实体、活动和派生关系；无需引入复杂系统，也可以保留“这条结论由什么产生”。

开工前做一次四问审查：目标是否可判定，非目标是否足以挡住扩张，所有关键事实是否有来源，验证是否覆盖用户结果。任一答案为否，AI 应继续只读探索或请求决策，而不是开始写代码。

一份好上下文包不会替 Agent 规划实现，也不会保证代码正确。它的价值是把猜测显性化，使首个补丁、后续评审和失败恢复都围绕同一任务合同展开。任务中途需求改变时，更新包的 revision，并标明哪些旧验收失效；不要在聊天尾部悄悄追加一句话，却让前面的边界继续被误用。

延伸阅读

• 编程 Agent 的上下文预算
• 编程 Agent 的仓库地图
• Vibe Coding 实践
• 编程 Agent 的改动验证门