【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本讲核心AI agent 的输入只有系统提示与任务描述、仓库文件内容、工具执行输出三样东西。Slack 历史、Jira 工单、Confluence 页面、甚至工程师脑中的架构决策对 agent 而言一律不存在。因此把关键决策信息写进仓库、让仓库成为唯一的 System of Record事实来源是最基础也最被低估的 harness 投资。读完本文你将掌握「知识可见性缺口」「全新会话测试」「发现成本」「ACID 状态管理」四大方法论并学会用仓库自带的评分脚本量化自己仓库的 agent 可读性。为什么 agent 的世界只有仓库你团队的架构决策散落在 Confluence、Slack、Jira 和几位资深工程师的脑子里。对人类来说这勉强够用可以问同事、搜聊天记录、翻文档实在不行还能去茶水间堵人。但对 AI agent 来说不在仓库里的信息等于不存在。这不是夸张。Agent 的输入只有三样东西系统提示和任务描述仓库里的文件内容工具执行的输出。你的 Slack 历史、Jira 工单、Confluence 页面、周五下午跟同事讨论的架构决定agent 全都看不到。它不能去问一下也不能搜一下聊天记录。它的整个工作世界就是仓库本身——它是一位被关在仓库里的工程师仓库外面的事它一概不知。所以问题变成了你给不给它一张足够好的地图OpenAI 在其 harness engineering 文章中把这个问题说得非常直白仓库里不存在的信息对 agent 来说等于不存在即仓库即规范repo as spec原则——仓库本身就是最高权威的规范文档。Anthropic 的 long-running agents 文档也强调持久化状态是长任务连续性的必要条件跨会话的知识可恢复性直接决定任务成功率而这些状态必须存在于仓库中因为那是 agent 唯一稳定可访问的存储。也许你会想我们团队人少知识都在大家脑子里不也工作得好好的吗对对人类来说确实可以。但只要你开始使用 agent就必须接受一个事实agent 不能问人。所有它需要知道的东西都必须写下来、放在它能找到的地方。需要澄清的是这不是写更多文档的问题而是把决策信息放到正确的位置的问题。一份放在src/api/目录下、只有 50 行的ARCHITECTURE.md比一份放在 Confluence 里、有 500 页却没人维护的设计文档有用得多。就近放置的价值远大于篇幅长短——就像一张手绘的办公室地图贴在办公桌上远比锁在文件柜里的漂亮建筑蓝图实用前者在你需要时就在手边后者可能技术水准更高但在关键时刻毫无用处。知识可见性规则怎么流进仓库本讲用一张流程图说明知识迁移的路径无论规则散落在 Slack、Confluence、工程师脑子里还是 Jira 工单最终都必须写进仓库文件AGENTS.md/ARCHITECTURE.md/PROGRESS.md让新的 agent 会话直接读仓库即可获取全部规则反之任何没有写进仓库的规则agent 就永远看不见。怎么检验你的地图画得够不够好做一个**全新会话测试Cold-Start Test**开一个全新的 agent 会话只让它看仓库内容看它能否回答五个基本问题如果它答不上来说明地图上有空白。空白的地方agent 就得自己猜猜错了就是 bug猜多了就浪费上下文。而且每个新会话都要重新猜一遍——猜的成本远高于一开始就把地图画好。五个核心概念知识可见性缺口Knowledge Visibility Gap项目总知识中不在仓库里的比例。缺口越大agent 失败的概率越高。估算方法把脑子里关于这个项目的隐性知识全算上再看有多少写进了仓库两者的差距就是可见性缺口。系统记录System of Record代码仓库作为项目决策、架构约束、执行状态和验证标准的权威信息源。仓库说了算别的地方说了不算。如果此路不通这个信息只存在于某个人的脑子里那每次都得去问写进仓库谁都不用问。全新会话测试Cold-Start Test上文说的五个问题。能回答几个你的地图就画了几分。发现成本Discovery Costagent 为了在仓库里找到一条关键信息需要消耗多少上下文预算。信息放得越隐蔽发现成本越高留给实际任务的预算就越少。把关键信息藏在十层目录深处的 README 里就像把灭火器锁进地下室的保险柜——它存在但你着火时找不到它。关键信息应放在 agent 最先看到的位置。知识衰减率Knowledge Decay Rate仓库中单位时间内变得过时的知识条目比例。文档和代码脱节是最大的敌人——过时的文档比没有文档更危险它会让 agent 走错方向还以为自己是对的。第六个是贯穿本讲的ACID 类比把数据库的事务管理原则原子性、一致性、隔离性、持久性应用到 agent 的状态管理上下文专门展开。怎么画好这张地图四条原则原则 1知识靠近代码。一条关于 API 端点认证的规则应该放在 API 代码旁边而不是藏在一个巨大的全局文档里。每个模块目录下放一个简短的文档说清楚该模块的职责、接口和特殊约束。模块目录本身就是天然的索引——agent 读到代码就能读到约束不用到处翻找。就像图书馆的架标想找历史书就直接走到写着 History 的书架前不必搜遍整座图书馆。原则 2用标准化的入口文件。AGENTS.md或CLAUDE.md是 agent 的着陆页。它不需要包含所有信息但必须能让 agent 快速回答三个问题这是什么项目、怎么跑、怎么验证。50–100 行就够了。原则 3最小但完备。每条知识都应该有明确的使用场景。如果删掉某条规则不影响 agent 的决策质量那这条规则就不应该存在但全新会话测试中的每个问题都必须有答案。这是一个需要持续调整的平衡不多不少刚好够用。原则 4和代码一起更新。把知识更新跟代码变更绑定在一起。最简单的方法把架构文档放在对应的模块目录里——改代码时自然会看到文档改完代码后再让 CI 提醒你检查文档是否需要更新。一个具体的仓库结构示例project/ ├── AGENTS.md # 入口项目概览、运行命令、硬约束 ├── src/ │ ├── api/ │ │ ├── ARCHITECTURE.md # API 层的架构决策 │ │ └── ... │ ├── db/ │ │ ├── CONSTRAINTS.md # 数据库操作的硬约束 │ │ └── ... │ └── ... ├── PROGRESS.md # 当前进度做了什么、在做什么、被什么阻塞 └── Makefile # 标准化的操作命令setup、test、lint、check仓库里的实战证据本仓库如何落地这套理论本仓库learn-harness-engineering本身就是这套理论的样板读者可以直接对照学习。1. 可执行的仓库可读性评分工具在 repo-reader.ts 中仓库提供了一个可直接运行的 TypeScript 脚本用来给任意目录打仓库可发现性分数。它内置了 8 项检查标准每项有对应的最大分值检查项检查内容最高分AGENTS.md / CLAUDE.md仓库根目录是否存在 agent 可读的指令文件15Documentation directory是否存在 docs/ 等专门的文档目录10Architecture documentation是否存在 architecture.md 等架构文档15Feature tracking是否存在 feature_list.json 等特性跟踪文件15Handoff / session continuity是否存在 HANDOFF.md / PROGRESS.md 等交接文件15Testing structure是否存在 test/ 等测试目录10Configuration files是否存在 package.json 等工程配置10README根目录是否存在 README10运行方式默认扫描当前目录也可传入目标路径npx tsx docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts [path]脚本会输出一张表格报告每项 PASS/FAIL 与得分并给出总分与等级90% 以上为 A仓库是强 System of Record、70% 以上为 B基础良好、有少量缺口、50% 以上为 C结构不完整、缺口明显、30% 以上为 D结构极少、agent 难以导航、低于 30% 为 F缺乏可发现性信号。值得注意的是它的检查项几乎与全新会话测试一一对应——这正说明冷启动能力是可以被工具化、量化验收的而不是一句抽象口号。2. 冷启动问题清单system-of-record-checklist.md 把五个问题扩充成了一份可直接使用的验收清单一个全新的 agent 能否仅从仓库中发现——正在构建什么产品应用应该为用户做什么代码库如何组织应用如何启动如何检查健康状态当前正在进行什么工作哪些质量标准很重要这份清单可以作为每次迭代后的自检项。3. 仓库布局样例repo-knowledge-layout.txt 给出了一份知识就近放置的目录样例根目录AGENTS.md入口、docs/下的ARCHITECTURE.md/PRODUCT.md/RELIABILITY.md、docs/references/如 electron.md、sqlite.md 等依赖专项文档、docs/plans/active/与docs/plans/completed/两个计划目录、以及src/与scripts/。可以看到架构、产品、可靠性等不同维度的知识被拆成独立文件而不是塞进一个巨型文档。4. 对应的实战项目本仓库的 Project 02: Agent-Readable Workspace 就是本讲的配套练习从starter/AGENTS.md 极简、没有交接文档、harness 很弱出发经过两个 agent 会话完成文档导入、详情视图、持久化三个功能再在solution/含完整的docs/ARCHITECTURE.md、docs/PRODUCT.md、session-handoff.md上重跑对比第二个会话恢复上下文的速度。solution/AGENTS.md本身就是原则 1、2 的活案例见 projects/project-02/solution/AGENTS.md启动规则要求 agent 在写任何代码前先依次读 AGENTS.md 本身、docs/ARCHITECTURE.md、docs/PRODUCT.md、feature_list.json并运行npm run check它把 Electron 主进程/预加载/渲染层/服务层的边界约束写成条目定义了Definition of Done编译通过、应用可启动、feature_list.json 标记 pass、遵守层边界、更新对应文档并在文件末尾规定了 Session Handoff 的写入格式完成了什么、剩下什么、阻塞与决策、改过哪些文件。这正是本讲把规则写进仓库、让知识随代码更新、用文件交接会话三件事的直接落地。用 ACID 原则管理 agent 状态这个类比来自数据库的事务管理。你可能会觉得这是在把简单的事情搞复杂但它确实提供了一个非常实用的框架原子性Atomicity每次逻辑操作比如添加新端点并更新测试用一个 git commit 原子化。中途挂了就git stash回滚。要么全做要么不做没有做了一半的中间态。一致性Consistency定义一致状态的验证谓词比如所有测试通过、lint 无报错。Agent 每次操作后跑验证不一致的中间状态不要 commit。就像银行转账不能只扣款不加余额。操作完系统应该处于可验证的正确状态。隔离性Isolation多个 agent 并发工作时状态文件要避免竞争条件。简单方案每个 agent 用独立的进度文件或者用 git 分支隔离。并发写入同一文件是出问题的常见原因——就像两个厨师同时往同一口锅里加盐咸了算谁的持久性Durability关键的项目知识用 git 跟踪的文件持久化。临时状态可以只在会话内存里但跨会话必须的知识必须写到文件里。脑子里的不算写在纸上的才算。一个真实的改造故事一个团队维护一个包含约 30 个微服务的电商平台。架构决策服务间通信协议、数据一致性策略、API 版本化规则散落在四处Confluence部分过时、Slack难以搜索、几个资深工程师的脑子里不可扩展、以及零星的代码注释不系统。引入 AI agent 后70% 的任务需要人工干预。几乎每次失败都涉及 agent 违反了某个所有人都知道但从未写入仓库的隐性约束。这就像一个新人没人告诉他午餐订餐必须发到群聊里——他猜错了被批评了但批评之后依然没人把这条规则写下来下一个人还会再错一次。团队执行了改造仓库根目录创建AGENTS.md写明项目概览、技术栈版本、全局硬约束每个微服务目录下添加ARCHITECTURE.md描述该服务的职责、接口和依赖创建集中的CONSTRAINTS.md用MUST / MUST NOT式的明确语言记录硬约束每个服务目录添加PROGRESS.md记录当前工作状态。改造后同一个 agent 能在冷启动时回答所有关键项目问题任务完成质量显著提升。注意这个故事的要点它不是靠写更多文档解决的而是靠把散落各处的隐性约束迁移到 agent 恰好会读到的地方解决的。核心要点不在仓库里的知识对 agent 来说等于不存在。把关键决策信息放进仓库是最基本的 harness 投资——画好地图才不会迷路。用全新会话测试检验仓库质量全新会话能不能只看仓库就回答五个基本问题是什么系统、怎么组织、怎么跑、怎么验证、做到哪了。知识要靠近代码、最小但完备、跟代码一起更新。不是写更多文档而是把信息放到正确的位置。用 ACID 原则管理 agent 状态原子提交、一致性验证、隔离并发、持久化关键知识。知识衰减是最大敌人过时的文档比没有文档更危险它会让 agent 走错方向还以为自己是对的。本仓库还提供了可量化验收的工具用 repo-reader.ts 给仓库打分用 system-of-record-checklist.md 做冷启动自检并用 Project 02 做多会话实战演练。练习全新会话测试在你的项目里开一个全新的 agent 会话不提供任何口头上下文只让它看仓库内容然后问它五个问题这是什么系统怎么组织的怎么运行怎么验证现在进度如何记录它答不上来的问题然后改进仓库直到它全部答上来。知识外置化量化列出项目中所有对开发工作重要的决策和约束逐条标注是在仓库内还是仓库外算出你的知识可见性缺口不在仓库里的占比并制定计划把缺口降到 10% 以下。ACID 准则评估用本讲的 ACID 类比评估你的项目状态管理。原子性agent 的操作能不能干净地回滚一致性仓库有没有一致状态的验证如npm run check全绿隔离性多 agent 并发时会不会互相踩脚持久性跨会话的知识是不是都落到了 git 跟踪的文件里进阶跑一遍评分脚本用 repo-reader.ts 对你的项目目录打分对照 8 项检查标准逐项补缺目标是把总分做到 90% 以上A 级。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐gbrain System of Record 架构以 Markdown 为唯一事实来源的知识库设计gbrain System of Record 架构以 Markdown 为唯一事实来源的知识库设计 本文基于 gbrain 仓库的架构契约文档 docs/a人工智能RAGAgent 记忆MCP 服务知识管理什么是真正的 Harness五子系统框架与仓库即规范实战指南learn-harness-engineering 第 02 讲什么是真正的 Harness五子系统框架与仓库即规范实战指南learn harness engineering 第 02 讲 导读 本篇文章基于 learMeetily 本地 AI 会议助手转录纪要10 分钟跑通Meetily 本地 AI 会议助手转录纪要10 分钟跑通 Meetily 是一个本地 AI 会议助手桌面应用帮你录下会议用本地 Whisper 实时创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考