Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
style: refactor docs theme to match anthropic/claude style
sanbuphya7f05ab505f2
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mtsindex e27bc3f..7a2e941 100644--- a/docs/.vitepress/config.mts+++ b/docs/.vitepress/config.mts@@ -1,8 +1,10 @@+/// <reference types="node" />import { defineConfig } from "vitepress";const docsBase = process.env.DOCS_BASE_PATH ?? "/";const zhLectureItems = [+ { text: "欢迎", link: "/zh/" },{ text: "L01. 模型能力强,不等于执行可靠", link: "/zh/lectures/lecture-01-why-capable-agents-still-fail/" },{ text: "L02. Harness 的定义", link: "/zh/lectures/lecture-02-what-a-harness-actually-is/" },{ text: "L03. 让代码仓库成为唯一的事实来源", link: "/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },@@ -36,6 +38,7 @@ const zhResourceItems = [];const enLectureItems = [+ { text: "Welcome", link: "/en/" },{ text: "Lecture 01. Why Capable Agents Still Fail", link: "/en/lectures/lecture-01-why-capable-agents-still-fail/" },{ text: "Lecture 02. What a Harness Actually Is", link: "/en/lectures/lecture-02-what-a-harness-actually-is/" },{ text: "Lecture 03. Why the Repository Must Become the System of Record", link: "/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },@@ -76,6 +79,19 @@ export default defineConfig({cleanUrls: true,srcExclude: ["temp/**"],ignoreDeadLinks: true,+ 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>',+ search: {+ provider: "local"+ },+ socialLinks: [{ icon: "github", link: "https://github.com/walkinglabs/learn-harness-engineering" }]+ },+ markdown: {+ theme: {+ light: 'github-light',+ dark: 'github-dark'+ }+ },locales: {root: {label: "简体中文",@@ -96,25 +112,21 @@ export default defineConfig({link: "/zh/",themeConfig: {nav: [- { text: "首页", link: "/zh/" },- { text: "讲义", link: zhLectureItems[0].link },- { text: "项目", link: zhProjectItems[0].link },- { text: "资料库", link: "/zh/resources/" }- ],- sidebar: [- {- text: "讲义",- items: zhLectureItems- },- {- text: "项目",- items: zhProjectItems- },- {- text: "资料库",- items: zhResourceItems- }+ { text: "讲义", link: zhLectureItems[1].link, activeMatch: '^/zh/(lectures/.*)?$' },+ { text: "项目", link: zhProjectItems[0].link, activeMatch: '^/zh/projects/' },+ { text: "资料库", link: "/zh/resources/", activeMatch: '^/zh/resources/' }],+ sidebar: {+ '/zh/projects/': [+ { text: "项目", items: zhProjectItems }+ ],+ '/zh/resources/': [+ { text: "资料库", items: zhResourceItems }+ ],+ '/zh/': [+ { text: "讲义", items: zhLectureItems }+ ]+ },outline: {level: [2, 3]},@@ -139,25 +151,21 @@ export default defineConfig({link: "/en/",themeConfig: {nav: [- { text: "Home", link: "/en/" },- { text: "Lectures", link: enLectureItems[0].link },- { text: "Projects", link: enProjectItems[0].link },- { text: "Library", link: "/en/resources/" }- ],- sidebar: [- {- text: "Lectures",- items: enLectureItems- },- {- text: "Projects",- items: enProjectItems- },- {- text: "Resource Library",- items: enResourceItems- }+ { text: "Lectures", link: enLectureItems[1].link, activeMatch: '^/en/(lectures/.*)?$' },+ { text: "Projects", link: enProjectItems[0].link, activeMatch: '^/en/projects/' },+ { text: "Library", link: "/en/resources/", activeMatch: '^/en/resources/' }],+ sidebar: {+ '/en/projects/': [+ { text: "Projects", items: enProjectItems }+ ],+ '/en/resources/': [+ { text: "Resource Library", items: enResourceItems }+ ],+ '/en/': [+ { text: "Lectures", items: enLectureItems }+ ]+ },outline: {level: [2, 3]},@@ -175,11 +183,5 @@ export default defineConfig({darkModeSwitchTitle: "Switch to dark theme"}}- },- themeConfig: {- search: {- provider: "local"- },- socialLinks: [{ icon: "github", link: "https://github.com/walkinglabs/learn-harness-engineering" }]}});diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.jsindex 4bf9dfd..c697345 100644--- a/docs/.vitepress/theme/index.js+++ b/docs/.vitepress/theme/index.js@@ -1,4 +1,5 @@import DefaultTheme from 'vitepress/theme'+import './style.css'function syncRootLocaleLabel(siteData, href = '') {const locales = siteData.value?.localesdiff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.cssnew file mode 100644index 0000000..7215b06--- /dev/null+++ b/docs/.vitepress/theme/style.css@@ -0,0 +1,402 @@+/* ===== Learn Harness Engineering — Custom VitePress Styles ===== */+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Newsreader:opsz,[email protected],400;6..72,500;6..72,600&display=swap');++/* ---------- CSS Variables (Light) ---------- */+:root {+ /* Anthropic / Claude Docs Style Colors */+ --vp-c-bg: #FAF9F5;+ --vp-c-bg-alt: #F4F3EE;+ --vp-c-bg-elv: #FFFFFF;+ --vp-c-bg-soft: #F4F3EE;++ --vp-c-text-1: #1A1A1A;+ --vp-c-text-2: #4A4A4A;+ --vp-c-text-3: #757575;++ /* Brand - Orange */+ --vp-c-brand-1: #D95C41;+ --vp-c-brand-2: #C14E36;+ --vp-c-brand-3: #A8412B;+ --vp-c-brand-soft: rgba(217, 92, 65, 0.1);++ /* Sidebar */+ --vp-sidebar-bg-color: #F4F3EE;+ --vp-c-divider: rgba(0, 0, 0, 0.08);++ /* Layout tweaks */+ --vp-nav-bg-color: #FAF9F5;+ --vp-layout-max-width: 1376px;++ /* Typography */+ --vp-font-family-base: 'Inter', ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;+ --vp-font-family-mono: 'JetBrains Mono', 'Fira Code', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;+}++/* ---------- Dark mode overrides (Anthropic style dark mode if needed) ---------- */+.dark {+ --vp-c-bg: #1A1A1A;+ --vp-c-bg-alt: #141414;+ --vp-c-bg-elv: #242424;+ --vp-c-bg-soft: #141414;++ --vp-c-text-1: #E5E5E5;+ --vp-c-text-2: #B3B3B3;+ --vp-c-text-3: #808080;++ --vp-c-brand-1: #E07A64;+ --vp-c-brand-2: #D95C41;+ --vp-c-brand-3: #C14E36;+ --vp-c-brand-soft: rgba(224, 122, 100, 0.15);++ --vp-sidebar-bg-color: #141414;+ --vp-nav-bg-color: #1A1A1A;+ --vp-c-divider: rgba(255, 255, 255, 0.1);+}++/* ---------- Global typography ---------- */+.vp-doc {+ font-size: 16px;+ line-height: 1.75;+}++.vp-doc h1 {+ font-family: 'Newsreader', serif;+ font-size: 3.5rem;+ font-weight: 400;+ line-height: 1.1;+ letter-spacing: -0.02em;+ margin-top: 2rem;+ margin-bottom: 1.5rem;+ color: var(--vp-c-text-1);+}++.vp-doc h2 {+ font-family: 'Newsreader', serif;+ font-size: 2rem;+ font-weight: 400;+ line-height: 1.2;+ letter-spacing: -0.01em;+ margin-top: 2.5rem;+ padding-bottom: 0.4rem;+ border-bottom: 1px solid var(--vp-c-divider);+}++.vp-doc h3 {+ font-size: 1.25rem;+ font-weight: 600;+ margin-top: 2rem;+}++/* ---------- Links ---------- */+.vp-doc a {+ color: var(--vp-c-brand-1);+ text-decoration: none;+ transition: color 0.2s;+}++.vp-doc a:hover {+ color: var(--vp-c-brand-2);+ text-decoration: underline;+}++/* ---------- Blockquotes ---------- */+.vp-doc blockquote {+ border-left: 4px solid var(--vp-c-brand-1);+ background: var(--vp-c-brand-soft);+ border-radius: 0 8px 8px 0;+ padding: 12px 20px;+ margin: 16px 0;+ font-style: normal;+}++.vp-doc blockquote p {+ margin: 0;+}++/* ---------- Code blocks ---------- */+.vp-doc code {+ font-family: var(--vp-font-family-mono);+ font-size: 0.9em;+}++.vp-doc div[class*='language-'] {+ border-radius: 12px;+ margin: 16px 0;+ border: 1px solid var(--vp-c-divider);+ background-color: var(--vp-c-bg-elv);+}++.vp-doc div[class*='language-'] button.copy {+ background-color: var(--vp-c-bg-soft);+ border: 1px solid var(--vp-c-divider);+ border-radius: 6px;+}++.vp-doc :not(pre) > code {+ background: var(--vp-c-bg-alt);+ color: var(--vp-c-text-1);+ padding: 3px 6px;+ border-radius: 6px;+ border: 1px solid var(--vp-c-divider);+ font-size: 0.88em;+}++/* ---------- Lists ---------- */+.vp-doc ul, .vp-doc ol {+ padding-left: 1.25rem;+}++.vp-doc li {+ margin: 6px 0;+}++.vp-doc li::marker {+ color: var(--vp-c-brand-1);+}++/* ---------- Custom containers / tip blocks ---------- */+.vp-doc .custom-block {+ border-radius: 10px;+ margin: 16px 0;+}++.vp-doc .custom-block .custom-block-title {+ font-weight: 600;+}++/* ---------- Homepage hero ---------- */+.VPHero .name {+ font-size: 3.2rem !important;+}++.VPHero .text {+ font-size: 1.35rem !important;+ line-height: 1.5 !important;+ max-width: 600px !important;+}++.VPHero .tagline {+ font-size: 1.1rem !important;+ line-height: 1.6 !important;+ max-width: 560px !important;+}++/* ---------- Feature cards ---------- */+.VPFeatures .item {+ padding: 8px;+}++.VPFeature {+ border-radius: 12px !important;+ border: 1px solid var(--vp-c-divider) !important;+ transition: border-color 0.25s, box-shadow 0.25s, transform 0.25s !important;+ padding: 20px 24px !important;+}++.VPFeature:hover {+ border-color: var(--vp-c-brand-1) !important;+ box-shadow: 0 4px 20px rgba(99, 102, 241, 0.1) !important;+ transform: translateY(-2px) !important;+}++.VPFeature .title {+ font-weight: 600 !important;+ font-size: 1.05rem !important;+}++.VPFeature .details {+ line-height: 1.6 !important;+}++/* ---------- Sidebar ---------- */+.VPSidebar {+ background-color: var(--vp-sidebar-bg-color) !important;+ border-right: 1px solid var(--vp-c-divider) !important;+}++.VPSidebar .VPSidebarItem.level-0 > .item > .text {+ font-weight: 700;+ font-size: 0.95rem;+ color: var(--vp-c-text-1);+}++.VPSidebar .VPSidebarItem .item .link {+ position: relative;+ border-radius: 8px !important;+ transition: background-color 0.2s, color 0.2s;+ color: var(--vp-c-text-2) !important;+ font-size: 0.9rem;+ padding: 8px 12px !important;+ margin: 2px 0;+}++.VPSidebar .VPSidebarItem .item .link:hover {+ color: var(--vp-c-text-1) !important;+ background-color: rgba(0, 0, 0, 0.04) !important;+}++.VPSidebar .VPSidebarItem.is-active > .item > .link {+ color: var(--vp-c-text-1) !important;+ font-weight: 600 !important;+ background-color: rgba(0, 0, 0, 0.06) !important;+}++.VPSidebar .VPSidebarItem.is-active > .item > .link::before {+ display: none !important;+}++.dark .VPSidebar .VPSidebarItem .item .link:hover {+ background-color: rgba(255, 255, 255, 0.05) !important;+}++.dark .VPSidebar .VPSidebarItem.is-active > .item > .link {+ background-color: rgba(255, 255, 255, 0.08) !important;+}++/* ---------- Navigation ---------- */+.VPNav {+ background-color: var(--vp-nav-bg-color);+}++.VPNav .VPNavBar {+ background-color: transparent;+ border-bottom: 1px solid var(--vp-c-divider);+}++.VPNavBarTitle {+ font-family: 'Newsreader', serif;+ font-size: 1.25rem;+ font-weight: 500;+ color: var(--vp-c-text-1);+}++.VPNavBarTitle .title {+ display: flex;+ align-items: center;+ gap: 8px;+}++/* Nav links styling */+.VPNavBarMenuLink {+ position: relative;+ color: var(--vp-c-text-2) !important;+ font-weight: 500 !important;+ padding: 0 2px !important;+ margin: 0 12px;+ border-radius: 0 !important;+ background-color: transparent !important;+ transition: all 0.2s ease;+ height: 100%;+ display: flex;+ align-items: center;+}++.VPNavBarMenuLink:hover {+ color: var(--vp-c-text-1) !important;+ background-color: transparent !important;+}++.VPNavBarMenuLink.active {+ color: var(--vp-c-text-1) !important;+}++.VPNavBarMenuLink.active::after {+ content: '';+ position: absolute;+ bottom: -1px;+ left: 0;+ right: 0;+ height: 2px;+ background-color: var(--vp-c-text-1);+}++.dark .VPNavBarMenuLink.active {+ background-color: transparent !important;+}++/* GitHub Black Button */+.VPNavBarSocialLink {+ background-color: #1A1A1A !important;+ color: #FFFFFF !important;+ border-radius: 20px;+ padding: 0 16px 0 12px !important;+ height: 32px !important;+ width: auto !important;+ display: flex !important;+ align-items: center;+ text-decoration: none;+ gap: 6px;+ transition: background-color 0.2s ease;+}++.VPNavBarSocialLink:hover {+ background-color: #333333 !important;+}++.VPNavBarSocialLink::after {+ content: "GitHub";+ font-size: 0.85rem;+ font-weight: 500;+ font-family: var(--vp-font-family-base);+ margin-left: 4px;+}++.dark .VPNavBarSocialLink {+ background-color: #E5E5E5 !important;+ color: #1A1A1A !important;+}++.dark .VPNavBarSocialLink:hover {+ background-color: #FFFFFF !important;+}++/* ---------- Tables ---------- */+.vp-doc table {+ border-collapse: collapse;+ width: 100%;+ margin: 16px 0;+ border-radius: 8px;+ overflow: hidden;+}++.vp-doc th, .vp-doc td {+ padding: 10px 16px;+ border: 1px solid var(--vp-c-divider);+}++.vp-doc th {+ background: var(--vp-c-brand-soft);+ font-weight: 600;+}++/* ---------- Horizontal rule ---------- */+.vp-doc hr {+ border: none;+ border-top: 1px solid var(--vp-c-divider);+ margin: 2rem 0;+}++/* ---------- Scrollbar (Webkit) ---------- */+::-webkit-scrollbar {+ width: 6px;+ height: 6px;+}++::-webkit-scrollbar-thumb {+ background: var(--vp-c-brand-soft);+ border-radius: 3px;+}++::-webkit-scrollbar-thumb:hover {+ background: var(--vp-c-brand-1);+}++/* ---------- Back-to-top button ---------- */+.VPDoc .back-to-top-btn {+ border-radius: 50%;+}++/* ---------- Page transition smoothness ---------- */+.VPContent {+ transition: background-color 0.3s;+}diff --git a/docs/en/index.md b/docs/en/index.mdindex 275fde4..5aafe3b 100644--- a/docs/en/index.md+++ b/docs/en/index.md@@ -1,67 +1,71 @@-# Learn Harness Engineering+# Welcome to 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 designing environments, state, verification, and control systems for Codex and Claude Code.-This course is a work in progress. Content may change as it evolves.+## Core Thesis-Chinese is now the default site language. The Chinese homepage is available at [/zh/](/zh/).+When you let models do work, the human's job is to define the rules and boundaries. That's the harness.-## Overview+**The key point:** Models are powerful, but that doesn't mean they can reliably complete real engineering tasks on their own. They need explicit rules to constrain their scope, clear handoff mechanisms to maintain continuity across long tasks, and verification methods to confirm they did the work correctly.-Harness engineering is about building a complete working environment around the model so it produces reliable results. It's not just about writing prompts. It also covers:+We're not trying to "make the model smarter." We're studying how to build a reliable working environment around the model so the same model produces more reliable output.-- Where code lives and how it's organized-- What the agent is and isn't allowed to do-- How to track task progress and pick up where you left off-- How to verify that work was done correctly-- How to diagnose problems when they arise-- What rules must always be followed-- How to leave things clean after each session+## Quick Start-This course is **hands-on**. We won't stop at concepts. You'll have Codex or Claude Code work repeatedly on the same evolving Electron application, comparing weak harnesses against strong ones.+You don't need to read all the lectures first. If you want to jump in, grab these template files from the resource library and adapt them to your project.-The questions this course actually cares about:+**Recommended starter set:**-- Which harness designs improve task completion rates?-- Which designs reduce rework and incorrect completions?-- Which mechanisms keep long-running tasks progressing steadily?-- Which structures keep the system maintainable after multiple agent runs?+- `AGENTS.md` or `CLAUDE.md` — root instruction file+- `feature_list.json` — feature status tracker+- `claude-progress.md` — progress log+- `init.sh` — initialization script-## Core Thesis+Put these four files in your project before you start having an agent do real work. The results will be significantly more stable than just writing a big prompt.-When you let models do work, the human's job is to define the rules and boundaries. That's the harness.+Browse all templates: [English Templates](/en/resources/templates/) or [中文模板](/zh/resources/templates/).-**The key point:** Models are powerful, but that doesn't mean they can reliably complete real engineering tasks on their own. They need explicit rules to constrain their scope, clear handoff mechanisms to maintain continuity across long tasks, and verification methods to confirm they did the work correctly.+## Who This Is For-We're not trying to "make the model smarter." We're studying how to build a reliable working environment around the model so the same model produces more reliable output.+This course is for:++- Engineers already using coding agents who want better stability and quality+- Researchers or builders who want a systematic understanding of harness design+- Tech leads who need to understand how environment design affects agent performance++This course is not for:++- People looking for a zero-code AI introduction+- Those who only care about prompts without real implementation+- Learners not prepared to let agents work in real repositories++## Environment Requirements++This is a hands-on course that requires running a coding agent.++You need at least one of these tools:++- Claude Code+- Codex+- Another IDE / CLI coding agent that supports file editing, command execution, and multi-step tasks-## Syllabus+The course assumes you can:-### Lectures+- Open a local repository+- Allow the agent to edit files+- Allow the agent to run commands+- Inspect output and repeat tasks-- [Lecture 01. Strong models don't mean reliable execution](/en/lectures/lecture-01-why-capable-agents-still-fail/)-- [Lecture 02. What harness actually means](/en/lectures/lecture-02-what-a-harness-actually-is/)-- [Lecture 03. Make the repository your single source of truth](/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)-- [Lecture 04. Split instructions across files, not one giant file](/en/lectures/lecture-04-why-one-giant-instruction-file-fails/)-- [Lecture 05. Keep context alive across sessions](/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/)-- [Lecture 06. Initialize before every agent session](/en/lectures/lecture-06-why-initialization-needs-its-own-phase/)-- [Lecture 07. Draw clear task boundaries for agents](/en/lectures/lecture-07-why-agents-overreach-and-under-finish/)-- [Lecture 08. Use feature lists to constrain what the agent does](/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/)-- [Lecture 09. Stop agents from declaring victory early](/en/lectures/lecture-09-why-agents-declare-victory-too-early/)-- [Lecture 10. Only a full-pipeline run counts as real verification](/en/lectures/lecture-10-why-end-to-end-testing-changes-results/)-- [Lecture 11. Make the agent's runtime observable](/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/)-- [Lecture 12. Clean handoff at the end of every session](/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)+## Core References-### Projects+Primary:-- [Project 01. Prompt-only vs. rules-first: how much difference does it make](/en/projects/project-01-baseline-vs-minimal-harness/)-- [Project 02. Make the project readable and pick up where you left off](/en/projects/project-02-agent-readable-workspace/)-- [Project 03. Keep the agent working across session restarts](/en/projects/project-03-multi-session-continuity/)-- [Project 04. Use runtime feedback to correct agent behavior](/en/projects/project-04-incremental-indexing/)-- [Project 05. Make the agent verify its own work](/en/projects/project-05-grounded-qa-verification/)-- [Project 06. Build a complete agent harness](/en/projects/project-06-runtime-observability-and-debugging/)+- [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)-### Resource Library+Supplementary:-- [English Resource Overview](/en/resources/)-- [Chinese Resource Library](/zh/resources/)+- [LangChain: The Anatomy of an Agent Harness](https://blog.langchain.com/the-anatomy-of-an-agent-harness/)+- [Thoughtworks: Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)+- [HumanLayer: Skill Issue: Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents)diff --git a/docs/zh/index.md b/docs/zh/index.mdindex a7ba819..cf00e56 100644--- a/docs/zh/index.md+++ b/docs/zh/index.md@@ -1,31 +1,6 @@-# Learn Harness Engineering+# 欢迎来到 Learn Harness Engineering-> 这是一门项目制课程:系统学习如何通过环境、状态、验证与控制机制,让 Codex 和 Claude Code 更可靠地工作。--本课程仍在持续建设中,内容后续可能会调整。--英文入口见:[English Home](/en/)--## 课程概览--Harness engineering 指的是:围绕模型搭建一整套工作环境,让它干活更靠谱。这不只是写提示词,还包括:--- 代码放哪、怎么组织-- 什么能干、什么干不了-- 任务做到哪了、下次怎么接上-- 做完怎么验证对不对-- 出了问题怎么排查-- 哪些规矩必须遵守-- 怎么保持干净、不留烂摊子--这门课是**强实践导向**的。我们不会只停留在“概念解释”,而是会让 Codex 或 Claude Code 在同一个不断演化的 Electron 应用上反复工作,并比较弱 harness 与强 harness 的差异。--课程真正关心的问题是:--- 哪些 harness 设计会提升任务完成率?-- 哪些设计会减少返工和错误完成?-- 哪些机制能让长时任务更稳定地持续推进?-- 哪些结构能让系统在多轮 agent 运行后仍然可维护?+系统学习如何通过环境、状态、验证与控制机制,让 Codex 和 Claude Code 完成真实工程任务。## 核心观点@@ -33,42 +8,7 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它**为什么这个重要:** 模型很强,但不代表它能自动靠谱地完成真实工程任务。它需要一套明确的规则来约束自己的行为范围,需要清晰的交接机制来维持长时任务的连续性,需要验证手段来确认自己做对了。-我们不是在尝试“让模型本身更聪明”,而是在研究:怎么给模型搭建一个靠谱的工作环境,让同一个模型做出更可靠的工作。--## 课程大纲--### 讲义--> 讲义正文目前仍以英文为主,中文先提供导览和说明。--- [Lecture 01. 为什么强模型依然会失败](/zh/lectures/lecture-01-why-capable-agents-still-fail/)-- [Lecture 02. 什么才算 harness](/zh/lectures/lecture-02-what-a-harness-actually-is/)-- [Lecture 03. 为什么仓库必须成为唯一事实来源](/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)-- [Lecture 04. 为什么一个巨大的 instruction 文件会失败](/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/)-- [Lecture 05. 为什么长时任务会失去连续性](/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/)-- [Lecture 06. 为什么初始化必须是独立阶段](/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/)-- [Lecture 07. 为什么任务边界必须被显式化](/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/)-- [Lecture 08. 为什么验证必须外部化](/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)-- [Lecture 09. 为什么运行时反馈必须进入 harness](/zh/lectures/lecture-09-why-agents-declare-victory-too-early/)-- [Lecture 10. 为什么完整验证才算真的验证](/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/)-- [Lecture 11. 为什么可观测性必须进入 harness](/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/)-- [Lecture 12. 为什么每次会话都必须干净收尾](/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)--### 项目--> 项目正文目前仍以英文为主,中文先提供导览和学习路径。--- [Project 01. 基线提示词 vs 最小 harness](/zh/projects/project-01-baseline-vs-minimal-harness/)-- [Project 02. 让项目对 agent 可读,并接住上次的工作](/zh/projects/project-02-agent-readable-workspace/)-- [Project 03. 让 agent 在会话重启后继续推进](/zh/projects/project-03-multi-session-continuity/)-- [Project 04. 用运行时反馈修正 agent 的行为](/zh/projects/project-04-incremental-indexing/)-- [Project 05. 让 agent 学会评审并验证自己的工作](/zh/projects/project-05-grounded-qa-verification/)-- [Project 06. 基准测试、清理与综合 harness](/zh/projects/project-06-runtime-observability-and-debugging/)--### 资料库--- [资料库总览](/zh/resources/)-- [英文资料库](/en/resources/)+我们不是在尝试"让模型本身更聪明",而是在研究:怎么给模型搭建一个靠谱的工作环境,让同一个模型做出更可靠的工作。## 快速开始@@ -85,17 +25,6 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它- 评审模板:[`evaluator-rubric.md`](/zh/resources/templates/evaluator-rubric.md)- 启动脚本参考:`docs/zh/resources/templates/init.sh`-英文版本:--- 入口:[English Home](/en/)-- 资料库:[英文资料库](/en/resources/)-- 根指令文件:[`AGENTS.md`](/en/resources/templates/AGENTS.md) 或 [`CLAUDE.md`](/en/resources/templates/CLAUDE.md)-- 功能状态文件:[`feature_list.json`](/en/resources/templates/feature_list.json)-- 进度记录文件:[`claude-progress.md`](/en/resources/templates/claude-progress.md)-- 会话交接文件:[`session-handoff.md`](/en/resources/templates/session-handoff.md)-- 收尾检查清单:[`clean-state-checklist.md`](/en/resources/templates/clean-state-checklist.md)-- 评审模板:[`evaluator-rubric.md`](/en/resources/templates/evaluator-rubric.md)-推荐最小起步组合:- `AGENTS.md` 或 `CLAUDE.md`@@ -105,26 +34,13 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它先把这四样放进你的项目里,再开始让 agent 真正干活,效果会比只写一段大 prompt 稳定得多。-## 建议学习节奏--这门课适合按 6 个单元推进:--- **单元 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--如果你想慢一点,也可以把每个单元当成一周来学。-## 适合谁这门课适合:- 已经在使用 coding agent、希望提升稳定性和质量的工程师- 想系统理解 harness 设计的研究者或构建者-- 需要理解“环境设计如何影响 agent 表现”的技术负责人+- 需要理解"环境设计如何影响 agent 表现"的技术负责人这门课不适合:@@ -164,14 +80,3 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它- [LangChain: The Anatomy of an Agent Harness](https://blog.langchain.com/the-anatomy-of-an-agent-harness/)- [Thoughtworks: Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)- [HumanLayer: Skill Issue: Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents)--## 本地预览--本仓库使用 VitePress 作为文档查看器。--```sh-npm install-npm run docs:dev-```--然后在浏览器里打开 VitePress 输出的本地地址即可。diff --git a/package.json b/package.jsonindex dd480d3..bb178fe 100644--- a/package.json+++ b/package.json@@ -4,6 +4,9 @@"version": "0.1.0","description": "Course docs for Learn Harness Engineering powered by VitePress.","scripts": {+ "dev": "vitepress dev docs",+ "build": "vitepress build docs",+ "preview": "vitepress preview docs","docs:dev": "vitepress dev docs","docs:build": "vitepress build docs","docs:preview": "vitepress preview docs",