6.6 Context Engineering——上下文工程的系统方法论模块六：运营增长与高级话题

模块六：运营增长与高级话题 | 第06讲：Context Engineering——上下文工程的系统方法论

课程项目：VibeNote 智能笔记
技术栈：Next.js、React、TypeScript
本节目标：把「提示词技巧」升级为「系统供给信息的工程」：知道给什么、何时给、给多少、如何更新与校验。

一、开场：Prompt Engineering 是战术，Context Engineering 是战略

参考《核心概念与范式演进》反复强调：变化的核心不是自然语言替代键盘，而是软件生产方式转向编排系统。在这个视角下，AI 的产出质量主要由「它看到了什么」决定——包括代码、规范、历史决策、接口契约、错误样例与验收标准。

**Context Engineering（上下文工程）**回答四个问题：

哪些信息必须始终在场？（被动上下文）
哪些信息应该按需检索？（主动上下文）
如何把大仓库压缩成高信号摘要？（分形文档）
如何在有限窗口内做取舍？（上下文预算）

对 VibeNote 这种会持续演进的 Next.js 全栈项目，没有上下文工程，你会反复遇到：风格不一致、目录乱长、重复造轮子、以及「AI 以为你还在用旧栈」。

二、有限窗口：更多上下文 ≠ 更好

模型上下文窗口虽然在增长，但三类问题不会消失：

噪声稀释：无关文件越多，关键约束越不突出。
成本与延迟：token 变多，费用与响应时间上升。
注意力衰减：即便能塞下，模型也可能「看不见」中段关键句。

因此上下文工程的第一性原理是：在预算内最大化信噪比。

flowchart TD
    I[候选信息全集] --> F[过滤/分层]
    F --> P[被动上下文\n小且稳定]
    F --> A[主动上下文\n按需注入]
    P --> M[模型推理]
    A --> M

三、被动上下文 vs 主动上下文

被动上下文（Passive）：默认就在场，适合「长期稳定、违反代价高」的信息：

技术栈与框架版本（Next.js App Router / RSC 策略）
目录结构与模块边界
代码风格、测试策略、提交规范
安全红线（密钥、PII、日志）

落地形态：AGENTS.md、.cursor/rules、项目级 Skill。

主动上下文（Active）：遇到任务才检索，适合「大而多变」的信息：

某条业务链路的完整调用栈
某个 Bug 的相关文件集合
历史 PRD 片段、设计稿说明

落地形态：@文件、代码搜索、RAG、以及「分阶段让 AI 自己提出要读的文件」（但要配审查）。

参考《工具链与开发框架》里关于 AGENTS.md vs Skills 的讨论：被动上下文的稳定性往往更高，因为不依赖「模型是否记得去触发 Skill」。

sequenceDiagram
    participant U as 你
    participant H as Host(Cursor)
    participant M as 模型
    U->>H: 发起任务
    H->>M: 注入被动上下文(规则/栈/目录)
    M->>H: 请求读取某文件(主动)
    H->>M: 注入文件内容
    M-->>U: 提交方案/补丁

四、分形文档（Fractal Docs）：从 README 到叶子模块

分形的意思是：在不同层级重复同一结构——概览 → 边界 → 入口 → 风险点。这样 AI（和人类）在任何目录都能快速定位。

建议 VibeNote 至少三层：

根目录 AGENTS.md：全局栈、目录地图、绝对禁忌。
docs/architecture.md：子系统关系、数据流、鉴权模型。
关键模块 README.md：例如 app/(dashboard)/README.md 说明路由与权限。

每层都遵循同一模板：

这是啥 / 不是啥
关键入口文件
常见改动路径
已知坑

五、上下文预算：给 AI 的「token OKR」

你可以把一次任务的上下文当作预算表：

类别	建议占比	内容
规则与栈	10%–20%	AGENTS、类型约束
目标与验收	10%–20%	PRD 片段、测试用例
相关代码	50%–70%	只放调用链相关文件
样例	5%–10%	一个「好例子」胜过十段描述

操作口诀：先补「验收标准」，再补「代码」；不要先贴一百行无关样式文件。

六、`AGENTS.md` 怎么写才真的有用？

避免写成「正确的废话」。要包含可执行约束：

# VibeNote — AGENTS

## 非目标
- 不引入新的 ORM（已选 Drizzle）
- 不把密钥写进客户端 bundle

## 目录
- app/(marketing) 仅静态与 SEO 页面
- app/(app) 登录后应用壳
- lib/ai 只允许通过 server action 调用

## 质量门槛
- 改动 UI 必须处理 loading / empty / error 三态
- API 变更必须同步更新 Zod schema 与前端类型

这段的价值在于：当 AI 想「顺手引入 Prisma」时，会被明确禁止。

七、与 Vibe Coding 工作流对齐：规格是新的源代码

当实现大量交给 Agent，规格不清的代价会被放大。把 PRD、接口契约、错误码表保持更新，本质是在维护「生成器的输入」。

推荐节奏：

每次架构变更：先改 AGENTS.md 与架构文档，再改代码。
每次发版：用变更摘要更新「分形文档」叶子节点。

八、把「上下文」当成产品：版本、OWNERS、变更记录

当中型团队加入 VibeNote，你会发现上下文文件也会「腐烂」。最小治理三件套：

版本戳：在 AGENTS.md 顶部写 Last verified with: Next 15.x / React 19.x。
OWNERS：每个关键目录标明负责人（可以是 Git CODEOWNERS）。
变更记录：重大架构调整写 ADR（Architecture Decision Record），避免「为什么当初这样选」失传。

flowchart LR
    ADR[ADR/决策记录] --> AG[AGENTS.md]
    AG --> R[Cursor Rules]
    R --> PR[PR 模板勾选]

九、常见反模式

把聊天记录当文档：不可检索、不可版本化。
复制粘贴整库：噪声爆炸。
规则互相打架：A 文件要求 tailwind，B 文件要求 css modules。
只加不改：栈升级后文档仍写旧版本。
过度依赖 RAG：检索错一次，比不检索更糟；要有校验。

十、用 AI 维护上下文：「元工作流」

你可以让 Agent 做这些事（仍需你审）：

从 diff 反向更新 AGENTS.md 的目录说明
把一次线上故障整理成 docs/incidents/2026-xx.md
将散落约定合并成单一规则源

关键是：上下文也需要 CI——至少在 PR 模板里问一句「是否更新 AGENTS？」

十一、把课程方法映射到 VibeNote：一周的上下文改造计划

Day 1：写根 AGENTS.md（非目标 + 目录 + 红线）。
Day 2：补 docs/architecture.md（数据流、鉴权、AI 调用边界）。
Day 3：给 lib/ai 与 app/api 各加叶子 README。
Day 4：整理一份「好例子 PR」链接索引（供模型模仿）。
Day 5：在 PR 模板加两项：是否更新文档 / 是否更新埋点或指标。

十二、进阶：RAG 与「按需知识」怎么不进坑？

当 VibeNote 需要把大量历史笔记、帮助文档接入问答，常见方案是向量检索（RAG）。它与上下文工程的关系是：RAG 是主动上下文的一种实现，但仍要遵守预算与校验。

建议实践：

检索前过滤权限：用户只能看到自己 workspace 的文档切片。
引用必须可点击：回答要附 note_id 或段落锚点，否则不可审计。
拒答策略：检索置信度低时明确说「找不到」，不要胡编。
离线评测集：准备 30~50 条真实问题，比较「有检索 vs 无检索」的准确率与延迟。

没有评测的 RAG，往往只是把幻觉从「代码」迁移到「产品答案」。

十三、实操附录：一次「上下文裁剪」对话模板

当你发现模型开始胡改 unrelated 文件，可以把下面这段当作系统提示的补丁（按需改写）：

你只允许修改列出的路径：app/(app)/notes/**、lib/notes/**。
任何数据库迁移必须先输出计划并等待确认。
若信息不足，只允许提出最多 3 个澄清问题，不要猜测业务规则。
所有新 API 必须附带 Zod 校验与 1 个失败样例测试。

这类模板的价值是：把边界从「你心里知道」变成「模型每次都能看到」。

最后补一条「人性约束」：上下文工程不是把文档写得像论文，而是写得像可执行的运行手册——越能直接指导下一步动作，越容易在 Vibe Coding 里稳定复用。把「可验证」写进句子：能指向文件路径、命令、测试用例名，就不要只写形容词。

十四、小结

Context Engineering 是系统问题：被动/主动、分层文档、预算与更新机制（建议每周复盘一次是否过期）。
AGENTS.md 应包含非目标、目录边界、质量门槛。
分形文档让大仓库在不同尺度都可导航。
上下文质量比单次 prompt 措辞更能决定长期交付稳定性；把验证点写清楚，比堆更多背景更有效。

思考题

你的 VibeNote 仓库里，哪些信息必须被动化，哪些必须主动化？各写三条并说明理由。
如果你只能给模型 8K tokens，你会如何为「修复鉴权 Bug」任务分配预算？
当规则文件过多开始互相冲突，你会如何重构为「单一事实源」并保证可执行？

下节预告

下一讲进入 Multi-Agent 协作：当单智能体长对话开始失忆、跑偏、上下文膨胀，工业界常用的解法是 角色分工 + 上下文隔离 + 编排。我们将对照 Claude Code Swarms 的思路，给你一套可落地的任务拆解与评审流程，服务 VibeNote 的大型改造与多模块并行开发。

6.6 Context Engineering——上下文工程的系统方法论