让 Coding Agent 写出一段能运行的代码，已经不难。真正麻烦的是后半段：它是否理解你要解决的产品问题，是否改坏了旁边的逻辑，是否在接近真实用户的环境里跑过，是否留下了可以审查的证据，合并前有没有跟主分支冲突。

这几个问题没有一个能靠”换一个更强的模型”自动消失。模型负责提出和执行下一步，工程流程负责限制它能做什么、告诉它怎样算完成、在出错时把它拉回来。没有流程，Agent 很像一个速度很快的实习生：会产出很多东西，也会让你不敢离开屏幕。

Kun Chen 在视频 L8 Principal’s Agentic Engineering Workflow 里给出了一套很完整的个人实践：用终端管理多个会话，用全局和项目级记忆给 Agent 入职，用技能按需加载规则，用可交互的工件讨论方案，用验证管线把首次实现推向可审查的 PR，再用 worktree、长任务和一个协调层扩展并行工作。

这篇文章不要求你购买视频里出现的工具，也不要求你使用 tmux、Neovim 或 Claude Code。它们是作者的一套具体实现。本文关心的是其中可迁移的工程结构：怎样把一次”帮我实现这个功能”的对话，变成可计划、可验证、可恢复、可并行的交付过程。

封面图取自原视频公开缩略图。文中对具体开源工具的能力，以其公开项目页面为准；视频里的速度、成本和个人产能数据属于演讲者的经验陈述，不把它当成普遍保证。

读完后，你应该能做到这些事：

1. 为自己的项目写出不臃肿的 Agent 记忆文件；
2. 区分常驻规则和按需技能，避免把所有说明塞进每次请求；
3. 用”意图、验收条件、风险边界”发起任务，别只给一句模糊需求；
4. 为 Agent 的改动建立独立验证、证据和人工决策点；
5. 用 Git worktree 安全地并行推进多个任务；
6. 判断一件事能否交给长时间运行的 Agent，以及该在什么地方停下来让人确认；
7. 搭一个不依赖特定厂商的最小 Agentic Engineering Workflow。

Agentic Engineering：交付闭环里的分工变化

传统开发的重心放在实现上。需求来了，工程师读代码、设计方案、修改、测试、提 PR。Coding Agent 出现后，实现的速度突然变快，但需求澄清、风险判断和验收并没有自动变快。很多人的体验于是变成：AI 一小时写了五个改动，我花两小时看 diff、回滚和补测试。

Agentic Engineering 要解决的范围比”让 Agent 少写错一点”更大。它重新划分分工：

这张表里最容易被忽略的是第三行。没有工作流时，人必须亲自充当调度器、记忆库、测试员和事故处理人。Agent 数量一多，人的注意力反而先耗尽。

可以把一次工程任务写成下面这个闭环：

  flowchart LR
  A["意图\n用户问题与业务目标"] --> B["规划\n选项、范围、验收标准"]
  B --> C["实现\n受限工具与独立分支"]
  C --> D["验证\n测试、审查、运行证据"]
  D --> E{"满足验收条件?"}
  E -->|否| F["带着证据修正\n或请求人工决策"]
  F --> C
  E -->|是| G["交付\nPR、文档、风险说明"]
  G --> H["反馈写回记忆\n减少下一次重复失误"]
  H --> A
  

注意最后那条从交付回到意图的线。项目如果没有把上一次纠正沉淀成下一次能加载的规则，Agent 就会在同一处反复出错。

工作台只是外壳：为什么视频从终端、tmux 和编辑器讲起

视频一开始花了不少时间介绍 WezTerm、tmux 和 Neovim。初学者很容易误会，以为 Agentic Engineering 的门票是先把终端配得很炫。不是。

作者使用终端的理由有两条：手尽量不离开键盘，以及同一个会话能在不同设备继续。tmux 的价值在于会话持久化和多任务可见性。一个 pane 可以运行 Agent，一个 pane 看日志，另一个 pane 留给人执行命令；断开后再连回去，工作状态仍在。这个模式对多会话很顺手。

但这些只是”降低切换摩擦”的方式。你用 VS Code、JetBrains、Cursor、浏览器还是终端，都可以采用同一条原则：

1

人需要随时看见：哪些任务正在跑、每个任务在哪个仓库副本里、它在等什么、失败后谁负责处理。

如果工具界面不能让你回答这四个问题，就算它有再多动画和面板，也不适合管理长任务。反过来，哪怕只是一个命名清楚的终端 tab、一张任务表和 Git 分支列表，也足够起步。

Agent harness 是什么，为什么不该把流程绑死在一个产品上

视频把 Claude Code、Codex CLI、Pi 和 OpenCode 叫作 agent harness。你可以把 harness 理解成”把模型、工具、终端、权限、会话历史接到一起的运行环境”。不同 harness 的命令、默认提示词、工具集和交互界面不同，但它们都要解决同一件事：模型提出操作请求后，谁来真正执行，谁来把结果送回去。

你的工程流程应尽量放在仓库和 Git 里，而不是只藏在某个客户端的设置里。下面这些东西换 Agent 后仍然有用：

• 项目说明、目录约定和常用验证命令；
• 测试脚本、lint、构建和 CI；
• 分支策略、worktree 使用规则和 PR 模板；
• 任务的验收标准与风险分类；
• 可以给任何 Agent 阅读的技能文件或操作手册。

某个工具的专用命令可以提高便利性，但不该成为唯一的真相来源。否则一换模型或团队成员，流程就失效了。

第一层：用记忆给新 Agent 入职

每启动一个新会话，Agent 都像一个刚加入项目的人。它不认识仓库约定，不知道你讨厌什么写法，也不知道”修复登录问题”在这个项目里必须跑浏览器端到端测试。你当然可以每次在提示词里重复说明，但很快会烦，也容易遗漏。

视频把记忆分成全局和项目两层，这个分法非常实用。

全局记忆：少而稳定，所有项目都要遵守

全局记忆是每个 Agent 会话都会加载的内容。它适合放你的通用偏好和安全底线，例如：

1
2
3
4
5
6
7

# 我的全局 Agent 约定

- 回答和 PR 描述使用简洁中文，不使用长破折号。
- 执行会修改远端、删除文件、发送网络请求的动作前，先说明影响并请求确认。
- 做 Bug 修复时，先写出可复现步骤，再讨论修复方案。
- 技术方案不要因为"开发工作量看起来大"而自动选择临时补丁；说明维护成本和回滚路径。
- 测试失败时，报告命令、退出码和最短的关键日志，不要只说"测试没过"。

它的特点是短。因为它每次都跟着请求走，写 500 行”人生信条”会变成一笔固定 Token 税，也会让重要规则淹没在里面。视频里作者的全局文件只有几十行，原因就在这里。

全局记忆也不该放项目细节。比如某个仓库的数据库端口、某条 npm 命令、某个组件的历史包袱，对其他项目没有帮助，反而会让所有会话带着无关信息。

项目记忆：只记录会反复改变决策的事实

项目级记忆可以更具体，但也不是 README 的副本。它应该回答一位新 Agent 真正会问的问题：这是个什么项目，改动通常落在哪里，哪些概念容易混淆，怎样验证，哪些规则踩过坑。

一个可直接改用的最小模板如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 项目工作说明

## 产品与边界
- 这是面向管理员的库存后台。普通用户路径不在本仓库维护。
- 价格和库存的最终事实来自 inventory-service，前端不能自行计算后写回。

## 目录地图
- apps/web：Next.js 前端
- services/inventory：库存 API
- packages/ui：共享组件，改动会影响多个应用

## 常用验证
- 单元测试：pnpm test
- 前端端到端测试：pnpm --filter web e2e
- 类型检查：pnpm typecheck

## 容易犯错的地方
- 修改库存接口时，同步更新 packages/contracts 中的 schema。
- Playwright 测试必须使用 test inventory，不连接开发数据库。
- 不要编辑 generated/ 下的文件，它们由代码生成步骤覆盖。

这份文件最好来自真实的失败记录。视频里的做法是，每次发现 Agent 重复犯错，就纠正它，并把”以后在什么条件下该怎么做”写入项目记忆。这个循环很朴素，却比所谓”自动长期记忆”可靠得多：你能看到每条规则，能 review，能删掉过期内容，也能随代码一同提交。

记忆腐化：规则越多，Agent 不一定越聪明

项目运行久了，记忆文件会不断膨胀。常见症状有三个。

第一，规则互相矛盾。去年写”所有接口错误都返回 200”，今年网关已经统一改为 4xx/5xx。

第二，内容太具体。某次事故的完整日志被原样贴进去，之后每个会话都要阅读它。

第三，规则没有触发条件。”如何跑端到端测试”对纯代码阅读没有任何价值，却每次加载。

处理方式不是立刻引入复杂的向量数据库。先做两件小事：每月删掉无法解释价值的条目；把只在某类任务中需要的操作说明迁到技能。下一节会讲这个边界。

第二层：技能是按需加载的操作手册，不是提示词插件市场

记忆和技能都在给 Agent 提供知识，但加载方式不同。

记忆像员工手册首页，打开工位就看得到。技能像”发布流程”、”浏览器测试”、”数据库迁移”这些操作手册，只有任务需要时才打开。视频把这种做法称为 progressive disclosure：启动时只让 Agent 知道有哪些技能及其简短描述，选中某个技能后才读详细内容。

这能解决两个问题。

一是省 Token。端到端测试说明可能有两百行，用户只是问”这个组件在哪里定义”，就不必加载。

二是让规则有明确的适用范围。比如”修改 UI 后如何录制证据”属于 verify-ui-change 技能，不会误导数据库迁移任务。

一个合格技能要写清触发时机、输入、步骤、产物和停止条件。下面是一个端到端验证技能的骨架：

1
2
3
4
5
6
7
8
9
10
11

---
name: verify-ui-change
description: 当任务修改用户可见界面、交互或导航时使用。运行端到端测试并保存可审查的证据。
---

1. 从任务描述中提取用户路径和预期结果。
2. 使用 test inventory 启动本地服务，不访问生产环境。
3. 运行对应的 Playwright 场景；若场景不存在，先说明缺口并补最小测试。
4. 保存截图或视频到 artifacts/<task-id>/。
5. 返回执行命令、结果、证据路径、已知限制。
6. 若涉及付款、真实用户数据或外部发送操作，停止并请求人工确认。

这比”写高质量前端代码并充分测试”有用得多，因为后者没有定义 Agent 该做什么，也没有定义人如何检查它真的做了。

为什么热门技能也可能让 Agent 变差

视频里有一个很值得保留的提醒：GitHub Star 是传播度，不是评测结果。一个技能可能让 Agent 调用更多工具、加载更多上下文、执行不必要的仪式，最后消耗更多 Token，成功率反而下降。

更严重的是安全边界。技能文件本质上是对 Agent 的指令，而 Agent 往往有读文件、运行命令、访问网络的能力。你从互联网装进来的技能，可能要求它读取凭据、上传日志、关闭权限提示，或者引入你没审过的安装脚本。

安装第三方技能前，至少做一次这样的检查：

先在一个没有密钥、没有生产凭据的临时仓库试跑，比直接装进日常开发环境安全得多。技能的正确使用方式是少量、可审、能解释，而不是囤积。

第三层：工具也需要为 Agent 设计

视频把这件事叫作 Agent ergonomics。人用起来顺手的工具，不一定适合 Agent。人可以从一大页网页里凭视觉挑出需要的信息，也能从含糊的报错里猜下一步。Agent 看到的通常是文本、结构化结果和工具 schema。输出太长、字段太多、分页规则不清、错误信息没有动作建议，都会增加调用轮次和上下文噪声。

这不是说 MCP、CLI、网页自动化中哪一种天然更好。真正该问的是：某个接口是否把当前任务最需要的信息，用稳定且足够小的形式交出来。

假设 Agent 要找”最近 30 天由我负责、还没有关闭的 bug”。下面两种工具设计，给它的工作量完全不同：

1
2
3
4
5
6
7

差的接口：
get_everything()
  -> 返回所有项目、所有 issue、所有评论、完整用户资料和 HTML 片段

好的接口：
list_issues(owner, state, assignee, labels, since, limit, cursor)
  -> 返回编号、标题、标签、更新时间、下一页游标

前者把筛选责任和大量无关数据交给模型。后者让程序完成确定性筛选，Agent 只做需要判断的部分。工具越接近后者，Agent 越容易成功，也越容易控制成本。

判断一个工具是否适合 Agent 的六个问题

这张表对你自己写的脚本同样适用。许多团队把 bash 当万能工具，然后让 Agent 拼接复杂命令、解析彩色终端输出、从几十个文件里猜状态。给它一个小而明确的命令，往往更省事。

例如，不要只提供 deploy --all。至少拆出 deploy status、deploy plan、deploy apply --environment staging 和 deploy rollback <release>，让读取、预览、执行和回滚成为不同动作。Agent 才能在每一步把证据带回上下文，也能在高风险动作前停下来。

视频中 AXI 的主张是把工具接口当作 Agent 的一等用户。你不必采用它的具体格式或数字结论，但可以拿上面的六个问题审查自己的工具链。很多时候，减少一次无用工具调用，比写长一页提示词更有效。

第四层：规划必须产出可讨论的东西，不能只留一堵文字墙

复杂任务常在”开始编码之前”就走偏。用户说”把个人中心做得更有成长感”，这句话包含产品目标，却没有告诉你页面结构、奖励节奏、信息优先级、哪些现有行为不能动。Agent 如果直接开始写，通常会把自己的猜测当需求实现出来。

视频中的 Lavish 用 HTML 工件把选项画出来，并允许在具体区域批注。你不需要使用同一个工具，也能采用这个思路：计划阶段的产物应该能被人指着讨论。

对于不同任务，工件可以是不同形态：

工件化规划有一个很实际的好处：反馈会指向具体对象。你不必对 Agent 说”第三段方案不太对”，而可以在原型里的按钮旁边写”这里保留原入口，不要合并”。这种反馈短、准确，也不容易在多轮对话里丢失。

一个功能开始前，至少要回答五个问题

无论计划是图还是文字，进入实现前请让 Agent 给出下面五项：

1
2
3
4
5

1. 要解决的用户问题是什么？不要把方案当问题。
2. 哪些已有行为必须保持不变？
3. 什么证据能证明改动有效？测试、截图、指标还是人工体验？
4. 哪些决定仍需要人来选？例如文案、产品策略、隐私边界。
5. 失败后怎样回滚，或者怎样让改动不影响主分支？

如果其中任何一项仍然模糊，继续讨论比立刻让 Agent 写代码便宜。AI 让实现变快后，返工的代价也更容易被低估。你可能五分钟就能生成一个页面，但花半天才发现页面解决错了问题。

第五层：验证必须留下证据

视频里我最认同的一段，是验证管线。多开 Agent 和语音输入都只是效率工具，验证决定了你能否放心交付。

当 Agent 说”完成了”，它表达的是一个判断，不是事实。它可能跑过单元测试，也可能只读了一遍 diff 后自信地收尾。你需要另一条独立链路：用任务意图检查改动，用接近用户的方式运行产品，保存能回看的证据，再由人决定高风险部分是否接受。

Kun Chen 的 no-mistakes 项目把这种思路做成了 Git 前置关卡。它会在独立 worktree 中运行审查、测试、文档、lint、推送、PR 与 CI 相关步骤；安全的机械修复可自动应用，涉及产品意图的发现会升级给人。项目 README明确说明，分支只有在所有检查通过后才会转发到配置好的远端。

你不必照搬它，也应该建立同样的层次：

  flowchart TD
  A["首次实现\nAgent 修改代码"] --> B["冻结任务意图\n本次到底要改变什么"]
  B --> C["隔离验证环境\nbranch 或 worktree"]
  C --> D["独立审查\n寻找边界、回归和遗漏"]
  D --> E["执行验证\n单元、集成、端到端"]
  E --> F["保存证据\n日志、截图、视频、指标"]
  F --> G["更新文档与静态检查"]
  G --> H{"风险是否需要人判断?"}
  H -->|是| I["人审查意图与证据\n批准、修改或拒绝"]
  H -->|否| J["创建或更新 PR"]
  I --> J
  

单元测试不能独自代表”用户能用”

视频强调 Bug 修复尽量从端到端复现开始。这个观点很重要。单元测试擅长证明一个函数在给定输入下返回预期输出，却不一定能证明用户从页面点击到最终结果的路径正确。认证状态、路由跳转、缓存、浏览器权限、后端配置常常藏在函数之间。

一个简单的验证层级可以这样理解：

不是每一次小改动都要跑完五层。但你要能说明为什么这个改动只需要前两层，为什么另一个涉及登录、支付或数据写入的改动必须有端到端证据。风险越高，验证越该接近真实使用。

人应该审什么：从逐行 diff 转向意图和风险

“不看 diff”很容易被误解成放弃审查。更准确的说法是：人不该把全部注意力平均花在每一行自动生成代码上。

低风险、可重复、验证充分的改动，可以主要看任务摘要、测试证据和风险报告。高风险改动仍值得深入看代码，例如权限、资金、数据删除、并发控制、隐私边界、复杂迁移。人最适合做价值判断和异常判断，而不是机械地替 Agent 扫一遍格式化后的 diff。

给每个任务加一个简单风险标签就够用：

1
2
3

低风险：文案、样式、隔离组件，自动测试和截图齐全。
中风险：业务规则、共享 API、数据读写，需要人工看摘要和关键 diff。
高风险：权限、付款、删除、迁移、生产配置，必须有人批准，必要时双人复核。

风险标签不必假装精确。它把注意力从”所有改动一视同仁”转到”哪里最可能造成不可逆伤害”。

第六层：长时间运行的 Agent，先定义目标和停止条件

视频里的 gnhf 工具用于让 Agent 循环执行一项长期目标，比如以 7 岁孩子的视角使用应用，发现第一个会造成困惑的可用性问题，修复后再继续。这个模式很吸引人，因为它把人从中间执行过程里释放出来。

不过”让它跑一晚上”只适合一类任务：目标可验证，或者你愿意授权 Agent 在清晰边界内做判断。下面这张表可以帮助区分：

让 Agent 长时间运行之前，把任务写成一个”目标合同”。至少包含：

1
2
3
4
5
6
7

目标：将结算页的 LCP 从当前 3.2s 降到 2.4s 以下。
基线：保存当前 Lighthouse 报告和测试环境版本。
允许动作：只改 apps/web/checkout，允许添加测试和依赖的 lockfile 更新。
禁止动作：不改支付接口，不访问生产，不删除现有埋点。
每轮必须做：运行指定性能脚本，记录分数、改动和 git commit。
停止条件：连续 3 轮无改善；达到目标；Token 达到预算；遇到需要产品取舍的问题。
交付物：分支、提交列表、性能报告、未解决问题。

这份合同比”优化结算页性能，尽量多做一些”可靠得多。它让调度器知道何时停，也让你第二天醒来时可以判断 Agent 有没有越界。

预算不是可选项

长任务可能进入”不断尝试小改动”的循环。没有 Token 上限、迭代次数上限、超时时间和外部副作用限制，它会把昂贵的失败变成长时间的失败。

预算应当和目标一起写入。你不需要精确预测所有成本，但必须有一条明确的熔断线。例如”最多 20 次迭代或 300 万 Token，先到者停止”。停止后不代表任务失败，它只是把控制权交还给人，让你根据报告决定是否继续。

第七层：并行的单位是隔离工作区，不是一堆同时开着的聊天框

多个 Agent 在同一目录修改文件，就像几个人同时编辑同一份未保存文档。它们不知道谁先写，测试产生的临时文件也可能互相污染。即使没有 Git 冲突，彼此的未提交状态也会让结果无法解释。

Git worktree 提供了很直接的隔离：同一个仓库可以有多个工作目录，每个目录检出不同分支。Agent A 在 worktree A 改 UI，Agent B 在 worktree B 查 API 问题，互不覆盖。最后再把经过验证的分支合并回来。

最基础的命令并不复杂：

1
2
3
4
5
6
7
8

# 从当前仓库创建一个用于修复登录问题的独立工作目录
git worktree add ../app-fix-login -b agent/fix-login

# 查看有哪些 worktree、分别对应什么分支
git worktree list

# 任务完成且分支已处理后再移除目录
git worktree remove ../app-fix-login

难点在管理。视频里的 Treehouse 试图解决 worktree 的”心理债务”：目录叫什么，里面是否还有 Agent，任务结束没有，能否复用。你可以用任何工具，也可以先用一个 WORKTREES.md 或任务看板记录这些信息。

每个并行任务至少应该有一条记录：

有了这条记录，十个并行任务也不会全塞进你的短期记忆。没有它，三个 tab 就足够让人忘记”这个窗口到底在干什么”。

并行前先看依赖图

并行并不总是更快。两个任务如果都修改同一份 API schema，拆成两个 worktree 也不能消除最后的合并和契约冲突。此时应先写出依赖关系：

1
2
3
4

定义新的订单状态 schema
  ├─ 更新后端状态机
  ├─ 更新前端展示
  └─ 更新端到端测试

根任务没有确定前，后三项最多做研究，不要同时开始写入。相反，下面这种结构适合真正并行：

1
2
3
4

读取最近三个用户反馈
  ├─ 排查图片上传交互
  ├─ 排查消息状态显示
  └─ 排查语音按钮提示

它们碰不同文件，验收也可以分开，才值得分配给不同 Agent。并行的本质是隔离依赖，不是增加窗口数量。

第八层：协调者负责路由任务

视频最后的 First Mate 很像一个”总管”。它接收一个高层请求，拆分为多个仓库任务，创建 worktree，启动 Agent，等待验证管线，再把需要人的问题集中呈现。它试图消除频繁切 tab、记住每个任务上下文、手动收尾的管理负担。

这类协调层值得理解，但也最容易被神化。一个协调 Agent 不能凭空获得更好的产品判断。它要成功，依赖的是前面已经准备好的东西：项目清单、任务模板、权限边界、worktree 策略、验证管线和状态记录。没有这些，它只会更快地把模糊命令分发给更多模糊的子任务。

一个最小协调器要做的事情其实很有限：

1
2
3
4
5
6
7
8
9

收到任务
  -> 判断任务属于哪个项目
  -> 读取项目记忆和风险规则
  -> 检查能否拆分、是否有共享写入
  -> 为独立子任务分配 worktree 与分支
  -> 启动执行者，记录状态
  -> 调用验证管线
  -> 将产品选择、权限升级和高风险发现汇总给人
  -> 关闭或回收已完成的工作区

这条流程并不要求你自己造一个 First Mate。开始阶段，你可以作为协调者，手工执行前四步。等到同类任务重复出现，才把其中稳定的环节自动化。自动化应当追随你已经验证过的习惯，而不是提前替你发明习惯。

运行中的任务也需要可观测性

任务一旦超过十分钟，”正在运行”就不是足够的信息。你需要知道它做到了哪一步，卡在哪里，消耗了多少预算，是否等待你的决定。视频里 tmux 的状态栏、gnhf 的迭代次数和提交数量，都是在回答这些问题。

不必为此先搭监控平台。一个与任务放在同一处的状态文件就能解决大半问题：

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

{
  "id": "fix-login-redirect",
  "branch": "agent/fix-login-redirect",
  "worktree": "../app-fix-login",
  "phase": "e2e-verification",
  "status": "waiting-for-review",
  "startedAt": "2026-06-21T20:45:00+08:00",
  "lastEvent": "刷新页面后的登录态测试已通过",
  "budget": { "iterations": 5, "maxIterations": 12 },
  "evidence": ["artifacts/fix-login/refresh-session.webm"],
  "needsHuman": "确认 session cookie 的过期策略"
}

这里最有用的字段不是”完成百分比”，而是 phase、lastEvent 和 needsHuman。完成百分比很容易产生虚假的确定感。一个任务显示 90%，可能正卡在最需要产品判断的地方；另一个只显示 40%，却已经把难点解决了，后面只是跑测试。

给长任务加心跳和超时也很重要。若 Agent 两小时没有写入事件，不要假定它仍在认真工作。把任务标记为 stalled，保留最后日志和当前 commit，再决定是重试、缩小范围，还是让人介入。恢复任务时也不要从头开始，而是把上次的任务合同、状态文件、失败证据和 Git 状态一起交给新的执行者。

这样做的目的不是监视 Agent 的每一步。它是为了让人能在几十秒内恢复上下文，而不是重新翻聊天记录、终端滚屏和散落的临时文件。

把整套方法落到一个真实任务：修复”登录后又跳回登录页”

现在不用抽象名词，完整走一次最小闭环。假设用户反馈：输入正确密码后，会短暂进入首页，随后又跳回登录页。

1. 先写任务卡，别直接说”修一下”

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

# 任务：修复登录成功后的错误重定向

用户影响：已登录用户无法稳定进入首页。
已知现象：首次跳转成功后，页面刷新或路由守卫再次把用户送回 /login。
非目标：不改登录页面视觉样式；不调整账户权限模型。

验收条件：
- 新用户登录后进入 /home，刷新后仍保持登录状态；
- 退出登录后访问 /home 会回到 /login；
- 浏览器端到端测试覆盖两条路径；
- 不读取生产用户数据。

风险：中。涉及 cookie、session 和路由守卫的顺序。

这一步把产品意图和实现猜测分开。你没有预先断言”cookie 写入太晚”，因为那只是可能原因。

2. 用只读探索拿证据

让一个只读 Agent 找认证调用链，交付物限定为文件路径、关键函数、证据和未确认项。它可以翻日志、搜索路由和运行不写入的测试，但不能修改代码。

这样主 Agent 或人拿到的是一份短报告，而不是几百行搜索输出。比如报告可能指出：authMiddleware.ts 在 cookie 持久化前检查 session，现有端到端测试只断言点击后出现 toast，没有刷新页面。

3. 在独立 worktree 实现

创建 agent/fix-login-redirect 分支和专属 worktree。实现 Agent 的任务合同写清：只改认证和测试相关文件；先补能失败的端到端测试；不要修改生成文件；完成后返回 diff 概要与命令输出。

这里先写失败测试不是仪式。它迫使 Agent 把”错误重定向”翻译成可观察现象。测试若从未失败，后面的修复也就没有证明目标。

4. 验证管线检查不同层次

运行类型检查、认证相关单元测试、浏览器端到端测试。保存成功登录、刷新、退出登录三段操作的截图或录像。再用一个独立审查任务提问：这次修改是否会让过期 session 被错误接受？测试是否真的覆盖页面刷新？

审查者不负责重写整个功能，它只要找到边界问题。这个独立视角能避免实现者把自己的假设当成结论。

5. 人只决定该由人决定的事

如果管线发现”cookie 应设为 7 天还是会话级”这种产品和安全取舍，停止并交给人。若所有验收条件已经满足，风险说明没有新问题，提交 PR。人检查任务摘要、证据和高风险差异，不必从第一行开始阅读所有格式化改动。

这个例子没有用到任何神秘能力。它之所以可靠，是因为每一步都有输入、输出、边界和证据。

给初学者的 90 分钟落地版

别一上来就装十个插件、开五个 Agent、让它们通宵重构。先选一个有测试的小仓库，完成下面这套最小流程。

前 20 分钟：写两份记忆

创建一个全局偏好文件和一个项目说明文件。前者不超过 20 行，后者不超过 100 行。只写你能解释的规则，尤其是验证命令、禁止修改的目录、容易出错的概念和外部副作用的确认要求。

接着 20 分钟：做一个技能

不要下载陌生技能。先把项目里已有的”运行端到端测试”说明抽成一个本地技能，要求它返回命令、证据路径和失败日志。自己写一遍，你才会知道技能文件到底在给 Agent 什么权限和指令。

再用 25 分钟：建立验收模板

在仓库里新建 docs/agent-task-template.md：

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

# 任务标题

## 用户问题

## 非目标

## 验收条件

## 允许修改的范围

## 禁止事项与外部副作用

## 验证命令和证据位置

## 风险与人工决策点

下一次让 Agent 改代码时，先填它。它能大幅减少”AI 明明做了很多，却不是我想要的”的情况。

最后 25 分钟：跑一次隔离任务

用 git worktree add 创建一个专属目录，让 Agent 修一个小 Bug 或补一条端到端测试。要求它在完成时交付四项：改了什么、执行了什么、证据在哪里、还有什么不确定。然后你手工移除 worktree。整个过程跑通后，再考虑把验证和清理自动化。

这 90 分钟不会让你突然拥有”Agent 舰队”。它会让你获得一件更有用的东西：知道一个 Agent 任务从开始到结束，哪些环节需要留下可复查的痕迹。

容易把流程带偏的七种做法

1. 把模型输出当成验收结果

“已完成”只是模型的回复。没有测试、运行证据或人工确认，它不能替代验收。

2. 把全部规则塞进根提示词

每次都加载的大提示词既贵又难维护。稳定通用的放全局记忆，项目事实放项目记忆，条件流程放技能。

3. 用热门程度判断技能质量

Star、转发和截图都不是安全审计或效果评测。先看行为、权限、网络访问和可复现结果。

4. 让多个 Agent 直接写同一个目录

并发修改共享工作区会产生覆盖和无法解释的状态。用 worktree 隔离，或将共享文件的改动串行化。

5. 给长任务一个诗意但不可测的目标

“让产品更好”、”继续找问题并优化”没有终点。写指标、停止条件、预算、允许范围和交付物。

6. 自动化高风险动作，却没有人工闸门

部署、付费、删数据、权限变更、对外发送消息，都应在执行前停下来让人确认。自动化不等于放弃责任。

7. 一开始就造协调系统

如果你还没稳定地完成一次单 Agent 任务，先不要做 First Mate。先把任务卡、验证管线和 worktree 流程做顺。协调器只会放大已有流程的优点和缺点。

最后：人的瓶颈会移动，但不会消失

这套工作流承认一个事实：Agent 把实现速度提高后，人的瓶颈会从”写代码”移动到”决定什么值得做、怎样才算做好、哪些风险可以接受”。

你不需要把自己变成全天候盯着终端的调度员。相反，好的流程应该把中间的机械劳动交给 Agent，把人的时间留给用户问题、需求取舍、证据审阅和异常决策。

从一份短记忆、一个验证技能、一张任务卡和一个 worktree 开始就够了。等这些步骤能稳定重复，再扩展到并行 Agent、长任务和协调层。这样做慢一点，却能让每一次自动化都有清楚的边界。

参考资料

• Kun Chen：L8 Principal’s Agentic Engineering Workflow 视频
• Kun Chen：no-mistakes 项目
• Kun Chen：gnhf 项目
• Kun Chen：Treehouse 项目
• Kun Chen：Lavish AXI 项目
• AXI：Agent eXperience Interface