learn-harness-engineering

每个子系统都有一个职责：

• 指令 — 告诉代理要做什么、顺序以及在开始前需要阅读的内容。不是一个巨大的文件，而是一个渐进式披露结构，代理按需导航。
• 状态 — 跟踪已经完成的、正在进行的和接下来的任务。持久化到磁盘，以便下一次会话能够从上一次离开的地方继续。
• 验证 — 只有测试套件通过才算作证据。代理不能在没有可运行证据的情况下宣告胜利。
• 范围 — 将代理限制在一次只处理一个功能。不越界。不半途完成三件事。不篡改功能列表以隐藏未完成的工作。
• 会话生命周期 — 在开始时初始化。在结束时清理。为下一次会话留下干净的重启路径。

本课程存在的原因

问题不是“模型能否编写代码？”它们可以。问题是：它们是否能够在真实的代码仓库中、跨多个会话、在没有持续人工监督的情况下可靠地完成真实的工程任务？

目前，答案是：没有辅助措施是做不到的。

    WITHOUT HARNESS                            WITH HARNESS
    ==============                             ============

    Session 1: agent writes code               Session 1: agent reads instructions
               agent breaks tests                         agent runs init.sh
               agent says "done"                          agent works on one feature
               you fix it manually                        agent verifies before claiming done
                                                          agent updates progress log
    Session 2: agent starts fresh                         agent commits clean state
               agent has no memory
               of what happened before         Session 2: agent reads progress log
               agent re-does work                         agent picks up exactly where it left off
               or does something else entirely            agent continues the unfinished feature
               you fix it again                           you review, not rescue

    Result: you spend more time                Result: agent does the work,
            cleaning up than if you                    you verify the result
            did it yourself

本课程真正关注的问题：

• 哪些安全带设计可以提高任务完成率？
• 哪些设计可以减少返工和错误完成？
• 哪些机制可以保持长期任务的稳定进展？
• 哪些结构可以在多次代理运行后保持系统的可维护性？

课程大纲与文档

有关完整课程资料，请访问 文档网站。

课程分为三个部分：

1. 讲座：13 个概念单元，讲解驾驭工程背后的理论。
2. 项目：7 个实践项目，在这些项目中，你将从零开始构建一个自主工作空间。
3. 资源库：可直接使用的模板（AGENTS.md、feature_list.json、init.sh 等），可在你自己的仓库中立即使用。

快速入门：今天就提升你的智能体

你不需要在开始获得价值之前阅读所有14讲。如果你已经在真实项目中使用编码代理，下面是如何立即改进它的方法。

这个想法很简单：不要仅仅编写提示，而是给你的代理一组结构化文件，这些文件定义了应该做什么、已经做了什么以及如何验证工作。这些文件存放在你的代码仓库中，因此每次会话都从相同的状态开始。

    YOUR PROJECT ROOT
    ├── AGENTS.md              <-- the agent's operating manual
    ├── CLAUDE.md              <-- (alternative, if using Claude Code)
    ├── init.sh                <-- runs install + verify + start
    ├── feature_list.json      <-- what features exist, which are done
    ├── claude-progress.md     <-- session progress (historical filename; agent-agnostic)
    └── src/                   <-- your actual code

从资源库获取启动模板并将它们放入你的项目中。就这么简单。四个文件，你的代理会话就会比单独运行提示稳定得多。

claude-progress.md 是一个通用的、仅限仓库的会话进度日志；名称保留是为了与课程示例兼容。它与 Claude 代码无关，也不会由任何代理自动更新。Codex、OpenHands、Antigravity 以及其他编程代理在它们的根指令要求启动时读取并在交接前更新时，也可以使用同一个文件。

毕业设计项目：一个真实应用

所有六个课程项目都围绕同一产品展开：一个基于 Electron 的个人知识库桌面应用程序。

    ┌──────────────────────────────────────────────────────┐
    │             Knowledge Base Desktop App               │
    │                                                      │
    │  ┌──────────────┐  ┌──────────────────────────────┐  │
    │  │ Document List│  │       Q&A Panel              │  │
    │  │              │  │                              │  │
    │  │ doc-001.md   │  │  Q: What is harness eng?     │  │
    │  │ doc-002.md   │  │  A: The environment built    │  │
    │  │ doc-003.md   │  │     around an agent model... │  │
    │  │ ...          │  │     [citation: doc-002.md]   │  │
    │  └──────────────┘  └──────────────────────────────┘  │
    │                                                      │
    │  ┌─────────────────────────────────────────────────┐ │
    │  │ Status Bar: 42 docs | 38 indexed | last sync 3m │ │
    │  └─────────────────────────────────────────────────┘ │
    └──────────────────────────────────────────────────────┘

    Core features:
    ├── Import local documents
    ├── Manage a document library
    ├── Process and index documents
    ├── Run AI-powered Q&A over imported content
    └── Return grounded answers with citations

选择这个项目是因为它结合了较强的实用价值、足够的真实世界产品复杂性，以及观察配置改进前后的良好环境。

每个课程项目的入门/解决方案都是此 Electron 应用在该演化阶段的完整复制品。P(N 1) 的入门来源于 P(N) 的解决方案——随着你的配置技能增长，应用会不断演化。

学习路径

该课程设计为按顺序进行。每个阶段都建立在前一个阶段的基础上。

    第1阶段：看到问题              第2阶段：构建仓库
    ========================              ==========================

    L01 强大的模型 ≠ 可靠         L03 仓库作为单一
         execution                              source of truth
    L02  马具实际上意味着什么
                                          L04  Split instructions across
         |                                     files, not one giant file
         v
    P01  仅提示 vs.                       |
         rules-first comparison                v
                                               P02  Agent-readable workspace

    第3阶段：连接会话             第4阶段：反馈  &  范围
    ==========================            =========================

    L05 保持上下文活跃               L07 明确任务界限
         across sessions
                                          L08  Feature lists as harness
    L06 在每个原语之前初始化
         agent session
                                               |
         |                                     v
         v                                     P04  Runtime feedback to
    P03 多会话连续性                   正确的代理行为

    第5阶段：验证                 第6阶段：综合所有内容
    =====================                 ============================

    L09 停止代理                 L11  创建代理的运行时
         declaring victory early               observable

    L10  全流程运行 =              L12  最终交接清理
         real verification                      every session

         |                                     |
         v                                     v
    P05  代理验证自己的工作      P06  构建完整的线束
                                               (capstone project)

    第7阶段：自动化循环
    ==========================

    L13 停止提示你的代理 —
         design loops instead

         |
         v
    P07 构建你的第一个自动循环
         (goal loop, timer loop, maker-checker)

    第8阶段：构建系统
    =============================

    L14  将系统画成图表 —
         nodes, edges, shared state, routing

         |
         v
    P08 将你的工作流程画成图表
         (explicit graph, parallel fan-out/fan-in,
          rollback edges, human-in-the-loop)

如果你是兼职的话，每个阶段大约需要一周时间。如果你想加快进度，阶段1到3可以在一个长周末完成。

教学大纲

讲座 — 14 个概念单元，每个单元回答一个核心问题

阅读每场讲座的完整文本，请访问 文档网站。

项目——8 个动手项目，将讲座方法应用到同一个 Electron 应用

    PROJECT EVOLUTION
    =================

    P01  Prompt-only vs. rules-first       You see the problem
     |
     v
    P02  Agent-readable workspace          You restructure the repo
     |
     v
    P03  Multi-session continuity          You connect sessions
     |
     v
    P04  Runtime feedback & scope          You add feedback loops
     |
     v
    P05  Self-verification                 You make the agent check itself
     |
     v
    P06  Complete harness (capstone)       You build the full system
     |
     v
    P07  Your first automated loop        You step outside the loop
     |
     v
    P08  Draw your workflow as a graph    You draw the system as a graph

    Each project's solution becomes the next project's starter.
    The app evolves. Your harness skills grow with it.

资源库

智能体会话生命周期

本课程的核心理念之一：代理的会话应遵循结构化的生命周期，而不是随意进行。 其表现如下：

    代理会话生命周期
    ======================

    ┌──────────────────────────────────────────────────────────────────┐
    │  开始                                                           │
    │                                                                  │
    │  1. 代理阅读 AGENTS.md / CLAUDE.md                            │
    │  2. 代理运行 init.sh（安装、验证、健康检查）           │
    │  3. 代理阅读 claude-progress.md（上次发生了什么）     │
    │  4. 代理阅读 feature_list.json（已完成的内容，接下来的任务）     │
    │  5. 代理检查 git 日志（最近的更改）                        │
    │                                                                  │
    │  选择                                                          │
    │                                                                  │
    │  6. 代理仅选择一个未完成的功能
    │  7. 代理仅在该功能上工作
    │                                                                  │
    │  执行                                                         │
    │                                                                  │
    │  8. 代理实现该功能                                 │
    │  9. 代理运行验证（测试、代码检查、类型检查）            │
    │  10. 如果验证失败：修复并重新运行                       │
    │  11. 如果验证通过：记录证据
    │                                                                  │
    │  总结                                                         │
    │                                                                  │
    │  12. 代理更新 claude-progress.md                            │
    │  13. 代理更新 feature_list.json                             │
    │  14. 代理记录仍然损坏或未验证的部分                        │
    │  15. 代理提交（仅在安全时恢复）                            │
    │  16. 代理为下一次会话留出干净的重启路径                    │
    │                                                                  │
    └──────────────────────────────────────────────────────────────────┘

    这个框架控制了生命周期中的每一次转换。
    模型决定每一步该写什么代码。
    如果没有框架，第9步变成“代理说看起来没问题。”
    有了框架，第9步是“测试通过，代码风格检查通过，类型检查通过。”

npm install
npm run docs:dev        # Dev server with hot reload
npm run docs:build      # Production build
npm run docs:preview    # Preview built site

learn-harness-engineering/
├── docs/                          # VitePress documentation site
│   ├── lectures/                  # 14 lectures (index.md + code/ examples)
│   │   ├── lecture-01-*/
│   │   └── ... (14 total)
│   ├── projects/                  # 8 project descriptions
│   │   ├── project-01-*/
│   │   └── ... (8 total)
│   └── resources/                 # Multilingual templates & references (14 languages)
│       ├── en/
│       └── ... (14 total)
├── projects/
│   ├── shared/                    # Shared Electron + TypeScript + React foundation
│   └── project-NN/                # Per-project starter/ and solution/ directories
├── skills/                        # Reusable AI agent skills
│   └── harness-creator/           # Harness engineering skill
├── tools/                         # Zero-dependency shell utilities
│   └── audit-harness.sh           # Shell-based harness audit (L03–L12, no Node.js needed)
├── package.json                   # VitePress + dev tooling
└── CLAUDE.md                      # Claude Code instructions for this repo

# Run directly on any repo
curl -fsSL https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/tools/audit-harness.sh | bash -s -- /path/to/your/repo

# Or after cloning
bash tools/audit-harness.sh /path/to/your/repo