AI Vibe Coding 03：上下文工程与范围控制（给够信息，不给噪音）

路线阶段：AI Vibe Coding 第 3 章。
本章目标：解决“上下文喂太少答非所问、喂太多开始胡写”的核心矛盾。

学习目标

完成本章后，你应该能做到：

1. 为不同任务构建最小充分上下文。
2. 通过白名单限制 AI 改动边界。
3. 处理多来源文档冲突与版本漂移。
4. 建立上下文衰减与复位机制，避免长期对话污染。

上下文工程不是“多贴文件”

常见误区：

1. 把整个仓库文件都喂给 AI。
2. 历史讨论全部保留不清理。
3. 把过期文档与最新代码混合注入。

结果是：模型注意力被稀释，输出稳定性下降。

最小充分上下文模型

推荐 5 份上下文上限：

1. 任务目标文档（1份）
2. 关键实现文件（2~3份）
3. 项目规范文件（1份）
4. 测试/验收样例（1份）

超过上限时，优先摘要而不是继续堆原文。

上下文分层

Layer 1：强约束（必须遵守）

1. 架构规范
2. 命名规范
3. 安全/性能红线

Layer 2：任务上下文（必须理解）

1. 目标模块代码
2. 输入输出契约
3. 相关测试

Layer 3：参考上下文（可选）

1. 历史实现
2. 设计讨论记录
3. 旧版本文档

范围控制（Scope Guard）

允许改动：
- src/ui/result/*
- src/domain/stage/result.ts

禁止改动：
- src/domain/combat/*
- src/security/*
- build/*

让 AI 在提示中显式确认范围：

请先输出你将修改的文件列表，再开始修改。
如果需要超出范围，先停止并说明原因。

上下文检索策略

关键词检索

按“功能词 + 结构词”组合：

1. result summary payload
2. reward grant idempotent
3. stage complete event

语义检索

对大型仓库建议先做代码索引，按 symbol 与调用链返回片段而不是整文件。

冲突消解

当文档与代码冲突时优先级：

1. 最新代码事实
2. 测试行为
3. 最新规范文档
4. 历史设计文档

并要求 AI 明确声明：

发现冲突：文档A与代码B不一致。
本次以代码B与测试C为准，并在结果中列出冲突点。

上下文衰减与复位

长会话建议每 3~5 轮执行一次：

1. 提炼当前事实摘要
2. 丢弃已失效讨论
3. 重新注入最新范围与验收

这能显著降低“后文污染前文”的问题。

结构化上下文包

可以给 AI 一个固定输入结构：

{
  "goal": "新增结算升级路径时间线",
  "scope": ["src/ui/result/*", "src/domain/stage/result.ts"],
  "constraints": ["no new deps", "keep api stable"],
  "files": [
    "src/ui/result/ResultPanel.tsx",
    "src/domain/stage/result.ts",
    "docs/ARCHITECTURE.md"
  ],
  "acceptance": [
    "build pass",
    "snapshot tests pass",
    "no new lint errors"
  ]
}

与团队流程对齐

1. Planner 负责打包上下文。
2. Builder 只在上下文包内执行。
3. Reviewer 对照上下文包做偏差检查。
4. CI 根据 acceptance 自动验证。

常见坑

坑 1：上下文包里混入过期分支代码

会导致 AI 改错目标。注入前必须确认当前分支版本。

坑 2：范围白名单缺失

AI 容易顺手修“看起来不顺眼”的无关文件。

坑 3：不做上下文复位

长会话后错误累积，输出质量明显下滑。

本月作业

完成一套“上下文包生成器”：

1. 输入任务描述自动检索候选文件。
2. 人工确认后生成标准 JSON 上下文包。
3. 对比有/无上下文包的任务一次通过率。

下一章：AI Vibe Coding 04《多代理协同：规划代理、执行代理、审查代理如何分工》。