From 332350ca549d241c04603282918c0f203ab877e3 Mon Sep 17 00:00:00 2001 From: tradecatlabs <288998340+tradecatlabs@users.noreply.github.com> Date: Sat, 4 Jul 2026 06:56:41 +0800 Subject: [PATCH] docs: research - add learn harness engineering domain --- README.md | 3 +- assets/ai-citation/llms-full.txt | 3 + docs/README.md | 3 + docs/research/AGENTS.md | 9 +- docs/research/README.md | 4 + docs/research/harness/AGENTS.md | 1 + docs/research/harness/README.md | 4 + docs/research/research-transfer-synthesis.md | 10 +- .../research-value-application-map.md | 11 +- .../AGENTS.md | 26 + .../README.md | 70 ++ .../analysis.md | 76 +++ .../deep-dive.md | 135 ++++ .../domain.yml | 41 ++ .../raw/AGENTS.md | 12 + .../raw/README.md | 16 + .../raw/github-languages.raw.json | 7 + .../raw/github-license.raw.txt | 21 + .../raw/github-readme.raw.md.txt | 612 ++++++++++++++++++ .../raw/github-repo.raw.json | 58 ++ .../raw/github-root-contents.raw.json | 226 +++++++ .../raw/sources.yml | 39 ++ llms.txt | 1 + metadata/taxonomy.yml | 9 + 24 files changed, 1386 insertions(+), 11 deletions(-) create mode 100644 docs/research/walkinglabs-learn-harness-engineering/AGENTS.md create mode 100644 docs/research/walkinglabs-learn-harness-engineering/README.md create mode 100644 docs/research/walkinglabs-learn-harness-engineering/analysis.md create mode 100644 docs/research/walkinglabs-learn-harness-engineering/deep-dive.md create mode 100644 docs/research/walkinglabs-learn-harness-engineering/domain.yml create mode 100644 docs/research/walkinglabs-learn-harness-engineering/raw/AGENTS.md create mode 100644 docs/research/walkinglabs-learn-harness-engineering/raw/README.md create mode 100644 docs/research/walkinglabs-learn-harness-engineering/raw/github-languages.raw.json create mode 100644 docs/research/walkinglabs-learn-harness-engineering/raw/github-license.raw.txt create mode 100644 docs/research/walkinglabs-learn-harness-engineering/raw/github-readme.raw.md.txt create mode 100644 docs/research/walkinglabs-learn-harness-engineering/raw/github-repo.raw.json create mode 100644 docs/research/walkinglabs-learn-harness-engineering/raw/github-root-contents.raw.json create mode 100644 docs/research/walkinglabs-learn-harness-engineering/raw/sources.yml diff --git a/README.md b/README.md index 38638a6..09dff20 100644 --- a/README.md +++ b/README.md @@ -532,9 +532,10 @@ * [**工程实践**](docs/references/quality-gates-and-pitfalls.md): 项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口。 * [**技术栈**](docs/references/technology-stack.md#reference-technology-stack-十四如何选择技术栈): 常见软件系统技术栈、选型维度、组合案例与初学者学习路径。 * [**研究域治理契约**](docs/research/research-domain-contract.md): 研究域的结构、raw 原始事实层、成熟度、证据、沉淀和归档规则。 -* [**研究价值与应用地图**](docs/research/research-value-application-map.md): 17 个研究域的用户价值、核心启示、应用位置和下沉路线。 +* [**研究价值与应用地图**](docs/research/research-value-application-map.md): 18 个研究域的用户价值、核心启示、应用位置和下沉路线。 * [**研究迁移综合**](docs/research/research-transfer-synthesis.md): 用对标拆解、改良迭代和杂交创新把研究转成可执行路线。 * [**Harness 工程解析**](docs/research/harness/harness-engineering.md): Harness Engineering 的工程控制、评估器与反馈闭环解析。 +* [**Learn Harness Engineering 研究域**](docs/research/walkinglabs-learn-harness-engineering/README.md): Harness Engineering 课程、模板、Skill 与审计工具对标对象。 * [**OpenAI Codex 研究域**](docs/research/openai-codex/README.md): 官方 coding agent 工具源码研究对象。 * [**Claude Code Best Practice 研究域**](docs/research/shanraisshan-claude-code-best-practice/README.md): Agentic Engineering 方法论对标研究对象。 * [**Cline 研究域**](docs/research/cline-cline/README.md): IDE/SDK/CLI 自主编码 Agent 研究对象。 diff --git a/assets/ai-citation/llms-full.txt b/assets/ai-citation/llms-full.txt index 85e0557..6c4425a 100644 --- a/assets/ai-citation/llms-full.txt +++ b/assets/ai-citation/llms-full.txt @@ -82,6 +82,9 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链 - docs/research/research-transfer-synthesis.md：将对标拆解、改良迭代和杂交创新转成可执行研究路线。 - docs/research/harness/README.md：Harness Engineering 的工程控制、评估器与反馈闭环研究对象。 - docs/research/harness/harness-engineering.md：Harness Engineering 的工程控制、评估器与反馈闭环解析。 +- docs/research/walkinglabs-learn-harness-engineering/README.md：Harness Engineering 课程、模板、Skill 与审计工具对标研究对象。 +- docs/research/walkinglabs-learn-harness-engineering/analysis.md：walkinglabs/learn-harness-engineering 的结构化研究结论、可迁移做法、风险和验证动作。 +- docs/research/walkinglabs-learn-harness-engineering/deep-dive.md：walkinglabs/learn-harness-engineering 的 L2 结构深度研究、关键机制和本仓应用建议。 - docs/research/aider-ai-aider/README.md：终端 AI 结对编程工具研究对象。 - docs/research/aider-ai-aider/analysis.md：Aider-AI/aider 的结构化研究结论、可借鉴点、风险和下一轮任务。 - docs/research/aider-ai-aider/deep-dive.md：Aider-AI/aider 的 L2 源码/结构深度研究、关键机制和可迁移模式。 diff --git a/docs/README.md b/docs/README.md index 3e9bfcb..a6885e0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -81,6 +81,9 @@ - [研究迁移综合](./research/research-transfer-synthesis.md) - 将对标拆解、改良迭代和杂交创新转成可执行研究路线。 - [Harness 研究对象](./research/harness/README.md) - Harness Engineering 的工程控制、评估器与反馈闭环研究对象。 - [Harness 工程解析](./research/harness/harness-engineering.md) - Harness Engineering 的工程控制、评估器与反馈闭环解析。 +- [walkinglabs/learn-harness-engineering 研究域](./research/walkinglabs-learn-harness-engineering/README.md) - Harness Engineering 课程、模板、Skill 与审计工具对标对象。 +- [walkinglabs/learn-harness-engineering 研究分析](./research/walkinglabs-learn-harness-engineering/analysis.md) - 结构化研究结论、可迁移做法、风险和验证动作。 +- [walkinglabs/learn-harness-engineering 深度研究](./research/walkinglabs-learn-harness-engineering/deep-dive.md) - L2 结构深度研究、关键机制和本仓应用建议。 - [tmux 蜂群协作](./research/tmux-ai-swarm.md) - 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式。 - [Aider-AI/aider 研究域](./research/aider-ai-aider/README.md) - 终端 AI 结对编程工具。 - [Aider-AI/aider 研究分析](./research/aider-ai-aider/analysis.md) - 结构化研究结论、可借鉴点、风险和下一轮任务。 diff --git a/docs/research/AGENTS.md b/docs/research/AGENTS.md index 373eafd..11f986e 100644 --- a/docs/research/AGENTS.md +++ b/docs/research/AGENTS.md @@ -24,6 +24,13 @@ research/ │ ├── README.md │ ├── harness-engineering.md │ └── AGENTS.md +├── walkinglabs-learn-harness-engineering/ +│ ├── README.md +│ ├── domain.yml +│ ├── analysis.md +│ ├── deep-dive.md +│ ├── raw/ +│ └── AGENTS.md ├── ai-for-developers-awesome-vibe-coding/ │ ├── README.md │ ├── domain.yml @@ -100,7 +107,7 @@ research/ 上方只展开了第一个外部仓库研究域的基础形态；所有外部仓库研究域都必须包含同样的原始事实层、 `analysis.md` 和 `deep-dive.md`。 -`deep-dive.md` 是 L2 产物；当前 17 个外部仓库研究域已经全部补齐，P3 只表示采用优先级低， +`deep-dive.md` 是 L2 产物；当前 18 个外部仓库研究域已经全部补齐，P3 只表示采用优先级低， 不再表示研究深度缺口。 ## 修改规则 diff --git a/docs/research/README.md b/docs/research/README.md index 4a3a7e5..f2add4c 100644 --- a/docs/research/README.md +++ b/docs/research/README.md @@ -16,6 +16,7 @@ | [研究价值与应用地图](research-value-application-map.md) | 研究体系给用户带来的价值、核心启示、应用位置和下沉路线。 | | [研究迁移综合](research-transfer-synthesis.md) | 将对标拆解、改良迭代和杂交创新转成可执行研究路线。 | | [Harness 研究对象](harness/) | 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。 | +| [walkinglabs/learn-harness-engineering 研究域](walkinglabs-learn-harness-engineering/) | Harness Engineering 课程、模板、Skill 与审计工具对标对象。 | | [tmux 蜂群协作](tmux-ai-swarm.md) | 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式。 | | [Aider-AI/aider 研究域](aider-ai-aider/) | 终端 AI 结对编程工具。 | | [cline/cline 研究域](cline-cline/) | IDE/SDK/CLI 自主编码 Agent。 | @@ -45,6 +46,9 @@ - [研究迁移综合](research-transfer-synthesis.md) - 将对标拆解、改良迭代和杂交创新转成可执行研究路线。 - [Harness 研究对象](harness/README.md) - 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。 - [Harness 工程解析](harness/harness-engineering.md) - Harness Engineering 的工程控制、评估器与反馈闭环解析。 +- [walkinglabs/learn-harness-engineering 研究域](walkinglabs-learn-harness-engineering/README.md) - Harness Engineering 课程、模板、Skill 与审计工具对标对象。 +- [walkinglabs/learn-harness-engineering 研究分析](walkinglabs-learn-harness-engineering/analysis.md) - 结构化研究结论、可迁移做法、风险和验证动作。 +- [walkinglabs/learn-harness-engineering 深度研究](walkinglabs-learn-harness-engineering/deep-dive.md) - L2 结构深度研究、关键机制和本仓应用建议。 - [tmux 蜂群协作](tmux-ai-swarm.md) - 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式。 - [Aider-AI/aider 研究域](aider-ai-aider/README.md) - 终端 AI 结对编程工具。 - [Aider-AI/aider 研究分析](aider-ai-aider/analysis.md) - 结构化研究结论、可借鉴点、风险和下一轮任务。 diff --git a/docs/research/harness/AGENTS.md b/docs/research/harness/AGENTS.md index 16afee6..adc4433 100644 --- a/docs/research/harness/AGENTS.md +++ b/docs/research/harness/AGENTS.md @@ -28,6 +28,7 @@ harness/ - 不承载通用工程模板；稳定模板迁移到 `docs/references/`。 - 不承载可执行能力；可复用能力迁移到 `skills/`。 - 不把单个工具、单篇文章或单次实验直接包装成稳定结论。 +- 单个外部仓库的一手研究放到同级独立研究域，例如 `../walkinglabs-learn-harness-engineering/`。 ## 证据要求 diff --git a/docs/research/harness/README.md b/docs/research/harness/README.md index c60ec29..d19e3bf 100644 --- a/docs/research/harness/README.md +++ b/docs/research/harness/README.md @@ -5,6 +5,7 @@ - 本目录把 Harness 作为独立研究对象维护。 - 稳定正文入口是 [Harness 工程解析](harness-engineering.md)。 - 研究重点是工程控制、评估器、反馈闭环、上下文注入、架构约束和长期治理。 +- 相关对标研究域是 [walkinglabs/learn-harness-engineering](../walkinglabs-learn-harness-engineering/README.md)。 - 成熟结论可晋升到 `docs/concepts/`、`docs/references/`、`docs/workflow/` 或 `skills/`。 ## 快速导航 @@ -12,6 +13,7 @@ | 文档 | 定位 | |:---|:---| | [Harness 工程解析](harness-engineering.md) | 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。 | +| [walkinglabs/learn-harness-engineering 研究域](../walkinglabs-learn-harness-engineering/README.md) | Harness Engineering 课程、模板、Skill 与审计工具对标对象。 | | [AGENTS](AGENTS.md) | Harness 研究对象目录操作规则。 |
@@ -20,6 +22,7 @@ ### 细粒度目录 - [Harness 工程解析](harness-engineering.md) - 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。 +- [walkinglabs/learn-harness-engineering 研究域](../walkinglabs-learn-harness-engineering/README.md) - Harness Engineering 课程、模板、Skill 与审计工具对标对象。 - [AGENTS](AGENTS.md) - Harness 研究对象目录操作规则。
@@ -27,6 +30,7 @@ ## 使用方式 - 需要理解 Harness Engineering 时，先读 Harness 工程解析。 +- 需要看课程、模板、Skill 和审计工具的外部对标时，读 walkinglabs/learn-harness-engineering 研究域。 - 需要新增来源、评估框架、工具链样例或采用判断时，先检查 AGENTS 中的对象边界。 - 结论稳定后，再迁移到对应的概念、参考、流程或技能文档。 diff --git a/docs/research/research-transfer-synthesis.md b/docs/research/research-transfer-synthesis.md index 297aa7a..c7e0f89 100644 --- a/docs/research/research-transfer-synthesis.md +++ b/docs/research/research-transfer-synthesis.md @@ -4,9 +4,9 @@ - 研究不是证明“我看过资料”，而是把成熟对象拆成可迁移机制、不可迁移边界和可验证动作。 - 本轮把 P1 研究对象合成为一条主线：Codex 负责执行控制面，Aider 负责 Git 编辑闭环，Cline 负责多入口平台化，Claude Code Best Practice 负责方法论资产化。 -- 当前 17 个研究域均已补齐 `deep-dive.md`，全量进入 L2 证据层。 +- 当前 18 个研究域均已补齐 `deep-dive.md`，全量进入 L2 证据层。 - 本仓不应该复制任何一个外部项目，而应该杂交成“AI 原生知识库控制面”。 -- 下一步最小试用动作是：补 `scripts` 风险登记、补研究域迁移表、补资源治理 schema、补工作流验证闭环。 +- 下一步最小试用动作是：补 `scripts` 风险登记、补 Harness 检查表、补资源治理 schema、补工作流验证闭环。 ## 研究质量问题 @@ -29,6 +29,7 @@ | 参考对象 | 核心机制 | 真正带来结果的动作 | 可迁移做法 | 不可迁移条件 | 下一步试用动作 | |:---|:---|:---|:---|:---|:---| | `openai/codex` | 执行控制面 | 把配置、沙箱、执行策略、工具、技能和项目上下文显式建模 | `scripts` 风险分级、Agent 执行边界、技能输入输出契约 | 不复制 Rust/Bazel/CLI runtime，本仓不是 coding agent 产品 | 建立 `scripts/manifest.yml`，记录 owner、风险、输入、输出、dry-run 和 CI 状态 | +| `walkinglabs/learn-harness-engineering` | Harness 课程到工具化 | 把 Agent 可靠性拆成指令、状态、验证、范围、生命周期、模板、Skill 和审计脚本 | 五子系统审计、feature state、init 验证入口、评估表、会话交接 | 不复制 VitePress 站点、多语言工程和 Electron 课程项目 | 为本仓 Harness 研究域补最小检查表，并抽样改写成文档仓库版本 | | `Aider-AI/aider` | Git 驱动编辑闭环 | 让每次 AI 修改都进入 diff、lint/test、commit、回滚和审查链路 | 研究域和文档修改必须保留 diff 证据、门禁命令和失败修复记录 | 不复制 Python 实现、repo map 算法和完整交互式终端产品 | 建立“AI 修改 -> diff 审查 -> make test -> commit”工作流模板 | | `cline/cline` | 多入口 agent 平台 | 同一套能力暴露为 IDE、CLI、SDK、rules、skills、examples 和测试平台 | 为人类入口、AI 入口、脚本入口、skill 入口、资源入口和 metadata 入口写清协议 | 不提前做 SDK、服务端 hub 或复杂 UI | 梳理本仓入口矩阵，记录每个入口的输入、输出、owner 和验证命令 | | `shanraisshan/claude-code-best-practice` | 方法论资产化 | 把经验拆成 best practice、implementation、workflow、reports、config | 把经验短句下沉为概念、模板、流程、skill 或检查项 | 不照搬 Claude Code 生态绑定配置，不把个人偏好当通用标准 | 建立“经验 -> 产物类型 -> 验证方式”的分流表 | @@ -40,6 +41,7 @@ | 研究域 | 类型 | 最有价值机制 | 本仓迁移位置 | 下一步动作 | |:---|:---|:---|:---|:---| | `openai-codex` | coding-agent-tooling | 执行控制面 | `scripts/`、`workflow/`、`references/` | 建脚本风险登记表 | +| `walkinglabs-learn-harness-engineering` | harness-engineering | Harness 课程、模板、Skill 与审计工具 | `docs/research/harness/`、`workflow/`、`scripts/`、`skills/` | 建最小 Harness 检查表 | | `aider-ai-aider` | coding-agent-tooling | Git 驱动编辑闭环 | `workflow/` | 建 AI 修改到提交的证据模板 | | `cline-cline` | coding-agent-tooling | 多入口 agent 平台 | `metadata/`、`llms.txt`、`skills/` | 建入口矩阵 | | `shanraisshan-claude-code-best-practice` | agentic-engineering-methodology | 方法论资产化 | `concepts/`、`workflow/`、`skills/` | 建经验分流表 | @@ -65,8 +67,8 @@ | 改动点 | 原模式 | 本仓改良 | 验证指标 | |:---|:---|:---|:---| -| 研究域分析 | 结构观察和可借鉴点 | 对标拆解、迁移边界、试用动作 | 17 个研究域 `analysis.md` 都有可执行动作 | -| 深度研究 | L2 证据和关键机制 | 保留证据链，另写迁移综合 | 17 个研究域均有 `deep-dive.md` | +| 研究域分析 | 结构观察和可借鉴点 | 对标拆解、迁移边界、试用动作 | 18 个研究域 `analysis.md` 都有可执行动作 | +| 深度研究 | L2 证据和关键机制 | 保留证据链，另写迁移综合 | 18 个研究域均有 `deep-dive.md` | | 价值地图 | 用户价值说明 | 增加组合方案和验收指标 | 能回答“看完有什么用” | ### 第二轮：让研究进入仓库控制面 diff --git a/docs/research/research-value-application-map.md b/docs/research/research-value-application-map.md index 2371483..4293d72 100644 --- a/docs/research/research-value-application-map.md +++ b/docs/research/research-value-application-map.md @@ -2,10 +2,10 @@ ## 字多不看 -- 当前研究体系已经覆盖 17 个独立研究域，17 个均已完成 L2 深度研究。 +- 当前研究体系已经覆盖 18 个独立研究域，18 个均已完成 L2 深度研究。 - 这些研究不是为了介绍外部项目，而是为了把外部项目拆成可验证事实、核心机制、迁移边界和本仓可执行改进项。 -- 17 个研究域的 `analysis.md` 已统一为对标拆解、改良迭代、可迁移清单、不可迁移清单和验证动作格式。 -- 17 个研究域的 `deep-dive.md` 已补齐 L2 证据层、关键机制、迁移边界和 L3 验证任务。 +- 18 个研究域的 `analysis.md` 已统一为对标拆解、改良迭代、可迁移清单、不可迁移清单和验证动作格式。 +- 18 个研究域的 `deep-dive.md` 已补齐 L2 证据层、关键机制、迁移边界和 L3 验证任务。 - 用户获得的直接价值是少走弯路、看见范式、拿到可落地路线。 - 本仓获得的直接价值是形成 `getting-started`、`references`、`workflow`、`skills`、`assets`、`scripts` 和 `research` 的改进输入。 @@ -16,8 +16,8 @@ | 层级 | 数量 | 状态 | 说明 | |:---|---:|:---|:---| -| 研究域 | 17 | 已建立 | 每个外部仓库一个独立研究域，均有 raw 原始事实层、`analysis.md` 和 `deep-dive.md` | -| L2 深度研究 | 17 | 已完成 | 覆盖工具、课程、资源索引、项目实践、中文主题雷达和归档工具样本 | +| 研究域 | 18 | 已建立 | 每个外部仓库一个独立研究域，均有 raw 原始事实层、`analysis.md` 和 `deep-dive.md` | +| L2 深度研究 | 18 | 已完成 | 覆盖工具、课程、资源索引、项目实践、中文主题雷达、Harness 课程和归档工具样本 | | L1 观察研究 | 0 | 已清空 | P3 仍是低采用优先级，不再代表研究深度缺口 | ## 用户能获得什么 @@ -140,6 +140,7 @@ | 研究来源 | 用户价值 | 本仓应用位置 | 可执行产物 | |:---|:---|:---|:---| | `openai/codex` | 理解 coding agent 控制面 | `scripts/`、`skills/`、`references/` | 脚本风险分级、沙箱/审批清单、Agent 控制面模板 | +| `learn-harness-engineering` | 理解 Harness 如何从概念变成课程、模板、Skill 和审计工具 | `docs/research/harness/`、`workflow/`、`scripts/`、`skills/` | 最小 Harness 检查表、feature state 样例、Agent 产出评估表 | | `aider` | 理解 Git 驱动 AI 修改闭环 | `workflow/`、`references/` | AI 修改到提交的标准流程、文档 map / repo map 机制 | | `cline` | 理解多入口 agent 平台 | `metadata/`、`llms.txt`、`skills/` | 人类入口、AI 入口、脚本入口、skill 入口的入口契约 | | `awesome-claude-code` | 理解资源治理 | `assets/external-resources/` | 资源 schema、生命周期字段、资源校验脚本 | diff --git a/docs/research/walkinglabs-learn-harness-engineering/AGENTS.md b/docs/research/walkinglabs-learn-harness-engineering/AGENTS.md new file mode 100644 index 0000000..05866a6 --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/AGENTS.md @@ -0,0 +1,26 @@ +# walkinglabs/learn-harness-engineering 研究域 Agent 指南 + +本目录维护 `walkinglabs/learn-harness-engineering` 的独立研究域。 + +## 目录职责 + +```text +walkinglabs-learn-harness-engineering/ +├── README.md # 研究域入口和判断层 +├── AGENTS.md # 本目录维护规则 +├── domain.yml # 事实摘要层：仓库元数据、研究角色、来源证据 +├── analysis.md # L1 结构化研究结论、可迁移做法、风险和验证动作 +├── deep-dive.md # L2 结构深度研究、关键机制和本仓应用建议 +└── raw/ # 原始事实层：拉取到本地的一手材料快照 +``` + +## 维护规则 + +- 本目录只研究 `walkinglabs/learn-harness-engineering`，不要混入其他仓库的横向比较正文。 +- 动态事实必须写入 `domain.yml.github_observed`，并更新 `observed_at`。 +- `raw/` 保存原始事实层，必须通过 `python3 scripts/fetch-research-raw.py` 刷新。 +- 不手工改写 `raw/*.raw.*` 文件；稳定事实摘要再同步到 `domain.yml`。 +- README 只写判断、定位、使用方式和后续观察点，不堆外部 README 全文。 +- `analysis.md` 写 L1 结构化理解；`deep-dive.md` 写 L2 结构证据、关键机制和可迁移模式。 +- 与通用 Harness 范式的横向比较放到 `docs/research/harness/` 或独立对比文档，不把本目录重新变成聚合域。 +- 修改后运行 `make sync-doc-toc` 和 `make test`。 diff --git a/docs/research/walkinglabs-learn-harness-engineering/README.md b/docs/research/walkinglabs-learn-harness-engineering/README.md new file mode 100644 index 0000000..0f2ada4 --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/README.md @@ -0,0 +1,70 @@ +# walkinglabs/learn-harness-engineering 研究域 + +## 字多不看 + +- 本目录研究 `walkinglabs/learn-harness-engineering` 这个外部仓库。 +- 当前优先级：P2；研究角色：Harness Engineering 课程、模板、Skill 与审计工具对标对象。 +- GitHub 动态事实放在 `domain.yml`，观测日期为 2026-07-04。 +- 它最值得迁移的不是站点形态，而是把 AI Agent 可靠性拆成指令、状态、验证、范围和生命周期。 + +## 快速导航 + +| 文档 | 定位 | +|:---|:---| +| [domain.yml](domain.yml) | 仓库事实快照、研究方向、优先级和来源证据。 | +| [analysis.md](analysis.md) | 本研究域的结构化研究结果、可迁移做法、风险和验证动作。 | +| [deep-dive.md](deep-dive.md) | L2 结构深度研究、关键机制和对本仓 Harness 体系的应用建议。 | +| [AGENTS.md](AGENTS.md) | 本研究域维护规则。 | + +
+完整细粒度目录（点击展开/收起） + +### 细粒度目录 + +- [domain.yml](domain.yml) - 仓库事实快照、研究方向、优先级和来源证据。 +- [analysis.md](analysis.md) - 本研究域的结构化研究结果、可迁移做法、风险和验证动作。 +- [deep-dive.md](deep-dive.md) - L2 结构深度研究、关键机制和对本仓 Harness 体系的应用建议。 +- [AGENTS.md](AGENTS.md) - 本研究域维护规则。 + +
+ +## 使用方式 + +- 先读本 README 的判断，再读 `analysis.md` 和 `deep-dive.md` 的研究结论，最后读 `domain.yml`。 +- 需要引用 stars、forks、release、归档状态、主页或主题标签时，先重新核验 GitHub。 +- 需要更新原始事实时，运行 `python3 scripts/fetch-research-raw.py walkinglabs-learn-harness-engineering`。 +- 如果形成稳定方法论，再下沉到 `docs/research/harness/`、`docs/workflow/` 或 `skills/`。 + +## 正文 + +### 研究定位 + +`walkinglabs/learn-harness-engineering` 的当前研究定位是：Harness Engineering +课程、模板、Skill 与审计工具对标对象。 + +### 当前判断 + +这是本仓 Harness 研究线的重要外部样本。它把 Harness Engineering 从概念解释推进到可操作系统： + +- 用 12 讲解释 Agent 为什么会失败，以及 Harness 如何约束失败面。 +- 用 6 个项目把同一个 Electron 知识库应用从 prompt-only 推进到完整 Harness。 +- 用模板沉淀 `AGENTS.md`、`feature_list.json`、`init.sh`、进度文件、交接文件和评估表。 +- 用 `skills/harness-creator` 与 `tools/audit-harness.sh` 把课程结论变成可运行工具。 + +对本仓最有价值的点是：把“AI 协作经验”升级成“仓库内可执行控制面”。经验如果只停留在提示词， +下一轮会丢失；经验如果写成状态机、验证命令、审计脚本和交接文件，就能被 Agent 反复执行。 + +### 观察字段 + +- GitHub URL：https://github.com/walkinglabs/learn-harness-engineering +- 当前研究方向：`harness-engineering` +- 当前优先级：P2 +- 当前归档状态：`false` +- 主要语言：`TypeScript` + +### 后续观察 + +- `skills/harness-creator` 是否继续演化出更强的自动创建、校验和 benchmark 能力。 +- `tools/audit-harness.sh` 的五子系统审计是否能转成本仓 `make` 门禁或独立脚本。 +- 课程项目中的 `feature_list.json`、`session-handoff.md`、`evaluator-rubric.md` 是否能改良成本仓任务治理模板。 +- 它引用的 OpenAI、Anthropic、LangChain、Thoughtworks、Cursor 等 Harness 文章是否出现新版本或新范式。 diff --git a/docs/research/walkinglabs-learn-harness-engineering/analysis.md b/docs/research/walkinglabs-learn-harness-engineering/analysis.md new file mode 100644 index 0000000..377bf82 --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/analysis.md @@ -0,0 +1,76 @@ +# walkinglabs/learn-harness-engineering 研究分析 + +## 本轮结论 + +`walkinglabs/learn-harness-engineering` 的核心价值不是“又一个 AI 编程教程”，而是把 Harness +Engineering 拆成可复制的仓库控制面：入口指令、状态文件、验证命令、范围约束、会话生命周期、 +评估器和审计工具。 + +本仓最应该迁移的是它的对象化交付方式：每个 Agent 可靠性问题都要落到仓库内 artifact， +而不是停留在经验句子或提示词技巧。对本仓而言，最有价值的迁移方向是： + +- 把 `docs/research/harness/` 的概念研究补成可执行检查清单。 +- 把 `feature_list.json` 的状态机思想迁移到任务治理、研究域推进和 Agent 工作包。 +- 把 `init.sh` 的单入口验证思想迁移到本仓 `make test`、raw 拉取和文档门禁。 +- 把 `evaluator-rubric.md` 的评分表思想迁移到重要产出的交叉审计。 + +## 本地证据 + +- 研究对象：`walkinglabs/learn-harness-engineering` +- 当前研究角色：Harness Engineering 课程、模板、Skill 与审计工具对标对象 +- 原始仓库：`raw/repository/` +- 原始来源清单：`raw/sources.yml` +- 事实摘要：`domain.yml` +- 深度证据：`deep-dive.md` + +## 对标拆解 + +| 项 | 内容 | +|:---|:---| +| 参考对象 | `walkinglabs/learn-harness-engineering` | +| 它解决的核心问题 | 强模型在真实仓库中仍会丢上下文、越界、提前宣告完成、跳过验证和无法跨会话延续 | +| 核心机制 | 12 讲课程、6 个递进项目、模板库、`skills/harness-creator`、`tools/audit-harness.sh` | +| 真正带来结果的动作 | 把经验变成仓库内可读、可执行、可验证、可交接的结构化 artifact | +| 可迁移做法 | 五子系统模型、fresh session test、feature list 状态机、pass-state gating、全链路验证、会话交接 | +| 不可迁移条件 | 不复制其 VitePress 站点、多语言工程和完整课程项目体量；本仓先保持轻量知识库和研究域结构 | +| 下一步试用动作 | 为本仓 Harness 研究域补一份“最小可执行 Harness 检查表”和一个研究任务状态机样例 | + +## 改良迭代 + +| 改良目标 | 原模式 | 本仓版本 | 验证指标 | +|:---|:---|:---|:---| +| 概念落地 | 课程用模板和项目演示 Harness | 本仓在 `docs/research/harness/` 增加可执行检查表 | 读者能直接审计自己的仓库 | +| 状态治理 | `feature_list.json` 管理功能状态 | 研究域和任务包使用 `id / behavior / verification / status / evidence` | 新会话能知道下一步，不靠聊天记忆 | +| 验证闭环 | `init.sh` 统一安装、验证和启动 | 本仓继续收敛到 `make test` + raw 拉取 + 文档结构门禁 | 任何新增研究域都能一命令验收 | +| 审计沉淀 | `evaluator-rubric.md` 评分后验收 | 本仓重要产出用“正确性、证据、范围、可维护性、交接”审计 | 研究报告读完有可执行结论 | + +## 可迁移清单 + +- 入口文件只做路由和硬约束，详细知识放到邻近文档中按需读取。 +- 把仓库当成 Agent 的系统真相源，重要上下文不能只留在聊天记录或人脑里。 +- 每个任务或功能都要有行为描述、验证方式、状态和证据，避免“差不多完成”。 +- 验证失败信息要写给 Agent 看，包含问题、原因和修复方向。 +- 会话结束前必须留下可恢复状态：做了什么、验证了什么、没做完什么、下一步是什么。 +- 对 Harness 组件做 ablation 思维：移除某个组件后失败是否增加，用结果判断优先级。 + +## 不可迁移清单 + +- 不把本仓变成 15 语言 VitePress 课程站点。 +- 不直接引入其 `harness-creator` 脚本作为本仓工具真相源，除非先完成安全、依赖和维护成本评估。 +- 不把教学项目的 Electron 技术栈误认为 Harness Engineering 的必要条件。 +- 不把 feature list 机械复制到所有文档；只有需要状态机和验证闭环的对象才引入。 + +## 验证动作 + +| 动作 | 成功信号 | 失败信号 | +|:---|:---|:---| +| 为本仓 Harness 研究域补最小检查表 | 能按五子系统审计一个仓库 | 仍只是概念解释，不能指导操作 | +| 把 feature list 思想用于一个真实任务包 | 新会话能从状态文件继续 | 仍需要翻聊天记录判断进度 | +| 抽取一条 Agent 错误反馈并转成门禁 | 同类错误下次能自动失败并提示修复 | 仍依赖人工反复提醒 | +| 试运行外部 `audit-harness.sh` 对本仓打分 | 能发现本仓 Harness 缺口 | 检查项与本仓结构不匹配且无法解释 | + +## 沉淀判断 + +- 稳定概念进入 `docs/research/harness/` 和 `docs/workflow/`。 +- 可执行检查表成熟后，可进入 `scripts/` 或 `skills/`。 +- 本研究域保持 P2，对齐 Harness Engineering 课程和工具化对标对象。 diff --git a/docs/research/walkinglabs-learn-harness-engineering/deep-dive.md b/docs/research/walkinglabs-learn-harness-engineering/deep-dive.md new file mode 100644 index 0000000..d6ab7d3 --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/deep-dive.md @@ -0,0 +1,135 @@ +# walkinglabs/learn-harness-engineering 深度研究 + +## 研究级别 + +- 当前级别：L2 结构深度研究。 +- 研究对象：`walkinglabs/learn-harness-engineering`。 +- 证据来源：本目录 `raw/` 下的 GitHub 元数据、README 快照和本地仓库工作树。 +- 观察日期：2026-07-04。 + +## L2 结论 + +`walkinglabs/learn-harness-engineering` 的成熟点在于：它没有把 Harness Engineering +讲成“写更好的提示词”，而是讲成一套围绕 Agent 的工程控制系统。 + +它的结构从上到下是四层： + +1. 课程叙事层：README、VitePress 首页、12 讲解释为什么 Agent 会失败。 +2. 项目实验层：6 个递进项目在同一个 Electron 知识库应用上逐步增加 Harness 机制。 +3. 资源模板层：`AGENTS.md`、`feature_list.json`、`init.sh`、进度、交接、评估表可直接复制。 +4. 工具执行层：`skills/harness-creator` 和 `tools/audit-harness.sh` 把课程结论转成生成与审计能力。 + +这对本仓的启示是：研究报告不能只说“应该更可靠”，而要把可靠性拆成仓库 artifact、 +状态机、门禁命令、评分表和会话交接。 + +## 源码证据 + +- `raw/repository/README.md`：主叙事入口，包含 Harness 五子系统、学习路径、12 讲、6 项目和资源库。 +- `raw/repository/docs/en/index.md`：站点入口，把课程分成 lectures、projects 和 resource library。 +- `raw/repository/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md`：定义五子系统模型。 +- `raw/repository/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md`：强调仓库是真相源。 +- `raw/repository/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md`：把 feature list 定义为 Harness 原语。 +- `raw/repository/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md`：把全链路验证和可执行架构规则绑定。 +- `raw/repository/docs/en/resources/templates/AGENTS.md`：给出启动流程、工作规则、完成定义和会话结束动作。 +- `raw/repository/docs/en/resources/templates/feature_list.json`：提供带状态、验证和证据字段的功能状态机。 +- `raw/repository/docs/en/resources/templates/init.sh`：统一安装、基线验证和启动命令。 +- `raw/repository/docs/en/resources/templates/evaluator-rubric.md`：把产出验收转成评分表。 +- `raw/repository/projects/project-06/solution/AGENTS.md`：完整项目末态的启动规则、边界、完成定义和清理要求。 +- `raw/repository/projects/project-06/solution/feature_list.json`：完整项目用证据字段声明每个功能通过状态。 +- `raw/repository/skills/harness-creator/SKILL.md`：将 Harness 创建、校验和报告生成封装成可复用 Skill。 +- `raw/repository/tools/audit-harness.sh`：零依赖 shell 审计脚本，按五子系统检查现有仓库。 +- `raw/repository/.github/workflows/deploy-pages.yml`：课程站点发布流程。 +- `raw/repository/.github/workflows/release-course-pdfs.yml`：PDF 课程产物发布流程。 + +## 关键机制 + +### 五子系统把可靠性从感觉变成检查项 + +课程把 Harness 拆成 instructions、tools、environment、state、feedback。这个分法的价值是让“Agent +不可靠”不再是笼统抱怨，而能被定位成入口不清、工具不足、环境不可复现、状态不可恢复或反馈缺失。 + +对本仓而言，研究域可以沿用这个检查框架： + +- Instructions：`AGENTS.md`、README、目录索引是否能让新 Agent 找到入口。 +- Environment：依赖、版本、raw 拉取、Makefile 是否可复现。 +- State：研究进度、任务状态和决策是否在仓库内。 +- Feedback：`make test`、链接检查、结构检查是否足够表达完成标准。 +- Tools：脚本、Skill 和 GitHub 流程是否被清楚登记。 + +### 仓库真相源减少跨会话猜测 + +Lecture 03 的核心不是“多写文档”，而是“把决策信息放到 Agent 能看到的位置”。它用 fresh session test +要求一个新会话仅凭仓库回答：系统是什么、如何组织、如何运行、如何验证、当前进度是什么。 + +本仓已经有 `AGENTS.md`、`llms.txt`、`assets/ai-citation/llms-full.txt` 和 docs 索引。缺口在于： +部分研究结论仍是散文式表达，尚未都转成可恢复状态和可执行验证。 + +### Feature list 是任务完成定义的机器接口 + +Lecture 08 把 feature list 从备忘录提升为 Harness 原语。核心不是 JSON 格式，而是四件事： + +- 每个条目有可观察行为。 +- 每个条目有验证命令或验证步骤。 +- 每个条目有状态。 +- 状态升级必须附带证据。 + +这比普通 TODO 更适合 AI 协作，因为 Agent 可以读取、选择、执行、验证、写回，而不是靠自然语言猜测 +“差不多完成”。 + +### 全链路验证改变 Agent 行为 + +Lecture 10 的关键判断是：只跑单元测试会遗漏组件边界问题，完整管线验证会反过来约束 Agent 的实现方式。 +它还强调把架构规则变成可执行检查，并把失败信息写成 Agent 能按步骤修复的反馈。 + +本仓当前 `make test` 已经包含 Markdown lint、链接、折叠块、docs 结构、metadata、AI 引用和 starter kit +检查。这是文档仓库的全链路验证雏形。下一步可以把研究域 raw 层、新研究域索引、目录 AGENTS 覆盖也纳入 +更强的结构性检查。 + +### Skill 与审计脚本让课程可执行 + +`skills/harness-creator/SKILL.md` 说明这个仓库不满足于讲课。它提供创建、校验、报告、benchmark 的工具入口。 +`tools/audit-harness.sh` 则从 shell 层给出五子系统审计。 + +这说明成熟研究对象应该至少有一条“从文章到工具”的路径。对本仓来说，Harness 研究成熟后应沉淀到： + +- `docs/research/harness/`：概念、机制、对标与判断。 +- `docs/workflow/`：日常执行流程和质量门禁。 +- `scripts/`：可自动检查的规则。 +- `skills/`：可复用的 Agent 操作能力。 + +## 可迁移模式 + +- 用五子系统表审计所有 Agent 协作入口。 +- 用 fresh session test 检查新会话能否从仓库恢复上下文。 +- 用 `feature_list.json` 的思想重构任务包和研究域进度，而不是复制固定文件名。 +- 用 `init.sh` 的思想保持“一条命令得到基线状态”，本仓对应 `make test`。 +- 用 `evaluator-rubric.md` 的思想要求重要产出必须有正确性、验证、范围、可靠性、维护性和交接评分。 +- 用 `audit-harness.sh` 的思想把可重复的 review feedback 晋升为自动门禁。 + +## 对本仓的影响 + +本仓当前强项是中文知识库、研究域治理、索引、质量门禁和 AI 引用入口；该仓强项是把 Harness +讲成课程、练习、模板、Skill 和脚本。 + +两者结合后的方向应该是： + +- `docs/research/harness/` 继续承载 Harness Engineering 概念与外部论文/文章对齐。 +- `docs/research/walkinglabs-learn-harness-engineering/` 承载该课程仓库的一手研究。 +- `docs/workflow/` 承载本仓实际如何使用 Harness 控制 AI 协作。 +- `scripts/` 或 `skills/` 只在检查逻辑稳定后再接管自动化。 + +关键取舍是：吸收控制面和验证闭环，不复制其课程站点和多语言工程复杂度。 + +## 风险和待验证项 + +- 本轮没有运行外部仓库的 VitePress 构建、PDF 构建、Skill 脚本和审计脚本。 +- 该仓库 star、fork、updated、topics 属动态事实，引用前必须重新核验。 +- 其模板默认面向代码项目，本仓是 Markdown 知识库，迁移时必须改成文档治理和研究域治理语言。 +- `skills/harness-creator` 作为外部 Skill 引入前需要单独做安全、依赖、许可证和维护成本评估。 + +## 下一步 L3 验证任务 + +- 在 `docs/research/harness/` 新增一份“最小 Harness 检查表”，用五子系统审计本仓。 +- 为一个真实研究域试写 `id / behavior / verification / status / evidence` 状态表。 +- 把一次重复出现的文档审查问题转成可执行脚本或 `make` 门禁。 +- 抽样运行 `raw/repository/tools/audit-harness.sh` 对本仓评分，并记录哪些检查项需要为 Markdown 知识库改写。 diff --git a/docs/research/walkinglabs-learn-harness-engineering/domain.yml b/docs/research/walkinglabs-learn-harness-engineering/domain.yml new file mode 100644 index 0000000..47e6c8c --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/domain.yml @@ -0,0 +1,41 @@ +version: 1 +repo: + name: walkinglabs/learn-harness-engineering + source_name: walkinglabs/learn-harness-engineering + url: https://github.com/walkinglabs/learn-harness-engineering +research: + domain_id: walkinglabs-learn-harness-engineering + domain_name: walkinglabs/learn-harness-engineering 研究域 + primary_direction: harness-engineering + role: Harness Engineering 课程、模板、Skill 与审计工具对标对象 + priority: 2 + why_study: 直接补强本仓 Harness 研究线，适合提炼 Agent 可靠性控制面、状态治理和验证闭环。 +github_observed: + observed_at: '2026-07-04' + source: gh repo view + stars: 9793 + forks: 1059 + archived: false + language: TypeScript + license: MIT + default_branch: main + pushed_at: '2026-06-30T01:33:03Z' + updated_at: '2026-07-03T22:42:37Z' + latest_release: null + homepage: https://walkinglabs.github.io/learn-harness-engineering/ + topics: + - agent + - harness + - harness-engineering + - harness-framework + - llm + - ai + - ai-agent + - agentic + - agentic-ai +source_evidence: + file: user-provided GitHub URL + line: null +maintenance: + fact_policy: GitHub 动态字段只代表 observed_at 当日快照，更新结论前必须重新核验。 + split_policy: 本目录已经是一等研究域；更深分析放入本目录新增文档。 diff --git a/docs/research/walkinglabs-learn-harness-engineering/raw/AGENTS.md b/docs/research/walkinglabs-learn-harness-engineering/raw/AGENTS.md new file mode 100644 index 0000000..fa93fd8 --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/raw/AGENTS.md @@ -0,0 +1,12 @@ +# raw/ Agent 指南 + +本目录是 `walkinglabs/learn-harness-engineering` 的原始事实层。 + +## 维护规则 + +- 只保存从研究对象拉取的一手材料，不写分析判断。 +- `repository/` 是本地 Git 工作树，刷新时由脚本 clone 或 fast-forward pull。 +- 不手工改写 `*.raw.*` 文件内容；需要刷新时运行 `python3 scripts/fetch-research-raw.py`。 +- `sources.yml` 必须记录拉取时间、来源命令和每个文件的状态。 +- 外部 README 原文必须保存为 `.txt`，避免本仓库 Markdown 链接检查误判。 +- 分析、判断、采用建议和沉淀路径写回上一级 `README.md`、`analysis.md` 或 `decisions.md`。 diff --git a/docs/research/walkinglabs-learn-harness-engineering/raw/README.md b/docs/research/walkinglabs-learn-harness-engineering/raw/README.md new file mode 100644 index 0000000..0eba396 --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/raw/README.md @@ -0,0 +1,16 @@ +# raw 事实层 + +本目录保存 `walkinglabs/learn-harness-engineering` 的本地原始材料快照。 + +这里不写分析结论，只保存可复查的一手资料： + +- `sources.yml`：来源清单、拉取时间、命令和文件状态。 +- `repository/`：Git 仓库工作树；本目录由 `.gitignore` 忽略，只作为本地研究材料。 +- `github-repo.raw.json`：GitHub 仓库元数据。 +- `github-readme.raw.md.txt`：GitHub README 原文快照。 +- `github-license.raw.txt`：GitHub license 原文快照；仓库无 license 时可能不存在。 +- `github-root-contents.raw.json`：默认分支根目录内容快照。 +- `github-languages.raw.json`：GitHub language 统计快照。 +- `github-latest-release.raw.json`：最新 release 快照；无 release 时可能不存在。 + +`repository/` 是外部源码快照，不参与本仓库 Markdown、链接、README/AGENTS 覆盖检查。原始 README 使用 `.txt` 后缀保存，避免其中的外部相对链接被本仓库 Markdown 链接检查误判。 diff --git a/docs/research/walkinglabs-learn-harness-engineering/raw/github-languages.raw.json b/docs/research/walkinglabs-learn-harness-engineering/raw/github-languages.raw.json new file mode 100644 index 0000000..2739ac0 --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/raw/github-languages.raw.json @@ -0,0 +1,7 @@ +{ + "TypeScript": 680843, + "Shell": 67054, + "JavaScript": 39301, + "HTML": 9660, + "Python": 6357 +} diff --git a/docs/research/walkinglabs-learn-harness-engineering/raw/github-license.raw.txt b/docs/research/walkinglabs-learn-harness-engineering/raw/github-license.raw.txt new file mode 100644 index 0000000..828bd85 --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/raw/github-license.raw.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 WalkingLab + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs/research/walkinglabs-learn-harness-engineering/raw/github-readme.raw.md.txt b/docs/research/walkinglabs-learn-harness-engineering/raw/github-readme.raw.md.txt new file mode 100644 index 0000000..0c94b9d --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/raw/github-readme.raw.md.txt @@ -0,0 +1,612 @@ +

+ English + 简体中文 + 繁體中文 + 日本語 + 한국어 + Español + Français + Русский + Deutsch + العربية + Tiếng Việt + Oʻzbekcha + Türkçe + Português-BR + Українська +

+ +

Learn Harness Engineering

+ +

A project-based course on building the environment, state management, verification, and control mechanisms that make AI coding agents work reliably.

+ +

+ 12 Lectures + 6 Projects + 15 Languages + MIT License + Join the Discord community +

+ +> 🌍 This course is available in **15 languages**: English, 简体中文, 繁體中文, 日本語, 한국어, Español, Français, Русский, Deutsch, العربية, Tiếng Việt, Oʻzbekcha, Türkçe, Portuguese (BR), Українська. Choose your language from the badges above. + +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: + +- [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) + +> **Quick start?** The [`skills/harness-creator/`](./skills/harness-creator/) skill can help you scaffold a production-grade harness (AGENTS.md, feature lists, init.sh, verification workflows) for your own project in minutes. + +--- + +## Table of Contents + +- [✨ Visual Preview](#-visual-preview) +- [What Harness Engineering Actually Means](#what-harness-engineering-actually-means) +- [Quick Start: Improve Your Agent Today](#quick-start-improve-your-agent-today) +- [Capstone Project: A Real App](#capstone-project-a-real-app) +- [Learning Path](#learning-path) +- [Syllabus](#syllabus) +- [Skills](#skills) +- [Other Courses](#other-courses) + +--- + +## ✨ Visual Preview + +### 🏠 Course Homepage +> A comprehensive course outline and introduction to core philosophies, providing a clear path to get started. + +![Course homepage preview](./docs/public/screenshots/readme/en-home.png) + +### 📖 Immersive Lectures +> Deep dives into real-world pain points and hands-on projects (like Project 01) for an immersive learning experience. + +![Course lecture preview](./docs/public/screenshots/readme/en-lecture-01.png) + +### 🗂️ Ready-to-Use Resource Library +> Templates and reference configurations designed to solve common pitfalls in multi-turn AI agent development, such as context loss and premature task completion. + +![Resource library preview](./docs/public/screenshots/readme/en-resources.png) + +## PDF Coursebooks + +The repository now includes a PDF build pipeline for the course content. + +- Run `npm run pdf:build` to generate the currently configured PDF coursebooks locally. +- Output files are written to `artifacts/pdfs/`. +- Run `npm run screenshots:readme` if you want to refresh the README preview images. +- GitHub Actions workflow [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml) can build the PDFs and publish them to GitHub Releases. + +--- + +## The Model Is Smart, The Harness Makes It Reliable + +There's a hard truth most people learn the hard way: **the strongest model in the world will still fail on real engineering tasks if you don't build a proper environment around it.** + +You've probably seen this yourself. You give Claude or GPT a task in your repo. It starts well — reads files, writes code, looks productive. Then something goes wrong. It skips a step. It breaks a test. It says "done" but nothing actually works. You spend more time cleaning up than if you'd done it yourself. + +This isn't a model problem. It's a harness problem. + +The evidence is clear. Anthropic ran a controlled experiment: same model (Opus 4.5), same prompt ("build a 2D retro game editor"). Without a harness, it spent $9 in 20 minutes and produced something that didn't work. With a full harness (planner + generator + evaluator), it spent $200 in 6 hours and built a game you could actually play. The model didn't change. The harness did. + +OpenAI reported the same thing with Codex: in a well-harnessed repository, the same model goes from "unreliable" to "reliable." Not a marginal improvement — a qualitative shift. + +**This course teaches you how to build that environment.** + +```text + THE HARNESS PATTERN + ==================== + + You --> give task --> Agent reads harness files --> Agent executes + | + harness governs every step: + | + +--> Instructions: what to do, in what order + +--> Scope: one feature at a time, no overreach + +--> State: progress log, feature list, git history + +--> Verification: tests, lint, type-check, smoke runs + +--> Lifecycle: init at start, clean state at end + | + v + Agent stops only when + verification passes +``` + +--- + +## What Harness Engineering Actually Means + +Harness engineering is about building a complete working environment around the model so it produces reliable results. It's not about writing better prompts. It's about designing the system the model operates inside. + +A harness has five subsystems: + +```text + ┌────────────────────────────────────────────────────────────────┐ + │ THE HARNESS │ + │ │ + │ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │ + │ │ Instructions │ │ State │ │ Verification │ │ + │ │ │ │ │ │ │ │ + │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │ + │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │ + │ │ feature_list │ │ git log │ │ smoke runs │ │ + │ │ docs/ │ │ session hand │ │ e2e pipeline │ │ + │ └──────────────┘ └──────────────┘ └────────────────────┘ │ + │ │ + │ ┌──────────────┐ ┌──────────────────────────────────────┐ │ + │ │ Scope │ │ Session Lifecycle │ │ + │ │ │ │ │ │ + │ │ one feature │ │ init.sh at start │ │ + │ │ at a time │ │ clean-state checklist at end │ │ + │ │ definition │ │ handoff note for next session │ │ + │ │ of done │ │ commit only when safe to resume │ │ + │ └──────────────┘ └──────────────────────────────────────┘ │ + │ │ + └────────────────────────────────────────────────────────────────┘ + + The MODEL decides what code to write. + The HARNESS governs when, where, and how it writes it. + The harness doesn't make the model smarter. + It makes the model's output reliable. +``` + +Each subsystem has one job: + +- **Instructions** — Tell the agent what to do, in what order, and what to read before starting. Not one giant file; a progressive disclosure structure the agent navigates on demand. +- **State** — Track what's been done, what's in progress, and what's next. Persisted to disk so the next session picks up exactly where the last one left off. +- **Verification** — Only a passing test suite counts as evidence. The agent cannot declare victory without runnable proof. +- **Scope** — Constrain the agent to one feature at a time. No overreach. No half-finishing three things. No rewriting the feature list to hide unfinished work. +- **Session Lifecycle** — Initialize at the start. Clean up at the end. Leave a clean restart path for the next session. + +--- + +## Why This Course Exists + +The question isn't "can models write code?" They can. The question is: **can they reliably complete real engineering tasks inside real repositories, over multiple sessions, without constant human supervision?** + +Right now, the answer is: not without a harness. + +```text + 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 +``` + +The questions this course actually cares about: + +- 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? + +--- + +## 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. + +The idea is simple: instead of just writing prompts, give your agent a set of structured files that define what to do, what's been done, and how to verify the work. These files live inside your repo, so every session starts from the same state. + +```text + 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 <-- what happened each session + └── src/ <-- your actual code +``` + +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. + +--- + +## Capstone Project: A Real App + +All six course projects revolve around the same product: **an Electron-based personal knowledge base desktop app**. + +```text + ┌──────────────────────────────────────────────────────┐ + │ 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 +``` + +This project was chosen because it combines strong practical value, enough real-world product complexity, and a good setting for observing before/after harness improvements. + +Each course project's starter/solution is a complete copy of this Electron app at that evolutionary stage. P(N+1)'s starter is derived from P(N)'s solution — the app evolves as your harness skills grow. + +--- + +## Learning Path + +The course is designed to be done in order. Each phase builds on the last. + +```text + Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO + ======================== ========================== + + L01 Strong models ≠ reliable L03 Repository as single + execution source of truth + L02 What harness actually means + L04 Split instructions across + | files, not one giant file + v + P01 Prompt-only vs. | + rules-first comparison v + P02 Agent-readable workspace + + + Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE + ========================== ========================= + + L05 Keep context alive L07 Draw clear task boundaries + across sessions + L08 Feature lists as harness + L06 Initialize before every primitives + agent session + | + | v + v P04 Runtime feedback to + P03 Multi-session continuity correct agent behavior + + + Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER + ===================== ============================ + + L09 Stop agents from L11 Make agent's runtime + declaring victory early observable + + L10 Full-pipeline run = L12 Clean handoff at end of + real verification every session + + | | + v v + P05 Agent verifies its own work P06 Build a complete harness + (capstone project) +``` + +Each phase takes about a week if you're going part-time. If you want to go faster, phases 1–3 can be done in a long weekend. + +--- + +## Syllabus + +### 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/en/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 | +| [L02](./docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | What does "harness" actually mean? | Five subsystems: instructions, state, verification, scope, lifecycle | +| [L03](./docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Why must the repo be the single source of truth? | If the agent can't see it, it doesn't exist | +| [L04](./docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Why does one giant instruction file fail? | Progressive disclosure: give a map, not an encyclopedia | +| [L05](./docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Why do long-running tasks lose continuity? | Persist progress to disk; pick up where you left off | +| [L06](./docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Why does initialization need its own phase? | Verify the environment is healthy before the agent starts work | +| [L07](./docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Why do agents overreach and under-finish? | One feature at a time; explicit definition of done | +| [L08](./docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Why are feature lists harness primitives? | Machine-readable scope boundaries the agent can't ignore | +| [L09](./docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Why do agents declare victory too early? | Verification gaps: confidence ≠ correctness | +| [L10](./docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Why does end-to-end testing change results? | Only a full-pipeline run counts as real verification | +| [L11](./docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Why does observability belong inside the harness? | If you can't see what the agent did, you can't fix what it broke | +| [L12](./docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Why must every session leave a clean state? | The next session's success depends on this session's cleanup | + +### Projects — 6 hands-on projects applying lecture methods to the same Electron app + +| Project | What You Do | Harness Mechanism | +|---------|------------|-------------------| +| [P01](./docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | Run the same task twice: prompt-only vs. rules-first | Minimal harness: AGENTS.md + init.sh + feature_list.json | +| [P02](./docs/en/projects/project-02-agent-readable-workspace/index.md) | Restructure the repo so the agent can read it | Agent-readable workspace + persistent state files | +| [P03](./docs/en/projects/project-03-multi-session-continuity/index.md) | Make the agent pick up from where it left off | Progress log + session handoff + multi-session continuity | +| [P04](./docs/en/projects/project-04-incremental-indexing/index.md) | Stop the agent from doing too much or too little | Runtime feedback + scope control + incremental indexing | +| [P05](./docs/en/projects/project-05-grounded-qa-verification/index.md) | Make the agent verify its own work | Self-verification + grounded Q&A + evidence-based completion | +| [P06](./docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Build a complete harness from scratch (capstone) | Full harness: all mechanisms + observability + ablation study | + +```text + 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 + + Each project's solution becomes the next project's starter. + The app evolves. Your harness skills grow with it. +``` + +### Resource Library + +- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references +- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考 +- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考 +- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス +- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료 +- [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias +- [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références +- [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники +- [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen +- [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع +- [Tiếng Việt](https://walkinglabs.github.io/learn-harness-engineering/vi/resources/) — mẫu, danh sách kiểm tra và tài liệu tham khảo +- [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar +- [Türkçe](https://walkinglabs.github.io/learn-harness-engineering/tr/resources/) — şablonlar, kontrol listeleri ve referanslar +- [Português (BR)](https://walkinglabs.github.io/learn-harness-engineering/pt-BR/resources/) — modelos, listas de verificação e referências de métodos + +--- + +## The Agent Session Lifecycle + +One of the core ideas in this course: **the agent's session should follow a structured lifecycle, not a free-for-all.** Here's what that looks like: + +```text + AGENT SESSION LIFECYCLE + ====================== + + ┌──────────────────────────────────────────────────────────────────┐ + │ START │ + │ │ + │ 1. Agent reads AGENTS.md / CLAUDE.md │ + │ 2. Agent runs init.sh (install, verify, health check) │ + │ 3. Agent reads claude-progress.md (what happened last time) │ + │ 4. Agent reads feature_list.json (what's done, what's next) │ + │ 5. Agent checks git log (recent changes) │ + │ │ + │ SELECT │ + │ │ + │ 6. Agent picks exactly ONE unfinished feature │ + │ 7. Agent works only on that feature │ + │ │ + │ EXECUTE │ + │ │ + │ 8. Agent implements the feature │ + │ 9. Agent runs verification (tests, lint, type-check) │ + │ 10. If verification fails: fix and re-run │ + │ 11. If verification passes: record evidence │ + │ │ + │ WRAP UP │ + │ │ + │ 12. Agent updates claude-progress.md │ + │ 13. Agent updates feature_list.json │ + │ 14. Agent records what's still broken or unverified │ + │ 15. Agent commits (only when safe to resume) │ + │ 16. Agent leaves clean restart path for next session │ + │ │ + └──────────────────────────────────────────────────────────────────┘ + + The harness governs every transition in this lifecycle. + The model decides what code to write at each step. + Without the harness, step 9 becomes "agent says it looks fine." + With the harness, step 9 is "tests pass, lint is clean, types check." +``` + +--- + +## Who This Is For + +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 +- People who only care about prompts and don't plan to build real implementations +- Learners not prepared to let agents work inside real repositories + +--- + +## Requirements + +This is a course where you actually run coding agents. + +You need at least one of these tools: + +- Claude Code +- Codex +- Another IDE or CLI coding agent that supports file editing, command execution, and multi-step tasks + +The course assumes you can: + +- Open a local repository +- Allow the agent to edit files +- Allow the agent to run commands +- Inspect output and re-run tasks + +If you don't have such a tool, you can still read the course content, but you won't be able to complete the projects as intended. + +--- + +## Local Preview + +This repository uses VitePress as a documentation viewer. + +```sh +npm install +npm run docs:dev # Dev server with hot reload +npm run docs:build # Production build +npm run docs:preview # Preview built site +``` + +Then open the local URL that VitePress outputs in your browser. + +--- + +## Prerequisites + +Required: + +- Familiarity with the terminal, git, and local development environments +- Ability to read and write code in at least one common application stack +- Basic software debugging experience (reading logs, tests, and runtime behavior) +- Enough time to commit to implementation-focused coursework + +Helpful but not required: + +- Experience with Electron, desktop apps, or local-first tools +- Background in testing, logging, or software architecture +- Prior exposure to Codex, Claude Code, or similar coding agents + +--- + +## Core References + +Primary: + +- [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) +- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/) +- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) +- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering) +- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html) +- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness) + +See the full layered reference list in [`docs/en/resources/reference/`](./docs/en/resources/reference/index.md). + +--- + +## Repository Structure + +```text +learn-harness-engineering/ +├── docs/ # VitePress documentation site +│ ├── lectures/ # 12 lectures (index.md + code/ examples) +│ │ ├── lecture-01-*/ +│ │ └── ... (12 total) +│ ├── projects/ # 6 project descriptions +│ │ ├── project-01-*/ +│ │ └── ... (6 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 +``` + +--- + +## How the Course Is Organized + +- Each lecture focuses on one question +- The course includes 6 projects +- Every project requires the agent to do real work +- Every project compares weak vs. strong harness results +- What matters is the measured difference, not how many docs were written + +--- + +## Skills + +This repository also includes reusable AI agent skills that you can install directly into your IDE or agent workspace. + +- [**harness-creator**](./skills/harness-creator/): A skill that helps you scaffold a production-grade harness for your own project in minutes. + +## Tools + +Zero-dependency utilities you can run without installing Node.js. + +- [**audit-harness.sh**](./tools/audit-harness.sh): A shell-based audit script that checks an existing repo against all five harness subsystems (L03–L12). Exits 0 when all CRITICAL items pass. No Node.js required — complements `harness-creator`'s `validate-harness.mjs`. + +```bash +# 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 +``` + +--- + +## Other Courses + +Our team has also created other courses! Check them out: + +[![Hands-on Modern RL](https://img.shields.io/badge/HANDS--ON_MODERN_RL-0052cc?style=for-the-badge)](https://github.com/walkinglabs/hands-on-modern-rl) + +**Hands-on Modern RL**: An open-source, hands-on curriculum bridging the gap from basic RL concepts to LLM alignment, RLVR, and advanced Agentic systems. + +[![Modern LLM Notebook](https://img.shields.io/badge/MODERN_LLM_NOTEBOOK-0052cc?style=for-the-badge)](https://github.com/walkinglabs/modern-llm-notebook) + +**Modern LLM Notebook**: A hands-on course for building modern LLMs from scratch in PyTorch, with 23 runnable Jupyter Notebooks covering tokenizers, attention, MoE, RLHF, inference, evaluation, and distillation. + +--- + +## Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=walkinglabs/learn-harness-engineering&type=date&legend=top-left)](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left) + +--- + +## 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 an agent from scratch, from a single loop to isolated autonomous execution. diff --git a/docs/research/walkinglabs-learn-harness-engineering/raw/github-repo.raw.json b/docs/research/walkinglabs-learn-harness-engineering/raw/github-repo.raw.json new file mode 100644 index 0000000..291714d --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/raw/github-repo.raw.json @@ -0,0 +1,58 @@ +{ + "createdAt": "2026-03-29T12:28:19Z", + "defaultBranchRef": { + "name": "main" + }, + "description": "Harness engineering beginner tutorial, from 0 to 1", + "forkCount": 1059, + "homepageUrl": "https://walkinglabs.github.io/learn-harness-engineering/", + "isArchived": false, + "isFork": false, + "isMirror": false, + "latestRelease": null, + "licenseInfo": { + "key": "mit", + "name": "MIT License", + "nickname": "" + }, + "nameWithOwner": "walkinglabs/learn-harness-engineering", + "primaryLanguage": { + "name": "TypeScript" + }, + "pushedAt": "2026-06-30T01:33:03Z", + "repositoryTopics": [ + { + "name": "agent" + }, + { + "name": "harness" + }, + { + "name": "harness-engineering" + }, + { + "name": "harness-framework" + }, + { + "name": "llm" + }, + { + "name": "ai" + }, + { + "name": "ai-agent" + }, + { + "name": "agentic" + }, + { + "name": "agentic-ai" + } + ], + "stargazerCount": 9793, + "updatedAt": "2026-07-03T22:42:37Z", + "url": "https://github.com/walkinglabs/learn-harness-engineering", + "watchers": { + "totalCount": 43 + } +} diff --git a/docs/research/walkinglabs-learn-harness-engineering/raw/github-root-contents.raw.json b/docs/research/walkinglabs-learn-harness-engineering/raw/github-root-contents.raw.json new file mode 100644 index 0000000..60dc788 --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/raw/github-root-contents.raw.json @@ -0,0 +1,226 @@ +[ + { + "name": ".github", + "path": ".github", + "sha": "f94c46c41587f309ef09ad91509152476bc5f730", + "size": 0, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/.github?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/.github", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/f94c46c41587f309ef09ad91509152476bc5f730", + "download_url": null, + "type": "dir", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/.github?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/f94c46c41587f309ef09ad91509152476bc5f730", + "html": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/.github" + } + }, + { + "name": ".gitignore", + "path": ".gitignore", + "sha": "d86c77a7235307d1943b1d5f87124c692de53d8d", + "size": 341, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/.gitignore?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/.gitignore", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/d86c77a7235307d1943b1d5f87124c692de53d8d", + "download_url": "https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/.gitignore", + "type": "file", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/.gitignore?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/d86c77a7235307d1943b1d5f87124c692de53d8d", + "html": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/.gitignore" + } + }, + { + "name": "CLAUDE.md", + "path": "CLAUDE.md", + "sha": "4ca05c29c3ffd194245deeda918c7be4b0c4b134", + "size": 3083, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/CLAUDE.md?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/CLAUDE.md", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/4ca05c29c3ffd194245deeda918c7be4b0c4b134", + "download_url": "https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/CLAUDE.md", + "type": "file", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/CLAUDE.md?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/4ca05c29c3ffd194245deeda918c7be4b0c4b134", + "html": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/CLAUDE.md" + } + }, + { + "name": "LICENSE", + "path": "LICENSE", + "sha": "828bd8559abead81e06920d2424d92f76d158f99", + "size": 1067, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/LICENSE?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/LICENSE", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/828bd8559abead81e06920d2424d92f76d158f99", + "download_url": "https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/LICENSE", + "type": "file", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/LICENSE?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/828bd8559abead81e06920d2424d92f76d158f99", + "html": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/LICENSE" + } + }, + { + "name": "README.md", + "path": "README.md", + "sha": "0c94b9d5b46fa41c1897f1444f3b2ec33d059f67", + "size": 36562, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/README.md?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/README.md", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/0c94b9d5b46fa41c1897f1444f3b2ec33d059f67", + "download_url": "https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/README.md", + "type": "file", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/README.md?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/0c94b9d5b46fa41c1897f1444f3b2ec33d059f67", + "html": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/README.md" + } + }, + { + "name": "docs-readme", + "path": "docs-readme", + "sha": "2c8d05dae051d6a228195fd365ef5a398c19a0b1", + "size": 0, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/docs-readme?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/docs-readme", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/2c8d05dae051d6a228195fd365ef5a398c19a0b1", + "download_url": null, + "type": "dir", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/docs-readme?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/2c8d05dae051d6a228195fd365ef5a398c19a0b1", + "html": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/docs-readme" + } + }, + { + "name": "docs", + "path": "docs", + "sha": "524e15258f6031fe450d0261088fab18df86de54", + "size": 0, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/docs?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/docs", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/524e15258f6031fe450d0261088fab18df86de54", + "download_url": null, + "type": "dir", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/docs?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/524e15258f6031fe450d0261088fab18df86de54", + "html": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/docs" + } + }, + { + "name": "get_anthropic_logo.js", + "path": "get_anthropic_logo.js", + "sha": "9f371b182c51b460a6fdcae211a64a16242d3746", + "size": 246, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/get_anthropic_logo.js?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/get_anthropic_logo.js", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/9f371b182c51b460a6fdcae211a64a16242d3746", + "download_url": "https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/get_anthropic_logo.js", + "type": "file", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/get_anthropic_logo.js?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/9f371b182c51b460a6fdcae211a64a16242d3746", + "html": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/get_anthropic_logo.js" + } + }, + { + "name": "package-lock.json", + "path": "package-lock.json", + "sha": "b59ae3f38e283c6f4acc4ebf465d3feafcc122da", + "size": 163209, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/package-lock.json?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/package-lock.json", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/b59ae3f38e283c6f4acc4ebf465d3feafcc122da", + "download_url": "https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/package-lock.json", + "type": "file", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/package-lock.json?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/b59ae3f38e283c6f4acc4ebf465d3feafcc122da", + "html": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/package-lock.json" + } + }, + { + "name": "package.json", + "path": "package.json", + "sha": "5891609f7c69e036e782f746b9b72167ca616342", + "size": 968, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/package.json?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/package.json", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/5891609f7c69e036e782f746b9b72167ca616342", + "download_url": "https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/package.json", + "type": "file", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/package.json?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/blobs/5891609f7c69e036e782f746b9b72167ca616342", + "html": "https://github.com/walkinglabs/learn-harness-engineering/blob/main/package.json" + } + }, + { + "name": "projects", + "path": "projects", + "sha": "9270d7cb774a4e05909508166c58638622efe7de", + "size": 0, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/projects?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/9270d7cb774a4e05909508166c58638622efe7de", + "download_url": null, + "type": "dir", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/projects?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/9270d7cb774a4e05909508166c58638622efe7de", + "html": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects" + } + }, + { + "name": "scripts", + "path": "scripts", + "sha": "00603fc11b318853b52a56e71d327e35a4ef67b5", + "size": 0, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/scripts?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/scripts", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/00603fc11b318853b52a56e71d327e35a4ef67b5", + "download_url": null, + "type": "dir", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/scripts?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/00603fc11b318853b52a56e71d327e35a4ef67b5", + "html": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/scripts" + } + }, + { + "name": "skills", + "path": "skills", + "sha": "1aab46198af95628b525ce92670739d94de1376f", + "size": 0, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/skills?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/1aab46198af95628b525ce92670739d94de1376f", + "download_url": null, + "type": "dir", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/skills?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/1aab46198af95628b525ce92670739d94de1376f", + "html": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills" + } + }, + { + "name": "tools", + "path": "tools", + "sha": "f5c6fed4eddb143c0980f277360fdf13c364df64", + "size": 0, + "url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/tools?ref=main", + "html_url": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/tools", + "git_url": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/f5c6fed4eddb143c0980f277360fdf13c364df64", + "download_url": null, + "type": "dir", + "_links": { + "self": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/contents/tools?ref=main", + "git": "https://api.github.com/repos/walkinglabs/learn-harness-engineering/git/trees/f5c6fed4eddb143c0980f277360fdf13c364df64", + "html": "https://github.com/walkinglabs/learn-harness-engineering/tree/main/tools" + } + } +] diff --git a/docs/research/walkinglabs-learn-harness-engineering/raw/sources.yml b/docs/research/walkinglabs-learn-harness-engineering/raw/sources.yml new file mode 100644 index 0000000..983d2de --- /dev/null +++ b/docs/research/walkinglabs-learn-harness-engineering/raw/sources.yml @@ -0,0 +1,39 @@ +version: 1 +domain_id: walkinglabs-learn-harness-engineering +object: + type: github_repository + name: walkinglabs/learn-harness-engineering + url: https://github.com/walkinglabs/learn-harness-engineering +pulled_at: '2026-07-03T22:52:11+00:00' +puller: scripts/fetch-research-raw.py +files: + - path: repository/ + kind: git-working-tree + status: ok + source: 'git -C docs/research/walkinglabs-learn-harness-engineering/raw/repository pull --ff-only' + message: 'Already up to date.' + - path: github-repo.raw.json + kind: repository-metadata + status: ok + source: 'gh repo view walkinglabs/learn-harness-engineering --json nameWithOwner,url,description,homepageUrl,isArchived,isFork,isMirror,defaultBranchRef,licenseInfo,primaryLanguage,repositoryTopics,stargazerCount,forkCount,watchers,createdAt,updatedAt,pushedAt,latestRelease --jq .' + - path: github-readme.raw.md.txt + kind: readme + status: ok + source: 'gh api repos/walkinglabs/learn-harness-engineering/readme -H Accept: application/vnd.github.raw' + - path: github-license.raw.txt + kind: license + status: ok + source: 'gh api repos/walkinglabs/learn-harness-engineering/license -H Accept: application/vnd.github.raw' + - path: github-root-contents.raw.json + kind: root-contents + status: ok + source: 'gh api repos/walkinglabs/learn-harness-engineering/contents' + - path: github-languages.raw.json + kind: languages + status: ok + source: 'gh api repos/walkinglabs/learn-harness-engineering/languages' + - path: github-latest-release.raw.json + kind: latest-release + status: missing_or_error + source: 'gh api repos/walkinglabs/learn-harness-engineering/releases/latest' + message: 'gh: Not Found (HTTP 404)' diff --git a/llms.txt b/llms.txt index a18bb48..9a1ae07 100644 --- a/llms.txt +++ b/llms.txt @@ -55,6 +55,7 @@ vibe-coding-cn 是一个中文 Vibe Coding / AI 结对编程系统教程，帮 - docs/research/research-value-application-map.md - docs/research/research-transfer-synthesis.md - docs/research/harness/harness-engineering.md +- docs/research/walkinglabs-learn-harness-engineering/README.md - docs/research/openai-codex/README.md - docs/research/shanraisshan-claude-code-best-practice/README.md - docs/research/cline-cline/README.md diff --git a/metadata/taxonomy.yml b/metadata/taxonomy.yml index 107383a..ebff0fa 100644 --- a/metadata/taxonomy.yml +++ b/metadata/taxonomy.yml @@ -181,6 +181,15 @@ documents: - path: docs/research/harness/harness-engineering.md title: Harness 工程解析 role: 工程控制、评估器、反馈闭环与 AI 生成系统可靠性 + - path: docs/research/walkinglabs-learn-harness-engineering/README.md + title: walkinglabs/learn-harness-engineering 研究域 + role: Harness Engineering 课程、模板、Skill 与审计工具对标对象 + - path: docs/research/walkinglabs-learn-harness-engineering/analysis.md + title: walkinglabs/learn-harness-engineering 研究分析 + role: 结构化研究结论、可迁移做法、风险和验证动作 + - path: docs/research/walkinglabs-learn-harness-engineering/deep-dive.md + title: walkinglabs/learn-harness-engineering 深度研究 + role: L2 结构深度研究、关键机制和本仓应用建议 - path: docs/research/aider-ai-aider/README.md title: Aider-AI/aider 研究域 role: 终端 AI 结对编程工具