Skip to content

Harness engineering beginner tutorial, from 0 to 1

Polish Chinese docs and resource translations

sanbuphye8e1c5d652b9
diff --git a/README-CN.md b/README-CN.md
index d8fc8cf..d6375dd 100644
--- a/README-CN.md
+++ b/README-CN.md
@@ -2,7 +2,7 @@
> 这是一门项目制课程:系统学习如何通过环境、状态、验证与控制机制,让 Codex 和 Claude Code 更可靠地工作。
-[English Version](./README.md)
+[英文版](./README.md)
本课程仍在持续建设中,内容后续可能会调整。
@@ -18,7 +18,7 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- 哪些规矩必须遵守
- 怎么保持干净、不留烂摊子
-这门课是**强实践导向**的。我们不会只停留在"概念解释",而是会让 Codex 或 Claude Code 在同一个不断演化的 Electron 应用上反复工作,并比较弱 harness 与强 harness 的差异。
+这门课是**强实践导向**的。我们不会只停留在“概念解释”,而是会让 Codex 或 Claude Code 在同一个不断演化的 Electron 应用上反复工作,并比较弱 harness 与强 harness 的差异。
课程真正关心的问题是:
@@ -29,11 +29,11 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
## 核心观点
-以后让模型干活,人只需要定好规则和边界——这就是 harness。
+以后让模型干活,人只需要定好规则和边界。这就是 harness。
**这事的关键:** 模型很强,但不代表它能自动靠谱地完成真实工程任务。它需要一套明确的规则来约束自己的行为范围、需要清晰的交接机制来维持长时任务的连续性、需要验证手段来确认自己做对了。
-我们不是在尝试"让模型本身更聪明",而是研究:怎么给模型搭建一个靠谱的工作环境,让同一个模型做出更可靠的工作。
+我们不是在尝试“让模型本身更聪明”,而是在研究:怎么给模型搭建一个靠谱的工作环境,让同一个模型做出更可靠的工作。
## 快速开始
@@ -69,7 +69,7 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- [`clean-state-checklist.md`](./docs/resources/zh/templates/clean-state-checklist.md) —— 每次会话结束前的清理清单
- [`evaluator-rubric.md`](./docs/resources/zh/templates/evaluator-rubric.md) —— 评审 agent 产出质量的评分表
-每个文件的详细用法写在 [中文模板指南](./docs/resources/zh/templates/index.md)。英文版见 [English template guide](./docs/resources/en/templates/index.md)。
+每个文件的详细用法写在 [中文模板指南](./docs/resources/zh/templates/index.md)。英文版见 [英文模板指南](./docs/resources/en/templates/index.md)。
如果你想直接用 OpenAI 那篇 harness engineering 文章里的更完整高级结构,可以继续看
[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/index.md)
@@ -103,25 +103,25 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
### 资料库
-- [Resource Library 总览](./docs/resources/index.md)
+- [资料库总览](./docs/resources/index.md)
- [中文资料库](./docs/resources/zh/index.md)
-- [English Resource Library](./docs/resources/en/index.md)
+- [英文资料库](./docs/resources/en/index.md)
## 学习路径推荐
这门课按顺序来效果最好,每一阶段都建立在前一个的基础上。
-**第一阶段 — 先看到问题。** 读 Lecture 01-02,做 Project 01。你会跑两次同样的任务:一次只给提示词,一次加了最基本的规则。差距一目了然。
+**第一阶段 — 先看到问题。** 读讲义 01-02,做项目 01。你会跑两次同样的任务:一次只给提示词,一次加了最基本的规则。差距一目了然。
-**第二阶段 — 让项目对 agent 友好。** Lecture 03-04,Project 02。你会重组项目结构,让 agent 能读懂,并且加上跨会话的持久文件。
+**第二阶段 — 让项目对 agent 友好。** 讲义 03-04,项目 02。你会重组项目结构,让 agent 能读懂,并且加上跨会话的持久文件。
-**第三阶段 — 让会话接得上。** Lecture 05-06,Project 03。这里开始有意思了——让 agent 在你关掉会话后重新打开,还能从上次停下的地方接着干。
+**第三阶段 — 让会话接得上。** 讲义 05-06,项目 03。这里开始有意思了,让 agent 在你关掉会话后重新打开,还能从上次停下的地方接着干。
-**第四阶段 — 加上反馈和范围控制。** Lecture 07-08,Project 04。防止 agent 做多了或做少了,用运行反馈让它保持在正轨上。
+**第四阶段 — 加上反馈和范围控制。** 讲义 07-08,项目 04。防止 agent 做多了或做少了,用运行反馈让它保持在正轨上。
-**第五阶段 — 验证和自查。** Lecture 09-10,Project 05。让 agent 学会验证自己的工作,而不是做完就说"好了"。
+**第五阶段 — 验证和自查。** 讲义 09-10,项目 05。让 agent 学会验证自己的工作,而不是做完就说“好了”。
-**第六阶段 — 全部串起来。** Lecture 11-12,Project 06。这是 capstone。你将从零开始搭建一套完整的 harness,把前面学的全用上。
+**第六阶段 — 全部串起来。** 讲义 11-12,项目 06。这是综合项目。你将从零开始搭建一套完整的 harness,把前面学的全用上。
每个阶段大约一周(兼职节奏)。想快的话,前三个阶段一个周末就能跑完。
@@ -131,7 +131,7 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- 已经在使用 coding agent、希望提升稳定性和质量的工程师
- 想系统理解 harness 设计的研究者或构建者
-- 需要理解"环境设计如何影响 agent 表现"的技术负责人
+- 需要理解“环境设计如何影响 agent 表现”的技术负责人
这门课不适合:
@@ -156,7 +156,7 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- 允许 agent 运行命令
- 检查输出并重复执行任务
-如果你没有这类工具,仍然可以阅读课程内容,但无法按预期完成课程 project。
+如果你没有这类工具,仍然可以阅读课程内容,但无法按预期完成课程项目。
## 本地预览
@@ -200,7 +200,7 @@ npm run docs:dev
## 贯穿项目
-本课程的大多数 project 都围绕同一个产品展开:
+本课程的大多数项目都围绕同一个产品展开:
- 一个基于 Electron 的个人知识库桌面应用
@@ -210,7 +210,7 @@ npm run docs:dev
- 管理文档库
- 处理与索引文档
- 对导入内容发起 AI 问答
-- 返回带引用的 grounded 回答
+- 返回带引用且可追溯的回答
之所以选择这个项目,是因为它同时具备:
@@ -222,8 +222,8 @@ npm run docs:dev
本课程包含两类内容:
-- **Lectures**:12 个概念单元,每个单元只回答一个核心问题
-- **Projects**:6 个实践项目,把 lecture 里的方法落实到同一个 Electron 应用上
+- **讲义**:12 个概念单元,每个单元只回答一个核心问题
+- **项目**:6 个实践项目,把讲义里的方法落实到同一个 Electron 应用上
每个 project 都要求你:
@@ -231,20 +231,20 @@ npm run docs:dev
- 比较弱 harness 与强 harness 的差别
- 观察可靠性、连续性、验证质量、可维护性的变化
-最后一个 project 同时也是整个课程的 capstone harness。
+最后一个项目同时也是整个课程的综合 harness。
## 课程组织方式
-- 每个 lecture 聚焦一个问题
-- 整门课配套 6 个 project
-- 每个 project 都要求 agent 真正干活
-- 每个 project 都要做弱 harness / 强 harness 对照
-- 我们关心的是效果变化,而不是"写了多少说明文档"
+- 每个讲义聚焦一个问题
+- 整门课配套 6 个项目
+- 每个项目都要求 agent 真正干活
+- 每个项目都要做弱 harness / 强 harness 对照
+- 我们关心的是效果变化,而不是“写了多少说明文档”
## 仓库结构
- `docs/lectures/` - 全部讲义
-- `docs/projects/` - 全部实践项目,包括 capstone
+- `docs/projects/` - 全部实践项目,包括综合项目
- `docs/resources/` - 中英双语的可复用模板、检查清单和方法参考
-每个 lecture 都带一个 `code/` 目录,用来放小型真实示例和 supporting artifacts。
+每个讲义都带一个 `code/` 目录,用来放小型真实示例和配套材料。
diff --git a/docs/index.md b/docs/index.md
index f53d327..60d07f0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -43,13 +43,13 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- [Lecture 01. 为什么强模型依然会失败](/lectures/lecture-01-why-capable-agents-still-fail/)
- [Lecture 02. 什么才算 harness](/lectures/lecture-02-what-a-harness-actually-is/)
-- [Lecture 03. 为什么仓库必须成为 system of record](/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
+- [Lecture 03. 为什么仓库必须成为唯一事实来源](/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
- [Lecture 04. 为什么一个巨大的 instruction 文件会失败](/lectures/lecture-04-why-one-giant-instruction-file-fails/)
- [Lecture 05. 为什么长时任务会失去连续性](/lectures/lecture-05-why-long-running-tasks-lose-continuity/)
- [Lecture 06. 为什么初始化必须是独立阶段](/lectures/lecture-06-why-initialization-needs-its-own-phase/)
-- [Lecture 07. 为什么 scope 必须被显式化](/lectures/lecture-07-why-agents-overreach-and-under-finish/)
+- [Lecture 07. 为什么任务边界必须被显式化](/lectures/lecture-07-why-agents-overreach-and-under-finish/)
- [Lecture 08. 为什么验证必须外部化](/lectures/lecture-08-why-feature-lists-are-harness-primitives/)
-- [Lecture 09. 为什么 runtime feedback 必须进入 harness](/lectures/lecture-09-why-agents-declare-victory-too-early/)
+- [Lecture 09. 为什么运行时反馈必须进入 harness](/lectures/lecture-09-why-agents-declare-victory-too-early/)
- [Lecture 10. 为什么完整验证才算真的验证](/lectures/lecture-10-why-end-to-end-testing-changes-results/)
- [Lecture 11. 为什么可观测性必须进入 harness](/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
- [Lecture 12. 为什么每次会话都必须干净收尾](/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
@@ -58,18 +58,18 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
> 项目正文目前仍以英文为主,中文先提供导览和学习路径。
-- [Project 01. 基线 vs 最小 harness](/projects/project-01-baseline-vs-minimal-harness/)
-- [Project 02. Agent-readable workspace 与 continuity scaffold](/projects/project-02-agent-readable-workspace/)
-- [Project 03. Scope control 与 grounded verification](/projects/project-03-multi-session-continuity/)
-- [Project 04. Runtime feedback 与 structural control](/projects/project-04-incremental-indexing/)
-- [Project 05. Evaluator loop 与三角色升级](/projects/project-05-grounded-qa-verification/)
-- [Project 06. Benchmark、cleanup 与 capstone harness](/projects/project-06-runtime-observability-and-debugging/)
+- [Project 01. 基线提示词 vs 最小 harness](/projects/project-01-baseline-vs-minimal-harness/)
+- [Project 02. 让项目对 agent 可读,并接住上次的工作](/projects/project-02-agent-readable-workspace/)
+- [Project 03. 让 agent 在会话重启后继续推进](/projects/project-03-multi-session-continuity/)
+- [Project 04. 用运行时反馈修正 agent 的行为](/projects/project-04-incremental-indexing/)
+- [Project 05. 让 agent 学会评审并验证自己的工作](/projects/project-05-grounded-qa-verification/)
+- [Project 06. 基准测试、清理与综合 harness](/projects/project-06-runtime-observability-and-debugging/)
### 资料库
- [资料库总览](/resources/)
- [中文资料库](/resources/zh/)
-- [English Resource Library](/resources/en/)
+- [英文资料库](/resources/en/)
## 快速开始
@@ -86,16 +86,16 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- 评审模板:[`evaluator-rubric.md`](/resources/zh/templates/evaluator-rubric.md)
- 启动脚本参考:`docs/resources/zh/templates/init.sh`
-English version:
+英文版本:
-- Entry: [English Home](/en/)
-- Library: [English Resource Library](/resources/en/)
-- Root instructions: [`AGENTS.md`](/resources/en/templates/AGENTS.md) or [`CLAUDE.md`](/resources/en/templates/CLAUDE.md)
-- Feature state: [`feature_list.json`](/resources/en/templates/feature_list.json)
-- Progress log: [`claude-progress.md`](/resources/en/templates/claude-progress.md)
-- Session handoff: [`session-handoff.md`](/resources/en/templates/session-handoff.md)
-- Clean-exit checklist: [`clean-state-checklist.md`](/resources/en/templates/clean-state-checklist.md)
-- Evaluator rubric: [`evaluator-rubric.md`](/resources/en/templates/evaluator-rubric.md)
+- 入口:[English Home](/en/)
+- 资料库:[英文资料库](/resources/en/)
+- 根指令文件:[`AGENTS.md`](/resources/en/templates/AGENTS.md) 或 [`CLAUDE.md`](/resources/en/templates/CLAUDE.md)
+- 功能状态文件:[`feature_list.json`](/resources/en/templates/feature_list.json)
+- 进度记录文件:[`claude-progress.md`](/resources/en/templates/claude-progress.md)
+- 会话交接文件:[`session-handoff.md`](/resources/en/templates/session-handoff.md)
+- 收尾检查清单:[`clean-state-checklist.md`](/resources/en/templates/clean-state-checklist.md)
+- 评审模板:[`evaluator-rubric.md`](/resources/en/templates/evaluator-rubric.md)
推荐最小起步组合:
@@ -110,12 +110,12 @@ English version:
这门课适合按 6 个单元推进:
-- **Unit 1**: Lecture 01-02 + Project 01
-- **Unit 2**: Lecture 03-04 + Project 02
-- **Unit 3**: Lecture 05-06 + Project 03
-- **Unit 4**: Lecture 07-08 + Project 04
-- **Unit 5**: Lecture 09-10 + Project 05
-- **Unit 6**: Lecture 11-12 + Project 06
+- **单元 1**:Lecture 01-02 + Project 01
+- **单元 2**:Lecture 03-04 + Project 02
+- **单元 3**:Lecture 05-06 + Project 03
+- **单元 4**:Lecture 07-08 + Project 04
+- **单元 5**:Lecture 09-10 + Project 05
+- **单元 6**:Lecture 11-12 + Project 06
如果你想慢一点,也可以把每个单元当成一周来学。
diff --git a/docs/resources/index.md b/docs/resources/index.md
index 9a4d223..7ca6756 100644
--- a/docs/resources/index.md
+++ b/docs/resources/index.md
@@ -1,8 +1,8 @@
# 资料库
-这里是课程的双语 starter library,用来把课程里的方法整理成可直接复用的模板、检查清单和参考材料。
+这里是课程的双语资料库,用来把课程里的方法整理成可直接复用的模板、检查清单和参考材料。
-英文入口见:[English Resource Overview](/en/resources)
+英文入口见:[英文资料总览](/en/resources)
## 先看中文
@@ -10,11 +10,11 @@
- [中文模板](./zh/templates/index.md)
- [中文参考](./zh/reference/index.md)
-## English Resources
+## 英文资料
-- [English Resource Library](./en/index.md)
-- [English Templates](./en/templates/index.md)
-- [English Reference](./en/reference/index.md)
+- [英文资料库](./en/index.md)
+- [英文模板](./en/templates/index.md)
+- [英文参考](./en/reference/index.md)
## 这里能找到什么
@@ -22,7 +22,7 @@
- 功能状态与进度文件
- 会话交接与收尾检查清单
- 启动脚本参考
-- initializer 与 coding-agent 工作流说明
+- 初始化代理与编码代理的工作流说明
- 适合更长周期协作的 OpenAI 风格高级仓库骨架
## 推荐最小起步
@@ -32,11 +32,11 @@
- `claude-progress.md`
- `init.sh`
-先从这四个文件开始,再根据项目复杂度补充 handoff、evaluator 和质量治理材料。
+先从这四个文件开始,再根据项目复杂度补充交接、评审和质量治理材料。
## 高级资源包
-如果最小 harness 已经不够,可以继续看 OpenAI 风格的 advanced pack:
+如果最小 harness 已经不够,可以继续看 OpenAI 风格的高级资源包:
- 中文:[`zh/openai-advanced/index.md`](./zh/openai-advanced/index.md)
-- English:[`en/openai-advanced/index.md`](./en/openai-advanced/index.md)
+- 英文:[`en/openai-advanced/index.md`](./en/openai-advanced/index.md)
diff --git a/docs/resources/zh/index.md b/docs/resources/zh/index.md
index 63a26b7..de8e4d5 100644
--- a/docs/resources/zh/index.md
+++ b/docs/resources/zh/index.md
@@ -37,7 +37,7 @@
- [`templates/`](./templates/index.md):可以直接复制到真实仓库里的模板
- [`reference/`](./reference/index.md):方法说明、启动流程和问题对照表
-- [`openai-advanced/`](./openai-advanced/index.md):更完整的 OpenAI 风格高级资源包,包括 repo skeleton、质量文档、执行计划和系统级治理文件
+- [`openai-advanced/`](./openai-advanced/index.md):更完整的 OpenAI 风格高级资源包,包括仓库骨架、质量文档、执行计划和系统级治理文件
## 推荐最小组合
diff --git a/docs/resources/zh/openai-advanced/index.md b/docs/resources/zh/openai-advanced/index.md
index 63a588e..5d7981a 100644
--- a/docs/resources/zh/openai-advanced/index.md
+++ b/docs/resources/zh/openai-advanced/index.md
@@ -6,16 +6,16 @@ agent-first world》里更完整、更高阶的仓库组织方式整理成可以
当最小 harness 已经不够用,而你的仓库开始需要下面这些能力时,就该看这一套:
- 一个简短、负责路由的 `AGENTS.md`
-- 放在仓库里的 system-of-record 文档体系
+- 放在仓库里的“唯一事实来源”文档体系
- 活跃执行计划与已完成计划的分层管理
- 明确的产品、可靠性、安全、前端治理文件
- 按产品领域和架构层持续更新的质量评分
-- 面向模型阅读的 reference 材料目录
+- 面向模型阅读的参考材料目录
- 针对架构、知识沉淀、运行验证的标准 SOP
## 包含的目录骨架
-[`repo-template/`](./repo-template/index.md) 里提供了一套可直接复制的 starter
+[`repo-template/`](./repo-template/index.md) 里提供了一套可直接复制的起步
结构,核心布局如下:
```text
@@ -54,7 +54,7 @@ docs/
[`repo-template/`](./repo-template/index.md) 里的骨架复制到你的仓库。
3. 保持 `AGENTS.md` 很短,把深层规则拆到 `docs/` 里。
4. 把质量文档、可靠性文档、执行计划当成日常开发的一部分,而不是事后补写。
-5. 把生成物和外部 reference 明确收进仓库,避免 agent 依赖聊天上下文或人的记忆。
+5. 把生成物和外部参考材料明确收进仓库,避免 agent 依赖聊天上下文或人的记忆。
## SOP 资料库
@@ -62,15 +62,15 @@ docs/
- 分层领域架构搭建 SOP
- 把不可见知识编码进仓库的 SOP
-- 本地 observability stack 与 feedback loop SOP
+- 本地可观测性栈与反馈回路 SOP
- 用 Chrome DevTools 做 UI 验证闭环的 SOP
## 设计原则
- 短入口,深链接
-- 仓库就是 system of record
+- 仓库就是唯一事实来源
- 机械约束优先于口头约定
- 计划、质量和技术债都和代码一起版本化
-- cleanup 与 harness 简化是常规工作,不是临时救火
+- 清理与 harness 简化是常规工作,不是临时救火
这套资源包是有倾向性的模板,不是必须逐字照抄。最好的用法是把它当成一套高质量起点,再按你的项目改造。
diff --git a/docs/resources/zh/openai-advanced/repo-template/AGENTS.md b/docs/resources/zh/openai-advanced/repo-template/AGENTS.md
index 39991d1..cc0a0e4 100644
--- a/docs/resources/zh/openai-advanced/repo-template/AGENTS.md
+++ b/docs/resources/zh/openai-advanced/repo-template/AGENTS.md
@@ -1,6 +1,6 @@
# AGENTS.md
-这个仓库面向长时运行的 coding-agent 工作流。保持这个文件简短,把它当成 system-of-record 文档的入口和路由层,而不是一个不断膨胀的大说明书。
+这个仓库面向长时运行的 coding-agent 工作流。保持这个文件简短,把它当成“唯一事实来源”文档的入口和路由层,而不是一个不断膨胀的大说明书。
## 开工流程
diff --git a/docs/resources/zh/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/resources/zh/openai-advanced/repo-template/docs/design-docs/core-beliefs.md
index e183d8d..3d56113 100644
--- a/docs/resources/zh/openai-advanced/repo-template/docs/design-docs/core-beliefs.md
+++ b/docs/resources/zh/openai-advanced/repo-template/docs/design-docs/core-beliefs.md
@@ -1,9 +1,9 @@
-# Core Beliefs
+# 核心信念
-- 仓库就是 agent 的 system of record。
+- 仓库就是 agent 的唯一事实来源。
- `AGENTS.md` 是路由器,不是百科全书。
- 验证证据比自信更重要。
- 一次做好一个有边界的任务,胜过同时开很多半成品。
- 反复出现的人类反馈要升级成可复用的 harness 规则。
-- cleanup 与 simplification 都是交付的一部分,不是事后补救。
+- 清理与简化都是交付的一部分,不是事后补救。
- 如果 agent 不能在仓库里发现某个事实,就把这个事实视为运行上不存在。
diff --git a/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/index.md
index 7bedbb4..6a67efb 100644
--- a/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/index.md
+++ b/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/index.md
@@ -1,4 +1,4 @@
-# Active Plans
+# 当前执行计划
这个文件夹里每一份 markdown 都代表一份当前仍在执行的计划。
diff --git a/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/index.md
index 520632f..9e6315b 100644
--- a/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/index.md
+++ b/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/index.md
@@ -1,3 +1,3 @@
-# Completed Plans
+# 已完成计划
已完成的计划移动到这里,不要直接删掉。完成计划也是仓库记忆面的一部分,后续 agent 需要靠它理解代码为什么会变成现在这样。
diff --git a/docs/resources/zh/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/resources/zh/openai-advanced/repo-template/docs/generated/db-schema.md
index 7232451..8aaf66b 100644
--- a/docs/resources/zh/openai-advanced/repo-template/docs/generated/db-schema.md
+++ b/docs/resources/zh/openai-advanced/repo-template/docs/generated/db-schema.md
@@ -1,4 +1,4 @@
-# Database Schema
+# 数据库结构
这个目录用来存放那些生成出来但又值得 agent 直接阅读的工件,避免它每次都去源码里反推。
diff --git a/docs/resources/zh/openai-advanced/repo-template/docs/product-specs/index.md b/docs/resources/zh/openai-advanced/repo-template/docs/product-specs/index.md
index ea7641f..e012d00 100644
--- a/docs/resources/zh/openai-advanced/repo-template/docs/product-specs/index.md
+++ b/docs/resources/zh/openai-advanced/repo-template/docs/product-specs/index.md
@@ -1,8 +1,8 @@
-# Product Specs Index
+# 产品规格索引
这个目录用来放当前仍然有效的用户可见行为规格。
-## Active Specs
+## 当前有效规格
- `new-user-onboarding.md`
diff --git a/docs/resources/zh/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/resources/zh/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md
index 16460a8..99c916e 100644
--- a/docs/resources/zh/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md
+++ b/docs/resources/zh/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md
@@ -1,4 +1,4 @@
-# New User Onboarding
+# 新用户引导
## 目标
diff --git a/docs/resources/zh/openai-advanced/repo-template/index.md b/docs/resources/zh/openai-advanced/repo-template/index.md
index cf3d7ce..4de4782 100644
--- a/docs/resources/zh/openai-advanced/repo-template/index.md
+++ b/docs/resources/zh/openai-advanced/repo-template/index.md
@@ -1,6 +1,6 @@
# 高级仓库模板
-当你希望把仓库升级成更接近 OpenAI 文中那种 agent-first 文档面,而不只是一个最小 harness 时,就复制这套 starter。
+当你希望把仓库升级成更接近 OpenAI 文中那种 agent-first 文档面,而不只是一个最小 harness 时,就复制这套起步模板。
## 推荐复制顺序
diff --git a/docs/resources/zh/openai-advanced/sops/observability-feedback-loop.md b/docs/resources/zh/openai-advanced/sops/observability-feedback-loop.md
index 931946b..d941014 100644
--- a/docs/resources/zh/openai-advanced/sops/observability-feedback-loop.md
+++ b/docs/resources/zh/openai-advanced/sops/observability-feedback-loop.md
@@ -1,4 +1,4 @@
-# SOP:Observability Feedback Loop
+# SOP:可观测性反馈闭环
当调试太慢、agent 总在没证据的情况下宣布成功、或者运行时行为比代码本身还难看懂时,就用这份 SOP。
diff --git a/docs/resources/zh/reference/method-map.md b/docs/resources/zh/reference/method-map.md
index e2f54ec..b442f35 100644
--- a/docs/resources/zh/reference/method-map.md
+++ b/docs/resources/zh/reference/method-map.md
@@ -4,9 +4,9 @@
| 失败模式 | 实际表现 | 首要修复 | 主要工件 |
| --- | --- | --- | --- |
-| 冷启动混乱 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为 system of record | `claude-progress.md` |
-| 范围蔓延 | 一次启动多个功能,最后没有一个完整收尾 | 限制 active scope | `feature_list.json` |
-| 提前宣布完成 | 代码改了就说 done,但没有可运行证据 | 把完成绑定到验证证据 | `clean-state-checklist.md` |
+| 冷启动混乱 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为唯一事实来源 | `claude-progress.md` |
+| 范围蔓延 | 一次启动多个功能,最后没有一个完整收尾 | 限制当前活跃范围 | `feature_list.json` |
+| 提前宣布完成 | 代码改了就说“完成了”,但没有可运行证据 | 把完成绑定到验证证据 | `clean-state-checklist.md` |
| 启动脆弱 | 每轮会话都要重新学怎么启动项目 | 统一启动与验证路径 | `init.sh` |
| 交接薄弱 | 下一轮看不出哪里可用、哪里坏了、接下来做什么 | 明确写交接摘要 | `session-handoff.md` |
| 评审主观 | 质量判断依赖个人记忆和感觉 | 用固定维度做评分 | `evaluator-rubric.md` |
diff --git a/docs/resources/zh/templates/CLAUDE.md b/docs/resources/zh/templates/CLAUDE.md
index 8d0bc63..bc2bed3 100644
--- a/docs/resources/zh/templates/CLAUDE.md
+++ b/docs/resources/zh/templates/CLAUDE.md
@@ -21,7 +21,7 @@
- 没有可运行证据时,不要声称完成
- 不要通过重写功能清单来隐藏未完成工作
- 不要为了“看起来完成”而删除或削弱测试
-- 以仓库内文件作为 system of record
+- 以仓库内文件作为唯一事实来源
## 必需文件
diff --git a/docs/zh/index.md b/docs/zh/index.md
index 8e73559..810f9ee 100644
--- a/docs/zh/index.md
+++ b/docs/zh/index.md
@@ -4,6 +4,8 @@
本课程仍在持续建设中,内容后续可能会调整。
+英文入口见:[English Home](/en/)
+
## 课程概览
Harness engineering 指的是:围绕模型搭建一整套工作环境,让它干活更靠谱。这不只是写提示词,还包括:
@@ -16,7 +18,7 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- 哪些规矩必须遵守
- 怎么保持干净、不留烂摊子
-这门课是**强实践导向**的。我们不会只停留在"概念解释",而是会让 Codex 或 Claude Code 在同一个不断演化的 Electron 应用上反复工作,并比较弱 harness 与强 harness 的差异。
+这门课是**强实践导向**的。我们不会只停留在“概念解释”,而是会让 Codex 或 Claude Code 在同一个不断演化的 Electron 应用上反复工作,并比较弱 harness 与强 harness 的差异。
课程真正关心的问题是:
@@ -27,47 +29,47 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
## 核心观点
-以后让模型干活,人只需要定好规则和边界——这就是 harness。
+以后让模型干活,人只需要定好规则和边界。这就是 harness。
-**为什么这个重要:** 模型很强,但不代表它能自动靠谱地完成真实工程任务。它需要一套明确的规则来约束自己的行为范围、需要清晰的交接机制来维持长时任务的连续性、需要验证手段来确认自己做对了。
+**为什么这个重要:** 模型很强,但不代表它能自动靠谱地完成真实工程任务。它需要一套明确的规则来约束自己的行为范围,需要清晰的交接机制来维持长时任务的连续性,需要验证手段来确认自己做对了。
-我们不是在尝试"让模型本身更聪明",而是研究:怎么给模型搭建一个靠谱的工作环境,让同一个模型做出更可靠的工作。
+我们不是在尝试“让模型本身更聪明”,而是在研究:怎么给模型搭建一个靠谱的工作环境,让同一个模型做出更可靠的工作。
## 课程大纲
### 讲义
-> 讲义内容为英文,暂未提供中文翻译。
+> 讲义正文目前仍以英文为主,中文先提供导览和说明。
- [Lecture 01. 为什么强模型依然会失败](/lectures/lecture-01-why-capable-agents-still-fail/)
- [Lecture 02. 什么才算 harness](/lectures/lecture-02-what-a-harness-actually-is/)
-- [Lecture 03. 为什么仓库必须成为 system of record](/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
+- [Lecture 03. 为什么仓库必须成为唯一事实来源](/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
- [Lecture 04. 为什么一个巨大的 instruction 文件会失败](/lectures/lecture-04-why-one-giant-instruction-file-fails/)
- [Lecture 05. 为什么长时任务会失去连续性](/lectures/lecture-05-why-long-running-tasks-lose-continuity/)
- [Lecture 06. 为什么初始化必须是独立阶段](/lectures/lecture-06-why-initialization-needs-its-own-phase/)
-- [Lecture 07. 为什么 scope 必须被显式化](/lectures/lecture-07-why-agents-overreach-and-under-finish/)
+- [Lecture 07. 为什么任务边界必须被显式化](/lectures/lecture-07-why-agents-overreach-and-under-finish/)
- [Lecture 08. 为什么验证必须外部化](/lectures/lecture-08-why-feature-lists-are-harness-primitives/)
-- [Lecture 09. 为什么 runtime feedback 必须进入 harness](/lectures/lecture-09-why-agents-declare-victory-too-early/)
-- [Lecture 10. 为什么结构和 taste 必须被强制执行](/lectures/lecture-10-why-end-to-end-testing-changes-results/)
-- [Lecture 11. 为什么更强的 harness 会拆分角色](/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
-- [Lecture 12. 为什么 harness 必须被持续度量和维护](/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
+- [Lecture 09. 为什么运行时反馈必须进入 harness](/lectures/lecture-09-why-agents-declare-victory-too-early/)
+- [Lecture 10. 为什么完整验证才算真的验证](/lectures/lecture-10-why-end-to-end-testing-changes-results/)
+- [Lecture 11. 为什么可观测性必须进入 harness](/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
+- [Lecture 12. 为什么每次会话都必须干净收尾](/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
### 项目
-> 项目内容为英文,暂未提供中文翻译。
+> 项目正文目前仍以英文为主,中文先提供导览和学习路径。
-- [Project 01. 基线 vs 最小 harness](/projects/project-01-baseline-vs-minimal-harness/)
-- [Project 02. Agent-readable workspace 与 continuity scaffold](/projects/project-02-agent-readable-workspace/)
-- [Project 03. Scope control 与 grounded verification](/projects/project-03-multi-session-continuity/)
-- [Project 04. Runtime feedback 与 structural control](/projects/project-04-incremental-indexing/)
-- [Project 05. Evaluator loop 与三角色升级](/projects/project-05-grounded-qa-verification/)
-- [Project 06. Benchmark、cleanup 与 capstone harness](/projects/project-06-runtime-observability-and-debugging/)
+- [Project 01. 基线提示词 vs 最小 harness](/projects/project-01-baseline-vs-minimal-harness/)
+- [Project 02. 让项目对 agent 可读,并接住上次的工作](/projects/project-02-agent-readable-workspace/)
+- [Project 03. 让 agent 在会话重启后继续推进](/projects/project-03-multi-session-continuity/)
+- [Project 04. 用运行时反馈修正 agent 的行为](/projects/project-04-incremental-indexing/)
+- [Project 05. 让 agent 学会评审并验证自己的工作](/projects/project-05-grounded-qa-verification/)
+- [Project 06. 基准测试、清理与综合 harness](/projects/project-06-runtime-observability-and-debugging/)
### 资料库
-- [Resource Library 总览](/resources/)
+- [资料库总览](/resources/)
- [中文资料库](/resources/zh/)
-- [English Resource Library](/resources/en/)
+- [英文资料库](/resources/en/)
## 适合谁
@@ -75,7 +77,7 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- 已经在使用 coding agent、希望提升稳定性和质量的工程师
- 想系统理解 harness 设计的研究者或构建者
-- 需要理解"环境设计如何影响 agent 表现"的技术负责人
+- 需要理解“环境设计如何影响 agent 表现”的技术负责人
这门课不适合:
@@ -100,7 +102,7 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- 允许 agent 运行命令
- 检查输出并重复执行任务
-如果你没有这类工具,仍然可以阅读课程内容,但无法按预期完成课程 project。
+如果你没有这类工具,仍然可以阅读课程内容,但无法按预期完成课程项目。
## 快速开始
@@ -117,16 +119,16 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- 评审模板:[`evaluator-rubric.md`](/resources/zh/templates/evaluator-rubric.md)
- 启动脚本参考:`docs/resources/zh/templates/init.sh`
-English version:
+英文版本:
-- Entry: [English Resource Library](/resources/en/)
-- Root instructions: [`AGENTS.md`](/resources/en/templates/AGENTS.md) or [`CLAUDE.md`](/resources/en/templates/CLAUDE.md)
-- Feature state: [`feature_list.json`](/resources/en/templates/feature_list.json)
-- Progress log: [`claude-progress.md`](/resources/en/templates/claude-progress.md)
-- Session handoff: [`session-handoff.md`](/resources/en/templates/session-handoff.md)
-- Clean-exit checklist: [`clean-state-checklist.md`](/resources/en/templates/clean-state-checklist.md)
-- Evaluator rubric: [`evaluator-rubric.md`](/resources/en/templates/evaluator-rubric.md)
-- Bootstrap script reference: `docs/resources/en/templates/init.sh`
+- 入口:[English Home](/en/)
+- 资料库:[英文资料库](/resources/en/)
+- 根指令文件:[`AGENTS.md`](/resources/en/templates/AGENTS.md) 或 [`CLAUDE.md`](/resources/en/templates/CLAUDE.md)
+- 功能状态文件:[`feature_list.json`](/resources/en/templates/feature_list.json)
+- 进度记录文件:[`claude-progress.md`](/resources/en/templates/claude-progress.md)
+- 会话交接文件:[`session-handoff.md`](/resources/en/templates/session-handoff.md)
+- 收尾检查清单:[`clean-state-checklist.md`](/resources/en/templates/clean-state-checklist.md)
+- 评审模板:[`evaluator-rubric.md`](/resources/en/templates/evaluator-rubric.md)
推荐最小起步组合:
@@ -141,12 +143,12 @@ English version:
这门课适合按 6 个单元推进:
-- **Unit 1**: Lecture 01-02 + Project 01
-- **Unit 2**: Lecture 03-04 + Project 02
-- **Unit 3**: Lecture 05-06 + Project 03
-- **Unit 4**: Lecture 07-08 + Project 04
-- **Unit 5**: Lecture 09-10 + Project 05
-- **Unit 6**: Lecture 11-12 + Project 06
+- **单元 1**:Lecture 01-02 + Project 01
+- **单元 2**:Lecture 03-04 + Project 02
+- **单元 3**:Lecture 05-06 + Project 03
+- **单元 4**:Lecture 07-08 + Project 04
+- **单元 5**:Lecture 09-10 + Project 05
+- **单元 6**:Lecture 11-12 + Project 06
如果你想慢一点,也可以把每个单元当成一周来学。
diff --git a/docs/zh/resources.md b/docs/zh/resources.md
index b56f950..1de664e 100644
--- a/docs/zh/resources.md
+++ b/docs/zh/resources.md
@@ -8,11 +8,11 @@
- [中文模板](/resources/zh/templates/) — 可直接复制使用的模板文件
- [中文参考](/resources/zh/reference/) — 方法论和参考文档
-## English Resources
+## 英文资料
-- [English Resource Library](/resources/en/) — Entry and overview
-- [English Templates](/resources/en/templates/) — Ready-to-use template files
-- [English Reference](/resources/en/reference/) — Methodology and reference docs
+- [英文资料库](/resources/en/) — 英文入口与总览
+- [英文模板](/resources/en/templates/) — 可直接复制使用的模板文件
+- [英文参考](/resources/en/reference/) — 方法论和参考文档
## 推荐最小起步