Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
docs: sync readme with professional harness engineering tone and site links
sanbuphyf90e952e6e5d
diff --git a/README-CN.md b/README-CN.mdindex 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、类型检查、冒烟测试- +--> 边界:什么算"完成"、什么算"有问题"+ +--> 周期:开工时初始化,结束时留交接|vagent 只在验证通过后@@ -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.mdindex 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|vAgent 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 TodayYou 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.mtsindex 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.cssindex 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;