Agentic Engineering 实战：把计划、上下文和验证做成 AI 工作台

核心结论（一句话）

“Agent 面前摆着一张工作台”——AI 工作台 = 计划 / 上下文 / 执行 / 验证 / 治理 五层；个人可以 YOLO，团队必须把”任务卡 + 工作区隔离 + 可验证结果 + 合并规则”这四件事说清楚后再多开 Agent；CLAUDE.md 三段式（What/Domain/Validation）、plan.md 任务协议、Skill = 过程资产、Subagents = 隔离、团队 3 层权限渐进（只读→半自动→受控写入）构成可落地的最小工作台。

分类提炼

知识节点（8 个独立概念）

关联图谱

上游（基于 / 来自）

下游（应用于 / 验证于）

同级（横向 / 并列 / 镜像）

正文要点（8 条）

一、AI 工作台 5 层结构（核心范式）

Agent 面前摆着一张工作台：左边是计划，右边是上下文，后面接着测试、日志、权限和回滚。靠一句神奇提示词不够，它需要在一个被人整理过的现场里工作。

层 最小交付物 用来解决什么
计划 plan.md、验收勾选项 防止任务跑偏、提前收工
上下文 CLAUDE.md、任务资料包 防止靠聊天记忆硬撑
执行 worktree、Skills、Subagents 防止并行互相污染
验证 测试、日志、截图、trace、PR 说明 防止”看起来做完了”
治理 allowlist、hooks、权限表、回滚点 防止把个人 YOLO 带进团队

工作台搭得越清楚，Agent 干活越有边界。

二、多开 Agent 之前，先把”可控并行”说清楚

团队里多 Agent 三个常见翻车：

必须先回答 5 问：

  1. 任务怎么拆（哪些能独立执行，哪些需要留在主线里）
  2. 工作区怎么隔离（worktree / 临时分支 / 只读探索）
  3. 结果怎么验（每个子任务交什么证据）
  4. 冲突怎么收（谁合并、谁 review、谁决定丢弃）
  5. 错了怎么退（能不能回滚到任务开始前）

每开一个 Agent，先写一张”任务卡”：

1
2
3
4
5
6

任务：修复订单导出超时
工作区：worktree/order-export-timeout
边界：只改导出链路，不动权限模型
输入：issue 链接、报错日志、最近一次慢查询
交付：diff、测试命令、关键日志、剩余风险
合并：主会话 review 后再合入

worktree 解决的是物理隔离，验收、评审和合并，还得另外设计。 并行和协作不是一回事。

三、plan.md 8 段核心 + 2 段进阶

Matt 的工作流里最靠前的动作是先生成 plan.md。/ce-plan 不是写通用计划，而是先读代码库找已有模式/约定/历史经验，再写出带验收标准的 plan.md。

8 段核心：

  1. 目标 —— 这次要解决什么问题
  2. 不做什么 —— 明确排除哪些范围
  3. 背景和输入 —— issue / 截图 / 报错 / 用户反馈 / 链接
  4. 可能涉及的文件 —— 先列线索
  5. 实施步骤 —— 按可验证的小步拆
  6. 验收标准 —— 什么结果算完成
  7. 验证命令 —— 测试 / 构建 / lint / 截图 / 日志检查
  8. 当前状态 —— 已做、未做、阻塞、下一步

2 段进阶：

Agent 做长任务时一个常见问题是提前收工。它修了几个明显问题，跑了一个看起来还行的检查，然后自然进入总结状态。它不一定是在偷懒。很多时候，是我们没有把”完成条件”写清楚。

四、5 层上下文 × 3 档载入

层级 放什么 典型载体
当前窗口 当前目标、约束、最近观察、下一步决策 对话上下文
项目规则 架构边界、编码约定、禁止事项、验证方式 CLAUDE.md、rules
任务状态 计划、已做事项、阻塞、证据 plan.md、todo、issue
历史资料 会议、旧方案、事故、决策记录 Obsidian、Bear、Docs、搜索工具
结果 测试、日志、截图、trace、线上状态 CLI、MCP、hooks

3 档载入：

档位 怎么给 适合什么
直接放进窗口 当前目标、约束、最近错误、关键 diff 这一轮马上要推理
放文件让 Agent 读 plan.md、CLAUDE.md、运行说明、设计记录 任务过程中多次用到
放外部检索 会议全文、历史事故、社区讨论、旧 PR 只在需要时查

CLAUDE.md 三段式（重 Validation）：

Agent 往往不缺生成能力，缺的是知道在你们系统里，什么才算真的做完。

五、Skill = 过程资产（不是高级 prompt）

Skill 不是”最佳实践文档”，是可执行流程：

可用 Skill 至少 6+ 段：

  1. 什么场景触发
  2. 先读哪些资料
  3. 按什么步骤做
  4. 用哪些命令或脚本
  5. 常见失败模式是什么
  6. 最后交什么证据
  7. 失败以后怎么记录 gotchas

hooks 是另一层——“做到某一步时系统自动插手一下”：

分工矩阵：

机制 更适合做什么 不适合做什么
Skill 描述流程、检查清单、输出证据 强制阻断危险动作
hook 拦截命令、补日志、提醒验证 承载复杂推理
Subagent 隔离搜索、审计、评审 上下文处理
plugin 打包团队能力 代替权限治理

第一版 hooks 可以很小——能拦住一类危险命令，能把一类失败变成 Agent 看得懂的上下文，就已经能减少不少返工。

六、Subagents 的核心是”隔离”，不是”多几个角色”

适合拆出去的（独立可验型）：

不适合拆（强耦合型）：

主会话从 subagent 拿回高密度结果：结论 / 证据 / 风险 / 建议下一步。多 Agent 麻烦的地方，通常不在”谁扮演什么专家”，更多在结果怎么合并、证据怎么保留、失败怎么回到流程里。

七、团队 3 层权限渐进（个人 YOLO vs 团队分层）

Agent 正在从”代码助手”变成”执行层”——读邮件、查日历、搜 Slack、操作网页、拉会议记录、跑内部工具。

阶段 能力边界 备注
只读 读 issue/日志/文档/监控/测试结果/会议记录 先不写生产系统，不发消息，不改配置
半自动 生成草稿/命令/PR/变更单/回复建议 由人点击确认
受控写入 创建临时分支、更新草稿文档、本地脚本 低风险、可回滚、有审计

权限表：

能力 默认策略 说明
读代码、读文档 允许 注意私有仓库和敏感目录
跑测试、跑构建 允许 加上超时和资源限制
写本地文件 条件允许 尽量在分支或 worktree 里
发 PR 人工确认 PR 描述要带验证证据
访问 Slack / 邮箱 先只读 防止误发、泄露、prompt injection
改生产配置 默认禁止 走审批和审计
使用登录态操作网页 高风险 只在隔离账号和明确 allowlist 下试

接入真实系统前先写 5 行威胁模型：

这部分看起来不如”多开 Agent”酷，但团队后面能不能用起来，很多时候就卡在这里。

八、PR 模板 = 验证证据前置

Kaxil Naik：Agent 让他几个月没有手写代码，但工作并没变轻松。少了敲代码，多了方向、判断、review 和调试 Agent 失败。

两个现实问题：

PR 模板（必带 7 项）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

## 目标
这次 PR 解决什么问题。

## 改动范围
改了哪些模块，哪些明确没动。

## 验证证据
- 命令：
- 结果：
- 截图 / 日志：

## 风险
- 未覆盖：
- 需要人工确认：

没有这份证据，PR 很容易只是把工作从”写代码”转移到了”猜它有没有做对”。

7 天小试点（可借鉴实验）

天 动作
1 选任务（中等复杂度 + 风险低 + 复现路径明确）
2 写最小 plan.md（目标/不做什么/涉及文件/验收标准/验证命令）
3 只补一小段 CLAUDE.md（当前任务用得上的 Domain + Validation）
4 Agent 在隔离环境实现（独立分支/worktree + 每步留证据）
5 认真做一次人工 review（看 diff / 看测试 / 标静默失败）
6 把失败写回 gotchas（能变命令的先变命令，能变 hook 的接 hook）
7 看 4 问（重复劳动 / 验证 / review 成本 / 复用）+ 5 指标

5 个朴素指标：返工次数 / 验证遗漏 / 上下文污染 / 合并耗时 / 经验沉淀

5 个最小行动（行动笔记）

  1. 计划文件：复杂任务留一个文件出口，不只停在聊天里
  2. CLAUDE.md：项目是什么、领域边界是什么、怎么证明做完
  3. 验证 Skill：把团队最容易漏掉的验证流程写成 Skill
  4. hooks：第一版能挡一类危险命令 + 整理一类失败日志
  5. Subagents：能独立探索 / 独立验证 / 只返回高密度结果的任务才拆

关键术语索引

写作引用建议