Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
Polish Chinese docs and resource translations
sanbuphye8e1c5d652b9
diff --git a/README-CN.md b/README-CN.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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/) — 方法论和参考文档## 推荐最小起步