架构师（JiaGouX）我们都是架构师！架构未来，你来不来？
这两天读了两篇很有现场感的内容。
一篇是 Matt Van Horn 写的《Every Agentic Engineering Hack I Know》。他把自己到 2026 年 6 月为止的 Agentic Engineering 用法摊开了：Claude Code、Codex、语音输入、多会话、plan.md、last30days、远程控制、真实服务 CLI，全都放在同一套日常工作流里。
另一篇来自 John Kim 的 Claude Code 50 条使用经验。他是 Meta 的 Staff Engineer，讲的也不是”神奇提示词”，而是根目录启动、CLAUDE.md、Plan mode、/context、MCP、Skills、Subagents、worktrees、hooks 这些很工程化的细节。
我读的时候，脑子里一直有个画面：Agent 面前摆着一张工作台。
左边是计划，右边是上下文，后面接着测试、日志、权限和回滚。靠一句神奇提示词当然不够，它需要在一个被人整理过的现场里工作。
这些东西单独看都不新鲜。plan.md 像任务说明，CLAUDE.md 像项目备忘，hooks 像自动检查，Subagents 像分工。
但放在 Agentic Engineering 里，它们突然有了另一层味道：我们平时靠经验做的很多判断，开始有机会沉到工具和流程里。
说得朴素一点，工作台搭得越清楚，Agent 干活越有边界。
plan.md、Plan mode、Dynamic Workflows 这些东西，表面上是在写文档，实际是在给复杂任务留下目标、边界和停止条件。CLAUDE.md、历史计划、会议记录、搜索工具、笔记库，价值不在于堆上下文，而在于让 Agent 在需要时拿到合适的信息。| 层 | 最小交付物 | 用来解决什么 |
|---|---|---|
| 计划 | plan.md、验收勾选项 |
防止任务跑偏、提前收工 |
| 上下文 | CLAUDE.md、任务资料包 |
防止靠聊天记忆硬撑 |
| 执行 | worktree、Skills、Subagents | 防止并行互相污染 |
| 验证 | 测试、日志、截图、trace、PR 说明 | 防止”看起来做完了” |
| 治理 | allowlist、hooks、权限表、回滚点 | 防止把个人 YOLO 带进团队 |
现在很多人一看到 Agentic Engineering，第一反应会是”并行”。
Matt 的日常确实是这样：他会同时开几个 cmux 会话，一个在跑 /ce-plan，一个在用 /ce-work 执行，另一个在跑 last30days 做最近 30 天的社区调研，还有一个处理刚测试出来的问题。
John Kim 也讲并行：多个 Claude Code 实例、iTerm 分屏、Git worktrees、通知提示，让一个任务等待时，人能切到另一个任务继续推进。
这些做法确实很诱人。但如果直接照着来，团队里很容易先撞上三个问题：
所以我现在会把”多开 Agent”放到稍微后面一点。在并行之前，我更关心四个字：可控并行。
所谓可控，至少要把这几件事说清楚：
| 问题 | 可以先想什么 |
|---|---|
| 任务怎么拆 | 哪些能独立执行，哪些需要留在主线里 |
| 工作区怎么隔离 | 用 worktree、临时分支，还是只读探索 |
| 结果怎么验 | 每个子任务交什么证据 |
| 冲突怎么收 | 谁合并，谁 review，谁决定丢弃 |
| 错了怎么退 | 能不能回滚到任务开始前 |
这里可以加一张很小的”任务卡”。每开一个 Agent，会话前先写清：
1
2
3
4
5
6
任务：修复订单导出超时
工作区：worktree/order-export-timeout
边界：只改导出链路，不动权限模型
输入：issue 链接、报错日志、最近一次慢查询
交付：diff、测试命令、关键日志、剩余风险
合并：主会话 review 后再合入
这不是为了显得正式。它的价值很实际：当 4 到 6 个会话同时跑时，人还能知道每个窗口到底在做什么。
这也是我们之前写 worktree 时反复提到的：并行和协作不是一回事。 worktree 解决的是物理隔离，验收、评审和合并，还得另外设计。
Matt 的工作流里，最靠前的动作是先生成 plan.md。
他几乎所有事情都从 /ce-plan 开始：产品想法、GitHub issue、终端报错、截图、设计稿、Slack 讨论，都可以先变成计划。
这件事一开始容易被误解成”多写一份文档”。但放到 Agent 场景里，计划的意义会变。它不只是说明”我要做什么”，还在给后面的执行、验证和接手留一个位置。
Matt 的实践里有个细节我觉得很值得借鉴：/ce-plan 不是写一份通用计划，而是会先读代码库，找已有模式、约定和历史经验，再写出包含验收标准的 plan.md。这一步如果做扎实，后面的 Agent 就不太容易写出”语法对、风格错、边界乱”的代码。
一个够用的计划，大概会回答这些问题：
这里我最在意的是后两条。Agent 做长任务时，一个常见问题是提前收工。它修了几个明显问题，跑了一个看起来还行的检查，然后自然进入总结状态。它不一定是在偷懒。很多时候，是我们没有把”完成条件”写清楚。
所以如果在团队里试，我会先把 plan.md 当成一个轻量任务协议，而不是项目管理文档。可以先用很简单的结构：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# plan.md
## 目标
这次要解决什么问题。
## 不做什么
明确排除哪些范围，防止 Agent 顺手扩大任务。
## 背景和输入
issue、截图、报错、用户反馈、相关链接。
## 可能涉及的文件
先列线索，一开始不必完全准确。
## 实施步骤
按可验证的小步拆。
## 验收标准
什么结果算完成。
## 验证命令
测试、构建、lint、截图、日志检查。
## 当前状态
已做、未做、阻塞、下一步。
如果想再专业一点，我会补两个小节：
1
2
3
4
5
6
7
8
9
## 证据要求
- 哪些命令要跑；
- 需要截图还是日志；
- 哪些失败可以接受，哪些失败需要停下。
## 合并条件
- 谁 review；
- PR 需要带哪些说明；
- 哪些风险需要人工确认。
这个文件不是写给老板看的，也不只是写给人看的。它同时给 Agent、reviewer、下一个会话和未来的自己看。
两个大佬的做法里，还有一个共同点：他们都很重视上下文。
Matt 的做法更激进。会议录音不先总结，直接把 Granola 的原始 transcript 给 Agent；选技术方案前，先跑 last30days，把 Reddit、X、YouTube、HN、GitHub 和网页讨论拉回来；历史计划、笔记、会议记录，也都让 Agent 能读。
John Kim 的提醒则克制很多。CLAUDE.md 容易越写越厚；MCP 装多了会带来额外噪音；/context 要经常看 token 花在哪里；任务结束后，干净地 /clear 也很重要。
这两种做法看起来方向相反，其实可以合到一起：上下文不是越多越好，更重要的是放对位置。
如果放到团队里，我会先粗粗分成五层：
| 层级 | 放什么 | 典型载体 |
|---|---|---|
| 当前窗口 | 当前目标、约束、最近观察、下一步决策 | 对话上下文 |
| 项目规则 | 架构边界、编码约定、禁止事项、验证方式 | CLAUDE.md、rules |
| 任务状态 | 计划、已做事项、阻塞、证据 | plan.md、todo、issue |
| 历史资料 | 会议、旧方案、事故、决策记录 | Obsidian、Bear、Docs、搜索工具 |
| 结果 | 测试、日志、截图、trace、线上状态 | CLI、MCP、hooks |
上下文工程难的地方，不是把所有东西塞进模型窗口。更费心的是判断：这一轮推理到底用得上什么，哪些留在文件里，哪些按需检索，哪些只要摘要，哪些值得完整展开。
Simon Willison 写 context engineering 时提到，这个说法比 prompt engineering 更接近问题本身。很多时候，有用的不是那几句漂亮提示词，而是把任务所需的信息组织到模型有可能解决的程度。
放到工程团队里，这件事会非常具体。比如 CLAUDE.md，我现在不会把它写成大而全的百科。一个很小的版本，可以只保留三段：
1
2
3
4
5
6
7
8
## What
项目做什么，主要技术栈是什么，关键运行方式是什么。
## Domain
最容易误解的业务概念、数据边界、目录职责。
## Validation
改完以后怎么证明：测试命令、构建命令、截图方式、日志位置、回归样例。
其中最值得花时间的是 Validation。Agent 往往不缺生成能力，缺的是知道在你们系统里，什么才算真的做完。
我现在会把上下文载入分成三档：
| 档位 | 怎么给 | 适合什么 |
|---|---|---|
| 直接放进窗口 | 当前目标、约束、最近错误、关键 diff | 这一轮马上要推理 |
| 放文件让 Agent 读 | plan.md、CLAUDE.md、运行说明、设计记录 |
任务过程中多次用到 |
| 放外部检索 | 会议全文、历史事故、社区讨论、旧 PR | 只在需要时查 |
这个分层能帮团队避免两个极端：一边是窗口里塞满资料，模型开始抓不住重点；另一边是只给一句需求，Agent 只能凭训练记忆猜。
很多人第一次看到 Skills，会把它理解成”高级提示词”。这个理解可以入门，但往下走会不够用。
Matt 的经验里，任何重复超过两次的事情，都值得变成 Skill。Kaxil Naik 那篇长文说得更重：他花了大量时间迭代 skills、hooks、CLI、MCP 和集成，让 Agent 按自己的工程习惯工作。
Addy Osmani 在《Agent Skills》里也讲到一个我很认同的点：高级工程师很多工作不体现在 diff 里。规格、测试、评审、范围控制、拒绝发布无法验证的东西，这些才是交付质量的一部分。
所以我更愿意把 Skill 看成过程资产，而不只是提示词。
我读 Addy 那篇时，最受用的是这个区分：Skill 不是一篇”最佳实践文档”，而是一段可执行流程。
文档会说”注意测试质量”。流程会说”先写失败用例，跑一次确认失败，再写最小实现，跑测试，最后输出证据”。前者容易被 Agent 读完就忘，后者会把它推到下一步。
一个可用的 Skill，只写”请认真测试”往往不够。我会尽量补上这些东西：
如果一开始不知道写什么，我会先写一个验证类 Skill。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
---
name: api-change-verification
description: 当修改 API、DTO、权限逻辑或调用链时，用这个 Skill 验证兼容性和回归风险。
---
# API Change Verification
## 先读
- OpenAPI schema
- 相关 controller / route
- 调用方列表
- 最近一次相关事故记录
## 检查项
1. 跑契约测试。
2. 跑受影响模块单测。
3. 检查调用方字段兼容性。
4. 如果涉及权限，跑权限回归样例。
## 输出证据
- 改了哪些接口
- 跑了哪些命令
- 哪些通过，哪些失败
- 仍需人工确认的风险
## Gotchas
- 200 不代表业务成功，要看 body.code
- 老客户端可能还在传 legacy_id
hooks 是另一层。如果 Skill 是”这类事该怎么做”，hooks 更像”做到某一步时，系统自动插手一下”。
Claude Code 官方文档里，hooks 可以挂在 PreToolUse、PostToolUse、Stop、SubagentStart、PreCompact 等事件上。我理解 hooks 的价值，可以先从两个很实际的入口看：
如果把 Skills 和 hooks 放在一起看，分工会更清楚：
| 机制 | 更适合做什么 | 不适合做什么 | |
|---|---|---|---|
| Skill | 描述流程、检查清单、输出证据 | 强制阻断危险动作 | |
| hook | 拦截命令、补日志、提醒验证 | 承载复杂推理 | |
| Subagent | 隔离搜索、审计、评审 | 上下文处理 | |
| 强协同实现 | plugin | 打包团队能力 | 代替权限治理 |
第一版可以很小。能拦住一类危险命令，能把一类失败变成 Agent 看得懂的上下文，就已经能减少不少返工。
Subagents 很容易被讲成”多几个角色”。比如 reviewer agent、research agent、security agent、test agent。
这些名字当然有帮助，但我更在意的还是隔离。一个子任务如果会产生大量低密度上下文，比如搜索、扫日志、读很多文件、对比多个方案，放到 subagent 里会清爽很多。主会话不用背完整过程，只拿回高密度结果：
这和 Claude Code 官方文档里的定位也能对上：自定义 subagent 适合专门任务、上下文隔离和工具权限隔离。
我会优先考虑把这些任务拆出去：
反过来，如果一个任务需要频繁协商、共享大量中间状态，或者实现和规划强耦合，就不一定适合拆成多个 subagents。
多 Agent 麻烦的地方，通常不在”谁扮演什么专家”，更多在结果怎么合并、证据怎么保留、失败怎么回到流程里。
Matt 那套工作台里，最让我警醒的一层，是他把 Agent 接进了真实世界。
邮箱入口可以开新任务，远程控制可以在手机上接管家里 Mac 的会话，Printing Press 把各种网页服务包装成 CLI，Agent Cookie 让 CLI 带着真实浏览器登录态去操作服务。
这让我意识到，Agent 正在从”代码助手”变成”执行层”。
它不只是改文件，也开始读邮件、查日历、搜 Slack、操作网页、拉会议记录、跑内部工具。
这很强，也确实有风险。对个人工作台，风险偏好可以自己承担。放到团队里，我会保守得多。
如果团队也想往这个方向试，我会把节奏放慢，先分成三层：
第一层，只读。 让 Agent 能读 issue、日志、文档、监控、测试结果、会议记录，但先不写生产系统，不发消息，不改配置。
第二层，半自动。 Agent 可以生成草稿、命令、PR、变更单、回复建议，但由人点击确认。
第三层，受控写入。 低风险、可回滚、有审计的动作，可以再考虑让 Agent 直接执行。比如创建临时分支、更新草稿文档、跑只影响本地环境的脚本。
这里可以放一张很朴素的权限表：
| 能力 | 默认策略 | 说明 |
|---|---|---|
| 读代码、读文档 | 允许 | 注意私有仓库和敏感目录 |
| 跑测试、跑构建 | 允许 | 加上超时和资源限制 |
| 写本地文件 | 条件允许 | 尽量在分支或 worktree 里 |
| 发 PR | 人工确认 | PR 描述要带验证证据 |
| 访问 Slack / 邮箱 | 先只读 | 防止误发、泄露、prompt injection |
| 改生产配置 | 默认禁止 | 走审批和审计 |
| 使用登录态操作网页 | 高风险 | 只在隔离账号和明确 allowlist 下试 |
这里还可以加一条团队规则：凡是接入 Slack、邮箱、浏览器登录态、内部后台这类真实系统，先写威胁模型，再写自动化。不必很重，几行就够：
这部分看起来不如”多开 Agent”酷，但团队后面能不能用起来，很多时候就卡在这里。
Kaxil Naik 的长文里，有一段我读完后印象很深。
他说，Agent 让他几个月没有手写代码，但工作并没有变轻松。变化是：少了敲代码，多了方向、判断、review 和调试 Agent 失败。
他还提到两个很现实的问题。
第一个，代码生成几乎免费以后，review 变成瓶颈。 AI 生成的 PR 会越来越多，但每一行 review 成本没有消失。你 approve 了一行，就要在这个项目生命周期里为它负责。
第二个，Agent 会静默失败。 错误代码有时会报错，错误的 Agent 输出经常看起来很合理。它可能改错方向，写出没有测到关键逻辑的测试，或者生成一个读 diff 之前看不出问题的修复。
这也是我读完后很有共鸣的一点：验证证据跟着 PR 一起出现，会让后面的 review 轻松很多。
以后让 Agent 提 PR，我会希望同时看到这些东西：
可以直接做成 PR 模板：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
## 目标
这次 PR 解决什么问题。
## 改动范围
改了哪些模块，哪些明确没动。
## 验证证据
- 命令：
- 结果：
- 截图 / 日志：
## 风险
- 未覆盖：
- 需要人工确认：
没有这份证据，PR 很容易只是把工作从”写代码”转移到了”猜它有没有做对”。
如果团队也想试，我会先把目标放小一点，不急着复刻 Matt 的整套个人工作台。一个更容易开始的办法，是选一个边界清楚的小流程，连续跑一周。
比如”中等复杂度 bug 修复”。
目标先不设成”让 Agent 全自动修完所有问题”。我更想观察的是，这套工作台能否稳定留下计划、证据和经验。
plan.md。 目标 / 不做什么 / 涉及文件 / 验收标准 / 验证命令。CLAUDE.md。 只补当前任务用得上的 Domain 和 Validation；不必写成长篇项目百科；每条规则尽量对应一次真实失败或真实约束。如果想让复盘更可比较，可以再加几个很朴素的指标：
| 指标 | 记录方式 |
|---|---|
| 返工次数 | review 后要求 Agent 重做几次 |
| 验证遗漏 | 哪些错误是人工才发现的 |
| 上下文污染 | Agent 是否引用了过期目标或错误文件 |
| 合并耗时 | 从 PR 生成到可合并用了多久 |
| 经验沉淀 | 新增了几条 gotchas、Skill 或 hook |
如果四个问题都答不上来，我会先不急着加 MCP、Subagents 和插件。计划、验证和 review 这三件事能稳定留下来，就已经值得继续往下试。
落到自己手上，我会先留这五个动作：
CLAUDE.md。项目是什么，领域边界是什么，怎么证明做完。这三件事通常比”请保持代码优雅”更有用。Matt 最后一节提到，Agent 很容易让人上瘾。这话挺真实。
反馈太快了。你说一句，它长出来一点；你再改一句，它又变好一点。以前一天只能推进一两件事，现在十几个窗口都在动，很容易产生一种”我正在掌控一切”的错觉。
但工程里有个老规律：吞吐一上来，瓶颈一定会换地方。 以前很多时间花在写。现在更多时间会花在想清楚、拆清楚、验清楚、审清楚。再往后，瓶颈会到组织里：谁能给 Agent 权限，谁能审核它的输出，谁能维护那些 Skills，谁能判断一个自动化流程已经变成技术债。
所以我读完这些内容，最想带走的并不是某个命令。我更想记住的是一个很朴素的方向：把平时相信、也经常执行的工程习惯，慢慢写进工作台。
计划留得下来，上下文找得到，验证跑得起来，权限边界说得清，失败经验下次还能用。
Agent 会越来越能干。但团队能不能用好 Agent，最后可能还是看这些老东西：边界、证据、责任和持续维护。