Skip to content

Harness engineering beginner tutorial, from 0 to 1

docs: sync readme with professional harness engineering tone and site links

sanbuphyf90e952e6e5d
diff --git a/README-CN.md b/README-CN.md
index a77aeb3..1be9329 100644
--- a/README-CN.md
+++ b/README-CN.md
@@ -1,10 +1,15 @@
# Learn Harness Engineering
-> 这是一门项目制课程:系统学习如何通过环境、状态、验证与控制机制,让 Codex 和 Claude Code 更可靠地工作。
+> **这是一门项目制课程:系统学习如何通过环境、状态、验证与控制机制,让 AI 编程智能体(Coding Agents)更可靠地工作。**
-本课程仍在持续建设中,内容后续可能会调整。
+Learn Harness Engineering 是一门专注于 AI 编程智能体工程化落地的课程。本课程深度研究并总结了业内最前沿的 Harness Engineering(工具马具/脚手架工程)理论与实践,参考资料包括:
-[英文版](./README.md)
+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)
+
+[**官方网站及文档 (English & 中文)**](https://walkinglabs.github.io/learn-harness-engineering/) | [**English README**](./README.md)
---
@@ -34,7 +39,7 @@ OpenAI 用 Codex 也得出了同样结论:在一个 harness 搭得好的仓库
+--> 范围:一次一个功能,不越界
+--> 状态:进度日志、功能清单、git 历史
+--> 验证:测试、lint、类型检查、冒烟测试
- +--> 边界:什么算"完成"、什么算"有问题"
+ +--> 周期:开工时初始化,结束时留交接
|
v
agent 只在验证通过后
@@ -124,6 +129,18 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可
---
+## 课程大纲与文档
+
+关于完整的课程内容,请直接访问 **[官方文档站点 (VitePress)](https://walkinglabs.github.io/learn-harness-engineering/zh/)**。
+
+本课程分为三个主要部分:
+
+1. **讲义 (Lectures)**:12 个概念单元,深度解析 Harness 设计的理论基础。
+2. **项目 (Projects)**:6 个循序渐进的实战项目,带你从零开始搭建可靠的 Agent 工作环境。
+3. **资料库 (Resource Library)**:开箱即用的中英文模板(如 `AGENTS.md`、`feature_list.json`、`init.sh`),今天就可以直接复制到你自己的项目中使用。
+
+---
+
## 快速开始:今天就能改善你的 agent
不用读完 12 个讲义再动手。如果你已经在用 coding agent 做项目,下面这些能立刻改善效果。
@@ -140,37 +157,9 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可
└── src/ <-- 你的代码
```
-**第一步.** 把根指令文件复制到项目根目录:
-
-- [`AGENTS.md`](./docs/zh/resources/templates/AGENTS.md) 通用版,或者 [`CLAUDE.md`](./docs/zh/resources/templates/CLAUDE.md) 如果你用 Claude Code
-- 把里面的命令、路径和规则换成你自己项目的
+**第一步.** 直接前往 [资料库](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) 拿到上述文件的模板代码,然后放进你的项目根目录。
-**第二步.** 把启动脚本复制进去:
-
-- `docs/zh/resources/templates/init.sh` —— 一条命令完成依赖安装、验证和启动
-- 把 `INSTALL_CMD`、`VERIFY_CMD`、`START_CMD` 换成你自己的
-
-**第三步.** 把进度日志复制进去:
-
-- [`claude-progress.md`](./docs/zh/resources/templates/claude-progress.md) —— 每轮会话记录做了什么、验证了什么、下一步是什么
-- agent 每次开工会先读这个文件,从上次停下的地方继续
-
-**第四步.** 把功能清单复制进去:
-
-- [`feature_list.json`](./docs/zh/resources/templates/feature_list.json) —— 机器可读的功能列表,每个功能有状态、验证步骤和证据
-- 把示例功能换成你自己的
-
-四个文件,最小起步就够了。比光靠一段提示词稳定得多。
-
-等项目变复杂了,再补这些:
-
-- [`session-handoff.md`](./docs/zh/resources/templates/session-handoff.md) —— 会话之间的交接摘要
-- [`clean-state-checklist.md`](./docs/zh/resources/templates/clean-state-checklist.md) —— 每次会话结束前的清理清单
-- [`evaluator-rubric.md`](./docs/zh/resources/templates/evaluator-rubric.md) —— 评审 agent 产出质量的评分表
-
-每个文件的详细用法写在 [中文模板指南](./docs/zh/resources/templates/index.md)。英文版见 [英文模板指南](./docs/en/resources/templates/index.md)。
-
-如果你想直接用 OpenAI 那篇 harness engineering 文章里的更完整高级结构,可以继续看 [`docs/zh/resources/openai-advanced/`](./docs/zh/resources/openai-advanced/index.md) 和 [`docs/en/resources/openai-advanced/`](./docs/en/resources/openai-advanced/index.md)。
+就这么简单。四个文件,最小起步就够了。你的 Agent 表现会比光靠一段提示词稳定得多。
---
@@ -266,6 +255,8 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可
### 讲义 — 12 个概念单元,每个只回答一个核心问题
+*点击访问 [文档站点](https://walkinglabs.github.io/learn-harness-engineering/zh/) 阅读全部讲义。*
+
| 讲义 | 核心问题 | 关键概念 |
| ---- | -------- | -------- |
| [L01](./docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 模型能力强,不等于执行可靠 | 基准测试与真实工程之间的能力鸿沟 |
@@ -319,8 +310,8 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可
### 资料库
-- [中文资料库](./docs/zh/resources/index.md) — 中文模板、清单和方法参考
-- [英文资料库](./docs/en/resources/index.md) — English templates, checklists, and method references
+- [中文资料库](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考
+- [英文资料库](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — English templates, checklists, and method references
---
diff --git a/README.md b/README.md
index bcb8769..2c903c9 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,15 @@
# Learn Harness Engineering
-> A project-based course on building the environment, state management, verification, and control mechanisms that make Codex and Claude Code work more reliably.
+> **A project-based course on building the environment, state management, verification, and control mechanisms that make AI coding agents work reliably.**
-This course is a work in progress. Content may change as it evolves.
+Learn Harness Engineering is a course dedicated to the engineering of AI coding agents. We have deeply studied and synthesized the most advanced Harness Engineering theories and practices in the industry. Our core references include:
-[中文版本](./README-CN.md)
+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)
+
+[**Website & Docs (English & 中文)**](https://walkinglabs.github.io/learn-harness-engineering/) | [**中文 README**](./README-CN.md)
---
@@ -34,7 +39,7 @@ OpenAI reported the same thing with Codex: in a well-harnessed repository, the s
+--> Scope: one feature at a time, no overreach
+--> State: progress log, feature list, git history
+--> Verification: tests, lint, type-check, smoke runs
- +--> Boundaries: what counts as "done," what counts as "broken"
+ +--> Lifecycle: init at start, clean state at end
|
v
Agent stops only when
@@ -125,6 +130,18 @@ The questions this course actually cares about:
---
+## Course Curriculum & Documentation
+
+For the full course materials, please visit the **[Documentation Website](https://walkinglabs.github.io/learn-harness-engineering/)**.
+
+The curriculum is divided into three parts:
+
+1. **Lectures**: 12 conceptual units explaining the theory behind harness engineering.
+2. **Projects**: 6 hands-on projects where you build an agentic workspace from scratch.
+3. **Resource Library**: Copy-ready templates (`AGENTS.md`, `feature_list.json`, `init.sh`, etc.) to use in your own repositories today.
+
+---
+
## Quick Start: Improve Your Agent Today
You don't need to read all 12 lectures before you start getting value. If you're already using a coding agent on a real project, here's how to improve it right now.
@@ -141,37 +158,7 @@ The idea is simple: instead of just writing prompts, give your agent a set of st
└── src/ <-- your actual code
```
-**Step 1.** Copy the root instruction file into your project root:
-
-- [`AGENTS.md`](./docs/resources/en/templates/AGENTS.md) for most agents, or [`CLAUDE.md`](./docs/resources/en/templates/CLAUDE.md) if you're using Claude Code
-- Edit the commands, paths, and rules to match your project
-
-**Step 2.** Copy the startup script:
-
-- `docs/resources/en/templates/init.sh` — runs dependency install, verification, and startup in one shot
-- Replace the `INSTALL_CMD`, `VERIFY_CMD`, and `START_CMD` with your actual commands
-
-**Step 3.** Copy the progress log:
-
-- [`claude-progress.md`](./docs/resources/en/templates/claude-progress.md) — records what was done each session, what's verified, and what's next
-- The agent reads this at the start of every session to pick up where it left off
-
-**Step 4.** Copy the feature list:
-
-- [`feature_list.json`](./docs/resources/en/templates/feature_list.json) — a machine-readable list of features with status, verification steps, and evidence
-- Replace the example features with your own
-
-That's it for the minimum setup. Four files, and your agent sessions will already be more stable than running on prompts alone.
-
-When your project gets more complex, add these:
-
-- [`session-handoff.md`](./docs/resources/en/templates/session-handoff.md) — compact handoff note between sessions
-- [`clean-state-checklist.md`](./docs/resources/en/templates/clean-state-checklist.md) — checklist to run before ending each session
-- [`evaluator-rubric.md`](./docs/resources/en/templates/evaluator-rubric.md) — scorecard for reviewing agent output quality
-
-Each file has detailed usage instructions in the [English template guide](./docs/resources/en/templates/index.md). Chinese versions are available in [中文模板指南](./docs/resources/zh/templates/index.md).
-
-For the fuller OpenAI-style repository layout, use the advanced pack in [`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/index.md) or [`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/index.md).
+Grab the starter templates from the [Resource Library](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) and drop them into your project. That's it. Four files, and your agent sessions will already be significantly more stable than running on prompts alone.
---
@@ -267,6 +254,8 @@ Each phase takes about a week if you're going part-time. If you want to go faste
### Lectures — 12 conceptual units, each answering one core question
+*Read the full text for each lecture on the [Documentation Website](https://walkinglabs.github.io/learn-harness-engineering/).*
+
| Session | Question | Core Idea |
|---------|----------|-----------|
| [L01](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Why do strong models still fail on real tasks? | The capability gap between benchmarks and real engineering |
@@ -320,9 +309,8 @@ Each phase takes about a week if you're going part-time. If you want to go faste
### Resource Library
-- [Resource Library Overview](./docs/resources/index.md)
-- [English Resource Library](./docs/resources/en/index.md) — templates, checklists, and method references
-- [Chinese Resource Library](./docs/resources/zh/index.md) — 中文模板、清单和方法参考
+- [English Resource Library](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references
+- [Chinese Resource Library](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考
---
@@ -494,4 +482,4 @@ learn-harness-engineering/
## Acknowledgments
-This course was inspired by and draws ideas from [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) — a progressive guide to building agent from scratch, from a single loop to isolated autonomous execution.
+This course was inspired by and draws ideas from [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) — a progressive guide to building an agent from scratch, from a single loop to isolated autonomous execution.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index b39b869..c627d35 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -83,8 +83,11 @@ export default withMermaid(
cleanUrls: true,
srcExclude: ["temp/**"],
ignoreDeadLinks: true,
+ head: [
+ ['link', { rel: 'icon', type: 'image/svg+xml', href: 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect width="24" height="24" rx="4" fill="%23FFFFFF" /><path d="M12 4L13.4 8.6L18 10L13.4 11.4L12 16L10.6 11.4L6 10L10.6 8.6L12 4Z" fill="%23D95C41"/></svg>' }]
+ ],
themeConfig: {
- logo: 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="%23D95C41"><path d="M12 2L13.4 8.6L20 10L13.4 11.4L12 18L10.6 11.4L4 10L10.6 8.6L12 2Z"/></svg>',
+ logo: 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect width="24" height="24" rx="4" fill="%231A1A1A" /><path d="M12 4L13.4 8.6L18 10L13.4 11.4L12 16L10.6 11.4L6 10L10.6 8.6L12 4Z" fill="%23D95C41"/></svg>',
search: {
provider: "local"
},
@@ -118,15 +121,9 @@ export default withMermaid(
{ text: "Try Harness ↗", link: "https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/index.md", target: "_blank", rel: "noopener noreferrer" }
],
sidebar: {
- '/en/projects/': [
- { text: "Projects", items: enProjectItems }
- ],
- '/en/resources/': [
- { text: "Resource Library", items: enResourceItems }
- ],
- '/en/': [
- { text: "Lectures", items: enLectureItems }
- ]
+ '/en/projects/': { base: '/en/projects/', items: enProjectItems },
+ '/en/resources/': { base: '/en/resources/', items: enResourceItems },
+ '/en/': { base: '/en/', items: enLectureItems }
},
socialLinks: [{ icon: "github", link: "https://github.com/walkinglabs/learn-harness-engineering" }]
}
@@ -142,17 +139,11 @@ export default withMermaid(
{ text: "资料库", link: "/zh/resources/", activeMatch: '^/zh/resources/' },
{ text: "Try Harness ↗", link: "https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/resources/templates/index.md", target: "_blank", rel: "noopener noreferrer" }
],
- sidebar: {
- '/zh/projects/': [
- { text: "项目", items: zhProjectItems }
- ],
- '/zh/resources/': [
- { text: "资料库", items: zhResourceItems }
- ],
- '/zh/': [
- { text: "讲义", items: zhLectureItems }
- ]
- },
+ sidebar: {
+ '/zh/projects/': { base: '/zh/projects/', items: zhProjectItems },
+ '/zh/resources/': { base: '/zh/resources/', items: zhResourceItems },
+ '/zh/': { base: '/zh/', items: zhLectureItems }
+ },
outline: {
level: [2, 3]
},
diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css
index 8a72d5c..e164284 100644
--- a/docs/.vitepress/theme/style.css
+++ b/docs/.vitepress/theme/style.css
@@ -276,7 +276,17 @@
gap: 8px;
}
-/* Nav links styling */
+/* Nav Logo Fix */
+.VPNavBarTitle .logo {
+ height: 24px;
+ width: 24px;
+ margin-right: 6px;
+ border-radius: 4px;
+}
+
+.dark .VPNavBarTitle .logo {
+ filter: invert(1);
+}
.VPNavBarMenuLink {
position: relative;
color: var(--vp-c-text-2) !important;