Agent 工程实践简报 · 2026-11-19

今日概念:Bottleneck / Theory of Constraints(瓶颈 / 约束理论)

是什么:一条流水线一天能产出多少,取决于最慢的那一环,不取决于最快的那一环。约束理论(Theory of Constraints)的核心就一句话:先找到瓶颈,再改善瓶颈;在非瓶颈环节提速,只会让活在瓶颈前面越堆越多。

为什么现在要懂:哈佛的 Fiona Chen 和 James Stratton 用 Jellyfish 平台的数据(655 家公司、约 72 万名工程师、4.45 亿条 GitHub/Jira/日历事件)研究 AI 编程工具的效果,论文 11-14 刚更新(工作论文,尚未经过同行评审)。结论很直接:

HN 上这篇的报道有 319 分、439 条评论。

和你已会的东西的关系:

入门原文:Theory of constraints(Wikipedia);论文 Artificial Intelligence in the Firm: Bottlenecks in Software Production(Fiona Chen、James Stratton,Harvard,2026-11-14 版);HN 讨论

上手 prompt:

目标:用这个仓库的 git 历史(如果能访问,也用 PR 数据)找出我们交付流程里真正的瓶颈,只出报告,不改任何文件。

1. 先确认数据来源:git log 一定可用;如果仓库在 GitHub 且本机有已登录的 gh,就用 gh 只读命令拉最近 90 天已合并的 PR(创建时间、首次审查时间、批准时间、合并时间、改动行数、评论数、审查人)。拿不到的字段写「无数据」,不要估。
2. 按周统计:提交数、改动行数、PR 数、PR 中位数大小,以及每个 PR 的「等审时间」(创建到首次审查)、「审查时间」(首次审查到批准)、「合并等待」(批准到合并)。
3. 找瓶颈:哪个阶段耗时中位数最长、过去 90 天增长最快?审查是否集中在少数几个人身上(列出每人审查的 PR 数占比)?大 PR 和小 PR 的等审时间差多少?
4. 给出 3 条最能缓解瓶颈的做法,按「投入小、效果大」排序,每条写清改哪里、怎么衡量是否有效。例如:把 agent 产出的改动拆成更小的 PR、在 CLAUDE.md/AGENTS.md 里要求 PR 附测试命令和输出、把审查中反复出现的意见变成 lint 或 CI 检查。
5. 验收:每个结论都附上统计用的命令和原始数字;样本少于 20 个 PR 时明确说明结论不可靠。

参考:Fiona Chen、James Stratton《Artificial Intelligence in the Firm: Bottlenecks in Software Production》https://fion.ac/jellyfish.pdf

本期条目

1. Jesse Vincent(Superpowers 作者)新出 toolsmith 插件:agent 想写临时脚本时,交给专门的「工具匠」子 agent 写成可复用的工具并登记在册,下次直接找来用

目标:评估「把 agent 写的一次性辅助脚本沉淀成可复用工具」对这个仓库值不值得做,先出报告,不安装任何东西、不改文件。

1. 在仓库里和常见临时位置(如 tmp/、scratch/、scripts/、.claude/ 下以及 git 未跟踪的文件)找出 agent 或人写过的一次性辅助脚本:日志过滤、数据转换、调 API、批量改文件等。用 git status、git log 和文件修改时间作证据,列出路径、用途、大概用了几次。
2. 把它们分成两类:(a) 项目要交付的代码(应该正式放进仓库);(b) 只是帮 agent 干活的工具(适合放进一个独立的工具目录)。每条说明判断理由。
3. 对 (b) 类,设计一个最小方案:工具放在哪里、目录说明(catalog)长什么样、在 CLAUDE.md/AGENTS.md 里加哪几行规则让 agent 先查目录再动手写。规则不超过 5 行。
4. 对比直接安装 toolsmith 插件(https://github.com/prime-radiant-inc/toolsmith )的方案:它用 SessionStart/SubagentStart hooks + 一个专门的子 agent + ~/.local/share/toolsmith/tools 下的 git 仓库。列出两种方案各自的优缺点,以及对本仓库的建议。
5. 验收:清单里每个脚本都有路径证据;方案部分给出要加的规则原文;最后给出「建议做 / 不建议做」和理由。

参考:Jesse Vincent《The Toolsmith》https://blog.primeradiant.com/the-toolsmith/

来源:The Toolsmith(Jesse Vincent,Prime Radiant,2026-11-17);prime-radiant-inc/toolsmith;Jesse 的 X 帖


2. Thorsten Ball(Amp):靠斜杠命令触发 skill 可能是个反模式,好的 skill 应该让 agent 自己在需要时找到

目标:给我的 skills(项目里的 .claude/skills、.agents/skills,以及 ~/.claude/skills 下的,先列出实际存在的位置)做一次「可发现性和必要性」体检,只出报告和修改建议,不删除、不修改任何文件。

1. 列出每个 skill:路径、name、description 原文、SKILL.md 行数,以及它是否主要靠斜杠命令手动触发(看 description 和正文里有没有「用 /xxx 调用」之类的写法)。
2. 对每个 skill 判断三件事并给理由:
   a. 可发现性:只看 description,agent 能不能在真正需要的时候想到用它?description 有没有写清「什么情况下用」?
   b. 必要性:如果删掉它,只给 agent 一句高层目标,当前模型大概率能不能做好?哪些内容是模型自己就会的通用常识,可以删?
   c. 该不该换形式:里面有没有「每次都必须执行」的规则,更适合改成 lint、测试或 hook,而不是写在 skill 里?
3. 分成三组输出:保留(只改 description)、合并或精简、建议删除或改成检查。每个建议删除的 skill,写出删除后用什么替代(一句高层指令、一条检查,或什么都不用)。
4. 对「保留」组,给出改写后的 description 原文,要求写清触发场景。
5. 验收:每个判断都引用 SKILL.md 里的原文作证据;不要凭空推测 skill 的用途。

参考:Thorsten Ball 在 X 上的观点 https://x.com/thorstenball/status/2122922612770632070

来源:Thorsten Ball 的 X 帖(2026-11-18,点赞 143、收藏 88);Dave Bettin 的回复


3. poteto 的 /correct skill:让 agent 自己回顾被你纠正过的错误,然后替你把它写成确定性的检查

目标:把我最近反复纠正 agent 的问题变成自动检查。先出清单和方案,我确认后再动手。

1. 从这些地方找「同一类错误至少出现 2 次」的证据:最近 30 次提交里的修复提交(git log -p)、PR 审查评论(如果能用 gh 只读访问)、CLAUDE.md/AGENTS.md 里「不要……」「必须……」这类规则。每条列出出现次数和具体例子(提交哈希、文件和行号,或评论原文)。
2. 对每类错误,按这个顺序选最强的拦截方式,并说明为什么上一档做不到:(1) 改架构让错误写不出来;(2) 用类型让错误编译不过;(3) 加一条 lint,报错信息里直接写出正确做法;(4) 加一条测试;(5) 最后才是写进文档。
3. 对每条拟加的检查,说明怎么证明它有效:在一个临时分支上把过去那次真实的错误重新引入,检查必须失败;改回正确写法,检查必须通过。
4. 我确认后,每条检查单独一个提交,提交信息里写清它拦的是哪次历史错误;完成后贴出「引入错误 → 检查失败」「修正 → 检查通过」的命令和输出。
5. 如果某条规则做成检查后,CLAUDE.md/AGENTS.md 里对应的文字可以删掉,列出来让我决定。

参考:poteto 的 /correct skill https://github.com/cursor/plugins/blob/main/pstack/skills/correct/SKILL.md

来源:AI Engineer 发布的 poteto 演讲片段(2026-11-18;视频本期未观看,内容以帖文为准);poteto 的回复;/correct SKILL.md(poteto)


4. 【补课】planning-with-files(约 2.8 万星):把计划写进磁盘上的三个文件,再用 hook 每轮提醒 agent 看,上下文被清空也不丢计划

目标:给一个需要跨多轮、可能被 /clear 打断的长任务,建立「文件化计划」,让任何新会话都能从文件接着做。

1. 先读仓库,确认没有已有的计划文件约定(如 docs/plans、PLAN.md、.claude/ 下的计划目录);有就沿用,没有就在仓库根目录下建一个被 .gitignore 忽略的目录(例如 .agent-plan/),并告诉我你的选择。
2. 在其中建三个文件:task_plan.md(目标、验收标准、分阶段步骤,每步有「未开始/进行中/完成」状态)、findings.md(读代码时的发现和决定,每条附文件路径)、progress.md(按时间记录做了什么、跑了哪些命令、结果如何)。
3. 工作规则:每完成一步立刻更新 task_plan.md 状态和 progress.md;做决定前先读 findings.md;每次开始工作(包括 /clear 之后)先读三个文件再动手。
4. 可选:如果我同意,在 .claude/settings.json 里加一个 hook,在每次提交 prompt 时把 task_plan.md 的「当前阶段」一节注入上下文。先给我看 hook 配置原文,不要直接写入。
5. 验收:演示一次——做完第一步后,假设上下文被清空,只靠三个文件说出当前进度和下一步;贴出三个文件的内容。

参考:OthmanAdi planning-with-files https://github.com/OthmanAdi/planning-with-files

来源:OthmanAdi/planning-with-files(OthmanAdi,MIT)


本期去重用源链接(机器可读)