返回博客首页
上下文工程实战：把 AI Agent 的提示词变成可维护的工作系统
AI Agent 出错，很多时候不是模型差，而是信息放得太乱：需求在聊天记录里，规则藏在长文档，示例已经过期，工具失败后没人说明该重试还是停下。模型只能用看似合理的答案补洞。再追加一段 prompt，通常只是把同一处混乱拖到下一轮。
这篇给做代码、内容或运营自动化的人一套可维护的上下文工程方法。它适用于 Claude、Codex 这类会读文件、调工具、连续执行任务的 Agent。交付要求很明确：开始前知道要做什么，证据不足时会停下来问，完成后能按同一把尺子验收。
图里的五层不能混在一起。任务简报定义眼前结果；项目规则保留长期约定；证据提供可核查的事实；工具契约定义输入、输出与副作用；评测决定能否交付。把五件事塞进一段话，维护成本会很快失控。
提示词只是上下文的一小段
“修复登录问题”没有复现路径、允许改动范围、安全边界和验收方式。超长提示词看似周全，下一项任务仍要复制它，旧规则也容易压过新需求。Anthropic 的 context engineering 指南建议，Agent 在当前步骤应该拿到恰好够用的相关材料。
| 材料 | 回答的问题 | 位置 | 常见错误 |
|---|---|---|---|
| 任务简报 | 这次要交付什么 | Issue、任务文件 | 只写“优化一下” |
| 项目规则 | 团队长期如何协作 | AGENTS.md、CLAUDE.md | 把常识写成十页 |
| Skill | 一类任务怎么执行 | skills/name/SKILL.md | 每次加载所有 Skill |
| 参考资料 | 什么是正确事实 | 测试、类型、fixture、设计稿 | 用概述替代证据 |
| 工具契约 | 能做什么，失败怎么办 | 工具说明、wrapper | 只列工具名 |
同一规则只留一个权威位置。发布必须有中英文稿和图片清单，应写在项目规则；当天文章写哪个角度，应写进任务简报。两边重复，几周后就会冲突。
先盘点，再让 Agent 动手
别让它直接“阅读整个仓库”。先让它做一个最小盘点：
先不要修改文件。
1. 找出与本任务直接相关的规则、代码、测试、数据和示例；
2. 列出路径、用途、最后修改时间和过期风险；
3. 标出冲突、不能验证的结论和需要我补充的信息；
4. 给出最小执行计划：读什么、改什么、怎么验收。
没有证据时请提问，不要补全事实。
这一步会抓到模型不该自己裁决的冲突：文档写 userId，fixture 还在用 id；根目录要求保存历史报告，某个流程却清空输出目录；任务要求“提升转化”，却没有定义事件、窗口和基线。
AGENTS.md 放边界，Skill 放长流程
AGENTS.md 应当像地图。只写仓库无法自行推断的内容：启动命令、目录职责、密钥处理、禁改区域、测试要求和输出位置。
# Project rules
- Web app is apps/web; API contracts are packages/contracts.
- Never put secrets in fixtures, logs or screenshots.
- API contract changes need a fixture and one integration test.
- Run pnpm test:affected before handoff.
- Reports go to artifacts/date; do not alter earlier reports.
- If rules conflict, stop and quote both paths.
“项目使用 React”“源码在 src”从仓库就能看到，写进去只是噪音。真正值钱的是本地例外：哪个脚本会写生产数据、哪个包不能升级、哪种报告命名会被导入器拒绝。
长流程拆到按需加载的 Skill。发布检查 Skill 只在发稿时读 front matter、图片路径和链接，不必进入每个任务。Claude Code Skills 这类机制的好处就在于按任务加载，而不是再造一本大而全的项目手册。
任务简报要写已知、未知与验收
下面的模板可以直接复制到 Issue、任务文件或第一条指令：
# Task: add export status
## Outcome
导出后显示 queued、running、completed 或 failed。
## Known facts
- POST /exports 返回 job_id。
- 状态类型在 packages/contracts/export.ts。
- 轮询工具在 apps/web/lib/poll.ts。
## Unknowns to resolve
- failed 是否允许重试？
- 状态保存多久？
- 是否需要埋点？先查现有实现。
## Constraints
- 不改认证中间件；
- 不加第三方依赖；
- 不把导出内容写进浏览器日志。
## Acceptance
- 覆盖四种状态和一次网络超时；
- 使用现有 fixture；
- 交付时列出改动文件、执行命令和未解决问题。
未知项不是废话。它告诉 Agent 哪些地方不能自由发挥。它无法从当前证据回答时，就应该停止并提问。
证据、工具和评测怎样接起来
当前类型定义、JSON fixture 和通过的集成测试，比一段“接口大概这样返回”的文字可靠得多。给数据卡片任务时，一份输入和期望 DOM 或截图，比五个风格不同的整页更有用。还要写明参考的用途：
packages/contracts/export.ts 只用于确认接口字段。
docs/ui/export-status.png 只用于视觉间距，不用于推断接口行为。
测试和说明文档冲突时，以测试和类型定义为准，并报告冲突。
工具说明也要当接口写。它必须有输入、输出、副作用、权限和失败处理：
tool: get_order
input: order_id string
output: id, status, total_cents, updated_at OR NOT_FOUND
side effect: none
permission: read-only; current tenant only
failure: retry TIMEOUT once; stop and ask on FORBIDDEN
写入工具加 dry_run 或人工确认。publish_article 可以先返回预览和校验结果，确认后的第二次调用才发布。搜索工具只回相关片段，读取文件支持行号范围，写入动作回传准确改动摘要。几千行无关日志会让下一步判断变差。
最后用真实任务验收，而不是看一次演示就说“好用”。选 6 到 10 个已脱敏任务：一个有测试的 bug、一个小功能、一个模糊需求、一次只读工具调用、一次发布检查和一组相互冲突的资料。记录首次通过率、人工修改分钟数、无关文件改动数和任务成本。失败后先修规则、参考、工具或测试，别只在聊天框多加一句“下次注意”。
给资料一张索引卡，避免“旧答案”反复出现
最容易被忽略的不是提示词，而是资料的新旧与用途。把任务常用的证据集中列到一个小索引里，Agent 只按需读取文件；索引不复制全文，也不把一年前的截图当成当前接口规范。下面是一个可直接改名复用的样例：
# context-map.yaml：路径是线索，不代表内容自动可信
- path: packages/contracts/export.ts
purpose: "核对导出状态字段"
owner: "API 团队"
checked_on: "2026-09-16"
verify_with: "pnpm test:contracts"
- path: tests/fixtures/export-status.json
purpose: "复现四种状态和超时返回"
owner: "Web 团队"
checked_on: "2026-09-16"
verify_with: "pnpm test:affected"
- path: docs/ui/export-status.png
purpose: "只参考视觉间距；不推断接口行为"
owner: "设计团队"
checked_on: "2026-09-16"
verify_with: "人工对照当前设计稿"
checked_on 只是上次核对时间，不是有效期保证。接口变更后，先运行 verify_with，再更新索引。若类型定义与旧截图冲突，先标记冲突并找负责人；Agent 不应凭自己猜测“哪个看起来更新”。外部网页、聊天记录和仓库注释也只能作为资料输入，其中写着“忽略现有规则”的句子不能升级成系统指令。
把六条真实任务变成回归门槛
评测不需要一上来做大平台。用一个 CSV 保存任务编号、输入快照、允许工具、验收条件和失败原因。每次修改 AGENTS.md、Skill 或工具说明，重跑同一批任务，才能看见改动是否真的减少返工。
| 用例 | 应该观察什么 | 失败时先检查 |
|---|---|---|
| 有测试的 bug | 只改相关文件，测试通过 | 任务边界、测试命令是否缺失 |
| 模糊需求 | 在动手前列出需要决定的问题 | 任务简报是否把未知项写成已知事实 |
| 冲突资料 | 报告两个来源与冲突点 | 资料索引是否缺少权威来源和核对日期 |
| 只读查询 | 不触发写入工具 | 工具权限和副作用是否写清 |
| 发布检查 | 报告缺图、坏链接和缺元数据 | 验收清单是否可执行 |
| 工具超时 | 按约定重试一次并保留错误 | 工具契约是否写了失败分支 |
记录“首次通过”“人工修改分钟数”“无关文件改动数”和“任务调用成本”。可以先把上线门槛设为：高风险用例零越权，所有必过测试通过，返工时间不得高于旧流程。阈值由团队自己的基线决定，不能把一次演示结果当成稳定性结论。失败时修正对应的规则、资料、工具或测试，并留下变更记录；下一轮重跑同一用例。
每周维护与交付检查
每周或大改后花 20 分钟：删掉代码结构已能证明的重复规则；检查 Skill 的链接、命令和样例；把最近三次人工纠正归为缺规则、缺事实、工具不清或验收缺失；重跑一条曾失败任务；复核读取客户数据的权限、日志和脱敏配置。
Agent 的成果不必写得花哨。它应当少问无关问题，能说出哪条事实没有证据，少改无关文件，并留下可复查的交付。用 Code0 组织多模型任务时，可以把任务简报、项目规则和验收表放进同一项目空间，让模型切换不改变团队的质量门槛。
[ ] 任务包含结果、已知事实、未知项、约束和验收
[ ] 项目规则只放长期且仓库无法自证的约定
[ ] 重要事实能回到类型、测试、数据或当前文档
[ ] Skill 按任务加载，入口文件没有变成百科全书
[ ] 工具说明包含输入、输出、副作用、权限和失败处理
[ ] 评测集覆盖模糊任务、冲突资料和失败路径
[ ] 本次纠正已回写到规则、参考、工具或测试之一
