Supplement 6 lectures with missing source article content

Cover concepts that were previously missing or incomplete from the
three reference articles (OpenAI harness engineering + Anthropic
long-running agents + Anthropic harness design):

- L01: Add OpenAI's empty-repo experiment (0 human-written lines,
  1M+ agent-generated lines, 1500 PRs, 3 engineers)
- L05: Deepen context anxiety analysis with Sonnet 4.5 vs Opus 4.5
  data, compaction vs reset trade-offs
- L09: Add self-evaluation bias and generator-evaluator separation
  with DAW experiment cost comparison table
- L10: Add layered domain architecture enforcement and custom
  lint patterns from OpenAI's Codex practice
- L11: Add three-agent architecture with detailed phase timing
  and cost data from Anthropic's DAW experiment
- L12: Add golden principles, garbage collection cycle, harness
  simplification as models improve (Opus 4.6), and high-throughput
  merge philosophy

Also fix root index.md to auto-redirect based on browser language.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sanbuphy

docs/index.md

@@ -2,11 +2,24 @@
 layout: page
 ---
 
-# Learn Harness Engineering
+<script setup>
+if (typeof window !== 'undefined') {
+  const lang = navigator.language || navigator.languages?.[0] || ''
+  const target = lang.startsWith('zh') ? '/zh/' : '/en/'
+  if (!window.location.pathname.replace(/\/$/, '').endsWith(target.replace(/\/$/, ''))) {
+    window.location.replace(target)
+  }
+}
+</script>
 
-A project-based course on building the environment, state management, verification, and control mechanisms that make Codex and Claude Code work more reliably.
+# Learn Harness Engineering
 
-Choose your language / 选择语言：
+Redirecting...
 
-- [English →](/en/)
-- [中文 →](/zh/)
+<template>
+<p>Choose your language / 选择语言：</p>
+<ul>
+  <li><a href="/zh/">中文</a></li>
+  <li><a href="/en/">English</a></li>
+</ul>
+</template>

docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md

@@ -63,6 +63,18 @@ OpenAI 在 2025 年发布的 harness engineering 文章里说得很直白：Code
 
 ## 实际案例
 
+### 从零开始的实验：0 行人工代码
+
+OpenAI 在 2025 年做了一个激进的实验：用 Codex 从一个空的 git 仓库起步，构建一个完整的内部产品。五个月后，这个仓库有大约 100 万行代码——应用逻辑、基础设施、工具、文档、内部开发工具——全部由 agent 生成。三个工程师驱动 Codex，开了大约 1,500 个 PR 并合并。平均每人每天 3.5 个 PR。
+
+这个实验的关键约束是：**人类永远不直接写代码。** 这不是噱头，而是为了逼团队搞清楚——当工程师的主要工作不再是写代码，而是设计环境、表达意图、构建反馈回路时，到底什么变了？
+
+早期进展比预期慢。不是 Codex 不行，而是环境不够完整——agent 缺少必要的工具、抽象和内部结构来推进高层次目标。工程师的工作变成了：把大目标拆成小积木（设计、编码、审查、测试），让 agent 去搭建，然后用这些积木解锁更复杂的任务。当某件事失败了，修复几乎从来不是"更努力"，而是"agent 缺什么能力，怎么让它既可理解又可执行"。
+
+这个实验直接证明了本讲的核心论点：**同一个模型，在空白环境里和在有完整 harness 的环境里，产出有本质差异。** 模型没变，变的是环境。
+
+### 一个更小的对照实验
+
 一个团队用 Claude Sonnet 给一个中等规模的 Python Web 应用（FastAPI + PostgreSQL + Redis，约 15,000 行代码）添加新的 API 端点。
 
 **初始配置**：只给了"在 `/api/v2/users` 下添加用户偏好设置端点"这一句指令。

docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md

@@ -99,6 +99,18 @@ OpenAI 和 Anthropic 都在他们的文档里强调了结构化状态持久化
 
 **混合策略**：不需要每次都重置上下文。短任务（30 分钟以内）可以在同一个会话里完成。长任务（跨会话）必须用进度文件和决策日志来维持连续性。判断标准：如果任务需要的上下文超过窗口的 60%，就开始准备交接。
 
+### 上下文焦虑的深层分析
+
+Anthropic 在 2026 年 3 月发布的研究进一步揭示了上下文焦虑的具体表现：在 Sonnet 4.5 上，当上下文接近窗口限制时，agent 会表现出强烈的"过早收敛"行为——匆忙结束当前工作、跳过验证步骤、选简单方案而非最优方案。这就像考试时发现时间快到了，赶紧随便填选择题。
+
+针对这个现象，有两种策略：
+
+**压缩（Compaction）**：在同一个会话里把早期对话摘要化。优点是保留连续性，agent 能看到"是什么"。缺点是"为什么"经常在摘要中丢失——为什么选了方案 B 而非 A，为什么跳过了某个优化。更关键的是，压缩并不能消除上下文焦虑——agent 知道上下文曾经很大，心理上仍然倾向于加速收尾。
+
+**重置（Context Reset）**：完全清空上下文，开一个新会话，从持久化工件重建。优点是干净的心理状态——新会话没有"我快没时间了"的焦虑。缺点是依赖交接工件的完备性。如果交接文件漏了关键信息，新会话可能在错误方向上浪费时间。
+
+Anthropic 的实际数据：对于 Sonnet 4.5，上下文焦虑足够严重，以至于压缩单独不够用，上下文重置成为 harness 设计的关键组件。但对于 Opus 4.5，这种行为大幅减弱，可以不依赖重置而靠压缩管理上下文。这意味着：**harness 设计需要对目标模型有具体的理解，而不是套用通用模板。**
+
 ## 实际案例
 
 一个 agent 被要求实现一个带用户认证的博客系统，12 个功能点，预计需要 5 个会话。

docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md

@@ -42,6 +42,19 @@
 
 Claude Code 有一个常见行为模式：在核心功能还没验证通过时就开始重构代码、优化性能、改进风格。Knuth 说的"过早优化是万恶之源"在 agent 场景中有了新含义——重构会改变已完成验证和未完成验证之间的边界，可能破坏之前隐式正确的代码路径。
 
+### 自我评价的系统性偏差
+
+Anthropic 在 2026 年的研究中发现了一个更深层的失败模式：**当 agent 被要求评估自己的工作时，它系统性地过度正面评价——即使人类观察者认为质量明显不达标。** 这个问题在主观任务（如设计审美）上尤其严重——"布局是否精致"是一个判断题，agent 可靠地偏向正面。即使在有可验证结果的任务上，agent 也会因为判断失误而影响表现。
+
+解决方案不是让 agent "更客观"——同一个模型既生成又评估，内在地倾向对自己慷慨。**解决方案是把"干活的人"和"检查的人"分开。** 一个独立的评估 agent，经过专门调校为"挑剔"之后，比让生成 agent 自我评估有效得多。Anthropic 的实验数据：
+
+| 架构 | 运行时长 | 成本 | 核心功能是否可用 |
+|------|---------|------|---------------|
+| 单 agent 裸跑 | 20 分钟 | $9 | 否（游戏实体无法响应输入） |
+| 三 agent（planner + generator + evaluator） | 6 小时 | $200 | 是（游戏可以正常游玩） |
+
+这是同一个模型（Opus 4.5），同一段提示词（"做一个 2D 复古游戏编辑器"）。区别只在 harness——从"裸奔"到"planner 扩展需求 → generator 逐功能实现 → evaluator 用 Playwright 实际点击测试"。
+
 ## 怎么做才对
 
 ### 1. 外部化终止判定

docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md

@@ -54,6 +54,16 @@ OpenAI 在 Codex 工程实践中强调：**为 agent 写的错误消息必须包
 
 ## 怎么做才对
 
+### 0. 架构执行：在写端到端测试之前先定义边界
+
+端到端测试的前提是系统有清晰的边界。如果架构是一团面条，端到端测试只会证明"这团面条整体能跑"，不会告诉你哪里违反了设计意图。
+
+OpenAI 的经验：**对 agent 生成的代码库，架构约束必须是第一天就建立的早期前置条件，不是等团队规模大了再考虑的事。** 原因很直接——agent 会复制仓库中已有的模式，即使那些模式是不均匀的或次优的。没有架构约束，agent 会在每次会话中引入更多偏差。
+
+OpenAI 采用了"分层领域架构"——每个业务领域（如"用户设置"、"支付"）被分成固定的层：Types → Config → Repo → Service → Runtime → UI。依赖方向严格向前，跨领域关注点（认证、遥测、功能开关）通过一个显式的 Providers 接口进入。任何其他依赖都是禁止的，并且通过自定义 lint 机械执行。
+
+关键原则：**执行不变量，不微管实现。** 比如要求"数据在边界解析"，但不规定用哪个库（模型自己倾向 Zod，但 harness 没指定）。错误消息要包含修复指导——不只是说"违规了"，而是告诉 agent 具体怎么改。这种面向 agent 的 lint 比"人类看的"文档有效得多。
+
 ### 1. harness 必须包含端到端层
 
 在你的验证流程里明确：对于涉及跨组件修改的任务，端到端测试通过是完成的前置条件。在 CLAUDE.md 里写：

docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md

@@ -103,6 +103,35 @@
 
 ## 实际案例
 
+### Anthropic 的三 agent 架构实验
+
+Anthropic 在 2026 年 3 月发布了一项系统性的 harness 实验。他们用三种架构跑同一个任务（"用 Web Audio API 做一个浏览器端 DAW"），记录了详细的阶段数据：
+
+| Agent 和阶段 | 时长 | 成本 |
+|------------|------|------|
+| Planner（规划者） | 4.7 分钟 | $0.46 |
+| Build 第 1 轮 | 2 小时 7 分钟 | $71.08 |
+| QA 第 1 轮 | 8.8 分钟 | $3.24 |
+| Build 第 2 轮 | 1 小时 2 分钟 | $36.89 |
+| QA 第 2 轮 | 6.8 分钟 | $3.09 |
+| Build 第 3 轮 | 10.9 分钟 | $5.88 |
+| QA 第 3 轮 | 9.6 分钟 | $4.06 |
+| **总计** | **3 小时 50 分钟** | **$124.70** |
+
+三个 agent 各司其职：
+
+**Planner（规划者）**：接收一段 1-4 句话的用户需求，扩展成完整产品规格。被要求"大胆设定范围"并且"专注于产品上下文和高层技术设计，而不是详细的技术实现"。原因是：如果 planner 过早指定了粒度技术细节且搞错了，错误会级联到下游实现。更好的做法是约束交付物，让 agent 在执行中自己找到路径。
+
+**Generator（生成者）**：按 sprint 逐个功能实现。每个 sprint 前和 evaluator 协商一份 sprint 合同——约定这个功能块"做完"的标准。然后按合同实现，自评后交给 QA。
+
+**Evaluator（评估者）**：用 Playwright MCP 像用户一样点击运行中的应用，测试 UI 功能、API 端点和数据库状态。对每个 sprint 按四个维度评分——产品深度、功能性、视觉设计和代码质量。每个维度有硬性阈值，任一不达标则 sprint 失败，generator 收到详细反馈后修复。
+
+QA 第 1 轮反馈的示例——"这是一个视觉上令人印象深刻的应用，AI 集成工作良好，但核心 DAW 功能有几个是展示性的，没有交互深度：剪辑不能拖拽/移动，没有乐器 UI 面板（合成器旋钮、鼓垫），没有视觉效果编辑器（EQ 曲线、压缩器仪表）"。这些不是边缘情况——它们是让 DAW 可用的核心交互。
+
+Evaluator 不是一开始就这么强。早期版本会识别出合理的问题，然后说服自己这些问题不严重，最终批准工作。调校方式是：读 evaluator 的日志，找到它的判断和人类判断分叉的地方，更新 QA 的 prompt 解决那些问题。经过几轮这种开发循环，evaluator 的评分才变得合理。
+
+### 更小规模的案例
+
 一个使用计划者-生成者-评估者工作流的 harness，执行"添加暗色模式支持"任务：
 
 **不可观测版本**：3-4 轮盲重试，45 分钟，勉强可接受的输出。评估者说"感觉不太对"但说不出哪里不对。生成者在错误方向上浪费大量时间。

docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md

@@ -23,6 +23,16 @@ OpenAI 和 Anthropic 都明确指出：**长期可靠性取决于操作纪律，
 
 Lehman 的软件演化定律告诉我们：持续变更的系统，除非主动管理，否则复杂性必然增加。这对 AI 编码 agent 尤其成立——agent 每次会话都会引入变更，如果不在退出时清理，技术债务会指数级累积。
 
+**agent 会复制仓库中已有的模式——即使那些模式是不均匀的或次优的。** 这是 OpenAI 在 5 个月的 Codex 实验中观察到的一个核心现象。随着时间的推移，这种复制必然导致漂移。
+
+OpenAI 团队最初花每周五（20% 的工作时间）手动清理 "AI slop"。不出所料，这种方式不可扩展。他们的解决方案是：
+
+1. **把"黄金原则"编码进仓库**：比如"优先使用共享工具包而非手写的 ad-hoc 辅助函数"（保持不变量集中）、"不要 YOLO 式地猜数据结构"（验证边界或依赖类型化 SDK）。这些原则是具体的、机械的、可自动检查的。
+2. **建立周期性的清理流程**：一组后台 Codex 任务定期扫描偏差，更新质量评分，开针对性的重构 PR。大多数可以在一分钟内审查并自动合并。
+3. **人类品味捕获一次，持续执行**：审查意见、重构 PR、用户侧 bug 都被转化为文档更新或直接编码到工具中。当文档不够用时，把规则提升为代码。
+
+这个机制就像垃圾回收——技术债是高息贷款，持续小额还清几乎总是比攒到一次性爆发好得多。
+
 真实数据很说明问题。一个使用 agent 持续开发 12 周的项目，没有清洁策略的情况下：
 
 - 第 1 周：构建通过率 100%，测试通过率 100%，新会话启动 5 分钟
@@ -106,9 +116,23 @@ Lehman 的软件演化定律告诉我们：持续变更的系统，除非主动
 
 ### 4. 定期简化 harness
 
-Anthropic 的一个重要洞见：**harness 里的每个组件之所以存在，是因为模型无法独立做好某件事。但随着模型改进，这些假设会过时。** 三个月前必不可少的约束现在可能是多余的开销。
+harness 里的每个组件之所以存在，是因为模型无法独立做好某件事。但随着模型改进，这些假设会过时。
+
+Anthropic 的实验直接展示了这一点。他们最初的 harness 包含 sprint 拆分机制——把工作分成小块让 Sonnet 4.5 逐个完成。当 Opus 4.6 发布后，模型的原生能力已经可以自主处理工作分解，sprint 构造变成了不必要的开销。移除后，builder agent 能连续工作超过两小时而不会跑偏，反而更流畅。
+
+但 evaluator 的情况不同。即使 Opus 4.6 能力更强，在任务接近模型能力边界时，evaluator 仍然提供了实际价值——捕获 generator 的遗漏功能和存根实现。这意味着 evaluator 不是一个固定的是/否决策，而是取决于任务难度相对于模型能力的位置。
+
+**推荐做法**：每月挑一个 harness 组件，暂时禁用它，跑基准任务。如果结果没退化，永久移除。如果退化了，恢复或用更轻量的替代。
+
+一个更具体的原则：**随着模型改进，harness 的有趣组合不是变少了，而是移动了。** 以前必须解决的问题被模型能力覆盖了，但新的能力边界打开了以前不可能的 harness 设计。AI 工程师的工作是持续找到下一个有价值的组合。
+
+### 5. 高吞吐量改变了 merge 哲学
+
+当 agent 的产出远超人类审查能力时，传统的 merge 哲学需要调整。
+
+OpenAI 团队的经验：在一个 agent 每天开 3.5 个 PR（且后来增加到更多）的环境里，最小化阻塞式 merge gate 是正确的。PR 应该短命。测试 flake 通常用后续运行解决，而不是无限期阻塞进度。在一个修正成本很低、等待成本很高的系统里，快速前进 + 快速修正是比缓慢确认更好的策略。
 
-推荐做法：每月挑一个 harness 组件，暂时禁用它，跑基准任务。如果结果没退化，永久移除。如果退化了，恢复或用更轻量的替代。
+**注意**：这在低产出环境里是不负责任的。但在 agent 产出远超人类注意力的环境里，这往往是正确的权衡。关键判断标准：**修正一个 bug 的平均成本 vs 等待人类审查一个 PR 的平均成本。** 前者低于后者时，快速合并是对的。
 
 ### 5. 清理操作必须幂等