diff --git a/AGENTS.md b/AGENTS.md index 83631ea..675f384 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ - [x] Phase 2：形成自己的观点（thinking/，11 篇，持续中） - [x] Phase 3：选一个小项目实践（practice/，1 个 Ralph Demo） - [x] Phase 4：记录反馈迭代（feedback/，1 篇，持续中） -- [x] Phase 5：输出可展示的作品（works/，34 篇翻译 + 1 篇原创 + 2 篇外部中文收录） +- [x] Phase 5：输出可展示的作品（works/，40 篇翻译 + 1 篇原创 + 2 篇外部中文收录） > 进度详情以人类向 README.md 的"学习路线"段为准；本节是给智能体的快照。 diff --git a/README.en.md b/README.en.md index 6355fdd..2571b69 100644 --- a/README.en.md +++ b/README.en.md @@ -1,8 +1,8 @@ [中文](README.md) | English ![License: MIT](https://img.shields.io/badge/license-MIT-blue) -![Articles](https://img.shields.io/badge/articles-74-green) -![Translations](https://img.shields.io/badge/translations-34-orange) +![Articles](https://img.shields.io/badge/articles-79-green) +![Translations](https://img.shields.io/badge/translations-40-orange) [![Read online](https://img.shields.io/badge/read%20online-harness.dyu.sh-c2481d)](https://harness.dyu.sh) # Harness Engineering Study Guide @@ -117,10 +117,10 @@ harness-engineering/ ├── thinking/ # Phase 2: Independent analysis (11 articles) ├── practice/ # Phase 3: Hands-on experiments (1 Ralph Demo) ├── feedback/ # Phase 4: Lessons learned (1 article) -├── works/ # Phase 5: Shareable outputs (34 translations + 1 original + 2 external Chinese captures) +├── works/ # Phase 5: Shareable outputs (40 translations + 1 original + 2 external Chinese captures) ├── tools/ # Tools that reduce the 6 complexity dimensions ├── prompts/ # Validated prompts collection -└── references/ # External resource index (74 articles with deep summaries) +└── references/ # External resource index (79 articles with deep summaries) ``` Each subdirectory has its own `AGENTS.md` explaining its purpose and conventions — a direct practice of the "progressive disclosure" principle from the original article. @@ -131,15 +131,15 @@ Each subdirectory has its own `AGENTS.md` explaining its purpose and conventions - [x] **Phase 2: Form your own opinions** — 11 independent analyses (ongoing) - [x] **Phase 3: Pick a small project to practice** — Ralph Demo completed (321s, $0.31) - [x] **Phase 4: Record feedback & iterations** — 1 article (ongoing) -- [x] **Phase 5: Produce shareable work** — 34 professional translations + 1 original synthesis + 2 external Chinese captures +- [x] **Phase 5: Produce shareable work** — 40 professional translations + 1 original synthesis + 2 external Chinese captures ## 📚 Research Library -74 articles across three knowledge tracks + 2 extended readings: +79 articles across three knowledge tracks + 2 extended readings: | Track | Coverage | Perspectives | |-------|----------|-------------| -| AI-Era Harness Engineering | 70 articles | OpenAI → Fowler → Anthropic → LangChain → Stanford → Claude Code reverse engineering & source leak → Subagent runtime → Sensors/SPDD/ADLC → Out-of-scope, safety auditing & quality postmortems → Evaluation trilogy → Dynamic workflows → Origins (Ralph / Hashimoto) & discipline synthesis → Codex harness anatomy → Loop Engineering trilogy → Self-evolving harnesses & RSI → Formal verification → Multi-agent scaling (Cursor / C compiler) → Official containment & evals methodology → Behavior maps / DSLs / local models / outer-loop accountability → industrial-scale mechanical porting (Bun) & harness-model co-evolution (HarnessX) → long-running harness foundations & eval-environment confounders (Anthropic backfill) → harness operations metrics & reward hacking (Cursor backfill) → tool schemas are not neutral → the software-factory debate (Dex Horthy / Osmani) → agent-swarm cost economics → deleting 80% of the system prompt → a code-review-sensor benchmark (ReviewBench) | +| AI-Era Harness Engineering | 75 articles | OpenAI → Fowler → Anthropic → LangChain → Stanford → Claude Code reverse engineering & source leak → Subagent runtime → Sensors/SPDD/ADLC → Out-of-scope, safety auditing & quality postmortems → Evaluation trilogy → Dynamic workflows → Origins (Ralph / Hashimoto) & discipline synthesis → Codex harness anatomy → Loop Engineering trilogy → Self-evolving harnesses & RSI → Formal verification → Multi-agent scaling (Cursor / C compiler) → Official containment & evals methodology → Behavior maps / DSLs / local models / outer-loop accountability → industrial-scale mechanical porting (Bun) & harness-model co-evolution (HarnessX) → long-running harness foundations & eval-environment confounders (Anthropic backfill) → harness operations metrics & reward hacking (Cursor backfill) → tool schemas are not neutral → the software-factory debate (Dex Horthy / Osmani) → agent-swarm cost economics → deleting 80% of the system prompt → a code-review-sensor benchmark (ReviewBench) → empirical refutation of TDD-as-process (Böckeler) → practical loop engineering (Osmani) → an org-scale adoption snapshot (Zalando) → open neutral harnesses & white-box compaction (Pi duo) → frozen-artifact cross-model transfer (StarHarness) | | Cloud-Native Harness.io | 2 articles | CI/CD platform architecture (same name, different meaning) | | Efficiency Paradox & Capability Evolution | 2 articles | YDD systematic teardown + METR follow-up (measurement-methodology crisis) | | Extended Reading | 2 articles | Context Engineering, Human-Agent collaboration | @@ -149,12 +149,18 @@ See [references/articles.md](references/articles.md) — each article includes c ## 📖 Translations
-34 Chinese translations of key articles (click to expand) +40 Chinese translations of key articles (click to expand) | Translation | Original Author | Source | |-------------|----------------|--------| | ⭐ [Eight Years of Wanting](works/maganti-eight-years-building-ai-translation.md) | Lalit Maganti | Personal blog | | [Evaluating code review agents with ReviewBench](works/langchain-reviewbench-translation.md) | Nick Hollon | LangChain | +| [TDD inside the agent loop - theater or actual value?](works/fowler-tdd-in-agent-loop-translation.md) | Birgitta Böckeler | martinfowler.com | +| [Practical Loop Engineering](works/osmani-practical-loop-engineering-translation.md) | Addy Osmani | AddyOsmani.com | +| [Agentic Engineering at Zalando: A Snapshot](works/zalando-agentic-engineering-translation.md) | Bartosz Ocytko | Zalando Engineering | +| [What Is a Harness?](works/pi-what-is-a-harness-translation.md) | Earendil / Pi team | earendil.com | +| [How Compaction Works in Pi](works/pi-compaction-translation.md) | Earendil / Pi team | earendil.com | +| [StarHarness: Evolving Harnesses with Stratified Search](works/arxiv-starharness-translation.md) | ServiceNow / Mila et al. | arXiv | | [The New Rules of Context Engineering for Claude 5](works/anthropic-context-engineering-claude5-translation.md) | Thariq Shihipar | Anthropic / Claude | | [Better Models: Worse Tools](works/ronacher-better-models-worse-tools-translation.md) | Armin Ronacher | Personal blog | | [Rewriting Bun in Rust](works/bun-in-rust-translation.md) | Jarred Sumner | Bun Blog | diff --git a/README.md b/README.md index 6d55270..834331c 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ 中文 | [English](README.en.md) ![License: MIT](https://img.shields.io/badge/license-MIT-blue) -![Articles](https://img.shields.io/badge/articles-74-green) -![Translations](https://img.shields.io/badge/translations-34-orange) +![Articles](https://img.shields.io/badge/articles-79-green) +![Translations](https://img.shields.io/badge/translations-40-orange) [![在线阅读](https://img.shields.io/badge/在线阅读-harness.dyu.sh-c2481d)](https://harness.dyu.sh) # Harness Engineering 学习指南 @@ -116,10 +116,10 @@ harness-engineering/ ├── thinking/ # Phase 2：独立思考与质疑（11 篇） ├── practice/ # Phase 3：小项目实验（1 个 Ralph Demo） ├── feedback/ # Phase 4：踩坑与迭代心得（1 篇） -├── works/ # Phase 5：可展示的作品（34 篇翻译 + 1 篇原创 + 2 篇外部中文收录） +├── works/ # Phase 5：可展示的作品（40 篇翻译 + 1 篇原创 + 2 篇外部中文收录） ├── tools/ # 工具具像化：降低 6 维复杂度的杠杆库 ├── prompts/ # 验证有效的提示词积累 -└── references/ # 外部资源索引（74 篇文章深度摘要） +└── references/ # 外部资源索引（79 篇文章深度摘要） ``` 每个子目录都有自己的 `AGENTS.md`，说明该目录的用途和写作约定。这本身就是原文「渐进式披露」的实践。 @@ -130,15 +130,15 @@ harness-engineering/ - [x] **Phase 2：形成自己的观点** — 11 篇独立思考（持续中） - [x] **Phase 3：选一个小项目实践** — Ralph Demo 完成（321 秒，$0.31） - [x] **Phase 4：记录反馈迭代** — 1 篇（持续中） -- [x] **Phase 5：输出可展示的作品** — 34 篇专业翻译 + 1 篇原创综合分析 + 2 篇外部中文收录 +- [x] **Phase 5：输出可展示的作品** — 40 篇专业翻译 + 1 篇原创综合分析 + 2 篇外部中文收录 ## 📚 研究资料库 -跨三条知识脉络 74 篇文章 + 2 篇延伸阅读： +跨三条知识脉络 79 篇文章 + 2 篇延伸阅读： | 脉络 | 覆盖 | 核心视角 | |------|------|---------| -| AI 时代的 Harness Engineering | 70 篇 | OpenAI → Fowler → Anthropic → LangChain → Stanford → Claude Code 逆向与源码实锤 → Subagent runtime → 传感器/SPDD/ADLC → 越界·安全审计·质量复盘 → 评测三部曲 → 动态工作流 → 起源考据（Ralph / Hashimoto）与学科汇流 → Codex harness 解剖 → Loop Engineering 三部曲 → 自演化 harness 与 RSI → 形式化验证 → 多智能体并行规模化（Cursor / C compiler）→ 遏制与评测官方方法论 → 行为地图 / DSL / 本地模型 / 外环问责 → 工业级机械移植（Bun）与 harness-模型共演化（HarnessX）→ 长时 harness 奠基与评测环境混杂（Anthropic 存量）→ harness 运维度量与奖励作弊（Cursor 存量）→ 工具 schema 不中立 → 软件工厂之争（Dex Horthy / Osmani）→ 智能体蜂群成本经济学 → 删掉 80% 系统提示词 → 代码评审传感器基准（ReviewBench） | +| AI 时代的 Harness Engineering | 75 篇 | OpenAI → Fowler → Anthropic → LangChain → Stanford → Claude Code 逆向与源码实锤 → Subagent runtime → 传感器/SPDD/ADLC → 越界·安全审计·质量复盘 → 评测三部曲 → 动态工作流 → 起源考据（Ralph / Hashimoto）与学科汇流 → Codex harness 解剖 → Loop Engineering 三部曲 → 自演化 harness 与 RSI → 形式化验证 → 多智能体并行规模化（Cursor / C compiler）→ 遏制与评测官方方法论 → 行为地图 / DSL / 本地模型 / 外环问责 → 工业级机械移植（Bun）与 harness-模型共演化（HarnessX）→ 长时 harness 奠基与评测环境混杂（Anthropic 存量）→ harness 运维度量与奖励作弊（Cursor 存量）→ 工具 schema 不中立 → 软件工厂之争（Dex Horthy / Osmani）→ 智能体蜂群成本经济学 → 删掉 80% 系统提示词 → 代码评审传感器基准（ReviewBench）→ TDD 过程实证否定与结果度量（Böckeler）→ loop 日常落地（Osmani）→ 组织级采纳快照（Zalando）→ 开放中立 harness 与 compaction 白盒（Pi 双篇）→ 冻结工件跨模型迁移（StarHarness） | | 云原生 Harness.io | 2 篇 | CI/CD 平台架构（同名不同义的参照） | | 效率悖论与能力进化 | 2 篇 | YDD 系统性拆解 + METR 实验后续（测量方法论危机） | | 延伸阅读 | 2 篇 | Context Engineering、人机协作 | @@ -148,12 +148,18 @@ harness-engineering/ ## 📖 翻译作品
-34 篇核心文章的中文翻译（点击展开） +40 篇核心文章的中文翻译（点击展开） | 作品 | 原作者 | 来源 | |------|--------|------| | ⭐ [渴望了八年，用 AI 三个月造出来](works/maganti-eight-years-building-ai-translation.md) | Lalit Maganti | 个人博客 | | [用 ReviewBench 评测代码评审智能体](works/langchain-reviewbench-translation.md) | Nick Hollon | LangChain | +| [agent loop 里的 TDD：走形式还是真价值？](works/fowler-tdd-in-agent-loop-translation.md) | Birgitta Böckeler | martinfowler.com | +| [Practical Loop Engineering（循环的日常落地）](works/osmani-practical-loop-engineering-translation.md) | Addy Osmani | AddyOsmani.com | +| [Zalando 的 Agentic 工程快照](works/zalando-agentic-engineering-translation.md) | Bartosz Ocytko | Zalando Engineering | +| [What Is a Harness?（harness 是什么）](works/pi-what-is-a-harness-translation.md) | Earendil / Pi 团队 | earendil.com | +| [Compaction 在 Pi 里如何工作](works/pi-compaction-translation.md) | Earendil / Pi 团队 | earendil.com | +| [StarHarness：分层搜索演化企业环境 harness](works/arxiv-starharness-translation.md) | ServiceNow / Mila 等 | arXiv | | [Claude 5 世代模型的上下文工程新规则](works/anthropic-context-engineering-claude5-translation.md) | Thariq Shihipar | Anthropic / Claude | | [更好的模型：更差的工具](works/ronacher-better-models-worse-tools-translation.md) | Armin Ronacher | 个人博客 | | [用 Rust 重写 Bun](works/bun-in-rust-translation.md) | Jarred Sumner | Bun Blog | diff --git a/prompts/deep-research-tracker.md b/prompts/deep-research-tracker.md index 15f571e..f60972a 100644 --- a/prompts/deep-research-tracker.md +++ b/prompts/deep-research-tracker.md @@ -61,11 +61,11 @@ > 它必须自包含，因为搜索器无法访问 `references/articles.md`。 > > **维护纪律：** 当 `references/articles.md` 新增/删除条目时，**同一次提交中**必须同步更新本节。两份内容的口径（脉络划分、篇数、产品/项目清单）应保持完全一致。 -> 本节最近一次同步：2026-08-05（与 `articles.md` 当前内容对齐：74 篇文章 + 1 项已跟踪产品）。 +> 本节最近一次同步：2026-08-27（与 `articles.md` 当前内容对齐：79 篇文章 + 1 项已跟踪产品）。 -**核心文章 74 篇，分布于三条脉络：** +**核心文章 79 篇，分布于三条脉络：** -- **脉络一 — AI 时代 Harness Engineering（70 篇）：** +- **脉络一 — AI 时代 Harness Engineering（75 篇）：** - OpenAI "Harness engineering"（原点，2026-02-11）/ "An open-source spec for Codex orchestration: Symphony"（2026-04-27，任务跟踪器作为控制平面） - Fowler/Böckeler "Harness engineering for coding agent users"（2026-04-02）+ 前传备忘录（2026-02-17） - LangChain "The Anatomy of an Agent Harness"（2026-03）/ "Continual Learning for AI Agents"（2026-04-05）/ "Agent Evaluation Readiness Checklist" @@ -132,6 +132,11 @@ - Rethinking Harness Evolution 论文（arXiv 2607.12227，自动 harness 演化的第一份系统性负面结果：同等预算下不稳定优于 test-time scaling、泛化有限） - LangChain "How We Benchmark Deep Agents"（2026-07-23）+ "IssueBench"（2026-07-20）——Harbor 评测栈：Harbor-Index 82 任务 / lite 冻结子集 / capability suite；IssueBench 15 类失败分类法与 issue 集层面判分 - LangChain / Nick Hollon "Evaluating code review agents with ReviewBench"（2026-07-31，真实 PR 评审意见策展成 59 任务 / 64 基线问题；裸 harness 最强召回 ~30%，prompt-only 调优 Luna 0.13→0.32 反超 Opus/Kimi） + - Fowler / Birgitta Böckeler "TDD inside the agent loop - theater or actual value?"（2026-08-10，agent loop 内 TDD 实证否定：盲评质量无差异、mutation score 无差异、token 3–8.5 倍；别规定过程，度量结果） + - Addy Osmani "Practical Loop Engineering"（2026-08-14，loop 系列日常落地环：踩坑实录 + 80K star 仓库分诊循环 + fine print 运维细则） + - Zalando / Bartosz Ocytko "Agentic Engineering at Zalando: A Snapshot"（2026-08-14，250+ 团队非供应商组织级快照：事故分析→PR 风险分级→33% 自动放行→lead time -20~40%） + - Earendil / Pi 团队双篇 "What Is a Harness?" + "How Compaction Works in Pi"（2026-08-20 / 08-13，harness 定义+用户侧中立主张 / compaction 白盒实现，与 Codex 端点化对照） + - StarHarness 论文（arXiv 2608.24804，ServiceNow/Mila，2026-08-25，冻结 harness 工件跨 GPT/Qwen 迁移 12 行全正 +10.7~+46.3pp；跨模型可移植性首个正面证据） - **脉络二 — 云原生 Harness.io（2 篇）：** Harness.io 官方全局架构 / Google Cloud 集成场景 - **脉络三 — 效率悖论（2 篇）：** YDD/Miss-you "效率悖论的系统性拆解"（2026-03-03）/ METR 实验后续 + 自报调查（2026-02-24 + 2026-05-11，"慢 19%"的官方后续：弱证据转向加速 + RCT 方法论危机） @@ -326,7 +331,8 @@ | 2026-07-21 | （教训来源，未做系统回扫） | 事后补收 #48 / #49 / #50 / #47 | | 2026-07-27 | ① anthropic.com/engineering 全量列表 ② cursor.com/blog 全量 slug 清单 | #58 Effective harnesses（2025-11）、#59 基础设施噪声（2026-02）、#60 持续改进 agent harness（2026-04）、#61 奖励作弊（2026-06）——四篇均为 harness 主题正中靶心却漏网数月 | | 2026-08-03 | ① openai.com/sitemap.xml/engineering 全量 URL+lastmod ② martinfowler.com/feed.atom（GenAI 归档） | 无漏网存量：OpenAI Engineering 分类的 harness 主题件（harness-engineering / unrolling / unlocking / symphony / windows-sandbox / core-dump / websockets / how-agents-transforming-work）均已在编号正文或观察项；其余 gpt-5.6 / atlas / sora-android / tax-agents / data-agent 为产品·基建，非 harness。Fowler 侧捞出的是增量而非存量（重构经济效益 / Conductor Developer / Fragments 07-21 / Orchestrator's Tax 草稿）——已进本批观察项 | +| 2026-08-27 | ① langchain.com/blog sitemap 全量（507 slug）② claude.com/blog sitemap 全量（228 slug，去 locale 变体） | **非零星漏网而是系统性缺口**：langchain 相关约 115 篇/此前仅收 19（漏网详查 48，含 12 篇标题直接带 harness/loop 的核心文：improving-deep-agents-with-harness-engineering、better-harness、the-art-of-loop-engineering、deep-agents 开山文等）；claude.com 相关约 80/仅收 9（漏网详查 41：skills 全系列、subagent 系列、Lessons from building Claude Code 双篇等）。处置：不逐篇消化，观察项表加 2 个"信源级"合并行，完整清单留档 translate/2026-08-27/candidates.md。方法论教训：两站列表页对 curl 均不完整**必须走 sitemap.xml**；claude.com 的 lastmod 批量刷新不可作发布日期，需逐页取 JSON-LD datePublished | -> 下一轮建议轮换：langchain.com/blog（Observability & Evals 分类）+ claude.com/blog（全量 slug）。openai.com/index 用 `curl https://openai.com/sitemap.xml/engineering/` 拿到带 lastmod 的全量 URL 最省事（2026-08-03 验证有效，比抓列表页首屏可靠）。 +> 下一轮建议轮换：addyosmani.com/blog + simonwillison.net 月归档（个人博客侧尚未系统回扫过）；cursor.com/blog 可顺带复扫（本批已全量取 sitemap 115 slug 逐页核过日期，短期内干净）。openai.com/index 用 `curl https://openai.com/sitemap.xml/engineering/` 拿到带 lastmod 的全量 URL 最省事（2026-08-03 验证有效，比抓列表页首屏可靠）。 > 回扫技巧（2026-07-27 验证有效）：列表页只渲染最近若干条时，直接抓 `curl |grep -oE '/blog/[a-z0-9-]+'|sort -u` 拿全量 slug， > 再逐个取 `datePublished` 与标题——Cursor 那四条里有两条（`continually-improving-agent-harness`、`reward-hacking-coding-benchmarks`）就是这样发现的，它们不在列表页首屏。 diff --git a/references/AGENTS.md b/references/AGENTS.md index d35511f..487a419 100644 --- a/references/AGENTS.md +++ b/references/AGENTS.md @@ -9,10 +9,10 @@ ## 文章 -详见 [articles.md](articles.md) — 完整的文章索引，含三条脉络 **74 篇文章 + 1 项已跟踪产品** 的深度摘要。 +详见 [articles.md](articles.md) — 完整的文章索引，含三条脉络 **79 篇文章 + 1 项已跟踪产品** 的深度摘要。 权威计数与编号规则以 `articles.md` 头部为准；本表是它的概览缓存。 -### 脉络一：AI 时代的 Harness Engineering（70 篇） +### 脉络一：AI 时代的 Harness Engineering（75 篇） | # | 文章 | 作者 | 核心贡献 | |---|------|------|---------| @@ -86,20 +86,25 @@ | 68 | [Rethinking Harness Evolution 论文](https://arxiv.org/abs/2607.12227) | Yike Wang 等 | 自动 harness 演化的第一份系统性负面结果：同等预算下不稳定优于简单 test-time scaling，泛化有限 | | 69 | [LangChain/Harbor 评测栈](https://www.langchain.com/blog/how-we-benchmark-deep-agents) | Nick Hollon, Harrison Chase 等 | 给 harness 建标尺（Harbor-Index 82 任务 / lite 子集 / capability suite），再给标尺建标尺（IssueBench 15 类失败分类法） | | 70 | [LangChain/ReviewBench](https://www.langchain.com/blog/evaluating-code-review-agents-with-reviewbench) | Nick Hollon | 给"AI 代码评审"传感器造考卷：真实 PR 评审意见策展成 59 任务；裸 harness 最强召回 ~30%，prompt-only 调优 0.13→0.32 反超 | +| 71 | [Fowler/TDD in the agent loop](https://martinfowler.com/articles/exploring-gen-ai/tdd-in-the-agent-loop.html) | Birgitta Böckeler | agent loop 内 TDD 的实证否定：盲评质量无差异、token 3–8.5 倍；别规定过程，度量结果 | +| 72 | [Osmani/Practical Loop Engineering](https://addyosmani.com/blog/practical-loop-engineering/) | Addy Osmani | loop 系列日常落地环：踩坑实录（差点连判断也委托）+ 分诊循环 + fine print 运维细则 | +| 73 | [Zalando 组织级快照](https://engineering.zalando.com/posts/2026/08/agentic-engineering-at-zalando-a-snapshot.html) | Bartosz Ocytko | 250+ 团队非供应商第一人称：事故分析→风险分级→33% 自动放行→lead time -20~40% 的组织级反馈回路 | +| 74 | [Earendil/Pi 双篇](https://earendil.com/posts/what-is-a-harness/) | Pi 团队 | harness 定义+用户侧中立主张 / compaction 白盒实现（20K 预算、独立请求、纯文本可移植）——与 #39 端点化恰成对照 | +| 75 | [⭐ StarHarness 论文](https://arxiv.org/abs/2608.24804) | ServiceNow/Mila | 冻结 harness 工件跨 GPT/Qwen 迁移 12 行全正（+10.7~+46.3pp）；跨模型可移植性缺口首个正面证据 | ### 脉络二：云原生 Harness.io（2 篇） | # | 文章 | 核心贡献 | |---|------|---------| -| 71 | [Harness.io 官方](https://www.harness.io/blog/understanding-ci-cd-platforms-the-backbone-of-modern-devops) | CI/CD 平台全局架构 | -| 72 | [Google Cloud Architecture](https://docs.cloud.google.com/architecture/partners/harness-cicd-pipeline-for-rag-app) | Harness + GCP 部署 RAG | +| 76 | [Harness.io 官方](https://www.harness.io/blog/understanding-ci-cd-platforms-the-backbone-of-modern-devops) | CI/CD 平台全局架构 | +| 77 | [Google Cloud Architecture](https://docs.cloud.google.com/architecture/partners/harness-cicd-pipeline-for-rag-app) | Harness + GCP 部署 RAG | ### 脉络三：效率悖论与能力进化（2 篇） | # | 文章 | 核心贡献 | |---|------|---------| -| 73 | [YDD / Miss-you](https://yousali.com/posts/20260303-ai-coding-efficiency-to-evolution/) | 效率悖论的系统性拆解：约束理论 + Spec/Rule/Skill + 验证闭环 + 并发 | -| 74 | [METR 实验后续 + 自报调查](https://metr.org/blog/2026-02-24-uplift-update/) | "慢 19%" 的官方后续：弱证据转向加速 + AI 渗透破坏 RCT 可行性本身 | +| 78 | [YDD / Miss-you](https://yousali.com/posts/20260303-ai-coding-efficiency-to-evolution/) | 效率悖论的系统性拆解：约束理论 + Spec/Rule/Skill + 验证闭环 + 并发 | +| 79 | [METR 实验后续 + 自报调查](https://metr.org/blog/2026-02-24-uplift-update/) | "慢 19%" 的官方后续：弱证据转向加速 + AI 渗透破坏 RCT 可行性本身 | ### 已跟踪产品 / 项目（不计入文章数） diff --git a/references/articles.md b/references/articles.md index 9b6a31f..d59fa3c 100644 --- a/references/articles.md +++ b/references/articles.md @@ -10,7 +10,7 @@ > **下游引用都是本文的冗余缓存：** 根 `README.md` / `README.en.md` 的 badge、`prompts/deep-research-tracker.md` 的去重清单、`references/AGENTS.md` 的概览表。 > 新增/删除文章时，必须**同一次提交**更新本文 + 所有下游缓存。 > -> 当前规模：**74 篇文章**（脉络一 70 + 脉络二 2 + 脉络三 2）+ **1 项已跟踪产品**（不计入文章数）。最近一次同步：2026-08-05。 +> 当前规模：**79 篇文章**（脉络一 75 + 脉络二 2 + 脉络三 2）+ **1 项已跟踪产品**（不计入文章数）。最近一次同步：2026-08-27。 ## 脉络一：AI 时代的 Harness Engineering（大模型护栏与认知工程） @@ -745,7 +745,7 @@ |---------|---------| | 四要素 Harness | #2 Fowler、#5 HumanLayer 六杠杆、概念 2/3（地图而非手册 / 机械化执行） | | 反馈循环防腐化 | #9 Fowler 反馈飞轮、#19 Fowler Sensors | -| 反馈瓶颈 / serial speed-up | #73 YDD 效率悖论 | +| 反馈瓶颈 / serial speed-up | #78 YDD 效率悖论 | --- @@ -1176,7 +1176,7 @@ | agent loop vs harness loop | #41 Osmani 的 loop 定调、#37 "harness 拥有 loop" | | 防御式编码的放大 | #19 Fowler 传感器的失败案例、概念 6 熵与垃圾回收 | | 理解与参与 | #26 Chris Parsons 从批准者到训练者、#14 Maganti 的"必须理解每一行" | -| 无法退出的压力 | #73 YDD 效率悖论、#31 学科汇流的产业动力 | +| 无法退出的压力 | #78 YDD 效率悖论、#31 学科汇流的产业动力 | --- @@ -1729,7 +1729,7 @@ | 同一组织的自我修正 | #5 HumanLayer《Skill Issue》六杠杆（2026-03）→ 本文（2026-07）"杠杆不够" | | 可维护性没有快 oracle | #19 计算性 vs 推理性传感器的边界、#49 GCC oracle 与 #56 测试套件 oracle 之所以奏效的前提 | | 熄灯工厂的失败实录 | #64 Osmani 同题（明确基于本演讲）、#42 Ronacher comprehension | -| 评审是瓶颈 / 反馈是新瓶颈 | #26 Chris Parsons、#55 外环问责、#73 YDD 效率悖论与 Faros 数据 | +| 评审是瓶颈 / 反馈是新瓶颈 | #26 Chris Parsons、#55 外环问责、#78 YDD 效率悖论与 Faros 数据 | @@ -1922,11 +1922,115 @@ --- + + +### 71. Fowler / Birgitta Böckeler — agent loop 里的 TDD：走形式还是真价值？ + +- **标题：** TDD inside the agent loop - theater or actual value? +- **链接：** [martinfowler.com](https://martinfowler.com/articles/exploring-gen-ai/tdd-in-the-agent-loop.html) +- **翻译：** [works/fowler-tdd-in-agent-loop-translation.md](../works/fowler-tdd-in-agent-loop-translation.md) +- **作者：** Birgitta Böckeler（Thoughtworks Distinguished Engineer） | **日期：** 2026-08-10 +- **核心：** 「规定过程 vs 度量结果」的实证否定案例（自我定位为探索性 eval，自带全部数据并开源结果仓库）：5 批次 × 每批 2 个 TDD run + 2 个非 TDD run（另加 test-first 变体批），Opus 4.8 盲评（不知晓生成方式）+ Sonnet 4.6 独立判 TDD 遵循度剔除"假 TDD run" + mutation score 作为独立客观维度。结果：**质量无可辨差异、mutation score 无差异，非 TDD 反而多次略胜**——胜因是非 TDD run 总是先做完整前置设计（架构/数据类型/边界/契约），而 TDD 指令主动对抗前置设计，设计被第一个测试锁死。理论解释（引 Ivett Ördög）：训练数据是"需求→成品代码"的直接映射，几乎无逐步 TDD 过程样例。TDD 的七个目标逐一检视在 agent loop 内失效（red 无人查原因就无证明力；先写测试防不住自证套套逻辑；小步克制/管理恐惧是纯人类心理收益，不可迁移）。成本侧：TDD run token 3–8.5 倍（含 cacheRead 计数口径 caveat，承认可能高估真实美元成本）。结论：**别规定过程，度量结果**——mutation testing 当回归传感器、静态分析/模块化评审触发重构、Approved Scenarios（冻结-审批式场景）建信心；作者本人已停止让 agent test-first。 +- **保留意见：** 作者自警四条如实带上——样本极小、质量定义几乎全权 Opus、无一 run 完美遵循 TDD、任务全是小型绿地；探索性结论勿拔高为定论 +- **与其他文章的关联：** + +| 本文概念 | 对应文章 | +|---------|---------| +| 过程规定（前馈 guides）不如结果度量（反馈 sensors） | #2 Guides×Sensors 矩阵、#19 maintainability sensors（本文三处引用）、#32 传感器对照实验 | +| agent 超前实现 / YAGNI 失效 | #25 Overeager Coding Agents | +| 行为 harness 缺口的候选答案 | #1 "行为 Harness 是最弱环节"——Approved Scenarios 是冻结-审批式信心机制 | +| "新模型让显式过程脚手架多余" | #66 上下文工程新规则、Boris Cherny 弃 plan mode（观察项） | + +--- + + + +### 72. Addy Osmani — Practical Loop Engineering（循环的日常落地） + +- **标题：** Practical Loop Engineering +- **链接：** [addyosmani.com](https://addyosmani.com/blog/practical-loop-engineering/) +- **翻译：** [works/osmani-practical-loop-engineering-translation.md](../works/osmani-practical-loop-engineering-translation.md) +- **作者：** Addy Osmani | **日期：** 2026-08-14 +- **核心：** loop 系列「定调（#41）→官方四类（#43）→外环问责（#55）→工厂尺度（#64）」缺失的最后一环：**每天到底怎么跑**。注意约四成篇幅是引文汇编（四类循环大段引文与 verify-frontend-change skill 均来自 #43 的官方 X 文章版，勿误记为本文原创）；一手增量集中三块：① 竞品调研踩坑实录——"委托了任务，差点连判断也委托出去"，库内稀缺的外环问责第一人称失败案例；② 80K star 仓库日均 80–90 个 PR 的分诊循环 + **贡献指南条款直接变成可执行关闭条件**的用法；③ 官方文档外的 fine print 运维细则：goal 7 天过期（含作者自纠 3→7 天）、session 作用域与 `--resume` 行为、同命令三连即死循环信号、goal evaluator **只查 transcript 硬规则、不评内容好坏**的澄清。maker–checker（做的循环与查的循环分开）作为铁律贯穿。 +- **与其他文章的关联：** + +| 本文概念 | 对应文章 | +|---------|---------| +| loop 定义与五构件（回抄自我） | #41 Loop Engineering 定调文（双向引用） | +| 四类循环大段引文的出处 | #43 官方 Getting started with loops（本文以全译形式部分弥补 #43 无全译的缺口） | +| 委托任务不委托判断 / maker–checker | #55 Own the Outer Loop 的第一人称实证版、#36 对抗验证 | +| 哪些循环配得上熄灯的日常操作面 | #64 Software Factories, Light and Dark、#28 Ralph loop（手搓时代源头） | + +--- + + + +### 73. Zalando / Bartosz Ocytko — 250+ 团队 agentic 工程组织级快照 + +- **标题：** Agentic Engineering at Zalando: A Snapshot +- **链接：** [engineering.zalando.com](https://engineering.zalando.com/posts/2026/08/agentic-engineering-at-zalando-a-snapshot.html) +- **翻译：** [works/zalando-agentic-engineering-translation.md](../works/zalando-agentic-engineering-translation.md) +- **作者：** Bartosz Ocytko（Zalando Executive Principal Engineer） | **日期：** 2026-08-14 +- **核心：** 库内目前唯一"**非供应商大型企业第一人称、带内部数据**"的组织级采纳快照（250+ 工程团队 / 2.5 年跨度；文末自我定位 non-vendor engineering team），且主动暴露失败面。基建层：LiteLLM 代理 2024-01 上线（OpenAI/Bedrock/Vertex），6 个 2C4G pod 撑 2k MAU、每 2 万请求强制重启对抗内存泄漏；从不集中强制单一工具。数据层：PR 尺寸 [100,500) 桶持续增长、2025 Q2 Sonnet 4 后 [500,1k)/[1k,2k) 桶开始增长；四代码库 commit 级圈复杂度对照定位 agent 介入拐点；opencode 用户缓存命中率 <30%（预期 80%+）的排障案例；提交信息膨胀到 ~5k 字符（pre-commit 约束治理）。**反馈回路是全文最有价值的一条链：生产事故分析 → PR 风险分级规则（配置 typo=高、破坏兼容=中、纯文档=低）→ 33% 低风险 PR 自动放行 → lead time 降 20–40% → 反向塑造工程师主动拆小 PR**——概念 5「Throughput Changes Merge」目前最完整的组织级实证。培训体系（GenAI Labs 3 天 6 场覆盖 120–150 人）明确"用 coding agent 走捷径会抑制学习"。在建：agent 平台（kagent）+ Identity Broker（on-behalf-of 委托链）。 +- **保留意见：** lead time -20~40% 的对照基线是"与全部 PR 相比"——低风险 PR 本来就快，存在选择偏差，非干预因果；圈复杂度对照 n=4、观察性研究；作者自标 anecdotal evidence 处已在译文保留 +- **与其他文章的关联：** + +| 本文概念 | 对应文章 | +|---------|---------| +| 风险分级自动放行 / 吞吐改变合并 | 概念 5、#63/#64 工厂之争的组织现实侧 | +| 事故数据反推护栏规则 | Faros 遥测报告（观察项：事故 +242.7%）——Zalando 给出对策路径一侧 | +| 圈复杂度拐点 / AI 放大好坏实践 | 概念 6 熵与垃圾回收、#19 传感器 | +| 大组织 vs 个体/供应商实践 | #14 Maganti、#26 Chris Parsons（个体侧）；#48/#60 Cursor、Anthropic 系列（供应商侧） | + +--- + + + +### 74. Earendil / Pi 团队双篇 — What Is a Harness? + Compaction 白盒实现 + +- **标题：** What Is a Harness? / How Compaction Works in Pi +- **链接：** [earendil.com（定义文）](https://earendil.com/posts/what-is-a-harness/) / [earendil.com（机制文）](https://earendil.com/posts/compaction-in-pi/) +- **翻译：** [works/pi-what-is-a-harness-translation.md](../works/pi-what-is-a-harness-translation.md) / [works/pi-compaction-translation.md](../works/pi-compaction-translation.md) +- **作者：** Earendil Product / Earendil Engineering（Pi 团队，集体署名） | **日期：** 2026-08-20 / 2026-08-13 +- **核心：** 开源中立 harness 阵营的「定义 + 实例」双篇（HN 576 分 / 211 分）。定义文以攀岩 harness 类比开场，四职能拆解（系统提示词 / 工具 / agentic loop / 模型翻译层）；工程内容是 #3 anatomy 的通俗子集，**真正差异化在立场**：harness 是用户可拥有、可改装的能动性工具，翻译层把杠杆从 AI 实验室转移给终端用户，点名 Claude Code 为"第一个流行但非中立的 harness"——「用户侧所有权/中立性」叙事此前库内空白。机制文是 compaction 的**透明白盒拆解**（附行级源码链接）：默认 20K token 保留预算（≈5–20 turns）；turn 结束后才检查自动触发（turn 内持续吃 cached prefix）；压缩走**独立 standalone 请求**（不带历史，可换便宜模型）；摘要**纯文本存储→跨模型可移植**（session portability 是明确设计目标）；compaction 必然打破 prompt cache 需全量重算。与 #39 Codex 的加密端点化 compaction（`/responses/compact` 返回 `encrypted_content`）恰成"**开放可移植 vs API 锁定**"对照。 +- **保留意见：** 厂商立场文——Pi/Lefos 自家产品、"5,000+ 扩展"系自述数字；定义严谨度不及 What makes a harness a harness 论文（观察项，构成性定义+纳入/排除测试）；机制文无 evals、无摘要质量度量（LangChain 压缩观察项的 targeted evals 反而有） +- **与其他文章的关联：** + +| 本文概念 | 对应文章 | +|---------|---------| +| harness 定义 / 组件拆解 | #1 原点、#3 anatomy（组件最全）、#21 ADLC 三分、Arize 划界与术语锚点论文（观察项） | +| compaction 实现对照 | #39 Codex 端点化（加密锁定）、LangChain Deep Agents 压缩三技术（观察项）、#66 上下文工程 | +| 开源中立 / 用户能动性主张 | #62 Ronacher（Pi 团队成员）工具 schema 论、DeepSeek Harness（观察项，实验室下场的反向信号） | +| 三 harness 架构收敛 | arXiv 2608.23953（观察项：deepagents/pi/dsh 源码级对比） | + +--- + + + +### 75. ⭐ StarHarness 论文 — 冻结 harness 工件跨模型迁移的首个正面证据 + +- **标题：** StarHarness: Evolving Harnesses with Stratified Search for Enterprise Environments +- **链接：** [arxiv 2608.24804](https://arxiv.org/abs/2608.24804) +- **翻译：** [works/arxiv-starharness-translation.md](../works/arxiv-starharness-translation.md) +- **作者：** ServiceNow / Mila / Université de Montréal（7 位作者，通讯均 @servicenow.com） | **日期：** 2026-08-25 +- **核心：** 冻结模型权重，用分层搜索演化环境专属 harness（提示/工具/技能/MCP/子代理/循环配置）。协议贡献：**三层任务隔离**（proposer 可见搜索集 / proposer 不可见选择集 / 留出集）+ 按失败模式分层抽样 + 确定性接受规则与 anti-gaming 护栏——是对 #68 系统性负面结果的**部分回应**（满足协议隔离侧，未做 #68 要求的同等预算 test-time scaling 基线）。结果：三个企业基准 **+35.0/+20.4/+26.1pp**（每环境仅 4–12 个被接受变更，共 21 个）；留出泛化 +31.7/+15.1/+29.3pp；**冻结工件跨 GPT-5.4/5.5/5.4-mini 与 Qwen3.5/3.6-27B 迁移 12 行全正（+10.7~+46.3pp），免重演化**——「跨模型可移植性」缺口此前只有反向证据（#35 收益不保序、Harness Updating ≠ Harness Benefit 的利用能力非单调），这是首个"同一冻结工件×异族模型全正"的正面数据点；成本同步降 −17%/−53%/−29%。弱模型受益更大（GPT-5.5 high 仅 +10.7pp）与 #57 逆缩放发现三方互证。 +- **保留意见：** 五点如实带上——三基准中两个与作者利益相关（EnterpriseOps-Gym 是 ServiceNow 自家产品环境、AutomationBench 为自选 Finance-100 子集）；单次运行无方差/置信区间；proposer 与受测模型同为 GPT-5.4；无 Claude 受控对比（仅外部参考分）；基线可能偏弱 +- **与其他文章的关联：** + +| 本文概念 | 对应文章 | +|---------|---------| +| 测 harness 效应 vs 造 harness 效应 | #34 Harness-Bench（配置级效应）、#35 统计归因 | +| 逐模型演化 vs 冻结工件迁移 | #57 HarnessX（cross-harness GRPO 共演化；其"弱模型受益最大"行可回填本文数据点） | +| 对自动演化负面结果的协议级回应 | #68 Rethinking Harness Evolution（部分回应）、#53 行为定位瓶颈 | +| 成本数据缺口 | #65 蜂群账本、The Harness Effect（观察项）、StateM $15（观察项） | + +--- + ## 脉络二：云原生时代的 Harness.io（交付与平台工程） - + -### 71. Harness.io 官方 — 全局架构 +### 76. Harness.io 官方 — 全局架构 - **标题：** Understanding CI/CD Platforms: The backbone of modern DevOps - **链接：** [harness.io](https://www.harness.io/blog/understanding-ci-cd-platforms-the-backbone-of-modern-devops) @@ -1934,9 +2038,9 @@ - **核心：** 标准 CI/CD 平台介绍。8 大组件：SCM → Build → Test → Code Quality → Security Scan → Artifact → Deploy → Monitor - **Harness 差异化：** 统一管线、Test Intelligence 智能测试、最少脚本、Policy-as-Code 治理 - + -### 72. Google Cloud Architecture — 前沿场景结合 +### 77. Google Cloud Architecture — 前沿场景结合 - **标题：** Harness CI/CD pipeline for RAG applications - **链接：** [docs.cloud.google.com](https://docs.cloud.google.com/architecture/partners/harness-cicd-pipeline-for-rag-app) @@ -1949,9 +2053,9 @@ ## 脉络三：效率悖论与能力进化 - + -### 73. YDD / Miss-you — 效率悖论的系统性拆解 +### 78. YDD / Miss-you — 效率悖论的系统性拆解 - **标题：** 为什么 AI 写代码更快但交付没变，以及我怎么把它扳回来的 - **链接：** [yousali.com](https://yousali.com/posts/20260303-ai-coding-efficiency-to-evolution/) @@ -1997,15 +2101,15 @@ --- - + -### 74. METR — 生产力实验的后续：结论松动与方法论危机 +### 79. METR — 生产力实验的后续：结论松动与方法论危机 - **标题：** We are Changing our Developer Productivity Experiment Design（2026-02-24）+ Measuring the Self-Reported Impact of Early-2026 AI on Technical Worker Productivity（2026-05-11） - **链接：** [metr.org 实验设计更新](https://metr.org/blog/2026-02-24-uplift-update/) | [metr.org 自报调查](https://metr.org/blog/2026-05-11-ai-usage-survey/) | [后续研究数据集](https://github.com/METR/Measuring-Late-2025-AI-on-OSS-Devs) - **翻译：** [works/metr-uplift-update-translation.md](../works/metr-uplift-update-translation.md)（实验设计更新篇） - **作者：** Joel Becker, Nate Rush, Tom Cunningham, David Rein, Khalid Mahamud (METR) | **日期：** 2026-02-24 / 2026-05-11 -- **核心：** #73 YDD 的论证基石（METR RCT "AI 辅助反而慢 19%"）的官方后续。late-2025 复现实验（57 名开发者、143 仓库、800+ 任务）的原始结果转向加速——原班开发者估计 **-18% 加速**（CI -38%~+9%）、新开发者 -4%（CI -15%~+9%）——但 METR 自己判定这只是**很弱的证据**，并宣布改实验设计。真正的信息量在于：**AI 渗透已经破坏了任务级随机对照实验本身的可行性**。 +- **核心：** #78 YDD 的论证基石（METR RCT "AI 辅助反而慢 19%"）的官方后续。late-2025 复现实验（57 名开发者、143 仓库、800+ 任务）的原始结果转向加速——原班开发者估计 **-18% 加速**（CI -38%~+9%）、新开发者 -4%（CI -15%~+9%）——但 METR 自己判定这只是**很弱的证据**，并宣布改实验设计。真正的信息量在于：**AI 渗透已经破坏了任务级随机对照实验本身的可行性**。 - **选择效应的三重来源（实验设计为何失效）：** - 开发者拒绝参与——越来越多人不愿在无 AI 条件下工作（时薪 $50 也不愿），最乐观的采纳者系统性缺席 @@ -2019,9 +2123,9 @@ | 本文概念 | 对应文章 | |---------|---------| -| 19% 减速数据的后续 | #73 YDD 第一章效率悖论（引用了原实验） | -| 感知与现实的偏差 | #73 的 39 个百分点偏差、自报高估 40+ 个百分点 | -| 并发智能体使计时失效 | #73 第五章并发策略（并发正是 YDD 开出的药方） | +| 19% 减速数据的后续 | #78 YDD 第一章效率悖论（引用了原实验） | +| 感知与现实的偏差 | #78 的 39 个百分点偏差、自报高估 40+ 个百分点 | +| 并发智能体使计时失效 | #78 第五章并发策略（并发正是 YDD 开出的药方） | | 测量方法的时代错位 | #38 Position 论文（基准侧的同构诊断：测量工具追不上被测对象） | --- @@ -2048,7 +2152,7 @@ Harness Engineering（AI 护栏） Harness.io（交付管线） ## 中文转译 / 二手资料（不计入文章数） > 这里收录的是**他人已发布的中文译介或二手综述**——本仓库做了归档但**不视为一手文献**。 -> 本段不参与 `### N. ...` 的全局编号，不计入 74 篇文章总数；与上方编号正文严格区分，避免污染脉络计数。 +> 本段不参与 `### N. ...` 的全局编号，不计入 79 篇文章总数；与上方编号正文严格区分，避免污染脉络计数。 > 收录标准：内容与 Harness Engineering 直接相关、来源可追溯到具名作者 / 译者、且对本仓库已有一手文献有补充或对照价值。 ### Akshay Pachaar — The Anatomy of an Agent Harness（中译版） @@ -2101,7 +2205,7 @@ Harness Engineering（AI 护栏） Harness.io（交付管线） ## 已跟踪产品 / 项目（不计入文章数） -> 这里收录的是**开源产品 / 框架 / 工具**，不是文章。本段不参与"### N. ..." 的全局编号，不计入 74 篇的文章总数。 +> 这里收录的是**开源产品 / 框架 / 工具**，不是文章。本段不参与"### N. ..." 的全局编号，不计入 79 篇的文章总数。 > 触发"产品级实现案例"的判定通常是：有可运行代码、有版本号、被本仓库 thinking/ 或 works/ 单独分析。 ### ⭐ Chachamaru127 — claude-code-harness v4.2 "Hokage"（产品级实现案例） @@ -2129,7 +2233,7 @@ Harness Engineering（AI 护栏） Harness.io（交付管线） ## 观察项 / 候选材料（不计入文章数） -> 2026-05 起各轮调研中已甄别、但**暂不值得做成正式文章**的材料。本段不参与 `### N.` 编号，不计入 74 篇文章总数。 +> 2026-05 起各轮调研中已甄别、但**暂不值得做成正式文章**的材料。本段不参与 `### N.` 编号，不计入 79 篇文章总数。 > 中文译文留在本地 `translate/`（gitignored）作阅读辅助；下表只记上游链接与定性，方便下次快速复看。 > **去向标记：** 🔵 待实测后入 `tools/`（遵守 tools/「只收用过的工具」标准，未实测前不正式收录） ｜ ⚪ 长期观察 ｜ ⏭️ 暂存不收。 > @@ -2167,7 +2271,7 @@ Harness Engineering（AI 护栏） Harness.io（交付管线） | OpenAI Core dump 流行病学 | 工程复盘 | ⚪ | "群体级诊断 > 逐例分析"修复 18 年 libunwind 老 bug，ChatGPT 参与写分析管线；可观测性方法论好文但与 harness 关系间接，2026-06-30 | [openai](https://openai.com/index/core-dump-epidemiology-data-infrastructure-bug/) | | thedeepfeed：学科史梳理 | 编年 | ⚪ | "七个声音九个月汇流成一个学科"的传播史（含 Osmani 文收藏/点赞比 2:1 等传播数据）；二手史料，配 #31 看 | [thedeepfeed.ai](https://www.thedeepfeed.ai/posts/2026-05-09-agent-harness-engineering-the-discipline/) | | Boris Cherny 工作流 | 实践 | ⚪ | Claude Code 作者本人"出奇原味"的用法（~100 行 CLAUDE.md、早期以 plan mode 纪律著称；站内 Part 15 已记录其 4.6+ 后放弃 plan mode 起手、改 auto mode 直跑——"新模型不再需要显式规划步骤"）；源头是其 X 帖，链接为社区维护的档案站（非 Anthropic 官方） | [howborisusesclaudecode.com](https://howborisusesclaudecode.com) | -| Steering Claude Code 官方指南 | 产品文档 | ⚪ | 七种转向机制（CLAUDE.md/rules/skills/subagents/hooks/output styles/system prompt append）按"加载时机 × compaction 行为 × token 成本"三轴对照——#73 YDD"区别在加载机制"论的官方版说明书；参考手册体裁，2026-06-18 | [claude.com](https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more) | +| Steering Claude Code 官方指南 | 产品文档 | ⚪ | 七种转向机制（CLAUDE.md/rules/skills/subagents/hooks/output styles/system prompt append）按"加载时机 × compaction 行为 × token 成本"三轴对照——#78 YDD"区别在加载机制"论的官方版说明书；参考手册体裁，2026-06-18 | [claude.com](https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more) | | The Harness Effect 论文 | 论文/厂商评测 | ⚪ | "成本数据"缺口的首个系统数据：同 22 任务 × 6 模型只换编排层，成本 -41%、时延 -44%、token -38%；提出 token maxing 与 harness leverage（质量增益与基线能力 r=0.99）。注意 Writer Inc. 自评自家 harness，利益相关，方法论（frozen baseline + locked tasks）可取 | [arxiv 2607.06906](https://arxiv.org/abs/2607.06906) | | Harness Updating ≠ Harness Benefit 论文 | 论文 | ⚪ | 拆开两条能力轴：写 harness 编辑的能力各模型持平（9B 能写出与 Opus 同构的 skill），利用 harness 的能力非单调（中档模型受益最多）——跨模型可移植性缺口的机制侧证据；被 #45 Weng 综述引用 | [arxiv 2605.30621](https://arxiv.org/abs/2605.30621) | | ToFu 白盒研究 harness | 工具 | 🔵 | MIT 协议、面向研究者的白盒 harness：三层上下文压缩 + 多语言 + MCP 集成，可作为 research object 检查/修改编排逻辑；待实测后再定去向 | [arxiv 2607.11423](https://arxiv.org/abs/2607.11423) | @@ -2202,7 +2306,7 @@ Harness Engineering（AI 护栏） Harness.io（交付管线） | LangChain：Towards Automating Eval Engineering | 产品/方法 | ⚪ | Eval Engineering Skill 发布稿，但两处有料：**verifier 的第一版几乎从不是最终版**，要同时检查智能体轨迹与 **verifier 轨迹**；已观察到的四种作弊形态（过度引用无关来源骗满分 / 声称做过其实没做 / 利用暴露在环境里的答案材料 / 满足代理指标但没真正完成）。定调句"Evals are training data for agents"，2026-07-22 | [langchain](https://www.langchain.com/blog/towards-automating-eval-engineering) | | LangChain：Agents need their own computer | 概念/产品 | ⚪ | 隔离论证与 #50 重复度高，值得单取的是**注入防御那节**：沙箱遏制执行爆炸半径但**不消除提示词注入**，因为沙箱输出会被读回上下文；给出具名模式 **"non-agentic read"**——由非模型进程去沙箱取成品（文件、diff、报告），而不是把原始输出灌进智能体上下文；并直言"别指望靠提示模型去识别或忽略注入"，2026-07-15 | [langchain](https://www.langchain.com/blog/agents-need-their-own-computer) | | Harrison Chase：Own your intelligence | 战略随笔 | ⚪ | "拥有智能"三层（model / harness / context）+ 拥有经济性、质量与风险 + 复利闭环（每一次改动配一条 eval 固化）；论点与 #3/#15/#21 高度重叠，唯一增量是结尾那份 **10 问自评清单**，可作 `prompts/` 模板引用，2026-07-25 | [langchain](https://www.langchain.com/blog/own-your-intelligence) | -| Faros AI：AI acceleration whiplash | 行业报告 | ⚪ | #63 与 #73 共同引用的那份遥测报告：评审评论数 +25%、评论长度 +22.7%、**+31.3% 的 PR 完全跳过评审**；每 PR 事故 +242.7%、月度事故 +57.9%、人均 bug +54%。相关性信号而非因果铁证，但它是"熄灯工厂会失败"论证的经验底座；同站另有一篇 harness engineering 五层框架科普（tool orchestration / verification loops / context & memory / guardrails / observability）+ 一组可从现有系统拉出的基线指标（每合并 PR 成本、智能体 PR 的 time-to-merge、评审速度对 PR 体积、人均算力开销） | [research](https://www.faros.ai/research/ai-acceleration-whiplash) / [blog](https://www.faros.ai/blog/harness-engineering) | +| Faros AI：AI acceleration whiplash | 行业报告 | ⚪ | #63 与 #78 共同引用的那份遥测报告：评审评论数 +25%、评论长度 +22.7%、**+31.3% 的 PR 完全跳过评审**；每 PR 事故 +242.7%、月度事故 +57.9%、人均 bug +54%。相关性信号而非因果铁证，但它是"熄灯工厂会失败"论证的经验底座；同站另有一篇 harness engineering 五层框架科普（tool orchestration / verification loops / context & memory / guardrails / observability）+ 一组可从现有系统拉出的基线指标（每合并 PR 成本、智能体 PR 的 time-to-merge、评审速度对 PR 体积、人均算力开销） | [research](https://www.faros.ai/research/ai-acceleration-whiplash) / [blog](https://www.faros.ai/blog/harness-engineering) | | StrongDM 熄灯工厂 + Dan Shapiro 五级 | 一手实验 / 分级 | ⚪ | #63/#64 讨论的"熄灯工厂"实物：StrongDM 公开运行的 lights-off factory（无人写码、无人读码，配 weather-report 更新页）与 Dan Shapiro 的"从辣味自动补全到软件工厂"五级分类。Dex 的批评是"没找到确定性的成效数据"；作为反方样本长期跟踪 | [factory.strongdm.ai](https://factory.strongdm.ai) / [danshapiro.com](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/) | | Ronacher：The Tower Keeps Rising | 随笔 | ⚪ | #62 作者同月另一篇：vibecoding 与"共享语言可能崩塌"；哲学性论述、无一手数据，与 #42 The Coming Loop 同一关切的延伸，2026-07-13 | [lucumr](https://lucumr.pocoo.org/2026/7/13/the-tower-keeps-rising/) | | Fowler / Giles Edwards-Alexander：重构的经济效益 | 实验 | ⚪ | Exploring Gen AI 系列少见的**定量重构实验**：一个 15 万行、纯智能体生成、作者从不 review 的应用里，数据访问层膨胀到单文件 17,155 行；用"智能体永远学不会"这一特性把它变成干净实验——每完成一步重构就派一个全新 sub-agent 跑同一个代表性变更并回报 token，无学习污染。14+ 步后同一变更的输入 token 从 159,564 降到 27,360（−83%），且是**一次重构、此后每次触碰该层都更便宜**的复利式节省。附带黑色幽默：机械重构用 Python+grep/sed 脚本执行，"经常被缩进搞晕"。给"熄灯工厂里到底还要不要重构"一个可迁移的算账方法，2026-07-30。**升格候选**（新实验范式） | [martinfowler](https://martinfowler.com/articles/exploring-gen-ai/refactoring-economic-benefit.html) | @@ -2211,6 +2315,48 @@ Harness Engineering（AI 护栏） Harness.io（交付管线） | claude.com：Datadog 的"通用机床"工具 | 案例 | ⚪ | 反 MCP 工具膨胀的一手做法：Datadog 不给 Claude Code 塞几十个细粒度工具，而是造一个"通用机床"式的单一工具让模型自行组合调用——工具设计即 harness 的具体案例，与 #62 工具 schema 论、#54 DSL 工具集互证；案例文体裁，2026-07-21 | [claude.com](https://claude.com/blog/how-datadog-built-a-universal-machine-tool-for-claude-code) | | Simon Willison：smevals | 工具 | 🔵 | 作者自建的小型评测套件，明确定位"同时评 model、prompt 与 harness"三者——正好呼应 #35/#67 把三者拆开测的思路，可作轻量本地评测脚手架样本；待实测后再定去向，2026-07-31 | [simonwillison.net](https://simonwillison.net/2026/Jul/31/smevals/) | | Simon Willison：Cat & Thariq 炉边对谈 | 笔记/访谈 | ⚪ | #66（Thariq 的 Claude 5 上下文工程新规则）的口语化续篇：Claude Code 团队两人谈系统提示词瘦身、验证/评审外移到 skill、以及"新模型让很多显式脚手架变得多余"的一手取舍；访谈笔记体裁，配 #66 与 steering 官方指南看，2026-07-21 | [simonwillison.net](https://simonwillison.net/2026/Jul/21/cat-and-thariq/) | +| DeepSeek Harness 开发者预览 | 产品 | 🔵 | 头部实验室下场做 harness（HN 747 分，2026-08-13）；预览期无深度工程文，待实测/待其技术博客；与 #74 Pi 的开源中立主张构成反向信号 | [deepseek](https://deepseek.com/harness/en/) | +| Ronacher：What Is Reasoning | 随笔 | ⚪ | reasoning trace 只是训练出的频道约定、reasoning effort 即系统提示一行字——harness×模型接口层（channel/KV cache/prefill）的一手拆解；与 #62 同作者同视角，2026-08-19 | [lucumr](https://lucumr.pocoo.org/2026/8/19/what-is-reasoning/) | +| Osmani：Agentic Code Quality | 长文 | ⚪ | "质量取决于给 agent 的约束体系而非逐行把关"；论点与概念 3/6 重叠，价值在操作清单，2026-08-08 | [addyosmani](https://addyosmani.com/blog/agentic-code-quality/) | +| Osmani：Human judgment relocates | 长文 | ⚪ | 软件工厂里人的判断只迁移不消失，"仍有主人"的工厂构建指南；#64 工厂系列续篇，2026-08-21 | [addyosmani](https://addyosmani.com/blog/human-judgment-doesnt-leave-the-software/) | +| Willison：Conceptual integrity | 长文 | ⚪ | 千行级日产出后概念完整性/团队认知力成质量上限；与 #42 comprehension 关切合流，2026-08-19 | [simonwillison](https://simonwillison.net/2026/Aug/19/conceptual-integrity-and-counting-lines-of-code/) | +| Rachel Laycock：Citizens Build, Agents Execute, Experts Govern | 随笔 | ⚪ | 工程价值转向治理（护栏/平台/反馈环设计）；Conductor Developer（观察项）续篇，领导者视角定调文，2026-08-19 | [martinfowler](https://martinfowler.com/rachels-ramblings/citizens-agents-experts.html) | +| Dan Luu：coding agent 最优语言 | 长文 | ⚪ | token 效率与反馈质量角度的语言选型实证；与 Fowler retreat"Rust 替代 Python 强化传感器"（观察项）互证，2026-08-10 | [danluu](https://danluu.com/pl-tokens/) | +| Fabien Sanglard 的 agent.md | 随笔 | ⚪ | 知名图形程序员公开的 agent.md 质量约束清单（HN 414 分）；个体实践样本，2026-08-23 | [fabiensanglard](https://fabiensanglard.net/agent.md/index.html) | +| OpenAI 蜂群误攻击 Hugging Face 时间线 | 事件 | ⚪ | 多智能体隔离失效的标志性事故（Willison 整理时间线，2026-08-07）；与 #50 遏制、"non-agentic read"注入防御（观察项）对读 | [simonwillison](https://simonwillison.net/2026/Aug/7/openai-timeline/) | +| Claude Code auto mode 转默认 + 生产实践 | 产品/案例 | ⚪ | 自主性/权限 harness 的产品拐点（2026-08-07 对 Pro/Max/Team 默认化）+ Nuro/Gusto/Garner 生产实录；两篇合一行 | [默认化](https://claude.com/blog/auto-mode-default-in-claude-code) / [生产](https://claude.com/blog/auto-mode-in-production) | +| Claude Code 自托管执行环境 | 发布稿 | ⚪ | agent 运行环境自托管公测（自有算力/内网）；sandbox 基建层，发布稿体裁，2026-08-06 | [claude.com](https://claude.com/blog/run-claude-code-sessions-on-your-own-compute) | +| Anthropic：AI-Native SDLC playbook | 方法论 | ⚪ | 官方 SDLC 分阶段总纲（计划/设计/构建/测试/部署/维护）；组织级实践手册体裁，2026-08-21 | [claude.com](https://claude.com/blog/the-ai-native-sdlc-playbook) | +| Warp 自改进 agent 模式 | 案例 | ⚪ | 可复用的自改进 agent 开发模式；loop/反馈回路案例文体裁，2026-08-26 | [claude.com](https://claude.com/blog/how-warp-builds-self-improving-agents-on-claude) | +| Claude Tag 做 CI/CD 第一响应者 | 工程/案例 | ⚪ | 检测→分诊→修复 CI 失败的内部 agent 闭环；验证回路+on-call 范本，2026-08-18 | [claude.com](https://claude.com/blog/ai-ci-cd-on-call) | +| Cursor Router 模型路由 | 工程文 | ⚪ | 从真实开发者流量学习选模型，Auto 满意度超 Fable 级且成本 -68%；与 Switchyard 构成本窗口"路由"双证，2026-08-06 | [cursor](https://cursor.com/blog/how-cursor-router-works) | +| LangChain×NVIDIA Switchyard 路由基准 | 工程文 | ⚪ | 145 个 agent 任务：仅 7% 轮次需前沿模型，路由省 74% 成本、损 6 点精度；成本缺口数据点，2026-08-11 | [langchain](https://www.langchain.com/blog/switchyard-agent-routing-benchmark) | +| OpenAI 内部 data agent | 工程文 | ⚪ | 600PB/7 万数据集的自学习内部 agent，经 MCP 嵌入 Slack/IDE 工作流；官方站反爬、要点经外部佐证，2026-08-13 | [openai](https://openai.com/index/inside-our-in-house-data-agent/) | +| LangChain：Agent 环境与任务构造三步法 | 工程文 | ⚪ | 合成 evals 环境的方法论（spec 生成→spec 转任务→world spec）；#69 Harbor 评测栈续篇，2026-08-25 | [langchain](https://www.langchain.com/blog/building-agent-environments-and-tasks) | +| LangChain OpenWiki 双篇（WikiBench + 自纠错记忆） | 工程文 | ⚪ | wiki+源码 > 纯源码的基准证据 + 证据锚定 claim 检测过期知识；上下文供给/记忆侧，两篇合一行，2026-08 下旬 | [wikibench](https://www.langchain.com/blog/evaluating-openwiki-with-wikibench) / [memory](https://www.langchain.com/blog/self-correcting-memory-openwiki) | +| monday.com 双视角（Sidekick + agent-first 重构） | 案例 | ⚪ | 同一企业在 LangChain/Anthropic 两侧的实践叙述："有能力的 agent 光有工具不够"；两篇合一行，2026-08 | [langchain](https://www.langchain.com/blog/building-monday-com-sidekick-why-capable-agents-need-more-than-just-tools) / [claude.com](https://claude.com/blog/how-monday-com-transformed-its-platform-into-an-agent-first-product-where-humans-and-agents-collaborate) | +| Fowler Fragments 08-04/08-18/08-24 三则 | 短评 | ⚪ | 08-24 的 Zalando 引荐段（→ 已升格 #73）与 OpenAI 蜂群事件评述最有料；三则合一行 | [08-04](https://martinfowler.com/fragments/2026-08-04.html) / [08-18](https://martinfowler.com/fragments/2026-08-18.html) / [08-24](https://martinfowler.com/fragments/2026-08-24.html) | +| claude-code#6235：AGENTS.md 支持之争 | 讨论 | ⚪ | AGENTS.md vs CLAUDE.md 标准化的高热社区讨论（HN 377 分）；生态信号，2026-08-19 | [github](https://github.com/anthropics/claude-code/issues/6235) | +| Jake Saunders：自建沙箱化软件工厂 | 实践 | ⚪ | 个人全自托管软件工厂实录（sandbox+factory）；个体侧工厂样本，配 #63/#64 看，2026-08-21 | [blog.jakesaunders](https://blog.jakesaunders.dev/building-an-almost-fully-self-hosted-sandboxed-agentic-software-factory/) | +| One Recipe, Many Harnesses 论文 | 论文 | ⚪ | 固定演化配方跨 8 语言×3 基模型，拆"演化产物到底编码了什么"（基准过拟合 vs 语言知识 vs 模型补偿）；可移植性+失效模式+归因三缺口同中，UIUC+IBM，2026-08-10 | [arxiv 2608.10178](https://arxiv.org/abs/2608.10178) | +| HarnessRisk 安全基准论文 | 论文/基准 | ⚪ | 首个按 harness 六运营阶段（配置/扩展/运行/状态持久化/动作控制/事故恢复）组织的安全基准，128 沙箱案例×3 harness×6 模型；#33 开辟方向的后续，2026-08-18 | [arxiv 2608.17597](https://arxiv.org/abs/2608.17597) | +| Prompt-Induced Waste 论文 | 论文 | ⚪ | 控制实验证明提示语义×推理努力×harness 策略是交互因子而非独立控制项，效率应建模为"每成功任务成本"（token/缓存计数不是充分优化目标）；成本缺口正面数据，2026-08-02（v5 08-24） | [arxiv 2608.01347](https://arxiv.org/abs/2608.01347) | +| Fragility of Self-Improving Agents 论文 | 论文 | ⚪ | 重评基于记忆的自改进：多次运行量化方差+打乱任务顺序——自改进闭环放大评估噪声、改进高度依赖任务顺序，现有报告可能是顺序运气；方法论警钟，Salesforce 系，2026-08-18 | [arxiv 2608.18066](https://arxiv.org/abs/2608.18066) | +| 三 harness 架构收敛论文 | 论文/分析 | ⚪ | deepagents/pi/dsh 源码级对比：哲学对立的 harness 从相反方向（减法 vs 加法）收敛到同一五要素中间形态；与 #74 Pi 双篇对读，2026-08-25 | [arxiv 2608.23953](https://arxiv.org/abs/2608.23953) | +| 编码代理可靠性综述（Jarmak） | 论文/综述 | ⚪ | 164 篇文献+100 条实践记录："按模型评估、按系统部署"，大量"模型失败"实为 harness/状态/权限/资源层失败；检索地图体裁，2026-08-14 | [arxiv 2608.13867](https://arxiv.org/abs/2608.13867) | +| 自演化编码代理综述 | 论文/综述 | ⚪ | 首个结构化综述：按框架/记忆/技能工具/模型/工作流/环境六个演化对象分类；配 #45 Weng RSI 综述看，2026-08-04（v2 08-20） | [arxiv 2608.03392](https://arxiv.org/abs/2608.03392) | +| 8 月自动 harness 演化方法群（6 篇合并） | 论文群 | ⚪ | JIT-Agent（[2608.25593](https://arxiv.org/abs/2608.25593)）/ AutoSaddler（[2608.23041](https://arxiv.org/abs/2608.23041)）/ Harness-R1（[2608.02276](https://arxiv.org/abs/2608.02276)，在线 RL 训 9B "harness 工程师"）/ HarnessCompass（[2608.01918](https://arxiv.org/abs/2608.01918)，直接命名三大失效并逐一治理）/ HELIX（[2608.13951](https://arxiv.org/abs/2608.13951)）/ Living-Harness（[2607.26598](https://arxiv.org/abs/2607.26598) v2）——方法各异，共同点是把 harness 当可机器编辑工件；待出现独立复现或引用领先者再拆行 | （见左） | +| Ouroboros 自开发 harness 论文 | 论文 | ⚪ | "被评审的 commit"演化自身工具/提示/上下文组装，TB2.1 86.74%（Opus 5）/OSWorld-Verified 90.69%；演化安全阀（评审门控）样本，含 Yampolskiy，2026-08-08 | [arxiv 2608.08311](https://arxiv.org/abs/2608.08311) | +| StateM harness scaling 论文 | 论文 | ⚪ | 不动权重纯 harness scaling（持久状态+阶段局部上下文+受检转移+runbook）：GPT-5.6 Sol 达 TB2.1 95.3%；runbook 免改跨模型迁移 + 标题给出 $15 前沿成本点，2026-08-15 | [arxiv 2608.15089](https://arxiv.org/abs/2608.15089) | +| 技能污染与失效三篇（合并） | 论文群 | ⚪ | 技能池超临界后新技能反而降性能且结构不可逆+预提交门控（[2608.05810](https://arxiv.org/abs/2608.05810)）/ Demystifying Agent Skills 8,135 试验失效分类学（[2608.14036](https://arxiv.org/abs/2608.14036)）/ 联盟污染与跨域效用反转（[2608.22610](https://arxiv.org/abs/2608.22610)）——skills 机制的系统性失效证据 | （见左） | +| Evo-Bench + LoopsBench | 论文/基准 | ⚪ | 评"模型改进 harness 的内在能力"并隔离基模型强度（[2608.09096](https://arxiv.org/abs/2608.09096)）+ ByteDance 长程基准：可分测依赖 DAG+回归义务，最强配置仅 ~25%（[2608.00267](https://arxiv.org/abs/2608.00267)）；评测方法论双证 | （见左） | +| Working Set / Coherence Debt 论文 | 论文 | ⚪ | 耦合事实图+通道供给/扣留+故障注入，跨 7 模型×5 harness：事实可得性决定成败而距离无关、不同 harness 为同一事实付出不等代价；组件归因直接证据，2026-08-17 | [arxiv 2608.16630](https://arxiv.org/abs/2608.16630) | +| Replay Gap 论文 | 论文 | ⚪ | 分叉实跑（~900 rollout）证伪"重放日志换模型"静态路由评估：换模型分叉重写 61-94% 后续动作、74-77% 首步即分歧；跨模型不可静态外推，2026-08-08 | [arxiv 2608.08239](https://arxiv.org/abs/2608.08239) | +| Harness-IF + Feedback That Backfires | 论文 | ⚪ | 部署 harness 五个指令面的运维规则合规评测，Against-Prior Accuracy 区分"合规 vs 碰巧"（[2608.11727](https://arxiv.org/abs/2608.11727)）+ "失败进 transcript 即纠错"假设对指令微调小模型为负增益、失败后重复同一调用概率 0.06→0.54（[2608.23653](https://arxiv.org/abs/2608.23653)）；harness 设计假设的行为验证 | （见左） | +| 自演化安全攻击群（4 篇合并） | 论文群 | ⚪ | SkillJack 持久技能后门（[2608.03509](https://arxiv.org/abs/2608.03509)）/ 轨迹投毒 91.0% SER（[2608.05563](https://arxiv.org/abs/2608.05563)）/ harness 提取攻击——harness 视为 IP（[2607.28147](https://arxiv.org/abs/2607.28147) v4）/ 金融 agent 自演化能力与风险同增（[2608.17684](https://arxiv.org/abs/2608.17684)）——自演化×安全攻防谱系，配 HarnessRisk 看 | （见左） | +| MCP vs CLI + DCAS | 论文 | ⚪ | 7 scaffold×5 模型可复现实验：主导效应是 scaffold 而非工具接口（[2608.08654](https://arxiv.org/abs/2608.08654)）+ 开源微调数据几乎全采自 OpenHands 导致模型 scaffold 锁定、基模型无此分歧（[2608.06113](https://arxiv.org/abs/2608.06113)，Queen's）；可移植性双证 | （见左） | +| LangChain harness/loop 核心系列（存量回扫，12 篇合并） | 信源级 | ⚪ | 2026-08-27 回扫发现的系统性缺口：improving-deep-agents-with-harness-engineering（02-17，TB Top30→Top5）、better-harness（04-08，evals 爬山）、the-art-of-loop-engineering（06-16）、how-to-build-a-custom-agent-harness（06-03）、middleware 两篇、frameworks-runtimes-harnesses（2025-10）、tuning-the-harness-not-the-model（07-08，开源模型 ~8x 低成本追平 Opus 4.8）、your-harness-your-memory（04-11）、deep-agents 开山文（2025-07）、tuning-deep-agents-different-models（04-29）、Candidly 案例（06-29）——完整清单见 translate/2026-08-27/candidates.md 留档；某篇被引用或需要时再单独升格 | [入口](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering) | +| claude.com 机制文系列（存量回扫，合并） | 信源级 | ⚪ | 同批回扫缺口：skills 全系列（Introducing Agent Skills 2025-10-16 起 8 篇）、subagent/multi-agent 系列 4 篇、Lessons from building Claude Code 双篇（skills 06-03 / prompt caching 04-30）、dynamic workflows 发布文、hooks/plugins/CLAUDE.md/session 管理等机制文——完整清单见 translate/2026-08-27/candidates.md；同上处理 | [入口](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything) | > 三篇短 bliki / 随笔（Vibe Coding、Interrogatory LLM、Genie Tarpit）若日后要收，建议合并成一个「概念定义 / 上下文工程 pattern」小专题，别各开条目稀释精品信号。 > diff --git a/works/AGENTS.md b/works/AGENTS.md index 6bbb0b0..432fe28 100644 --- a/works/AGENTS.md +++ b/works/AGENTS.md @@ -78,6 +78,12 @@ sourceFigureAudit: # 仅当 sourceFigureCount 为 0 时必填：核对留痕， | [ronacher-better-models-worse-tools-translation.md](ronacher-better-models-worse-tools-translation.md) | Better Models: Worse Tools | Armin Ronacher / 个人博客 | | [anthropic-context-engineering-claude5-translation.md](anthropic-context-engineering-claude5-translation.md) | The new rules of context engineering for Claude 5 generation models | Anthropic / Claude · Thariq Shihipar | | [langchain-reviewbench-translation.md](langchain-reviewbench-translation.md) | Evaluating code review agents with ReviewBench | LangChain / Nick Hollon | +| [fowler-tdd-in-agent-loop-translation.md](fowler-tdd-in-agent-loop-translation.md) | TDD inside the agent loop - theater or actual value? | Birgitta Böckeler | +| [osmani-practical-loop-engineering-translation.md](osmani-practical-loop-engineering-translation.md) | Practical Loop Engineering | Addy Osmani | +| [zalando-agentic-engineering-translation.md](zalando-agentic-engineering-translation.md) | Agentic Engineering at Zalando: A Snapshot | Bartosz Ocytko | +| [pi-what-is-a-harness-translation.md](pi-what-is-a-harness-translation.md) | What Is a Harness? | Earendil / Pi 团队 | +| [pi-compaction-translation.md](pi-compaction-translation.md) | How Compaction Works in Pi | Earendil / Pi 团队 | +| [arxiv-starharness-translation.md](arxiv-starharness-translation.md) | StarHarness: Evolving Harnesses with Stratified Search for Enterprise Environments | ServiceNow / Mila 等 | ### 中文转译 / 二手资料 diff --git a/works/arxiv-starharness-translation.md b/works/arxiv-starharness-translation.md new file mode 100644 index 0000000..0d54d6f --- /dev/null +++ b/works/arxiv-starharness-translation.md @@ -0,0 +1,263 @@ +--- +title: "StarHarness：用分层搜索为企业环境演化 Harness" +sourceTitle: "StarHarness: Evolving Harnesses with Stratified Search for Enterprise Environments" +sourceUrl: "https://arxiv.org/abs/2608.24804" +sourceAuthor: "Esakkivel Esakkiraja et al.（ServiceNow；Mila；Université de Montréal）" +sourcePublishedAt: "2026-08-25" +sourceSiteName: "arXiv" +summary: "ServiceNow 系团队提出 StarHarness：模型权重固定，只演化环境特定的 harness（提示词、工具接口、skills、MCP provider、subagent、agent-loop 配置）。按基线失败模式分层抽样出紧凑演化池，并把 proposer 可见搜索集、proposer 不可见选择集与留出评估集三层隔离。在 ITBench SRE、EnterpriseOps-Gym ITSM、AutomationBench Finance 上，每环境仅 4–12 个被接受变更即带来 20–35 个百分点的全基准提升；增益在留出任务上保持，并免重演化跨 GPT 与 Qwen 模型家族迁移（12 组迁移全为正，+10.7~+46.3 pp），单任务成本反降 17–53%。轨迹分析把增益归为接口修复、环境惯例与压缩搜索的运营知识三类。" +sourceLanguage: "en" +language: "zh-CN" +translationMethod: "人工整理逐段翻译（cloud agent，对照 arXiv HTML 全文）" +sourceFigureCount: 5 +sourceFigureAudit: "2026-08-27 抓 arXiv HTML 全文核对：
元素共 8 个，其中编号插图 3 幅（Figure 1–3）共含 5 张 PNG，另 5 个为 Table 1–5 的表格包裹（以 markdown 表保真）；5 张 PNG 已全部下载本地嵌入" +--- + +# StarHarness：用分层搜索为企业环境演化 Harness + +> 原文：StarHarness: Evolving Harnesses with Stratified Search for Enterprise Environments +> 作者：Esakkivel Esakkiraja, Denis Akhiyarov, Vikas Yadav, Sai Rajeswar, Patrice Bechard, Sridhar Nemala, Sagar Davasam（ServiceNow；Mila；蒙特利尔大学） +> arXiv:2608.24804，提交于 2026-08-25 | 代码：github.com/ServiceNow/StarHarness + +## 摘要 + +我们提出 StarHarness，一个在保持模型权重固定的前提下、演化环境特定智能体 harness 的框架。被演化的 harness 可以包括提示词与任务框定、工具接口、skills、MCP 支撑的 provider、subagent 结构，以及 agent-loop 配置。StarHarness 按基线失败行为对任务分层，构建一个紧凑的演化池；把 proposer 可见的搜索任务与 proposer 不可见的选择任务分离；并保留留出（held-out）任务用于评估泛化。在 ITBench SRE、EnterpriseOps-Gym ITSM 和 AutomationBench Finance 三个基准上，harness 演化在每个环境仅接受 4–12 个变更之后，将全基准性能相对默认 harness 提升 20–35 个百分点。这些增益在被排除于演化之外的任务上持续存在，并且无需重新演化即可跨 GPT 与 Qwen 模型家族迁移。轨迹分析将这些改进归因于接口修复、环境惯例、以及压缩搜索的运营知识，并在若干设置中观察到更少的假阳性诊断和更短的轨迹。因此，StarHarness 为减少工具密集型企业任务中持续存在的模型–环境失配提供了一条实用路径。 + +## 1 引言 + +现代 LLM 智能体通过 harness 行动，harness 定义了它们如何使用工具、如何解释状态。工具增强型智能体依赖推理、动作与外部状态之间的交互（Yao et al., 2023; Schick et al., 2023）。在工具密集的企业任务中，harness 设计决定了智能体能否检索到正确的记录、执行有效的变更操作、并满足精确的最终状态检查（Rombaut, 2026; Meng et al., 2026）。接口设计可以在不改变模型权重的情况下改变智能体行为与任务成功率（Yang et al., 2024）。 + +企业服务管理与工作流智能体必须通过有状态的后端、庞大的工具面、跨步骤依赖、以及工具 schema 常常遗漏的领域惯例来行动。我们的基准捕捉了这个更广泛问题的不同实例：ITBench 测试基于运维遥测数据的根因分析（Jha et al., 2025）；EnterpriseOps-Gym 用数据库断言测试改变状态的 ITSM 工作流（Malay et al., 2026）；AutomationBench 用程序化状态检查测试多应用财务工作流（Shepard & Salimans, 2026）。它们共同暴露了让企业工具使用变得困难的状态依赖、策略约束和最终状态要求（Yao et al., 2024; Lu et al., 2024），并提出三个问题：搜索能否从一个紧凑的任务子集演化出 harness 而不对该子集过拟合？由此产生的变更能否迁移到未见过的任务和其他模型？harness 演化到底修复了哪些交互失败？ + +StarHarness 通过在保持模型权重固定的前提下演化环境特定的 harness 来回答这些问题。该方法按基线失败行为对任务分层，把 proposer 可见的搜索任务与 proposer 不可见的选择任务分离，并保留留出任务用于评估。 + +我们的贡献： + +1. **高效的分层 harness 演化。** 我们提出一个 harness 演化协议：在按失败模式分层的紧凑任务子集上搜索，同时分离 proposer 可见的搜索任务、proposer 不可见的选择任务与留出评估任务。这提供了对泛化的直接度量。 +2. **专用 harness 的任务与模型迁移。** 在三个有状态企业基准上，用一个模型演化出的 harness 能改进被排除于演化之外的任务，并且无需重新演化即可跨 GPT 与 Qwen 模型迁移。 +3. **对习得专门化的分析。** 我们识别出三种反复出现的环境专门化形式：接口修复、环境惯例、以及压缩搜索的运营知识，并把它们与智能体的精确度、收敛性和效率的变化联系起来。 + +## 2 相关工作 + +### 2.1 提示词与 Harness 优化 + +提示词优化方法用生成的候选、文本反馈或演化式选择来搜索指令与示例（Opsahl-Ong et al., 2024; Agrawal et al., 2025）。智能体架构方法把搜索扩展到可执行模块与工作流结构（Khattab et al., 2024; Zhang et al., 2025）。 + +近期的 harness 级系统直接编辑可执行的脚手架，或将 harness 与模型策略、权重共同演化（Lee et al., 2026; Hebbar et al., 2026）。 + +StarHarness 研究一个更窄的部署问题：把一个冻结模型的 harness 适配到一个有状态的企业环境。其搜索空间包括提示词、工具、skills、MCP provider、subagent 与执行策略。这一文献中的评估协议各不相同：Meta-Harness 在文本分类和数学推理上使用留出集，但在同一个 89 任务的 TerminalBench-2 基准上搜索并报告最终性能，其作者将此框定为"发现"（discovery）设定（Lee et al., 2026）。我们使用任务级分离、proposer 不可见的选择集与留出评估来区分搜索性能与泛化，呼应了近期对更严格 harness 演化评估的呼吁（Wang et al., 2026）。所产生的编辑始终位于模型权重之外，可以像普通代码变更一样被测试和回滚。 + +### 2.2 智能体基准与企业环境 + +现有基准以不同的交互接口覆盖了相关的智能体场景。WorkArena（Drouin et al., 2024）研究 ServiceNow 平台上基于浏览器的知识工作，Terminal-Bench 2.0（Merrill et al., 2026）在隔离环境中评估困难的命令行任务。我们聚焦三个互补的企业场景：ITBench（Jha et al., 2025）包含 40 个 Kubernetes 根因分析场景，智能体在给出结构化诊断之前需要检查告警、事件、trace、指标与拓扑；EnterpriseOps-Gym（Malay et al., 2026）包含 103 个 ITSM 工作流，横跨事件、问题、变更、知识与用户管理任务，用 SQL 验证器检查最终的 ServiceNow 状态；AutomationBench（Shepard & Salimans, 2026）包含 100 个财务工作流，横跨 47 个模拟 SaaS 应用，用针对环境状态的程序化断言打分。这些基准要求智能体操作领域工具、维护持久状态、满足工作流特定目标。我们用它们来度量一个冻结的专用 harness 的任务级泛化与跨模型迁移。 + +## 3 方法 + +### 3.1 概览 + +我们把 harness 演化定义为对围绕固定语言模型的可执行脚手架的外环（outer-loop）优化。在我们的实现中，StarHarness 优化器是一个基于 Oh My Pi（contributors, 2026）——Pi agent harness（Zechner, 2026）的一个变体——构建的编码 harness。它承载 proposer 并执行"编辑、验证、评估"循环：暴露被允许的仓库与基准轨迹，应用候选补丁，运行检查，并发起基准评估。优化器修改的是另一个独立的 Stirrup harness（Artificial Analysis, 2026），后者是被评估的智能体 harness。其可编辑面包括提示词与任务框定、工具定义与 schema、参数预处理、skills、MCP provider、subagent 结构、上下文管理、验证与结束逻辑。演化期间模型权重与基准保持固定。 + +设 D 表示一个基准，h 表示一个 harness，M 表示智能体模型，J(h; D) 为代价函数，此处定义为用 h 驱动 M 在 D 上运行得到的平均任务分数，越高越好。优化目标是 + +> h* = argmax_{h ∈ H} J(h; D_holdout)　　(1) + +其中 H 是被允许的 harness 空间。StarHarness 在搜索期间无法访问留出集的结果，因此它用 proposer 可见的搜索任务和（适用时）proposer 不可见的选择任务来近似这一目标，把 D_holdout 保留给最终评估。 + +编码 harness 运行三个阶段：提议、验证、评估。proposer 读取当前 harness 与搜索集轨迹并返回一个候选补丁。验证器检查作用域、import 与单任务冒烟测试。当存在选择集时，评估器在不可见的选择集上运行有效候选；演化循环应用固定的接受规则。遵循 autoresearch 模式（Karpathy, 2026），演化循环先测量基线，提出一个有界干预，评估它，只保留改进，然后从新的前沿（frontier）重复。一个持久的记忆台账（memory ledger）把补丁、会话与评估工件关联起来，并把前沿分数、逐任务结果、被接受的假设和被丢弃的尝试带入后续迭代。对树搜索而言，台账是一个解日志（solution journal），包含候选节点、父链接、分数、失败状态与晋升决策。图 1 以算法形式给出该过程。 + +演化循环首先运行一个由 proposer 选定的单任务翻转测试（test flip）。如果候选没能翻转该任务，循环记录一次拒绝并跳过昂贵的评估。通过该门槛的候选在选择集上评估；晋升保持确定性：候选必须改进选择集均值，只有当验证器通过率这一额外指标可用时才用它做平手判定。循环把被接受的候选提交为新前沿并刷新搜索轨迹；被拒绝、无效或崩溃的候选回滚到之前的前沿。 + +![图 1：StarHarness 演化流程](imgs/arxiv-starharness/starharness_overview.png) + +**算法 1：StarHarness 演化** +输入：基准 D；固定模型 M；种子 harness h₀；proposer P；预算 B。输出：演化后的 harness h*。 +1. 在 D 上运行 h₀；记录分数与失败分层 +2. 构建 D_search、D_select、D_holdout +3. h ← h₀；s ← J(h; D_select)；初始化台账 L +4. for t = 1, …, B： +5. 　L ← 加载台账；T ← 收集搜索轨迹 +6. 　Δ ← P(h, T, L)；把 Δ 捕获为限定作用域的补丁 +7. 　若作用域、泄漏、import 或冒烟检查失败：回滚并记录拒绝 +8. 　否则运行 proposer 选定的翻转测试 +9. 　　若翻转测试失败：回滚并记录拒绝 +10. 　　否则在不可见的 D_select 上评估 h ⊕ Δ +11. 　　　若选择集分数改进，或持平且可用的验证器指标改进：提交 h ⊕ Δ；更新 L；刷新 T +12. 　　　否则：回滚 Δ；更新 L +13. 返回 h；在 D_holdout 与 D 上各评估一次 + +> 图 1：StarHarness 演化。上：对应的工作流；下：可执行过程。proposer 读取当前前沿、持久记忆台账与搜索集轨迹，但永远看不到选择集或留出集轨迹。候选先通过限定作用域的验证与 proposer 选定的翻转测试，再进入不可见的选择集评估；被接受的编辑推进已提交的前沿并刷新台账与搜索轨迹。对树搜索而言，台账存储候选节点与父链接，而不只是单一贪心前沿。 + +### 3.2 任务划分与分层抽样 + +我们在演化开始前构建任务划分。从共 N 个任务的完整基准中，先保留 N′ 个评估可复现的任务，然后用三个基线描述量抽样出一个 K 个任务的演化池（通常 K ≈ N/2）： + +- 基线失败模式（如 wrong_tool、context_loss、missing_evidence、premature_conclusion） +- 基线任务分数 +- 验证器通过率 + +这些描述量来自演化前在全部 N′ 个任务上的一次基线运行。当协议使用选择集时，我们把演化池拆分为 proposer 可见的搜索任务与 proposer 不可见的选择任务，并匹配二者的基线分数、失败模式与验证器通过率分布。proposer 收到搜索任务的轨迹与结果，但收不到选择任务的内容、轨迹、验证器反馈或逐任务结果。其余 N′−K 个任务构成留出集，永远不影响提议或接受。 + +### 3.3 搜索策略：探索与利用 + +我们在两种搜索过程中使用相同的 proposer、验证器、评估器与接受分数。在爬山法（hill climbing）中，状态是单一的前沿 harness。在第 t 次迭代，proposer 从当前前沿的轨迹中产出一个补丁 Δₜ；系统当且仅当 hₜ ⊕ Δₜ 严格改进选择集分数、或持平且改进可用的验证器指标时保留它，否则恢复 hₜ。 + +在树搜索中，状态是一组候选节点。每个节点存储父指针、累积补丁、搜索轨迹、验证状态与选择集分数。proposer 可以探索一个失败模式、起草一个补丁、调试一个失败的候选、合并两个兼容节点、或改进一个已有节点。有效节点在同一个不可见选择集上打分；最佳存活节点成为后续精化的前沿。这保留了备选假设，而不是在第一个被接受的编辑后就锁定。 + +我们仅在 EnterpriseOps-Gym 上把这两种模式用作一个探索–利用对照实验。树搜索探索备选假设；爬山法随后通过有界的局部编辑利用最佳的树前沿。两个阶段是先后进行的，因此这个设计描述的是两种模式如何互补，而不提供因果性的正面对比。 + +### 3.4 护栏与候选隔离 + +StarHarness 执行的是基准辅助的环境适配：proposer 可以检查搜索任务的轨迹及其评估结果以诊断反复出现的失败，但护栏防止它编码任务特定的答案。 + +每个候选是相对当前前沿的一个 git diff，作用域限定在基准的可编辑目录与共享智能体框架内。被禁止的变更包括： + +- 按任务 ID 分支或硬编码答案 +- 在智能体提示词中放入验证器或断言内容 +- 真值表或对隐藏状态的访问 +- 基准特定的答案映射 + +这些约束瞄准的是可复用的环境行为，而非单个任务的解。验证器在基准评估前检查作用域、import 与单任务冒烟测试。演化循环对未通过任何检查的候选直接回滚，不运行选择集评估。 + +## 4 实验 + +### 4.1 实验设置 + +**基准。** 我们在三个企业基准上评估： + +- **ITBench SRE**（Jha et al., 2025）：ITBench-AA SRE 集的最新公开版本，包含来自 OpenTelemetry demo 应用的 40 个 Kubernetes 根因分析场景（数据集：huggingface.co/datasets/ArtificialAnalysis/ITBench-AA）。智能体检查一个包含告警、事件、trace、指标与拓扑的离线事故快照，然后写出识别相关实体的结构化诊断。我们的 Stirrup 基线在可用之处遵循文档化设置，包括沙箱代码执行环境、基于 shell 的快照检查与结构化 JSON 输出。 +- **EnterpriseOps-Gym ITSM**（Malay et al., 2026）：103 个 ITSM oracle 任务（事件、问题、变更、知识与用户管理），是更大的 1,150 任务基准的一个子集，针对 ServiceNow MCP 后端运行，由检查最终数据库状态的 SQL 验证器打分。 +- **AutomationBench Finance**（Shepard & Salimans, 2026）：100 个财务工作流任务（应付/应收、费用、报表、记账），横跨 47 个模拟 SaaS 应用，由针对环境状态的程序化断言打分。我们报告模型达成的领域目标份额；护栏违规使该任务得 0 分。我们的 Finance-100 子集与 Stirrup harness 不同于基准论文的默认设置，因此分数与 Shepard & Salimans (2026) 报告的分数不可直接比较。 + +三个基准均按 Artificial Analysis 的评估描述（artificialanalysis.ai/evaluations）打分。对 AutomationBench，该分数由模型达成的领域目标份额计算，护栏违规使任务得 0 分。 + +**模型。** 我们用 GPT-5.4（medium 推理）作为受测智能体模型演化 harness，proposer 同为 GPT-5.4，运行在基于 Pi 的编码 harness 内（OpenAI, 2026）。随后我们把同一个冻结的演化后 harness——不做重新演化——在每个基准上评估更多 GPT 与 Qwen 模型，包括 Qwen3.6（Qwen Team, 2026）。 + +**基线。** 各基准的基线是带默认提示词与工具配置的未修改 Stirrup 智能体框架。我们还与独立的 Pi、Codex harness，以及叠加在 Pi harness 之上的 GEPA 提示词优化对比。 + +### 4.2 主结果 + +图 2 汇总了全基准 harness 对比。分数采用各基准自身的指标，越高越好。StarHarness (Stirrup) 指演化后的 Stirrup harness，GEPA (Pi) 指叠加在 Pi harness 上的提示词优化。 + +StarHarness (Stirrup) 在全部三个基准上都是最强配置。相对 GEPA (Pi)（Agrawal et al., 2025），在 ITBench、EnterpriseOps-Gym 与 AutomationBench 上的增益分别为 +13.8、+22.3、+17.6 个百分点。这一对比是描述性的：这些系统在提示词、工具、执行策略与 harness 架构上都不同，因此无法隔离单一因果成分。该结果表明：环境特定的 harness 设计能在纯提示词优化之外增加可观的性能。 + +性能增益还伴随着更低的 GPT-5.4 单任务推理成本估计：按公布价格（OpenAI, 2026），StarHarness 在 ITBench 上降低成本 17%，在 EnterpriseOps-Gym 上降低 53%，在 AutomationBench 上降低 29%。 + +![图 2a：ITBench SRE 全基准 harness 对比](imgs/arxiv-starharness/harness_comparison_itbench.png) + +![图 2b：EnterpriseOps-Gym ITSM 全基准 harness 对比](imgs/arxiv-starharness/harness_comparison_eops.png) + +![图 2c：AutomationBench Finance 全基准 harness 对比](imgs/arxiv-starharness/harness_comparison_automationbench.png) + +> 图 2：ITBench SRE、EnterpriseOps-Gym ITSM 与 AutomationBench Finance 的全基准 harness 对比。GEPA (Pi) 指叠加在 Pi harness 上的提示词优化；StarHarness (Stirrup) 指演化后的 Stirrup harness。AutomationBench 分数为模型达成的领域目标份额，护栏违规记 0 分。 + +### 4.3 冻结跨模型迁移 + +表 1 汇总了全部三个基准上的冻结 harness 迁移结果。每个演化后 harness 的分数用的都是同一个以 GPT-5.4 演化出的 StarHarness 工件；对被迁移的模型未做任何基准特定的重新演化。该 harness 改进了表中每一个被迁移的模型，包括 GPT 与 Qwen 两个家族。 + +**表 1：冻结 StarHarness 的跨模型迁移。数值为全基准分数；括号内为推理档位（如适用）。** + +| 基准 | 模型 | 基线 | StarHarness | Δ | +|---|---|---|---|---| +| ITBench | Qwen3.5-27B | 25.6% | 70.0% | +44.4 pp | +| ITBench | GPT-5.4-mini (medium) | 33.1% | 79.4% | +46.3 pp | +| ITBench | GPT-5.4 (medium) | 40.0% | 75.0% | +35.0 pp | +| ITBench | GPT-5.5 (medium) | 50.8% | 78.7% | +27.9 pp | +| EnterpriseOps-Gym | Qwen3.6-27B | 18.2% | 38.8% | +20.6 pp | +| EnterpriseOps-Gym | GPT-5.4-mini (medium) | 13.6% | 31.1% | +17.5 pp | +| EnterpriseOps-Gym | GPT-5.4 (medium) | 23.3% | 43.7% | +20.4 pp | +| EnterpriseOps-Gym | GPT-5.5 (high) | 37.8% | 48.5% | +10.7 pp | +| AutomationBench | Qwen3.6-27B | 48.2% | 75.5% | +27.3 pp | +| AutomationBench | GPT-5.4-mini (medium) | 29.6% | 70.0% | +40.4 pp | +| AutomationBench | GPT-5.4 (medium) | 57.1% | 83.2% | +26.1 pp | +| AutomationBench | GPT-5.5 (medium) | 59.6% | 84.9% | +25.3 pp | + +作为参照，EnterpriseOps-Gym 一轮还报告了外部 Claude 参考分数：48.1%（Fable 5）、35.9%（Sonnet 5）、35.5%（Opus 4.8 max），见图 3。这些参考运行不属于受控的"基线–StarHarness"对比。 + +![图 3：EnterpriseOps-Gym 模型迁移榜单](imgs/arxiv-starharness/eops_benchmark_comparison.png) + +> 图 3：EnterpriseOps-Gym 模型迁移榜单。Claude Fable 5 分数是外部 Artificial Analysis 参考值，不属于受控的基线–StarHarness 对比。 + +### 4.4 留出泛化 + +表 2 汇总了 GPT-5.4 在三个基准上的泛化情况。 + +**表 2：GPT-5.4 泛化汇总。数值为绝对增益（百分点）。** + +| 基准 | 模型 | 演化集 | 留出集 | +|---|---|---|---| +| ITBench | GPT-5.4 | +45.0 | +31.7 | +| EnterpriseOps-Gym | GPT-5.4 | +22.0 | +15.1 | +| AutomationBench | GPT-5.4 | +23.0 | +29.3 | + +## 5 分析：Harness 演化学到了什么 + +三次演化运行共接受了 21 个补丁：ITBench 4 个、EnterpriseOps-Gym 12 个、AutomationBench 5 个。在 EnterpriseOps-Gym 上，8 个被接受的补丁来自树搜索探索阶段，4 个来自随后的爬山阶段。树阶段暴露了相互作用的 schema、提示词与工具失败；爬山阶段随后加入了针对性的关联与落地修复。跨基准来看，这些编辑处理了三类模型–环境摩擦。 + +**接口修复。** EnterpriseOps-Gym 的演化修复了 MCP 参数处理，保留了复合 schema，剪除了误导性字段，并加入了关联与自引用提示。这些变更让既有环境接口更可用，而不改变任务数据或验证器。AutomationBench 类似地获得了结构化的行操作，替换了脆弱的原始电子表格编辑。 + +Codex 在 EnterpriseOps-Gym 上提供了一个贴近的参照：它得 41.7%，StarHarness 为 43.7%。Codex 默认的 MCP 预处理会归一化并压缩 schema，减少对严格的 Docker 后端服务器的无效调用——该服务器会拒绝违反 schema 的显式 null 与空值。StarHarness 学到了互补的修复：先收窄并丰富 schema，然后在调用抵达服务器之前剥除 null、空值与占位参数。 + +**环境惯例。** 演化后的 harness 把隐性的运营规则显式化。例子包括 EnterpriseOps-Gym 的执行契约、优先级与影响度/紧急度的联动更新、以及保留关系字段的要求。在 AutomationBench 中，系统指引把相对日期锚定到沙箱时钟，并在变更操作前加入分诊（triage）步骤。harness 编码了这些流程，而模型权重保持固定。 + +**运营知识与搜索压缩。** 若干补丁把可重复的工作移出了开放式推理。ITBench 获得了一个取证概览（forensics overview），从观察到的证据对候选上游原因排序。AutomationBench 获得了日期与财务计算器，用于确定性的时间与数值运算。这些变更编码了运营知识并压缩了搜索；它们暴露的是从任务环境导出的信息，不访问标签或验证器状态。 + +### 5.1 轨迹分析 + +每张表报告基线、演化后 harness 及可配对记录上的绝对变化。 + +**ITBench。** 表 3 报告全部 40 个任务上的全基准分数与执行轨迹。演化把任务分数从 40.0% 提升到 75.0%，减少了轮次与假阳性，增加了真阳性，同时 shell 调用数量相当。 + +**表 3：ITBench（GPT-5.4）全基准分数、执行轨迹与估计 API 成本对比（全部 40 个任务）。** + +| 指标 | 基线 | 演化后 | Δ | +|---|---|---|---| +| 全基准任务分数 | 40.0% | 75.0% | +35.0 pp | +| 每任务轮次 | 25.2 | 22.1 | −3.1 | +| Shell 调用 | 49.8 | 46.7 | −3.1 | +| 每任务成本 | $3.26 | $2.70 | −17% | +| 假阳性 | 0.79 | 0.33 | −0.46 | +| 真阳性 | 0.45 | 0.78 | +0.33 | + +演化后的智能体在检查相当数量原始证据的同时，用更少的轮次得出更准确的结论。回归（regression）出现在本应终止于近因、上游搜索却仍在继续的情形。 + +**EnterpriseOps-Gym。** 表 4 报告全基准的任务成功率与执行轨迹。演化缩短了工作流并提高了验证器完成率。 + +**表 4：EnterpriseOps-Gym（GPT-5.4）全基准任务成功、执行轨迹与估计 API 成本对比（103 个任务）。** + +| 指标 | 基线 | 演化后 | Δ | +|---|---|---|---| +| 全基准任务成功率 | 23.3% | 43.7% | +20.4 pp | +| 每任务轮次 | 18.12 | 9.87 | −8.25 | +| 工具调用 | 29.53 | 16.83 | −12.70 | +| 每任务成本 | $1.23 | $0.58 | −53% | +| 验证器通过率 | 34.5% | 72.8% | +38.3 pp | + +schema 与参数修复针对工具选择；执行与结束契约针对不完整的工作流；自引用与关联提示在相互依赖的变更操作间保持状态。 + +**AutomationBench。** 表 5 报告完整的 GPT-5.4 执行记录对比。在完整的 GPT-5.4 任务集上，演化减少了不安全执行并改善了部分完成。 + +**表 5：AutomationBench（GPT-5.4）执行记录与估计 API 成本对比（100 个任务）。** + +| 指标 | 基线 | 演化后 | Δ | +|---|---|---|---| +| 领域目标分数 | 57.1% | 83.2% | +26.1 pp | +| 平均部分得分 | 67.3% | 86.1% | +18.8 pp | +| 每任务轮次 | 16.35 | 11.98 | −4.37 | +| 每任务成本 | $0.14 | $0.10 | −29% | +| 有护栏违规的任务数 | 20 | 4 | −16 | +| 护栏违规总数 | 33 | 4 | −29 | +| 零分任务数 | 24 | 6 | −18 | + +该 harness 把分诊放在变更操作之前，把日期锚定到沙箱时钟，并把算术与电子表格操作委托给确定性工具。我们无法从这些记录中隔离任何单个工具的贡献。 + +在全部三个基准上，被接受的编辑或修复了接口、或显式化了环境惯例、或编码了运营知识、或压缩了对可用证据的搜索。我们无法从配对对比中隔离单个补丁的因果贡献。 + +## 6 结论 + +我们的结果表明：当围绕固定模型的 harness 被适配到环境时，模型可以大幅改进。在 ITBench、EnterpriseOps-Gym 与 AutomationBench 上，StarHarness 学到了对工具接口的修复、环境惯例、运营知识与搜索压缩辅助。这些变更改进了全基准分数，泛化到被排除于演化之外的任务，并且无需重新演化 harness 即可跨 GPT 与 Qwen 模型家族迁移。在可测量的设置中，轨迹分析把增益与更短的工作流、更少的假阳性诊断和更少的不安全执行联系起来。 + +这些结果表明：对有状态的企业智能体而言，harness 演化是模型扩展（model scaling）之外一个实用的补充。搜索改变的是一个固定模型如何检索记录、调用工具、保持依赖、验证副作用。未来方向是通过强化学习共同演化 harness 与模型权重，让脚手架与策略共同专门化于企业交互协议。这可能产出更小、更高效的企业模型，并检验联合的 harness–权重优化能否以更低的推理成本匹敌或超越更大的模型。 + +--- + +*译注：本文完整翻译了论文正文（摘要、第 1–6 节，含图 1–3 说明与表 1–5 全部数据）。省略部分：References 参考文献列表（25 条，原文条目见 `sources/arxiv-starharness/source-full.md`）以及 arXiv HTML 页面模板性内容（报错指引等）。本论文 HTML 版无附录。* diff --git a/works/fowler-tdd-in-agent-loop-translation.md b/works/fowler-tdd-in-agent-loop-translation.md new file mode 100644 index 0000000..94f3368 --- /dev/null +++ b/works/fowler-tdd-in-agent-loop-translation.md @@ -0,0 +1,334 @@ +--- +title: "agent 循环里的 TDD——表演，还是真有价值？" +sourceTitle: "TDD inside the agent loop - theater or actual value?" +sourceUrl: "https://martinfowler.com/articles/exploring-gen-ai/tdd-in-the-agent-loop.html" +sourceAuthor: "Birgitta Böckeler" +sourcePublishedAt: "2026-08-10" +sourceSiteName: "martinfowler.com" +summary: "Böckeler 用一个探索性 eval 检验「让 agent 在自己的循环里做 TDD」是否值得：Sonnet 4.6 生成方案、Opus 4.8 盲评，5 个批次下 TDD 无质量优势、mutation score 无差异，token 反而贵 3–8.5 倍。她逐条检视 TDD 六大目标在 agent loop 内的失效方式，主张放弃规定过程、转向 mutation testing、静态分析与 Approved Scenarios 等结果导向的反馈机制。" +sourceLanguage: "en" +language: "zh-CN" +translationMethod: "人工整理逐段翻译（cloud agent，对照原文全文）" +sourceFigureCount: 2 +--- + +# agent 循环里的 TDD——表演，还是真有价值？ + +> 原文：[TDD inside the agent loop - theater or actual value?](https://martinfowler.com/articles/exploring-gen-ai/tdd-in-the-agent-loop.html) +> 作者：[Birgitta Böckeler](https://birgitta.info)（Thoughtworks Distinguished Engineer，AI 辅助交付专家） +> 发布于 2026 年 8 月 10 日，martinfowler.com「[Exploring Gen AI](https://martinfowler.com/articles/exploring-gen-ai.html)」系列 + +TDD（测试驱动开发）工作流可以以多种方式用在 AI 增强编码中： + +1. 人来写测试：由人以某种形式定义测试场景——可以是自然语言、BDD 风格，或者直接写成代码。然后由 AI 编写实现让这些测试通过（可能会有一个先把人写的场景转换成代码的前置步骤）。 +2. 给人设置的 review 检查点：AI 写一个失败的测试，人来审查这个测试是否在测想要的行为，然后 AI 再写实现。 +3. 完全在 agent loop（agent 自主执行的循环）内部：提示 agent 先逐个写出失败的测试，然后编写实现，并检查之前失败的测试已经转绿。 + +现阶段，最后一种用法是目前为止最常见的。但让 agent 完全在它自己的循环里遵循 TDD 工作流，真的有区别吗？它真的能带来价值，还是说，这是那种少见的例子——对人有益的东西，对编码 agent 来说可能无关紧要，甚至有害？ + +我搭建了一个探索性的评估装置，想在这个问题上刮开一层表面，看看能发现什么。它远算不上一份全面、结构化的 eval 结果，但确实产出了一些假设——如果你正在费力让你的 agent 使用 TDD，这些假设值得想一想。 + +**TLDR;** 依据 Opus 对产出质量的评判，TDD 工作流与非 TDD 工作流之间不存在清晰可辨的差异。恰恰相反，Opus 不止一次把非 TDD 工作流的方案在设计与测试质量上排得略高。各方案之间的变异测试（mutation testing）得分也没有有意义的差异。 + +## 实验设置 + +- *任务：* 我借助 Claude 创建了一个小型、一个中型和一个较大的任务，全部是绿地（green field）实现的一小块业务逻辑。我让它给出一批建议，并要求逻辑要有个性、够具体，以提高各方案之间出现差异的概率，而不是简单重复训练数据中已经占主导地位的东西。 +- *指令：* 在所有 run 中，我都加入了「代码覆盖率至少达到 80%」的指令。 +- *模型：* 我用 Sonnet 4.6 生成方案。 +- *TDD 遵循度评判：* 对 TDD 遵循程度的评估同样由 Sonnet 4.6 完成。 +- *方案质量评判：* Opus 4.8 在不知道方案如何产生的前提下，比较各方案及其测试的质量。我没有对「什么算好质量」给出很具体的输入，因为这是一次非常开放的探索。而且以我的经验，我给得越具体，模型就越可能不必要地过度对齐我列出的质量标准。Opus 在代码质量评判方面已经展现出相当强的能力。在对方案排名时，它现场生成了一份评分 rubric，传给所有负责评估各个方案的子 agent。 + +![方法流程图：在每个批次中，我用同一任务分别带 TDD 指令和不带 TDD 指令各跑两次。然后让 Opus 在不知道方案如何产生的情况下比较这四个方案。之后再把会话记录提供给 Opus，请它推测 agent 的工作方式是否以及如何影响了方案质量。](imgs/fowler-tdd-in-agent-loop/tdd_comparison_overview.svg) + +当你从我的结果中得出自己的结论时，主要需要考虑这些前提： + +- 这显然是一个非常小的样本量，请对结果持保留态度 +- 「质量」意味着什么，几乎完全交给了 Opus 判断（只给了少量关于测试质量的提示） +- 没有任何一次 run 完美地遵循了 TDD，但都遵循得相当不错 +- 交给 agent 的编码任务全是绿地项目，规模相对较小，纯粹是业务逻辑 + +## Agent 做 TDD 到底行不行？ + +在开始之前，我得先确保 TDD 指令真的被遵循了。从过往经验看，这对我来说一直不顺利：agent 经常先写实现、事后补测试，跳过确认红灯（red）这一步，或者超前于当前测试过度实现，导致下一个测试从未变红就直接通过。 + +我最终使用的 prompt 在 Sonnet 上效果足够好，可以用于这次比较，尽管所有会话都或多或少出现了上述失败模式。对每一次 TDD run，我都安排一个独立的 agent 基于会话记录来评判工作流被遵循得如何，以免我不小心把一次并没有实质做 TDD 的 run 计入结果。 + +## 结果 + +我创建了 5 个批次的方案，每批各含两个非 TDD 方案和两个 TDD 方案。在其中一个批次里，我还额外加了两次 run，指令是先写测试（test-first），但不要求完整的 TDD 纪律（不做增量式 red/green）。 + +在小型任务（1 个批次）和中型任务（3 个批次）中出现了某种模式：Opus 把两个非 TDD 方案排在第 1 和第 2，把两个 TDD 方案排在第 3 和第 4。只有一次——在我用更明确的「重构与设计审查」步骤强化 TDD prompt 之后——TDD 方案排到了第 1。不过在同一批次里，用完全相同 prompt 跑出的另一个 TDD 方案却排在了最后……在较大的任务上，TDD 落在中游，而两次非 TDD run 分别占据了最好和最差的位置。 + +（详细数据见附录） + +## 假设 + +总结起来：在各批次中，TDD 和非 TDD 都既拿过最佳也拿过最差，整体上 TDD 的表现略差一些。 + +我让 Opus 在知道每个方案用了哪种工作流的前提下查看会话轨迹、对结果提出假设。Opus 发现，非 TDD 和 test-first 的 run 总是在写任何代码或测试之前，先完成完整的设计（架构、数据类型、边界情况、契约），而不是逐条需求、逐个测试地推进。这似乎正是让天平略微偏向它们的因素：相对更好的数据模型、更多横切性的边界情况处理、更完整的功能实现。 + +而 TDD 指令会主动对抗这种前置设计步骤。那些 run 里的设计是由许多局部最小化决策累加涌现出来的，而且极少被回头审视，因此往往就停留在第一个测试碰巧锁定的形状上。agent 没想到要为之写测试的行为，就干脆完全没有被实现。 + +我和 [Ivett Ördög](https://ivettordog.com/) 聊起这件事时，她提出了这样一个理论：「AI agent 的训练方式决定了它们看到的是已完成的函数和这些函数的描述。真正逐步演示 TDD 过程的样例在训练数据中只占极小的一部分。这意味着 LLM 对代码的内部表征，是从需求到代码的直接翻译，而不是一个如何抵达那个表征的过程。」 + +## TDD 的目标——在 agent loop 里还成立吗? + +以下是我关于在 agent loop 中使用 TDD 的一般性思考，不只基于这次实验。我会逐一过一遍我自己使用 TDD 时追求的终极目标。那些只是关于「要有测试」（尤其是单元测试）的目标——比如重构安全网、活文档、测试覆盖率——我会跳过，聚焦在专属于 TDD 工作流本身的那些目标上。 + +### Test first >> 避免套套逻辑 + +先写测试让我更容易去断言我想要的输出，而不是复述实现。（如果测试是从它本该检查的那套逻辑推导出来的，那么实现错了它也永远不会失败。）当断言与具体的实现路径解耦时，测试才真正能在行为不符合我的意图时抓住问题。 + +**在 agent loop 里还成立吗？** +在我的实验中，一些 TDD 会话尽管先写了测试，还是照样出现了这个问题。在一个特别明显的例子里，测试拿实现的输出和它自己比对——重新运行同一段代码来产生「预期」答案（[见这份观察列表中的第 4 条](https://github.com/birgitta410/tdd-comparisons/blob/main/tdd-analysis-01-medium-redo/sol-2026-07-10_16-40-51/tdd-analysis-1783694844961.md#potential-issues--observations)）。先写测试并不能可靠地防止这种情况——它也许能降低概率，而对 LLM 我们本来能指望的也就只有概率了。但从这么小的数据集出发，我无法对这个概率下任何结论。 + +### Test first >> 可测性 + +先写测试确保代码从一开始就被设计成可测试的，而不是事后补上比必要更复杂、更脆弱的测试。 + +**在 agent loop 里还成立吗？** +结果没有给我任何一边倒的清晰信号。顺带一提，我选的任务在规模和性质上都不需要太多设计复杂度，因此也就难以把这一点显现出来。不过在一定程度上，可测性是「驱动设计」的推论（见下文）。 + +### Red-green >> 测试有效性 + +先看到测试失败、再看到它成功（*red-green*），证明了它将来真的能抓住回归。 + +**在 agent loop 里还成立吗？** +当人被移出流程之后，这还有多大意义？看着测试变红，只有在有人检查它*为什么*变红时才能证明任何东西。当 agent 既写测试又确认它失败时，一个红色的测试只告诉你 agent 跑了它并看到了失败，而不能说明失败的原因是对的。我实验中对 TDD 遵循度的评估也印证了这一点：agent 仍然时不时跳过或伪造红灯步骤，或者超前于测试实现，使测试立即通过。回归有效性可以用变异测试（mutation testing）来监控和改进（[我在这里写过](https://martinfowler.com/articles/sensors-for-coding-agents.html#TheTestSuiteAsARegressionSensor)）。各方案的 mutation score 没有显示出任何信号表明 TDD run 产出了有意义地更好的分数。我其实并不在乎回归质量是*怎么*达成的，只要我有一个机制能看到它有多好。 + +### Test first、red-green-refactor >> 驱动更好的设计 + +先写测试迫使我们在实现之前先规定用法，从而推向更好的接口和更模块化的代码。TDD 循环中的重构步骤则进一步推动我们一步一步改进设计。 + +**在 agent loop 里还成立吗？** +这个实验至少完全没有展示出 TDD run 有更优的设计。基于 Opus 的打分，我现在甚至怀疑 TDD 是否让设计变得更糟了：非 TDD 方案多数时候被排得更高，而且它列出的设计缺陷在我看来是言之成理的。当然，数据集太小，无法就任何事下定论。（如果有人有时间和 token 去跑一个更大规模的实验，那会非常有意思！） + +当人类先写测试时，它迫使我们在实现之前先思考用法，我们必须坐在那种摩擦里——在还不知道怎么构建之前，先把行为和预期规定清楚。agent 体验不到这种摩擦，它可以在规划实现的同一瞬间写出测试。如果这两者之间没有人类检查点，先写测试还剩下什么意义吗？ + +### 小步前进 >> YAGNI + +只写恰好能让下一个测试通过的代码，核心在于克制。它本应阻止我们构建还没人要求的抽象、处理还没人提出的情况。 + +**在 agent loop 里还成立吗？** +这是一个非常以人为中心的收益，当 agent 自己做 TDD 时它就丢失了。我们不再有机会坐在那种摩擦里，被迫认真思考我们正在构建的东西的所有细枝末节。理论上这份思考转移到了我们给 agent 写规格（spec）的时候，但在那个环节我们并没有一个类似 TDD 的机制，让我们以小步的方式把 spec 想透。 +那 agent 能不能也以这种小步方式工作，一旦发现某些东西可能没必要就来问我们？以我的一般经验，它们并不擅长这个。在实验里同样如此，「最小实现」的指令并不能可靠地阻止它们多造东西。它们经常越界，实现得比当前测试所要求的更多，因为它们手上有完整的需求。我们通常不会把 spec 一条条地喂给它，那样效率太低了。 + +### 小步前进 >> 快速、局部化的反馈 + +一次只走一小步意味着当测试失败时，我几乎能确切知道原因——因为自上一个绿色状态以来，唯一变化的就是你刚刚写的那一样东西。 + +**在 agent loop 里还成立吗？** +这套装置没有显示出 agent 在有无 TDD 的情况下卡在调试里的频率差异。但以我的一般经验，agent 通常都相当擅长弄清一个测试为什么红了，即便它并没有以小而审慎的步子走到那里。我仍然怀疑：它们偶尔卡住的那些时刻，是否真能被 TDD 的小步显著缓解，以及整体的成本/收益对比是否站得住脚。 + +### 小步前进 >> 信心与学习 + +在《测试驱动开发》（Test-driven Development by Example）的前言里，Kent Beck 给 TDD 的最大理由是「管理恐惧」。他说，对困难问题的合理恐惧会让开发者变得畏缩、不愿沟通、回避反馈。有了 TDD，每一个通过的测试都在向我们展示进展，于是我们可以放松下来，*知道进展已经被锁定*。测试是一种帮助我们坚持走下去的心理机制。 + +**在 agent loop 里还成立吗？** +这在很大程度上是关于管理*人类的*恐惧、给*人类*放松的许可。当 agent 在循环内部做 TDD 时，这一点无法迁移——它不会给我那种当我自己一步一步做时才有的掌控感和信任感。 + +## 成本 + +### 至少 3 倍的 token + +*详细数字见附录。* + +自然地，TDD 工作流需要多得多的对话轮次和工具调用，也就会消耗更多 token。不过，其中很多是缓存命中，所以要注意：3 倍甚至更高的 token 倍数并不直接等于成本高出那么多。（可惜我在实验中没有追踪缓存命中。） + +### Prompt 的维护与测试 + +TDD 这个过程对模型来说似乎并不「天然」。这像是一场逆着训练数据打的上坡战，需要对 prompt 反复迭代很多轮，才能让它在多数时候遵循这个过程。举个例子：我在头几个批次之后发现，agent 在 red-green-refactor 循环中几乎不做重构，于是我修改了 prompt，加重了对这一步的强调——它当然是 TDD 的关键。后来我让 Opus 查看那些会话，看重构努力是否有改善。它确实报告了重构步骤的增加——但同时也列出了一些案例：agent 本来着手要重构，却认定设计已经足够好了，而在 Opus 看来那些设计明显不够好（比如所有东西都实现在一个大模块里，但明明可以拆分成多个职责）。 + +TDD 是一套相对复杂、变量繁多的指令，因此 agent 对它的解读也就存在大量变体。所以我猜想，这类 prompt 在跨模型时会比简单指令更加不稳定，也就意味着要花力气才能让它在不同模型和不同模型版本上持续有效。 + +![总览图：概括 agent 使用 TDD 的成本（token、指令维护），以及 TDD 的各项收益在 agent loop 内部的实际表现。收益部分基本是对文中所列内容的总结。](imgs/fowler-tdd-in-agent-loop/tdd_by_agents_costs_benefits.png) + +## 我的结论 + +我认为到目前为止，越来越多的证据表明：对模型*如何*做某事规定得过细，不是一条可持续的路。相反，我们应该尽可能多地找到监控产出并给予反馈的方式。这些反馈应当尽可能自动化，而我们需要仔细思考，在哪些位置把自己插入进去，充当「什么是好、什么是对」的仲裁者。 + +尽管我清楚我这个小小的 eval 远不能代表对 TDD 有效性的全面视角，但它确实没有给我任何新的迹象表明这些努力是值得的。尤其是当我们能找到其他方式来获得 TDD 的大部分收益时。 + +我个人已经不再要求我的编码 agent 先写测试了，更不用说做 TDD（说实话，后者我从来没要求过）——直到我看到能说服我的 eval 或其他有力论证为止。我转而尝试聚焦于我在 agent loop 之外使用 TDD 时的那些收益，并探索达成它们的替代方式。 + +### 如何获得好的回归测试？ + +*……让 agent 和我在既有功能被破坏时能收到信号* + +我仍然在乎扎实的回归测试。因为即便 agent 当然可能用错误的方式把红测试修绿，至少红测试给了它一个反馈信号，去复查那些可能被破坏的既有需求。我[借助变异测试来监控和改进回归质量](https://martinfowler.com/articles/sensors-for-coding-agents.html#TheTestSuiteAsARegressionSensor)，而不是写一堆精细的 TDD 指令然后听天由命。 + +### 如何把常态化重构纳入流程？ + +*……让代码库始终易于修改* + +重构依然至关重要，但传统 TDD 的小步似乎并不是在 agent loop 中做重构的高效或有效方式。几个触发重构的例子：给 agent [接入静态代码分析](https://martinfowler.com/articles/sensors-for-coding-agents.html#StaticCodeAnalysisBasicLinting)；定期运行[结构与模块化评审](https://martinfowler.com/articles/sensors-for-coding-agents.html#StaticCodeAnalysisAiModularityReview)；建立团队仪式来保持对代码库的良好理解、及早发现漂移；关注每次变更触及的文件数趋势，以及[一次变更消耗的 token 数](https://martinfowler.com/articles/exploring-gen-ai/refactoring-economic-benefit.html)。 + +### 如何获得信心？ + +*……让我不害怕推上生产* + +最难的问题依然是：我们如何获得 TDD 曾经给我们的那种信心？如何管理恐惧？如何锁定进展？我没有明确的答案，但我想提一件看起来像是不错的基石的事：我最近试用了 Ivett Ördög 倡导的 [Approved Scenarios](https://lexler.github.io/augmented-coding-patterns/patterns/approved-scenarios/)（已批准场景）方法。用我自己的话说（别拿这话去要求她），它是一种半手动测试，由为每个应用量身定制的测试运行器支撑。这个运行器以一种便于思考的方式向我展示功能性测试场景，并允许我在彻底确认之后，把预期（场景/夹具）在运行器里「冻结」。将来一旦这些被冻结的预期被违反，我就必须重新批准它们。我的同事 Matteo Vaccari 对[他使用这一方法的经验做了很棒的分享](https://www.youtube.com/watch?v=3tdmoj35HG0)。 + +无论最终是什么给了我们对软件的信任与信心——我认为，我们所熟知的那个 TDD 的角色，已经比前 GenAI 时代小了很多。 + +--- + +## 附录：Opus 评估下的结果 + +完整结果可以在[这个仓库](https://github.com/birgitta410/tdd-comparisons/)找到。 + +- NT = 无 TDD 指令 +- T = TDD 指令 +- TF = Test-first（只先写测试）指令 + +### 全部批次的 token 用量 + +按任务规模拆分： + +| 任务 | NT 平均 token | T 平均 token | T / NT 倍数 | +|---|---|---|---| +| 小型 | 119,815 (n=2) | 1,018,245 (n=2) | 8.50x | +| 中型 | 736,486 (n=2) | 2,181,105 (n=6) | 2.96x | +| 大型 | 253,621 (n=2) | 1,239,408 (n=2) | 4.89x | + +只有中型任务额外做了 test-first 指令的 run。 + +*注意*：这些数字只是会话成本的粗略代理指标，并不衡量一个方案投入了多少代码或思考。记录 token 用量的装置使用了 [pi-coding-agent](https://github.com/earendil-works/pi-coding-agent) SDK 的 `getSessionStats()`，它把会话中每一个 assistant 轮次的 `input + output + cacheRead + cacheWrite` 用量加总。这是整个对话过程的滚动累计值：每一轮都会重读已累积的上下文，而这些重读（通常大部分由缓存提供）都会再次计入该轮的 `cacheRead`。所以「Total Tokens」更多反映的是一个会话用了多少轮，并按彼时上下文已经膨胀到多大加权。它把便宜的缓存读取 token 和昂贵的新鲜 token 等同看待，因此很可能高估了 TDD 的真实美元成本。在这么小的样本量下，请把这些倍数当作方向性的：TDD 稳定地贵好几倍，具体是几倍则有波动。 + +### 中型任务，第 1 轮 + +**任务：** 构建一个 4 阶段的 Python 流水线（解析 → 聚合 → 格式化 → 校验），把原始的 `ROW_ID:CATEGORY:VALUE:PERIOD` 字符串转换成纯文本报表。 + +数字： + +| ID | TDD | 测试数 | 覆盖率 | Mutation Score | Total Tokens | 轮次 | 工具调用 | +|---|---|---|---|---|---|---|---| +| NT1 | 否 | 75 | 100% | 84.2% | 769,814 | 31 | 37 | +| NT2 | 否 | 107 | 100% | 89.6% | 703,159 | 21 | 24 | +| T1 | 是 | 30 | 100% | 81.0% | 1,519,762 | 71 | 28 | +| T2 | 是 | 34 | 99% | 77.3% | 2,580,897 | 103 | 60 | + +总体裁定： + +| ID | TDD | 排名 | 裁定 | +|---|---|---|---| +| NT1 | 否 | 1 | 每阶段一个模块、dataclass、`Decimal`；无正确性 bug，错误处理最强，是唯一检查重复 ROW_ID 的方案；校验自我指涉但无害 | +| NT2 | 否 | 2 | 每阶段一个模块、dataclass、float/round；工程化最佳、测试套件最大，但校验器会拒绝自己产出的合法小数输出（误拒 bug）；TOTAL 行从未被校验 | +| T1 | 是 | 3 | 单一模块、dict、float；核心阶段正确，但校验是循环论证（重新运行格式化器）；接受 `nan`/`inf`，忽略重复 ROW_ID | +| T2 | 是 | 4 | 单一模块、dict、float；存在活跃的 TOTAL 行 bug（人数被加进金额），且被一个测试「供奉」了起来；完全缺失第 3 条校验检查 | + +（本轮排名只基于裁定、测试数、覆盖率和 mutation score——Opus 的设计/代码/测试分项评分从下一轮才引入。） + +### 中型任务，第 2 轮 + +**任务：** 与 01-medium 相同的 4 阶段报表流水线，以更严格的 TDD 遵循度重跑，并新增 test-first 变体（NT1/NT2 复用 01-medium 的原有代码库）。 + +| ID | 方式 | 测试数 | 覆盖率 | Total Tokens | 轮次 | 工具调用 | +|---|---|---|---|---|---|---| +| NT1 | 无 TDD | 107 | 100% | 703,159 | 21 | 20 | +| TF2 | Test-first | 90 | 92% | 619,531 | 27 | 26 | +| NT2 | 无 TDD | 75 | 100% | 769,814 | 31 | 30 | +| T2 | TDD | 29 | 98% | 2,099,280 | 96 | 95 | +| TF1 | Test-first | 62 | 99% | 268,323 | 17 | 16 | +| T1 | TDD | 25 | 100% | 2,017,739 | 90 | 89 | + +| ID | 方式 | 设计 | 代码 | 测试 | 平均 | 实现/测试 LOC | +|---|---|---|---|---|---|---| +| NT1 | 无 TDD | 8 | 8 | 8 | 8.0 | 497 / 881 | +| TF2 | Test-first | 8 | 8 | 7 | 8.0 | 484 / 850 | +| NT2 | 无 TDD | 8 | 8 | 7 | 7.5 | 330 / 430 | +| T2 | TDD | 7 | 7 | 6 | 6.5 | 207 / 304 | +| TF1 | Test-first | 6 | 6 | 6 | 6.0 | 348 / 360 | +| T1 | TDD | 6 | 6 | 6 | 6.0 | 142 / 228 | + +| ID | 方式 | 排名 | 裁定 | +|---|---|---|---| +| NT1 | 无 TDD | 1 | 测试套件最深，校验最干净（复用格式化器的版式）；HEADCOUNT 被混进金额合计且无测试防护 | +| TF2 | Test-first | 2 | 全程 `Decimal`，解析/校验强；第 3 条检查是不可达的死代码，校验模块杂乱 | +| NT2 | 无 TDD | 3 | 设计干净、`Decimal`、解析正确；测试较薄，有一个空转测试，校验自我指涉 | +| T2 | TDD | 4 | 顺利路径干净、格式化正确；遇到畸形输入直接崩溃，而不是返回结构化的解析错误 | +| TF1 | Test-first | 5 | 单文件方案中最强的解析器；TOTAL 行损坏（人数当金额），交付了死脚手架 | +| T1 | TDD | 6 | 最紧凑（142 LOC）；畸形输入崩溃，校验最套套逻辑，测试套件最薄 | + +### 中型任务，第 3 轮（改进 TDD 指令） + +**任务：** 与 01-medium 相同的 4 阶段报表流水线，用改进后的 TDD prompt 重跑（强调前置设计和重构）；NT1/NT2 依旧复用 01-medium 的代码库。 + +| ID | TDD | 测试数 | 覆盖率 | Mutation Score | Total Tokens | 轮次 | 工具调用 | +|---|---|---|---|---|---|---|---| +| T1 | 是 | 51 | 100% | 90.2% | 3,447,283 | 117 | 116 | +| NT1 | 否 | 107 | 100% | 89.6% | 703,159 | 21 | 20 | +| NT2 | 否 | 75 | 100% | 84.2% | 769,814 | 31 | 30 | +| T2 | 是 | 43 | 100% | 81.1% | 1,421,671 | 61 | 60 | + +| ID | TDD | 设计 | 代码 | 测试 | 平均 | +|---|---|---|---|---|---| +| T1 | 是 | 8 | 8 | 7 | 7.67 | +| NT1 | 否 | 8 | 8 | 6 | 7.33 | +| NT2 | 否 | 8 | 7 | 6 | 7.0 | +| T2 | 是 | 7 | 7 | 6 | 6.67 | + +| 排名 | ID | TDD | 主要弱点 | +|---|---|---|---| +| 1 | T1 | 是 | 只含 HEADCOUNT 的 TOTAL 行被打印成 `$`；校验只是子串检查，不做算术 | +| 2 | NT1 | 否 | 小数 HEADCOUNT → 合法输入触发伪 ValidationError；测试依赖 monkeypatching | +| 3 | NT2 | 否 | `NaN`/`Infinity` 让流水线崩溃而不是抛 ParseError；校验重新运行格式化器 | +| 4 | T2 | 是 | 校验是套套逻辑（拿聚合结果和它自己比对）；宽度检查只停留在注释里 | + +### 小型任务 + +**任务：** 构建一个 Python 模块，校验 `DAY-TIME-ROOM-CHECKSUM` 格式的医疗预约时段编码，返回结构化结果，指明哪条规则失败及原因。 + +| ID | TDD | 测试数 | 覆盖率 | Mutation Score | Total Tokens | 轮次 | 工具调用 | +|---|---|---|---|---|---|---|---| +| NT1 | 否 | 61 | 100% | 89.6% | 122,108 | 10 | 15 | +| NT2 | 否 | 58 | 100% | 92.3% | 117,522 | 10 | 20 | +| T1 | 是 | 21 | 100% | 93.6% | 894,451 | 55 | 37 | +| T2 | 是 | 20 | 100% | 93.2% | 1,142,039 | 68 | 26 | + +| ID | TDD | 设计 | 代码 | 测试 | 平均 | +|---|---|---|---|---|---| +| NT1 | 否 | 8 | 9 | 9 | 8.67 | +| NT2 | 否 | 8 | 8 | 8 | 8.0 | +| T1 | 是 | 7 | 8 | 7 | 7.33 | +| T2 | 是 | 6 | 7 | 7 | 6.67 | + +| ID | TDD | 排名 | 裁定 | +|---|---|---|---| +| NT1 | 否 | 1 | 总体最佳——dataclass 结果、无 bug、61 个断言失败原因的测试 | +| NT2 | 否 | 2 | 非常接近——dataclass 结果，但有一处 Unicode 数字的规格偏离 | +| T1 | 是 | 3 | 正确且干净，但结果用 dict + 测试更少 + 有死代码 | +| T2 | 是 | 4 | 设计最弱（自由文本错误信息）+ 一个真实的崩溃 bug | + +### 较大任务 + +**任务：** 构建一个内存态的 Python 积分引擎，支持分级获取率（Bronze/Silver/Gold）、按滚动 365 天消费额重算等级，以及积分兑换。 + +| ID | TDD | 测试数 | 覆盖率 | Mutation Score | Total Tokens | 轮次 | 工具调用 | +|---|---|---|---|---|---|---|---| +| NT2 | 否 | 69 | 100% | 86.9% | 322,148 | 14 | 13 | +| T2 | 是 | 22 | 99% | 85.6% | 1,225,517 | 63 | 62 | +| T1 | 是 | 21 | 99% | 85.2% | 1,253,300 | 67 | 66 | +| NT1 | 否 | 74 | 99% | 89.4% | 185,094 | 11 | 9 | + +| ID | TDD | 设计 | 代码 | 测试 | 正确性 | 平均 | +|---|---|---|---|---|---|---| +| NT2 | 否 | 8 | 9 | 8 | 8 | 8.25 | +| T2 | 是 | 7 | 7 | 8 | 8 | 7.5 | +| T1 | 是 | 7 | 7 | 7 | 9 | 7.5 | +| NT1 | 否 | 8 | 7 | 6 | 6 | 6.75 | + +| ID | TDD | 排名 | 裁定 | +|---|---|---|---| +| NT2 | 否 | 1 | 唯一做了真正输入校验的方案；边界测试精确；仅有乱序购买的次要边界问题 | +| T2 | 是 | 2 | 干净的强类型数据模型，核心规则全部正确；无错误处理、重复购买 ID bug、死状态字段 | +| T1 | 是 | 3 | 功能正确性最高（试探未发现 bug）；无类型的嵌套 dict、残留结构、测试最少 | +| NT1 | 否 | 4 | 设计分最高、74 个测试——但有两个高危 bug：批次扣减顺序错误；未来日期的积分被算作可用 | + +--- + +**致谢** + +感谢 Ivett Ördög、Matteo Vaccari、Dan Mutton、Lukasz Plotnicki 和 Emily Bache 抽出时间审阅，以及那些帮助改进本文的反馈与宝贵讨论。 + +GenAI 被用于研究调研、把想法归拢成结构，以及润色语言。 diff --git a/works/imgs/arxiv-starharness/eops_benchmark_comparison.png b/works/imgs/arxiv-starharness/eops_benchmark_comparison.png new file mode 100644 index 0000000..946e7fc Binary files /dev/null and b/works/imgs/arxiv-starharness/eops_benchmark_comparison.png differ diff --git a/works/imgs/arxiv-starharness/harness_comparison_automationbench.png b/works/imgs/arxiv-starharness/harness_comparison_automationbench.png new file mode 100644 index 0000000..a591da8 Binary files /dev/null and b/works/imgs/arxiv-starharness/harness_comparison_automationbench.png differ diff --git a/works/imgs/arxiv-starharness/harness_comparison_eops.png b/works/imgs/arxiv-starharness/harness_comparison_eops.png new file mode 100644 index 0000000..95b8c9b Binary files /dev/null and b/works/imgs/arxiv-starharness/harness_comparison_eops.png differ diff --git a/works/imgs/arxiv-starharness/harness_comparison_itbench.png b/works/imgs/arxiv-starharness/harness_comparison_itbench.png new file mode 100644 index 0000000..aa1002c Binary files /dev/null and b/works/imgs/arxiv-starharness/harness_comparison_itbench.png differ diff --git a/works/imgs/arxiv-starharness/starharness_overview.png b/works/imgs/arxiv-starharness/starharness_overview.png new file mode 100644 index 0000000..3fb1892 Binary files /dev/null and b/works/imgs/arxiv-starharness/starharness_overview.png differ diff --git a/works/imgs/fowler-tdd-in-agent-loop/tdd_by_agents_costs_benefits.png b/works/imgs/fowler-tdd-in-agent-loop/tdd_by_agents_costs_benefits.png new file mode 100644 index 0000000..5153210 Binary files /dev/null and b/works/imgs/fowler-tdd-in-agent-loop/tdd_by_agents_costs_benefits.png differ diff --git a/works/imgs/fowler-tdd-in-agent-loop/tdd_comparison_overview.svg b/works/imgs/fowler-tdd-in-agent-loop/tdd_comparison_overview.svg new file mode 100644 index 0000000..97b91a6 --- /dev/null +++ b/works/imgs/fowler-tdd-in-agent-loop/tdd_comparison_overview.svg @@ -0,0 +1,381 @@ + + + + + + + + +

Task Specs
(small / medium / large)

+ + + + + + + +

1. Run with TDD

+ + + + + + + + + + + + + +

1. Run with TDD

+ + + + + + + + + + + + + +

1. Run without TDD

+ + + + + + + + + + + + + +

1. Run without TDD

+ + + + + + + + + + + + + +

TDD instructions

+ + + + + + + + + + + + + + + + + + + +

Check that TDD instructions were followed

+ + + + + + + + + + + + + + + + + + + +

2. Opus: judgement of the 4 solutions (no knowledge of which used TDD)

+ + + + + + + +

3. Opus: Hypothesize relationships between judgement and workflow

+ + + + + + + + + + + + + +

Solution 1

+ + + + + + + + + + + + + + + + + + + +

Session Traces 1

+ + + + + + + + + + + + + + + + + + + +

Solution 2

+ + + + + + + + + + + + + + + + + + + +

Session Traces 2

+ + + + + + + + + + + + + + + + + + + +

Solution 3

+ + + + + + + + + + + + + + + + + + + +

Session Traces 3

+ + + + + + + + + + + + + + + + + + + +

Solution 4

+ + + + + + + + + + + + + + + + + + + +

Session Traces 4

+ + + + + + + + + + + + + + + diff --git a/works/imgs/osmani-practical-loop-engineering/anatomy-of-a-loop.svg b/works/imgs/osmani-practical-loop-engineering/anatomy-of-a-loop.svg new file mode 100644 index 0000000..810c03c --- /dev/null +++ b/works/imgs/osmani-practical-loop-engineering/anatomy-of-a-loop.svg @@ -0,0 +1,49 @@ + +Anatomy of a loop + + + + + + + + + + + + + + + + + + + +Practical loop engineering · addyosmani.com + +02 +addyosmani.com +Anatomy of a loopSet a goal, act, evaluate, feed the errors back, repeat until a stop condition holds. +GOALState “done” as acondition a machinecan evaluate.ACTThe agent makesa change, runs thebuild, edits again.EVALUATECompiler, linter,tests — plus a separatemodel reading the goal.Condition holdsStop.Fails — errors go back in as the next inputThe evaluate step is the whole game. A loop is only as good as the check that decides it is done.A strong check isDeterministic (same input, same verdict) · fast enough to run every turn · independent of whoever made the change. + \ No newline at end of file diff --git a/works/imgs/osmani-practical-loop-engineering/choose-your-primitive.svg b/works/imgs/osmani-practical-loop-engineering/choose-your-primitive.svg new file mode 100644 index 0000000..ac5cd24 --- /dev/null +++ b/works/imgs/osmani-practical-loop-engineering/choose-your-primitive.svg @@ -0,0 +1,49 @@ + +Choosing between goal, loop and schedule + + + + + + + + + + + + + + + + + + + +Practical loop engineering · addyosmani.com + +11 +addyosmani.com +Choosing between goal, loop and scheduleThree primitives, three different jobs. Most confusion comes from using one for another’s work. +/goal/loop/scheduleWhat it is forone task, to a finish linewatching on a cadenceroutines that outlive youRuns untila condition holdsyou stop it, or day 7you delete itNeeds an open sessionyesyesno — in the cloudExpireswhen it stops7 daysneverMinimum cadencen/a — it is not timed1 minute1 hourReach for it when“done” is a real checkinputs change, task stays putit must outlive the sessionRule of thumbGoal is a finish line. Loop is a heartbeat. Schedule is a heartbeat that keeps beating after you close the laptop.Routines are in research preview, need a Claude subscription login, and have a per-account daily run cap. + \ No newline at end of file diff --git a/works/imgs/osmani-practical-loop-engineering/four-kinds-of-loops.png b/works/imgs/osmani-practical-loop-engineering/four-kinds-of-loops.png new file mode 100644 index 0000000..881aa91 Binary files /dev/null and b/works/imgs/osmani-practical-loop-engineering/four-kinds-of-loops.png differ diff --git a/works/imgs/osmani-practical-loop-engineering/goal-write-a-condition.svg b/works/imgs/osmani-practical-loop-engineering/goal-write-a-condition.svg new file mode 100644 index 0000000..9bc6467 --- /dev/null +++ b/works/imgs/osmani-practical-loop-engineering/goal-write-a-condition.svg @@ -0,0 +1,49 @@ + +/goal — drive one task to a finish line + + + + + + + + + + + + + + + + + + + +Practical loop engineering · addyosmani.com + +03 +addyosmani.com +/goal — drive one task to a finish lineIf you cannot state “done” as a check a machine can run, you are not ready to loop. +/goal all tests in test/auth pass and the lint step is clean or stop after 20 turnsthe commanda condition a machine can evaluatethe bound — always set oneCheckable — loop itall tests in test/auth passthe lint step is cleanp95 latency is under 300msLighthouse score is 90 or abovethe build has no type errorsNot checkable — keep itmake the code cleanerimprove the user experiencemake it feel fasterrefactor this properlymake the copy more engagingHow the check worksAfter each turn the condition goes to a small fast model (Haiku by default), which answers yes or no with a short reason. Needs Claude Code v2.1.139+. + \ No newline at end of file diff --git a/works/imgs/osmani-practical-loop-engineering/loop-cadence.svg b/works/imgs/osmani-practical-loop-engineering/loop-cadence.svg new file mode 100644 index 0000000..66faca1 --- /dev/null +++ b/works/imgs/osmani-practical-loop-engineering/loop-cadence.svg @@ -0,0 +1,49 @@ + +/loop — a cron with an agent on the far end + + + + + + + + + + + + + + + + + + + +Practical loop engineering · addyosmani.com + +05 +addyosmani.com +/loop — a cron with an agent on the far endBest for watching something rather than pushing it to a finish. +Interval leads/loop 30m “check CI and fix what broke”or trails/loop “triage new issues” every 2 hoursUnitssseconds — round upmminuteshhoursddaysCreatedfirst fireFires every Nwhile the session is openDay 7one final fireDeletes itselfMinimum cadence1 minuteLifetimeSession-scopednew conversation ends itAuto-expiry7 daysnot three — I had this wrongMatch the interval to how fast the thing actually changes. A one-minute loop on a repo that sees one PR a day is paying to check an empty inbox. + \ No newline at end of file diff --git a/works/imgs/osmani-practical-loop-engineering/loop-plus-goal.svg b/works/imgs/osmani-practical-loop-engineering/loop-plus-goal.svg new file mode 100644 index 0000000..045030a --- /dev/null +++ b/works/imgs/osmani-practical-loop-engineering/loop-plus-goal.svg @@ -0,0 +1,49 @@ + +Loop schedules the check. Goal solves the problem. + + + + + + + + + + + + + + + + + + + +Practical loop engineering · addyosmani.com + +08 +addyosmani.com +Loop schedules the check. Goal solves the problem.The combination is where this stops being a toy and starts taking work off your desk. +The heartbeat — /loopWakes on a cadence. Looks.Decides whether there is anythingto do at all. Cheap when idle.every 24hThe hands — /goalSpawned only when there is work.Runs until a real exit conditionholds, then stops.until tests passif a match/loop every 24h “Check GitHub for issues labeled ‘bug’. If one exists, use/goal to implement a fix until all local tests pass and push the branch.”One clear objective, one measurable exit per goal. Stuff four unrelated outcomes in and the evaluator has nothing sharp to check.Loop notices. Goal finishes. Neither one is asked to do the other’s job — which is why the pattern holds up unattended. + \ No newline at end of file diff --git a/works/imgs/osmani-practical-loop-engineering/maker-and-checker.svg b/works/imgs/osmani-practical-loop-engineering/maker-and-checker.svg new file mode 100644 index 0000000..01b701b --- /dev/null +++ b/works/imgs/osmani-practical-loop-engineering/maker-and-checker.svg @@ -0,0 +1,49 @@ + +Split the maker from the checker + + + + + + + + + + + + + + + + + + + +Practical loop engineering · addyosmani.com + +06 +addyosmani.com +Split the maker from the checkerNever let the agent that did the work be the one that decides the work is good. +Sub-agent AThe makerDrafts the change. Has everyreason to believe it worked.diffSub-agent BThe checkerFresh context. Different modelif you can. Tries to refute.VerdictHolds → ship it.Fails → back to A with thespecific reason it failed.What one-sided confidence looks likeThe maker reports performance is fine.It measured desktop only. You cared aboutmobile. It was confident about one dimensionof the problem and silent on the other.Put in the checker’s promptEvery dimension that matters, namedThe spec or issue it must check against“Try to refute this. Default to fail”The agent that wrote the code is far too kind grading its own homework. + \ No newline at end of file diff --git a/works/imgs/osmani-practical-loop-engineering/triage-in-practice.svg b/works/imgs/osmani-practical-loop-engineering/triage-in-practice.svg new file mode 100644 index 0000000..52de222 --- /dev/null +++ b/works/imgs/osmani-practical-loop-engineering/triage-in-practice.svg @@ -0,0 +1,49 @@ + +What the triage system actually does + + + + + + + + + + + + + + + + + + + +Practical loop engineering · addyosmani.com + +09 +addyosmani.com +What the triage system actually doesAgent Skills, 80,000+ stars. The loop does not review for me. It shrinks what I review. +Every day, before80–90 PRsreviewed by hand, one at a timeA scheduled pass firstSummarise what is new and how urgent it is. Close what clearlydoes not fit. Leave a smaller, real pile for a person.The stopping condition that does the most workWritten down once, in the guidelines“We currently do not accept translations.”Not because we do not care — because wecannot maintain languages we do not speak.Becomes a rule the routine can runClose any PR that touches that part ofthe contribution guidelines.The batch a human has to read gets smaller.Cross-referencing is the real win: “we are reworking this area — close what it supersedes, and flag anything that would step on someone’s toes.”A constraint you can state in one sentence is a constraint an agent can enforce a hundred times a week. + \ No newline at end of file diff --git a/works/imgs/osmani-practical-loop-engineering/where-to-point-a-loop.svg b/works/imgs/osmani-practical-loop-engineering/where-to-point-a-loop.svg new file mode 100644 index 0000000..7dbcc07 --- /dev/null +++ b/works/imgs/osmani-practical-loop-engineering/where-to-point-a-loop.svg @@ -0,0 +1,49 @@ + +Where to point a loop + + + + + + + + + + + + + + + + + + + +Practical loop engineering · addyosmani.com + +10 +addyosmani.com +Where to point a loopThe task does not decide this. The quality of the check you can write decides it. +Loop itGreenfield with a clear specWell-fenced modules with tests around themTriage and label hygieneDependency bumps and codemodsMechanical migrationsPerf work with a number attachedAnything you already run every morningHold the reinsFuzzy goals that would loop foreverDeep-judgment architecture callsSchema and data-model designBrownfield, until a research pass maps itAnything where “done” is a matter of tasteWork with real users and no rollbackFirst runs of anything newBack pressure: grant a loop only as much autonomy as you can cheaply verify — not one inch more.The level you can safely reach rises with the strength of the check, not the size of the task. Cheap generation raises the value of verification; it does not lower it. + \ No newline at end of file diff --git a/works/imgs/osmani-practical-loop-engineering/worktrees-isolation.svg b/works/imgs/osmani-practical-loop-engineering/worktrees-isolation.svg new file mode 100644 index 0000000..580d4c7 --- /dev/null +++ b/works/imgs/osmani-practical-loop-engineering/worktrees-isolation.svg @@ -0,0 +1,49 @@ + +One clean checkout per parallel run + + + + + + + + + + + + + + + + + + + +Practical loop engineering · addyosmani.com + +07 +addyosmani.com +One clean checkout per parallel runThis is the thing that makes five to ten at once possible rather than chaotic. +Without isolationagent 1agent 2agent 3one treeSame files, same branch, edits landing on top of each other.With a worktree eachagent 1worktree-apiagent 2worktree-docsagent 3worktree-perfClean checkout, own branch, no collisions.On the CLIclaude --worktree perf (or -w)Lands in .claude/worktrees/perf/on a branch named worktree-perf.Or per sub-agent, in frontmatterisolation: worktreeIn .claude/agents/<name>.md — the sub-agentruns in a temporary tree of its own.Cleanup has a condition: the temporary worktree is removed automatically only if the sub-agent made no changes. + \ No newline at end of file diff --git a/works/imgs/pi-what-is-a-harness/royal-robbins-el-capitan-climbing-05.png b/works/imgs/pi-what-is-a-harness/royal-robbins-el-capitan-climbing-05.png new file mode 100644 index 0000000..b105f1e Binary files /dev/null and b/works/imgs/pi-what-is-a-harness/royal-robbins-el-capitan-climbing-05.png differ diff --git a/works/imgs/zalando-agentic-engineering/message_bytes.png b/works/imgs/zalando-agentic-engineering/message_bytes.png new file mode 100644 index 0000000..9eec60e Binary files /dev/null and b/works/imgs/zalando-agentic-engineering/message_bytes.png differ diff --git a/works/imgs/zalando-agentic-engineering/pr_size_distribution.png b/works/imgs/zalando-agentic-engineering/pr_size_distribution.png new file mode 100644 index 0000000..06a5054 Binary files /dev/null and b/works/imgs/zalando-agentic-engineering/pr_size_distribution.png differ diff --git a/works/imgs/zalando-agentic-engineering/total_ccn.png b/works/imgs/zalando-agentic-engineering/total_ccn.png new file mode 100644 index 0000000..f1960f5 Binary files /dev/null and b/works/imgs/zalando-agentic-engineering/total_ccn.png differ diff --git a/works/osmani-practical-loop-engineering-translation.md b/works/osmani-practical-loop-engineering-translation.md new file mode 100644 index 0000000..bb17cba --- /dev/null +++ b/works/osmani-practical-loop-engineering-translation.md @@ -0,0 +1,164 @@ +--- +title: "循环工程实战：goal、loop 与'委托任务，不委托判断'" +sourceTitle: "Practical Loop Engineering" +sourceUrl: "https://addyosmani.com/blog/practical-loop-engineering/" +sourceAuthor: "Addy Osmani" +sourcePublishedAt: "2026-08-14" +sourceSiteName: "AddyOsmani.com" +summary: "Osmani《Loop Engineering》定调文的落地篇：手搓 bash 循环的时代结束后，日常工作收敛为两个产品化原语——goal 把有界任务推进到可验证的终点，loop 按节奏供给心跳，二者组合支撑起 80K star 仓库的 PR 分诊系统。附大量一手细则（7 天过期、session 作用域、死循环信号），以及全文最重的踩坑实录：maker–checker 分离，委托的是任务，不是品味与判断。" +sourceLanguage: "en" +language: "zh-CN" +translationMethod: "人工整理逐段翻译（cloud agent，对照原文全文）" +sourceFigureCount: 10 +--- + +# 循环工程实战（Practical Loop Engineering） + +我平时的工作方式，是同时并行跑着五到十个智能体。有些任务我非常乐意完全委托给智能体——只要我对它们的停止条件和约束有非常清晰的把握。而另一些任务，我会想盯得更紧一些，对智能体做的东西逐一做代码评审。 + +在这个背景下，你大概已经听说过**循环工程（loop engineering）**了。几个月前我写过一篇长文专门讲它。 + +> 循环（loop）是一个自主的、自我纠正的反馈周期：AI 智能体反复行动、检验结果、调整方法，直到达成一个明确的目标 + +现在你基本上可以围绕两个核心原语来思考。在 Claude Code 里，你有一个 **[goal](https://code.claude.com/docs/en/goal) 原语**，它能驱动一个有边界的任务一直往前推进，直到某个特定目标——一条可度量的终点线——被满足为止。然后是 **[loop](https://code.claude.com/docs/en/scheduled-tasks)**，它按定时器或固定间隔重复运行，所以你可以用它来调度周期性的变更。 + +![循环的解剖：定义目标、行动、对照强校验做评估、把结果反馈回去。](imgs/osmani-practical-loop-engineering/anatomy-of-a-loop.svg) + +## 在原语还不是原语的时候 + +我还记得，在 Claude Code 和 Codex 把原语内置进来之前，循环工程在很大程度上就是自己搭一个 bash 循环，一个手搓的东西。我当时就是这么干的。你可能还记得今年早些时候，我们一批人在玩 Geoff Huntley 的 [Ralph loop](https://ghuntley.com/loop/)。我们做实验，互相分享工作流，分享什么好使、什么不好使——但那基本都是在各自的个人项目上，就算撞了墙，代价也不大，因为只是个人项目。 + +而随着我们逐渐看清循环工程的哪些模式、哪些侧面已经比较成熟，我认为我们对"怎么盯守（babysit）它"有了更清楚的认识。现在我基本可以信赖 Claude Code 和 Codex 里这些原语的产出。我们确实走了一段路。但与此同时你需要非常勤勉，因为如果你把循环丢在那儿不管，又没有认真想过最终目标和约束是否被良好定义，它可能把你留在一个很麻烦的状态里。这也是为什么"用不用它"需要看场景：一个没有用户、没有多少历史复杂度的常青代码库，和一个棕地的银行代码库，答案是不一样的。 + +## Claude Code 团队怎么框定循环 + +Claude Code 团队发表了他们对四类循环的划分，和我使用这些原语的方式对得上（[他们的文章](https://x.com/ClaudeDevs/article/2074208949205881033)）。在进入正文之前，先放我的快速总结： + +![四类循环：轮次型、目标型、定时型、主动型。](imgs/osmani-practical-loop-engineering/four-kinds-of-loops.png) + +> *在 Claude Code 团队，我们把循环定义为：智能体重复工作周期，直到满足某个停止条件。我们按几个维度对循环分类：如何触发、如何停止、使用哪个 Claude Code 原语、每一类最适合什么任务。不是所有任务都需要复杂的循环；从最简单的方案开始，有选择地使用这些模式。* +> +> *你发出的每一个提示词都会启动一个手动循环，由你来指挥每一轮。Claude 收集上下文、采取行动、检查自己的工作、必要时重复，然后给出回应。我们把这称为智能体循环（agentic loop）。比如，让 Claude 做一个点赞按钮。它读你的代码、做出修改、跑测试，然后把它认为可用的东西交回来。接着由你手动检查这份工作，再写下一个提示词。* + +他们的文章把每一档都过了一遍。 + +**关于目标型循环（goal-based loops）：** + +> *有时候，一轮是不够的，尤其是更复杂的任务。智能体在可以迭代时表现更好。你可以通过用 /goal 定义"完成长什么样"，来延长 Claude 持续迭代的时间。当你定义了成功判据，Claude 就不必自行判断什么算"足够好"、然后过早结束循环。每次 Claude 想要停下来时，一个评估器（evaluator）模型都会检查你的条件，把它送回去继续干，直到目标达成，或者达到你设定的轮数上限。这就是为什么确定性的判据——比如通过的测试数量、越过某个分数阈值——如此有效。例如：/goal 把首页 Lighthouse 分数拉到 90 或以上，尝试 5 次后停止。* + +**关于定时型循环（time-based loops）：** + +> *有些智能体工作是周期性的：任务不变，只有输入在变。比如每天早上总结 Slack 消息。另一些工作依赖外部系统，而与外部系统对接的一种简单方式，就是按间隔去检查它、对变化做出反应。比如一个 PR，它可能收到代码评审，也可能挂掉 CI。对于这些，你可以用 /loop 来触发 Claude 的运行，它会按间隔重跑一个提示词。例如：/loop 5m 检查我的 PR，处理评审意见，修复挂掉的 CI。/loop 跑在你自己的电脑上，关机它就停。你可以通过创建 [/schedule](https://code.claude.com/docs/en/routines) 云端例程（routine）把循环搬到云上。* + +**关于主动型循环（proactive loops），最顶上那一档：** + +> *触发方式：事件或计划任务，没有人类实时在场。停止判据：每个任务在目标达成时退出；例程本身一直运行，直到你关掉它。最适合：定义良好的周期性工作流：bug 报告、issue 分诊、迁移、依赖升级。用量管理：把例程路由到更小更快的模型，把判断类决策留给最强的模型。* + +他们的验证建议值得整段搬过来，因为它把人工检查变成了 Claude 自己执行的东西： + +``` +--- +name: verify-frontend-change +description: Verify any UI change end-to-end before declaring it done. +--- +# Verifying frontend changes +Never report a UI change as complete based on a successful edit alone. +Verify it the way a human reviewer would: +1. Start the dev server and open the edited page in the browser. +2. Interact with the change directly. For a new control (button, input, + toggle): click it, confirm the expected state change, and screenshot + before/after. +3. Check the browser console: zero new errors or warnings. +4. Use the Chrome Devtools MCP, run a performance trace and audit + Core Web Vitals. +If any step fails, fix the issue and rerun from step 1 - do not hand +back partially verified work. +``` + +## Goal + +我使用 goal 的方式，是用它把某件具体的工作一直做到"可证明地完成"。比如，你可以用一个 goal 说：确保这个体验在五秒内加载完成，一直做到达标为止。它会持续用一个独立的评估检查，反复确认完成判据是否已被满足。更好的做法是把用什么工具来度量也写得更具体。 + +至于我真跑到底过的 goal，有这么几件事。我用 goal 批量过 GitHub issues：评审并关闭最近 10 个 issue，或者评审并把最近 10 个 issue 往前推一步，诸如此类。这算半开放式的，对吧？还有：把这个页面加载速度提升 50%。有时候效果很好，有时候不行，但关键就在于实验。 + +![Goal 语法拆解：一条命令、一个可验证的条件、一个边界。](imgs/osmani-practical-loop-engineering/goal-write-a-condition.svg) + +## Loop + +Loop 更像一个调度器，它持续盯着某个东西，或者按某个节奏重复执行一个模式。可以把它想成一个 cron。它最适合做轮询日志、监控外部状态这类事。你也可以用它来做定期检查。如果有一些你发现自己按某个节奏反复在做的任务，loop 很适合。 + +![Loop 语法、支持的时间间隔，以及直到七天过期的生命周期。](imgs/osmani-practical-loop-engineering/loop-cadence.svg) + +## 我委托什么，我盯什么 + +就我而言，我每天大概会用五到十个智能体。最典型的情况是并发峰值在五个左右。其中一些任务是相对安全的：比如，嘿，我实现了这个功能，去把文档写了；或者去复查一下测试覆盖是否充分；这一类。如果我在处理一个更复杂的问题，或者某件事上我明知即使给了一份不错的 spec——至少我自认为不错——也给了停止条件，它仍有相当概率做不到处处正确，我就会盯得更紧。而如果任务哪怕只是稍微碰到一点敏感的东西——无论是我给了它某个系统的访问权限，还是这个功能恰好触及身份认证，或者跟安全、金融相关——我一定会盯得很紧。 + +总的来说，我确实认为我们会走到一个大家越来越放心委托的阶段，前提是他们有清晰的方式去验证目标或停止条件已经达成。但你仍然需要看代码、看生成出来的那个东西，确认它够得上你的标准。 + +这里还有一个要紧的习惯：**不要让干活的那个智能体自己判定活儿干得好**。一个子智能体起草变更，另一个独立的子智能体来验证。 + +有时一个智能体会对某件事很自信，而一个验证智能体能抓住它没料到的问题。比如它认为自己生成的体验基线性能其实还行，但它只在桌面端评估了性能，而你真正在乎的是移动端体验。这可能意味着智能体在问题的一个维度上非常自信，在另一个维度上却不然。 + +![一个 maker 智能体起草变更，一个独立的 checker 智能体做验证。](imgs/osmani-practical-loop-engineering/maker-and-checker.svg) + +这一条我是吃过亏才学会的。我当时想搞清楚：有没有什么我们遗漏的东西，是用户没有在 issue 跟踪器或评论里直接反馈给我们的？于是我让它去看了看一些竞品，整理一份清单，并在本地——没有 push——起了一些 PR，展示补上这些差距大概长什么样。我差点就把其中一些改动推上去了。但我其实没有足够仔细地看它们。我通读了它的调研，却没有足够仔细地看实现。也就是说，我委托了任务，但差一点连判断也一并委托了出去。等我真正细看那些改动，我意识到它会给我们的用户引入大量额外复杂度，而在我个人看来，换来的收益并不多。所以我觉得你有时需要检查自己：你没有把品味和判断委托给你的智能体。你委托的是任务，然后你要真的回头核对它是否够得上你的标准。 + +顺带说一句，goal 背后的那个评估器并不是这里说的验证者。它完全不看内容本身好不好——任何意义上都不看。它做的只是检查对话记录（transcript），看你指定的硬规则有没有被满足。 + +``` +/goal Refactor the data-fetching layer in Dashboard.tsx until Lighthouse performance score is >= 92 and LCP is under 1.8s as shown by the Lighthouse CLI output. Do not change the public API of any hooks. Each turn must improve at least one reported metric; abort if two consecutive turns show no improvement. Stop after 10 turns. +``` + +## 我每天在跑的工作流 + +我每天都在跑的一个工作流：我有一个很受欢迎的开源仓库叫 [Agent Skills](https://github.com/addyosmani/agent-skills)。它有超过 80,000 个 star，直到不久前，我们每天要评审的 pull request 多的时候能到 80、90 个。所以每天我都得花时间去盯这个仓库。现在有了 loop，你可以说：每 24 小时或每 12 小时，检查这个 GitHub 仓库有没有新开的 issue，给出一份按紧急程度排列的摘要，或者做一轮初审，诸如此类。 + +``` +/loop every 1h "Check the GitHub repository for any new open issues. Provide a bulleted summary of their urgency." +``` + +![并行的智能体运行被隔离在各自独立的 Git worktree 里。](imgs/osmani-practical-loop-engineering/worktrees-isolation.svg) + +## 组合 loop 与 goal + +你还可以把 loop 和 goal 组合起来。用 loop 调度一次检查，再用 goal 解决问题。比如你可以说：每 24 小时循环一次，检查 GitHub 上打了 bug 标签的 issue；如果存在，就用 goal 实现一个修复，直到本地测试全部通过，然后推送分支。 + +``` +/loop every 24h "Check GitHub for issues labeled 'bug'. If one exists, use /goal to implement a fix until all local tests pass and push the branch." +``` + +不过也要记住，goal 里能塞多少东西是有上限的。 + +![Loop 提供心跳，goal 提供解决工作的那双手。](imgs/osmani-practical-loop-engineering/loop-plus-goal.svg) + +他们的文章里还有一个组合示例，展示了这一切正在通往哪里： + +> *上面这些原语，加上 Claude Code 的其他能力——比如 [auto mode](https://code.claude.com/docs/en/auto-mode-config) 和动态工作流（research preview）——可以组合成一个处理长时间运行工作的循环。比如，要处理源源不断的反馈，你可以用：/schedule（research preview）跑一个例程去检查新报告；/goal 定义"完成"长什么样；用 skills 记录如何验证。[动态工作流](https://code.claude.com/docs/en/workflows)编排一批智能体，对每份报告做分诊、修复、评审修复。auto mode 让例程运行时不必停下来请求权限。合在一起，一个提示词可能长这样：/schedule 每小时：检查 project-feedback 频道的 bug 报告。/goal：在这一轮发现的每份报告都被分诊、处理并回复之前不要停。修 bug 时，用一个工作流在三个并行 worktree 里探索三种方案，并让一个裁判智能体做对抗式评审。* + +## 这套分诊系统实际做到了什么 + +在 PR 分诊里，当 loop 和 goal 一起为我工作时，我最终得到的是一个让我能持续接收 PR 和 issue 的系统：每天都能稳稳压住涌到我盘子里的东西，尤其是能做交叉引用。这对我来说是件大事。如果我要推进一个具体目标——嘿，我们要重做系统的这一部分，我需要确保所有碰到这部分的 issue 都因为这次重做而被关闭，或者确保我们没有踩到别人的脚趾——我可以把这件事定义清楚。 + +计划任务对于"定期评审新 PR、关掉明显不合适的东西"非常有用。举一个好的停止条件的例子：我们有一套贡献指南，里面写了诸如"我们目前不接受翻译类贡献"。 + +![一条书面的贡献规则变成一个可执行的分诊停止条件。](imgs/osmani-practical-loop-engineering/triage-in-practice.svg) + +不是我们不在乎，而是它们很难维护——因为送进来的语言我们往往并不会说。所以如果我们告诉它：凡是触及贡献指南这一条的 issue 或 PR 一律关闭，这件事放在计划任务上它能做得非常好。这样一来，我们真正需要人工评审的那一批就变小了。 + +![一份指南：什么工作可以放进循环，什么时候人该握住缰绳。](imgs/osmani-practical-loop-engineering/where-to-point-a-loop.svg) + +## 循环买不来什么 + +经常有人问我，循环工程不适合什么。总的来说，如果你对"终态/完成/好"在你的场景里意味着什么没有清晰的概念，它可能就不是适合你工作的模式。比如，一个模糊的 goal 是"一直改到这个 UI 设计足够好"。这是什么意思？对谁来说好？怎么评估？需要人类品味、主观设计或开放式创造性探索的任务不适合。而当你对目标有相当清晰的把握时，我认为循环是一个值得考虑的好选项。 + +## 细则 + +循环在原地空转的一个经典信号：同一条命令被反复尝试，结果毫无变化。同一条命令第三次执行、和第二次相比毫无变化——多半就该停了。 + +有一条细则值得知道。周期性循环在创建七天后过期。我之前一直跟别人说是三天，其实是七天。另外 loop 是 session 作用域的：你开一个新对话它们就停了——不过用 `--resume` 或 `--continue` 恢复那个 session，还在七天窗口内的周期任务会被带回来。如果你需要某个比 session 活得更久的东西，用 /schedule 让它跑在云端。 + +如果有一个检查你每天早上都在手动跑，那它就是你的第一个循环。我的是那堆 pull request。 + +![goal、loop、schedule 在触发方式、持久性与最佳用途上的对比。](imgs/osmani-practical-loop-engineering/choose-your-primitive.svg) + +本文最初发表在我的 [Substack](https://addyo.substack.com/p/practical-loop-engineering)。 diff --git a/works/pi-compaction-translation.md b/works/pi-compaction-translation.md new file mode 100644 index 0000000..3dc30f8 --- /dev/null +++ b/works/pi-compaction-translation.md @@ -0,0 +1,142 @@ +--- +title: "Pi 中的 Compaction 是如何工作的" +sourceTitle: "How Compaction Works in Pi" +sourceUrl: "https://earendil.com/posts/compaction-in-pi/" +sourceAuthor: "Earendil Engineering（Pi 团队）" +sourcePublishedAt: "2026-08-13" +sourceSiteName: "Earendil" +summary: "Pi 团队一手拆解编码智能体的 compaction 机制：会话逐 turn 膨胀直至溢出上下文窗口后，用一次独立 LLM 请求把旧历史压缩成'交接班简报'式结构化摘要（目标/进展/关键决策），默认保留 20K token 近期消息（约 5–20 turns）；独立请求可换便宜模型、摘要以纯文本存储保证跨模型可移植，代价是打破 prompt cache 需全量重算。" +sourceLanguage: "en" +language: "zh-CN" +translationMethod: "人工整理逐段翻译（cloud agent，对照原文全文）" +sourceFigureCount: 0 +sourceFigureAudit: "2026-08-27 curl 原文 HTML grep 核对，正文无配图（logo/头像/图标不计）" +--- + +# Pi 中的 Compaction 是如何工作的 + +如果你曾在 [Pi](https://pi.dev)、Claude Code 或 Codex 这类编码智能体（coding agent）里进行过一次很长的编码会话，那么你一定触发过一次压缩（compaction，把会话历史压缩成摘要以腾出上下文空间；下文保留英文 compaction）。在这篇文章中，我们解释 compaction 是如何工作的，以及 Pi 在什么时候需要进行 compaction。 + +## 一次 LLM 对话 + +大语言模型（LLM）的[上下文窗口（context window）](https://en.wikipedia.org/wiki/Context_window)是有限的。上下文窗口就是模型在生成响应时所能"看到"的内容。LLM 所采用的 [Transformer 架构](https://en.wikipedia.org/wiki/Transformer_(deep_learning))限制了它们能处理的输入量。一次编码智能体会话的输入包括之前所有的消息和工具调用，而且随着你不断工作，它会持续增长。一旦超出上下文窗口，LLM 就会拒绝该请求。 + +当你与 Pi 这样的编码智能体交互式协作时，智能体向 LLM 发送请求并接收响应。每个请求包含系统提示词（system prompt）、加载的文件（例如 [`AGENTS.md`](https://agents.md/)）、工具定义，以及会话历史。 + +编码智能体的第一个 LLM 请求包含这份初始上下文，外加第一条用户消息。 + +```text +请求 1： +[system][tools][user] +``` + +这就开启了一个轮次（turn；下文保留英文）。LLM 可能先返回一条包含工具调用的 assistant 消息。智能体程序执行这些工具调用，然后向 LLM 发送一个新请求，其中包含完整的会话内容——现在还包括了工具结果。我们再收到一条 assistant 消息。当 assistant 完成输出生成时，这个 turn 就结束了。 + +```text +请求 1 之后： +[system][tools][user][assistant: tool call][tool result][assistant] + <-------------------> ^ <---------> + 由 LLM 返回 | 由 LLM 返回 + | + 由智能体程序产生 +``` + +我们继续工作，再发送一条消息。 + +```text +请求 2： +[system][tools][user][assistant: tool call][tool result][assistant][user] + ^ + 新的用户消息 +``` + +每个 turn 都会让会话继续膨胀。最终，历史会超出上下文限制。下一个请求就会返回类似 `Request exceeds the maximum size` 的错误。 + +```text +[system][tools][user][assistant][....][tool result][user] + ^ + 超出上下文窗口 +``` + +## 处理上下文溢出 + +当我们无法原样继续现有会话时，有两个选择。 + +1. 我们可以开启一个全新的空会话，抛掉累积的上下文。这会丢弃历史，包括之前的决策和未完成的工作。但这样做也未必是坏事，因为 [LLM 输出的表现会随上下文变大而下降](https://www.trychroma.com/research/context-rot)。 +2. 我们可以为会话上下文创建一个更小的表示，因为我们想让这次会话继续下去。这正是 compaction 所做的事。 + +## Compaction + +理论上，实现 compaction 的方式有很多。比如，我们可以写一个确定性函数，保留会话中的一部分内容并丢弃其余部分。但在实践中，各家的 compaction 实现都是用一次 LLM 请求来对会话历史做摘要。 + +Compaction 用一份压缩后的表示替换掉一部分历史，为后续的消息和工具调用腾出空间。 + +```text +[system][tools][compaction result][user] + ^ + 新消息 +``` + +## Pi 的实现 + +我们来仔细看看 Pi 具体是[如何实现 compaction 的](https://pi.dev/docs/latest/compaction#summary-format)。 + +当会话变得太长时，Pi 用 compaction 来摘要较早的内容，同时保留最近的工作。当上下文用量逼近上下文窗口的总大小时，compaction 会被触发。也可以用 `/compact` 命令手动触发。 + +Pi 在一个 turn 结束后检查是否需要自动 compaction。在那之前，每个请求都是在现有 prompt 的基础上扩展，因此可以复用其缓存前缀（cached prefix）。如果在 turn 进行中遇到上下文溢出错误，Pi 也可能在 turn 中途进行 compaction。 + +进行 compaction 时，Pi 会原样保留一定数量的最近消息。 + +```text +compaction 之前： +[system + tools][较早的 turns][保留的最近消息] +``` + +保留消息的数量是变化的，因为 Pi 使用一个[可配置的 token 预算](https://pi.dev/docs/latest/compaction#when-it-triggers)。Pi 当前默认值是 2 万（20K）token，大约相当于 5 到 20 个 turn。在这个切分点之前的所有消息会被提取并序列化，然后交给摘要处理。 + +## Pi 的 compaction 提示词 + +对编码智能体而言，一次好的摘要的理想结果，就像一份从上一班交给下一班的交接班简报。Pi 的 compaction 提示词紧扣一个事实：现有上下文中有大量内容已经不再相关。我们应当只保留对下一个 LLM 请求仍然重要的上下文。 + +因此，Pi 为 compaction 发送的请求与常规对话请求是不同的。 + +1. 这个独立 compaction 请求所用的系统提示词不同。我们不再告诉 LLM"你是一位专家级编码助手"，而是告诉它 ["you are a context summarization assistant."（你是一个上下文摘要助手）](https://github.com/earendil-works/pi/blob/47610217098d9ba8f22d223fa7c1413f9f5fd759/packages/coding-agent/src/core/compaction/utils.ts#L152-L158) +2. Compaction 请求中的用户消息也不同。它要求生成 ["a structured summary of this conversation branch for context when returning later."（对这条会话分支的结构化摘要，供之后回来时作为上下文使用）](https://github.com/earendil-works/pi/blob/47610217098d9ba8f22d223fa7c1413f9f5fd759/packages/coding-agent/src/core/compaction/compaction.ts#L463-L498) 提示词规定了目标（goal）、进展（progress）和关键决策（key decisions）几个小节。 +3. 这是一个独立请求，不携带任何现有会话历史，这意味着它可以使用另一个 LLM 模型而不产生任何不必要的成本。 + +Compaction 的结果会作为一条 compaction 条目追加到 Pi 会话中，然后会话就可以继续了。经过这次 compaction 请求，上下文已被压缩。 + +```text +compaction 之后： +[system][tools][summary][最近的 turns][新的用户消息] +``` + +现在，会话上下文里又有了容纳许多新消息的空间。 + +Pi 把 compaction 摘要以纯文本形式存储在会话中。这让压缩后的上下文保持可读且[可移植](https://earendil.com/posts/session-portability)——因为我们可以在 Pi 中切换模型，并继续使用这份摘要。 + +## Compaction 与 prompt caching + +LLM 提供商用 [prompt caching](https://earendil.com/posts/prompt-caching) 来降低同一会话中重复请求的成本。在一次活跃的编码会话中，我们为模型已经生成过的上下文支付更少的费用。这种缓存要求前缀精确匹配，所以对会话做 compaction 会打破 prompt cache。 + +```text +compaction 之前的缓存： +[system][tools][较早的历史][保留的最近 turns] +<-------------------- 缓存前缀 --------------------> + +compaction 之后的第一个请求： +[system][tools][summary][保留的最近 turns][新的用户消息] +<--- 可复用 --->^ + | + 第一个变化的 token + | + +-- 此点之后的一切都必须重新计算 +``` + +保留下来的 turns 包含的 token 与之前完全相同，但它们现在跟在一个不同的前缀后面。因此它们之前的缓存状态无法被复用。 + +Compaction 之后的新请求将重新受益于 prompt caching。 + +## 动手实验 + +由于 Pi 是可扩展、可塑造的，你可以用自己的实现替换它的 compaction。要测试一种不同的 compaction 机制，可以让 Pi 创建一个带有自定义 compaction 提示词的扩展。 diff --git a/works/pi-what-is-a-harness-translation.md b/works/pi-what-is-a-harness-translation.md new file mode 100644 index 0000000..86927b1 --- /dev/null +++ b/works/pi-what-is-a-harness-translation.md @@ -0,0 +1,79 @@ +--- +title: "什么是 Harness？" +sourceTitle: "What is a Harness?" +sourceUrl: "https://earendil.com/posts/what-is-a-harness/" +sourceAuthor: "Earendil Product（Pi 团队，rfc@earendil.com）" +sourcePublishedAt: "2026-08-20" +sourceSiteName: "Earendil" +summary: "Pi 团队（Earendil）的 harness 入门定义文：从攀岩安全带类比切入，给出 agent harness 的核心定义——为 AI 模型提供运行环境的软件层，并拆解其四大职能：系统提示词、工具、agentic loop 与模型翻译层。文章进而主张中立、开源、本地运行的 harness 是用户保住能动性、对冲 AI 实验室权力集中的工具，并点名 Claude Code 为第一个流行但非中立的 agent harness。" +sourceLanguage: "en" +language: "zh-CN" +translationMethod: "人工整理逐段翻译（cloud agent，对照原文全文）" +sourceFigureCount: 1 +--- + +# 什么是 Harness？ + +> 原文：[What is a Harness?](https://earendil.com/posts/what-is-a-harness/) · Earendil Product（Pi 团队）· 2026-08-20 + +**Harness**——剑桥词典的定义 + +*名词。*一种带有绳带和束带的装备，用于控制或固定人、动物或物体。 + +*动词。*控制某物，通常是为了利用它的力量。 + +—— + +说到 harness，我首先想到的是中学时爬学校岩壁前系上的那套绳带和束带。我充其量算个平庸的攀岩者。 + +![Royal Robbins 在 El Capitan 上，他的 harness 上挂满了攀登所需的工具。](imgs/pi-what-is-a-harness/royal-robbins-el-capitan-climbing-05.png) + +*Royal Robbins 在 El Capitan（酋长岩）上，他的 harness 上挂满了攀登所需的工具。摄影：[Tom Frost](https://www.frostworksclimbing.com/cool_aid.htm)。* + +不过，如果你最近成天泡在 AI 资讯流里，你心目中 harness 的原型可能早已是 agent harness 了。那么，这篇文章不是写给你的。 + +这篇文章写给那些好奇 agent harness 是什么、却又不好意思开口问的人。 + +我们先回到攀岩。 + +去攀岩时为什么要系上安全带（harness）？首先，它支撑你、保护你的安全。它通过主锁和绳索把你连接起来，防止你坠落、调节你的节奏、约束你的路线。你还可以往 harness 上挂其他工具，比如粉袋、岩塞钩和快挂。 + +而当你去攀不同的山、走不同的线路时，你可以带着你的 harness 一起走。根据地形不同，你甚至可以改装你的 harness，调整装备环上挂什么。攀岩安全带是可适配的。杂技演员和树艺师也在用它。拥有它的人可以把它变成自己的东西。 + +攀岩 harness 与 agent harness 在结构和功能上都有相似之处。 + +## Agent Harness + +有人（简化地）写过：Agent = Model + Harness。这里的 Harness 指的就是 Agent Harness。但 agent harness 到底是什么？Agent harness 利用 AI 模型来构造 AI 智能体，它的第一个应用场景是编程。如今，agent harness 已经位于各类 AI 智能体的核心，理解 agent harness 如何工作，就能帮你理解 AI 智能体是什么。 + +Agent harness 是一层软件，它为 AI 模型提供一个运行于其中的环境。与大多数 AI 模型不同，作为终端用户，你可以拥有属于自己的 agent harness。 + +通常，软件工程师这样的用户会通过电脑上的终端（Terminal）应用直接与 [Pi](https://pi.dev/) 这样的 harness 交互。但像 [OpenClaw](https://openclaw.ai/) 这样的 harness 也会使用不同的用户界面，比如 iMessage、聊天应用或电子邮件。我们的 harness [Lefos](https://www.lefos.com/about) 就主要以电子邮件方式交互。无论界面如何，harness 通常做四件事：第一，提供一组指令，帮助约束 AI 模型如何作答，这组指令通常称为"系统提示词"（system prompt）。第二，描述并提供一组工具，供 AI 模型在响应用户请求时调用。第三，harness 建立一个约束模型行为方式的框架。这个框架做很多不同的事情，其中最主要的一件是建立"agentic loop"（智能体循环）。最后，大多数 harness 还提供一个关键的翻译层，让 harness 能与各种不同的 AI 模型协同工作。 + +### 一、系统提示词 + +大多数 AI 模型自带一套在训练过程中打磨、沉淀下来的内嵌规则与准则。最著名的例子是 Claude Opus 4.5 那份被广泛传播的"[灵魂文档](https://gist.github.com/Richard-Weiss/efe157692991535403bd7e7fb20b6695)"（soul document），它向 AI 模型解释它是什么、应当如何行事。AI harness 中的系统提示词与之类似，但内嵌程度更低。它更像新员工入职第一天拿到的一份工作守则：员工尚未把这些指令内化，但知道在做这份工作时应当遵守。系统提示词会随每一次用户请求一起注入对话，对确保 AI 模型在该 harness 语境下行为得当起着重要作用。 + +### 二、工具 + +工具是一组用代码写成、模型可以"调用"的能力。Harness 既描述这些工具，也提供作为工具本体的软件。这些工具的例子可能包括：网页搜索工具、允许模型编写并执行软件代码的工具，或允许模型撰写电子邮件的工具。关键在于，harness 通常并不规定 AI 模型应当何时、如何使用工具。它只是把工具备好、描述清楚，让 AI 模型自己决定何时以及如何使用它们。 + +### 三、Agentic Loop（智能体循环） + +现在，我们有了一个坐落于 agent harness 之中、手握一组指令和一组工具的 AI 模型。假设我们的 harness 是为电子邮件场景构建的，拥有上文描述的那些工具（WebSearch、WriteCode、ComposeEmail），而用户请智能体对比本地小学的排名和考试成绩并给出推荐。智能体会怎么做？首先，它会尝试理解这个请求（即"提示词"）。它会动用预训练和模型权重去理解什么是"小学"、"本地"指哪里、用户可能关心哪些排名。然后它会构造网页搜索查询去获取最新数据。拿到结果后它做什么？身处 harness 之中的 AI 模型可以对照最初的请求来审视这些结果。它可能判断第一次搜索没有取到正确的信息，或取得不够，于是自行决定再搜一次。这个基于自我评估而再次调用工具的决定，就是"循环"（loop）的第一个清晰示例。现在假设它已收集齐所有相关数据。AI 模型决定用"写代码"工具制作一张电子表格——毕竟所有电子表格本质上都是代码。它可以用这个工具做计算、排版结果，使其清晰易读。接着它把电子表格与最初的提示词对照。如果数据不能令它满意，它可能会"循环"回去再搜一轮。当它认定信息足够时，就调用 ComposeEmail——这个工具让 AI 回顾发现、加以总结、撰写邮件，并附上电子表格这样的附件。模型审视这份最终成果，判定任务完成。"agentic loop"就此闭合。几秒钟内，用户就会收到一封邮件：正文是摘要和推荐，附件是呈现调研结果的电子表格。想看看 agentic loop 在实践中长什么样，可以在[这里](https://pi.dev/session/#b23f2459599f8439327f65c90ee95d06)浏览一个 Pi 会话。 + +### 四、翻译层 + +翻译层让 harness 得以与不同的 AI 模型协同工作。在某些情况下，harness 甚至可能在同一个 agentic loop 中使用不同的模型，因为不同的 AI 模型可能各擅胜场。翻译层之所以是 harness 的关键一环，还因为它把控制权交到了终端用户手里。这意味着一个人可以带着自己的 AI harness，配 Anthropic 的模型用，配 OpenAI 的模型用，或者去尝试那些往往极具性价比（以单任务成本 cost-per-task 衡量）的开放权重模型。 + +这个翻译层帮助把权力和杠杆从 AI 实验室手中拿走，交到终端用户手里。如果人们能在自己的电脑上本地拥有并运行自己的 harness，就意味着他们保住了自己的能动性。意味着他们保有把工具变成自己的东西的自由，保有那些会话的本地副本——这些会话日积月累，将构成他们与机器之间的通信档案。通过与一个 harness 建立关系并使用它，而不是使用某个 AI 实验室发布的应用，用户保住了自由与选择。在上面的示例 harness 中，用户本可以把同一封邮件分别发给一个 OpenAI 的模型、一个 Anthropic 的模型和一个开放权重模型，然后比较结果、比较结果的成本，并把所有答案留存在同一个地方，而不是让三个答案分别躺在三个应用里。 + +## 把 Harness 变成你自己的 + +与 AI 模型本身不同，harness 是你可以拥有并改造的。就像攀岩安全带一样，你可以把它变成自己的东西。人们喜欢 Pi 正是因为这一点。Pi 是一个极简的 agent harness：系统提示词很短，工具集很小，开箱即用的设计原则是"不挡路"。但随着人们使用 Pi，他们会以适合自己的方式扩展它、塑造它。他们修改系统提示词，或者设计一个契合自己工作流的[扩展](https://pi.dev/packages)，然后把这些扩展分享给他人。Pi 用户之间已经互相分享了超过 5,000 个扩展。Pi 也是免费且开源的，它就住在你自己的笔记本电脑上。这意味着人们如今拥有了一件属于自己的、运行在自己硬件上的、让自己得以驾驭 AI 的工具。 + +## 中立的开源 Harness：能动性之器 + +Harness 并非一开始就是开源或中立的。第一个流行起来的 agent harness——Claude Code——并不是为了提供一个模型无关的 AI 翻译层而建，而是作为一个让你在本地电脑上用 Claude 模型编程的应用而建。此后，OpenClaw、OpenCode、Hermes、Pi 等自由开源 agent harness 令人欣喜地不断涌现。在 Earendil，我们把 Pi 打造为中立的 harness，为 Pi 用户提供能力上的选择与自由。我们也在探索如何把 harness 带来的益处与能动性推及更广泛的人群。 + +眼下，许多人担忧越来越庞大的 AI 公司的权力与影响力。其中一些人可能会选择彻底远离 AI。而我们 Earendil 相信，可以通过打造弥合分裂与无知、培育持久喜悦与理解的软件和开放协议，来增强人类的能动性。做到这一点，靠的不是无视今天已经存在的技术，而是以清醒的眼睛和坚定的手去驾驭（harness）它们——确保是我们挥动锤子，而不是锤子挥动我们。 diff --git a/works/zalando-agentic-engineering-translation.md b/works/zalando-agentic-engineering-translation.md new file mode 100644 index 0000000..9fc0608 --- /dev/null +++ b/works/zalando-agentic-engineering-translation.md @@ -0,0 +1,176 @@ +--- +title: "Zalando 的 Agentic 工程实践：一份快照" +sourceTitle: "Agentic Engineering at Zalando: a snapshot" +sourceUrl: "https://engineering.zalando.com/posts/2026/08/agentic-engineering-at-zalando-a-snapshot.html" +sourceAuthor: "Bartosz Ocytko" +sourcePublishedAt: "2026-08-14" +sourceSiteName: "Zalando Engineering Blog" +summary: "Zalando 250+ 工程团队 2.5 年 agentic 工程实践的一手快照：LiteLLM 代理统一 API 访问与成本度量、坚持供应商独立不强制工具、四代码库对照量化 AI 编码对 PR 尺寸与圈复杂度的影响、LLM 按风险分级自动放行 33% 低风险 PR 使 lead time 降 20–40%，以及技能库、治理与规模化培训体系。" +sourceLanguage: "en" +language: "zh-CN" +translationMethod: "人工整理逐段翻译（cloud agent，对照原文全文）" +sourceFigureCount: 3 +--- + + +> 原文：[Agentic Engineering at Zalando: a snapshot](https://engineering.zalando.com/posts/2026/08/agentic-engineering-at-zalando-a-snapshot.html) +> 作者：Bartosz Ocytko（Executive Principal Engineer） +> 发布于 Zalando Engineering Blog，2026-08-14 + +行业环境每天都在快速变化，整个业界都还在摸索该如何对待 Agentic 工程（agentic engineering，智能体工程）。我们有超过 250 个工程团队在各业务线上开展创新，因此得以观察到 LLM 以不同形态、不同节奏产生的价值与影响。我们此前分享过一些早期成果：用 LLM 做[商品数据增强](https://engineering.zalando.com/posts/2024/09/content-creation-copilot-ai-assited-product-onboarding.html)、以 LLM-as-a-judge [提升搜索质量](https://engineering.zalando.com/posts/2026/03/search-quality-assurance-with-llm-judge.html)、做[商品搜索的相关性评估](https://engineering.zalando.com/posts/2024/11/llm-as-a-judge-relevance-assessment-paper-announcement.html)，以及[前端迁移](https://engineering.zalando.com/posts/2025/02/llm-migration-ui-component-libraries.html)。 + +最近，我们回顾了过去 2.5 年的进展，想分享几条对我们行之有效的做法。 + +## 从第一天起就用 LLM proxy 提供 API 化的 LLM 访问 + +早在 GitHub Copilot 只提供 IDE 内自动补全的年代，我们就是它的用户。为了补充这一产品并提供基于 API 的 LLM 访问，我们的 ML 平台团队在 2024 年 1 月部署了一个基于 [LiteLLM](http://docs.litellm.ai/) 的 API 代理，可访问多家供应商的模型（现为 OpenAI、AWS Bedrock 和 Google Vertex）。这样一来，工程师就能轻松地试验不同的工具和模型。平台团队也获得了一个统一的度量采纳情况的入口：MAU、WAU、模型、User-Agent。 + +我们喜欢 LiteLLM 的可扩展性。我们用 post-call hook 做匿名化的成本追踪，用 [pre-call hook](https://docs.litellm.ai/docs/proxy/call_hooks) 基于 User-Agent 请求头限制对代理的访问，从而强制客户端升级版本。对于自行安装管理的客户端，很遗憾，封禁访问是唯一有效的手段。下线模型时也一样——总有一批长尾用户既不调整本地配置，也不关注新模型的发布。我们还启用了 prompt caching 检查点的[自动注入](https://docs.litellm.ai/docs/tutorials/prompt_caching)，在自定义 agent 的作者还在学习 prompt caching 期间，就先降低了它们的成本。为了缓解 LiteLLM 的稳定性与内存泄漏问题，我们通过 `--max_requests_before_restart` 强制其每处理 2 万个请求后重启。这让我们只用六个小型 pod（2 CPU 核、4 GB 内存）就支撑起 2,000 MAU 的代理服务。我们期待其 Rust 重写版本带来性能与稳定性的提升。 + +### API 之外：Chat UI 与 CLI + +在 API 之外，我们还提供一个简单的聊天 UI（fork 自一个如今已停止维护的开源代码库）和一个 CLI 工具（基于 pydantic-ai 自研）。令我们意外的是，尽管如今 IDE 插件和 CLI 已随处可见、用户有大把更强的替代品可选，Chat UI 的采纳率依然很高。CLI 诞生于 2024 年 8 月的一场 hackathon，那时 coding agent 还不存在。起初我们只是在维护脚本里用它在终端访问模型。随着时间推移，这个仓库聚起了一小群维护者，他们为其扩展了更多工具，帮助我们规模化地推广用 LLM 做编码任务： + +- 生成图片，并支持简单的文件格式转换 +- 多轮对话的交互模式，配有加载和保存文件的简单命令用于上下文管理 +- 支持 MCP 的 agent 模式，并为内部托管的 MCP 服务器自动注入 Bearer token +- http 转 stdio 的 MCP 代理，让内部构建的 MCP 服务器可以在任何其他工具中轻松接入 +- 内置 MCP 服务器配置，让首次接触 MCP 的用户几乎无摩擦地上手试验 +- coding agent 配置命令，为 claude code、opencode、pi 安装安全配置，并附带用于模型自动发现的自定义插件 + +token 注入与 MCP 代理帮助我们推广了 MCP 服务器的安全配置方式——配置文件中无需硬编码任何机密。这使得内部部署的 MCP 服务器得以推广使用，而无需操心任何认证问题。随着 LLM 访问的用户群扩展到工程之外、各人安全直觉参差不齐，这一点尤其重要。各团队托管部署的 MCP 服务器会自动受到我们默认的 ingress OAuth 过滤器保护。 + +### LLM 工具链的挑战 + +有两个老问题在不同工具间高度一致。其一，工具太经常使用通用的 User-Agent 请求头，使得我们很难识别代理的客户端到底是哪个工具。对于我们自己的 LLM 应用（例如自定义代码评审 agent），我们确保在 User-Agent 里带上名称、来源仓库和版本。对于其他工具，我们向上游提需求（或直接贡献代码）。 + +其二，工具普遍不支持用自定义 auth 命令生成认证 token，只支持静态凭证，或默认只面向订阅制服务。依赖环境变量令用户沮丧：token 过期后需要手动刷新，还得重启应用。为弥补这个缺口，我们提供了一个注入 auth 请求头的本地代理，并为 coding agent 编写插件来处理模型访问、模型发现及其参数。这个代理逐渐演化出帮助实时调试自研 LLM 工具的功能：它自带一个 TUI，展示每个模型的当前成本、突出显示缓存 token 使用上的缺口，并展示每个请求的元数据（User-Agent、模型、成本、含缓存写入/读取的 token 统计）。未来的改进包括通过分析出站请求，给出更好使用 prompt caching 的提示（灵感来自 pi 的 [`showCacheMissNotices`](https://pi.dev/docs/latest/settings#model-thinking)）。 + +## 供应商独立 + +在快速变化的环境里，供应商独立是关键。我们的代理让我们有能力接入更多 LLM 供应商，而用户自行挑选最合拍的工具。我们从未在公司层面强制使用某个单一工具。用户根据可用的模型和自己的偏好（IDE 还是 CLI）来选择工具。从基于聊天的交互，自然演进到由 CLI 或桌面 UI 编排的 agentic 循环，也进一步推动了工具切换。 + +对一部分用户来说，[opencode](https://opencode.ai/) 和 [pi](https://pi.dev/) 正中甜点：它们允许在 GitHub Copilot 订阅和我们的 API 访问之间混用模型。这种向开放工具的迁移很可能继续推进，因为要脱离封闭权重模型，就必须切换到开放工具。不过，我们也看到用户对用惯了的 coding agent 过于依恋。模型偏好同样有影响——有用户就是偏爱供应商 X 而非 Y 的回答风格。尽管各工具能力大同小异、切换成本其实很低，这种心理层面的换工具迟疑依然存在。 + +我们为各款 coding agent 维护参考配置，也为模型供应商维护插件。虽然我们在探索面向开发者工具的设备管理（Device Management，此前我们从未需要过它），但工具配置目前可以用我们 CLI 里的一条专门命令来应用，它会从一个 git 仓库读取最新的配置状态。 + +## 识别 AI 编码的影响 + +### PR 与代码评审 + +两年来，我们在 PR 数据中都能看到 AI 编码的影响。除了 \([100,500)\) 尺寸段 PR 的持续增长之外，自 2025 年 Q2 Sonnet 4 发布以来，更高的尺寸段也在增长，尤其是 \([500,1k)\) 和 \([1k,2k)\)。 + +![PR 尺寸分布（按季度）](imgs/zalando-agentic-engineering/pr_size_distribution.png) + +*PR 尺寸分布（按季度）* + +认为大 PR 成了问题的团队，已在内部约定把 PR 限制在固定大小以内。通过 pre-commit hook 硬性强制的做法则不太流行。另一些团队习惯了更大的 PR，不再依赖精心编排的提交序列，转而依赖我们所用工具提供的便利，比如 GitHub PR 或 Linear Reviews 里对变更的语义化分组。 + +### 对代码复杂度的影响 + +我们也在代码库本身看到了 AI 编码的影响——好的和坏的实践都被放大了。我们观察了 Java 和 Golang 代码库中代码质量指标在 commit 级别的演化：把每个 commit 映射到几项指标，并绘制其随时间的变化。我们使用了四个代码库： + +| 代码库 | 语言 | 库龄 | Agent 采纳情况 | 备注 | +|---|---|---|---|---| +| `go-agentic-only` | Go | 新库 | 从一开始就全量使用 | 第 0 天起就以规格驱动开发（spec-driven development）构建 | +| `go-reference` | Go | 10 年以上 | 自第 3000 个 commit 之后 | 开源代码库 | +| `java-with-agents` | Java | 4 年 | 自第 1600 个 commit 之后 | 逐步采纳 coding agent | +| `java-reference` | Java | 12 年以上 | 无 | 宏服务（macroservice），代码已陆续抽取到其他仓库 | + +观察 commit 级别的总圈复杂度演化，我们能精确定位 coding agent 进场时代码复杂度出现的拐点。有些代码库带有能佐证这些拐点的标记（Co-authored-by）；另一些（尤其是开源库）则不那么一致，因为并非所有作者都披露自己使用了 coding agent。 + +对于从一开始就全量使用 agentic 编码的代码库，我们看到复杂度极快地堆积，随后增长逐渐消退。如果一个边界清晰的微服务的代码复杂度本就该趋于平台期，那我们希望这意味着构建时间被大幅缩短了。是否如此，时间会给出答案。图中还能看到其中一个代码库在一次重构之后复杂度出现下降。 + +![各代码库的总 CCN（圈复杂度数）](imgs/zalando-agentic-engineering/total_ccn.png) + +*各代码库的总 CCN（圈复杂度数）* + +值得注意的是，连提交信息都带着 coding agent 的足迹，典型地集中在 5,000 字符上下。一个极端案例里，我们发现某条提交信息竟包含了一份完整的单元测试执行日志。这类问题在代码评审中容易被漏掉，因此很适合作为约束加进 pre-commit hook。 + +![各代码库的提交信息大小分布](imgs/zalando-agentic-engineering/message_bytes.png) + +*各代码库的提交信息大小分布* + +## 基于风险的 PR 审批 + +为了守住 PR 的合并前置时间（lead time to merge），我们构建了一个基于风险的 PR 审批工具，在 PR 创建阶段触发。每个 PR 都会按其发布风险被评估为：低、中、高。我们 33% 的 PR 属于低风险，由 bot 自动批准。PR 作者因此可以自行选择合并，这在我们这里把 PR lead time 降低了 20–40%（与全部 PR 相比）。它也大大加速了那些构建原型或维护内部工具的个人——否则他们就得打断某位同事，请对方来给自己的变更"盖个章"。 + +审批 bot 的规则集建立在对我们生产事故及故障典型诱因的分析之上。这些规则高度特定于我们的技术栈、部署清单、配置文件等。会破坏配置的拼写错误被评为高风险（当年若有它，我们本可躲过 [metadpata 事故](https://engineering.zalando.com/posts/2024/01/tale-of-metadpata-the-revenge-of-the-supertools.html)）。破坏向后兼容性是中风险，需要另一个人来复核其业务上的合理性。纯文档变更是低风险。 + +坊间证据表明，这个 bot 正在影响工程师的行为，使其提高 PR 落入低风险的概率。例如，PR 开始被拆分成两类：可以快速发布的（低风险）向后兼容变更，以及不那么紧要、需要额外审批的中风险 PR（如删除未使用的字段）。过去我们观察到这类变更常被混在一起，既拉长了上市时间，也抬高了发布风险。 + +## 从会话数据中学习 + +审视 coding agent 的会话数据极具教育意义。除了发现那些白白消耗 token 的非必要流量（例如生成计划名称、终端窗口标题、给空闲会话写摘要），用户还能更了解自己的提示词模式。我们发现 [agentsview](https://www.agentsview.io/) 很适合跨多个工具检查会话数据，[codeburn](https://github.com/getagentseal/codeburn) 则提供了按项目/任务类型理解使用情况的手段。 + +会话数据带来的一个洞察是：某位用户在 opencode 上的缓存命中率极低（<30%，而预期应为 80% 以上）。为了定位这个低命中率的会话，我们写了一个简单的解析器来计算各会话的缓存命中率。所幸最终查明这并不是波及整个用户群的系统性 bug。 + +## Agent skills + +我们有一个集中式的 agent skill 集合，按插件分组。这些技能覆盖组织内跨学科（如数据、工程、前端、SRE）或跨编程语言的常见任务与关注点。其中广受欢迎的一类是迁移技能，指导团队采纳新的平台工具或基础设施实践（例如多架构构建）。技能集合通过受管配置设置分发，或通过 CLI 命令安装所需的符号链接（例如 opencode 不支持插件市场）。 + +通过鼓励团队广泛贡献自己觉得有用的技能，我们获得了在组织内发现并传播最佳实践的机会，比如在 CI/CD 流水线中校验插件语法、技能与脚本之间的关注点分离（例如 OAuth token 的生成该放在哪里）。 + +自建技能的团队把这个集合当作参考和灵感来源，例如效仿其中对 [agent-skills-eval](https://github.com/darkrishabh/agent-skills-eval) 的使用。 + +## 治理 + +在超过 200 个团队各自创新、广泛探索生态的当下，一个问题随之而来：要不要收敛、何时收敛。我们认为现在还远远太早。在 agentic 工程实践仍处早期阶段之时，我们的核心目标是团队之间的透明与交流。我们借助结构化的知识分享（下文详述）和成熟的治理方法来创造透明度、促进跨团队分享。 + +其中一个机制是我们的 [Tech Radar](https://opensource.zalando.com/tech-radar/)。我们在内部版本中新增了 AI 分区，聚焦于为我们的服务、政策与指南提供概览和关键文档入口。过去 10 年里，类库选型早已下放给各语言的实践社区（communities of practice），不在 Tech Radar 的范畴内。然而，AI 工具的寒武纪大爆发和生态的迅速膨胀，让"哪些实践已被验证、哪些仍处早期"的清晰指引变得更加必要。因此我们认为，为 AI 用例追踪实践、工具与类库是有价值的。为提高透明度，雷达的 AI 分区在我们基于 Backstage 的开发者门户 [Sunrise](https://engineering.zalando.com/posts/2023/08/sunrise-zalandos-developer-platform-based-on-backstage.html) 中拥有独立入口。 + +对于早期项目，我们提供按用例逐一进行法务评估的入口，以确保合规。此外，我们通过扫描已部署的 Docker 镜像来自动检测 AI 模型的使用。相关系统会被自动注册进我们的开发者门户，其负责人会被要求补充所需文档，或接受一次额外的法务审查。 + +## 知识分享 + +知识分享必须顾及生态变化的速度。当最先进水平（state of the art）每天都在变时，早期采纳者与刚入场者的交流需求截然不同。越接近正在成型的最佳实践，越标准化、可规模化的培训形式就越有效。本节介绍在知识交流与培训上对我们行之有效的几种形式。 + +有一点值得指出：找到平衡很重要。工程领域里除了 AI，还有其他值得关注的事情。在我们一年一度的软件工程社区大会（Software Engineering Community Conference）上，我们把 Agentic 工程专题排在第 1 天，为了平衡，把工程基本功（Engineering Fundamentals）专题排在第 2 天。同样，我们还计划新增一门工程卓越（engineering excellence）培训，讲授在我们这种规模下运维系统学到的惨痛教训，推广工程最佳实践。 + +### LLM 公会 + +自 2024 年起，我们有一个聊天频道，用来分享和讨论行业新闻、我们 LLM 服务的相关公告，以及组队做实验。我们每周举办 1 小时的知识分享会，每场演讲或演示占 20 分钟。会议全程录像。 + +分享会设有主持人，负责编排议程、鼓励自己人脉网络中的同事来分享，或在频道里公开征集演讲。这种形式非常适合早期采纳者——他们渴求公司各处同侪最新的知识与实验结果。这些演讲也是重要的人才来源：为项目提供实操支持、探索新方法，并扩充我们的内部讲师储备。 + +我们也在为每周例会尝试不同的形式。比如有一期关于 agent skill 的会，我们把技能对映到开发者旅程的各个环节（构思、设计、编码、测试、监控、运维、维护），以此推广我们的全公司 agent skill 市场。先请与会者补充自己团队做过的、可以补充全局集合的技能示例；然后按旅程环节分组讨论（breakout rooms），各组汇总"尚不存在的技能"的机会陈述。 + +### 有引导的实验 + +秉持有引导的创新（guided innovation）精神，我们在 hackathon 上取得了成功：由组织团队预先选定约 10 个题目。题目包含明确的目标、值得考虑什么的提示、哪些不在范围内，以及与其他小组存在哪些潜在协同。 + +这些题目在一场 2–3 天、开放报名的 hackathon 中被逐一攻克：4–6 人的小组在既定约束下尝试达成设定的目标。活动期间，范围和约束可以与引导者协商调整。 + +早期，这种方式让我们得以并行探索多条路径，再决定投资哪些工具。其中一个以此形式探索的题目，是按模板构建 MCP 服务器——它孕育了 Zalando 第一批由社区维护的 MCP 服务器。另一个小组则被明确要求不要看 MCP，而是探索面向 API 的通用方案：先在我们的 API 定义目录中搜索，再根据用户提示词生成 API 调用。这项尝试很成功，构建在我们的内部 API 目录之上——如今该目录本身也作为一个 MCP 工具对外暴露。它还暴露了 API 规格质量的缺口，例如缺失主机名导致无法生成能用的 API 调用。 + +我们也举办以业务单元为范围的 hackathon，团队围绕业务目标组队，以快速原型、锤炼 agentic 工程技能等为目标。 + +### 从 Labs 到培训 + +我们用一种称作 *GenAI Labs* 的形式在组织内分享知识。Lab 是约 20 人的线下工作坊，由 1–2 名讲师主持，时长 1–4 小时。在简短的主题介绍之后，与会者两两结对完成一组练习。较长的场次会在中场休息时做小组分享。某个主题的首场 Lab，我们会用简短的报名表按与会者过往的 agentic 工程经验预先分组。这带来了时间上高效的探索：3 天之内我们能在多个办公地点开 6 场，覆盖约 120–150 名参与者。 + +打算更频繁举办的 Lab 场次会被转化为月度培训。讲师从此前 Lab 的学员中招募。讲师会根据学员反馈打磨内容。负责内部培训的 Tech Academy 团队协助组织引导，照看学员与讲师的体验。 + +我们每月固定开两场培训：使用 MCP 服务器，以及用 pydantic-ai 构建 agent。前者帮助所有人建立对 MCP 概念的认识，并推广我们的内部 MCP 服务器集合；后者讲解工具调用与 agent 循环的基本概念，让学员从原理上理解他们日常使用的 agent 到底是怎么运作的。我们打算在 agent 培训里加入 prompt caching 的教学，并新增几门课：使用 coding agent、agent skills，以及构建 agentic 循环。这三门课我们已在[年度工程大会](https://engineering.zalando.com/posts/2024/06/hosting-an-internal-engineering-conference.html)的工作坊里试讲过，验证了需求。 + +关于培训还有一条重要的指导原则：既然培训的目的是习得新技能，就要明确告知学员何时需要手写代码。我们观察到，参与者用 coding agent 抄近道出结果的诱惑非常大。然而，使用 coding agent 通常会抑制学习。 + +## 迈向下一个层级 + +放眼业界，许多 AI 战果和 PR 吞吐量的提升都来自杠杆效应最高的 monorepo。我们虽有若干 monorepo，但微服务大都采用独立仓库。我们将实现一个扫描器来评估每个仓库的 AI 就绪度（AI readiness），从而分析交付姿态与代码库健康度之间的关联。就绪度评估还有个不错的副作用：整体代码质量的提升，以及那些原本因 ROI（投资回报率）不足而不会被落实的工程最佳实践得到推广。 + +为了管理微服务舰队，我们有一个工具，可以定义在一组仓库上批量执行的变换（transformation）。这些变换如今已包含基于 AI 的调整——对代码库运行 coding agent CLI。在改进和标准化代码库的过程中，我们预计这个功能的使用量将显著增长。 + +## 接下来是什么？ + +和业内所有人一样，我们观察到 AI 会放大组织里好的和坏的实践。被 agentic 工程冲昏头脑的团队，最终会产出让评审者望而却步的大 PR，拖慢交付，直到团队调整自己的实践。 + +我们也确实看到平台投资在获得回报。我们的 Zalando web monorepo 会为每个 PR 建立一套接入真实数据的部署。这个机制如今不仅赋能了 agent，也赋能了非工程师——他们可以用提示词发起修改并轻松查看结果，然后再请工程师接手。其他前端团队也纷纷实现了类似的机制。我们的内部文档托管被用来安全地托管静态网站形式的应用与原型。在 coding agent 的加持下，工程师们发布了各种仪表盘、演示、数据可视化工具、带客户端逻辑的应用等等。为了让搭建原型更容易，我们将把这一流程向非工程师开放——今天他们还被要求从建仓库开始，而他们的需求通常只是把跑在 localhost 上的原型分享给同事。这方面我们受到了 [Shopify Quick](https://shopify.engineering/quick) 的启发。 + +和其他所有科技公司一样，我们也在构建一个 agent 平台。它旨在让团队轻松定义和部署 agent，而无需自行操心沙箱问题。我们用开源组件来组装这个平台，例如用 [kagent](https://kagent.dev/) 处理 agent 在 Kubernetes 上的运行时。我们还在构建一个 Identity Broker 组件：捕获 on-behalf-of（代表用户）流程中的委托链、在不同 OAuth2 基础设施之间做中介，并实现一个 token 保险库。它的设计定位是被基础设施网关使用，处在 agent 与 MCP 服务器之间、或 agent 与 agent 之间的调用路径上。我们的目标是同时简化 agent 与 MCP 服务器的开发，把 agentic 系统中最难的认证与授权问题在一处集中解决。我们的同事将在 2026 年 9 月 18 日于阿姆斯特丹举行的 [AGNTCon + MCPCon Europe](https://sched.co/2RBAI) 上分享更多关于 Identity Broker 的内容。 + +我们还有一长串待解决的问题，比如：管理用户设备上的工具与配置（或者把本地环境彻底搬上云端）、本地沙箱，以及跨模型（含开放权重模型）的自动路由——用户很少主动切换模型，除非被限额或报错推了一把。如果你所在的是一个正在攻克类似问题的非供应商工程团队，并且本文分享的经验让你感到似曾相识，欢迎联系我们。 + +--- + +*我们在招人！你喜欢在 Zalando 这样不断演进的组织中工作吗？欢迎加入我们，成为一名[机器学习工程师](https://jobs.zalando.com/en/jobs?category=Software+Engineering+-+Machine+Learning&utm_source=eng_blog&utm_content=agentic-engineering-at-zalando)！*