【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本文围绕「System of Record系统记录仓库」这一 harness engineering 核心实践展开AI Agent 只有三种输入——系统提示与任务描述、仓库文件内容、工具执行输出仓库之外的信息对 Agent 而言等于不存在。文中将拆解《Aula 03》提供的「新会话清单」system-of-record-checklist.md——七个必须仅凭仓库即可回答的问题并配套讲解其背后的核心概念、四项设计原则、ACID 状态管理框架以及本仓库中可用于量化检验的评分工具repo-reader.ts与实战项目Project 02。读完你将掌握一套可立即落地的「地图绘制」方法让新会话的 Agent 无需向人类提问即可恢复上下文、继续工作。为什么仓库必须成为唯一的信息源课程 《Aula 03. Tornando o Repositório a Fonte Única da Verdade》 开篇就点破了一个残酷事实架构决策散落在 Confluence、Slack、Jira 和资深工程师脑子里时对人类还能勉强运转——你可以问同事、翻聊天记录、找文档但对 Agent 来说这些渠道全部不可达。Agent 无法找人问问无法搜索聊天历史它的整个工作宇宙就是仓库本身。这个观点的行业依据来自两处公开实践OpenAI 在 harness engineering 文章中提出的 repo as spec 原则——仓库本身就是最高权威的规格文档以及 Anthropic 关于长时运行 Agent 的工程文章——持久状态是长任务连续性的必要条件而仓库是 Agent 唯一稳定、可靠、可访问的持久存储。这不是多写文档的问题而是把决策信息放到正确位置的问题。一个放在src/api/目录里的 50 行ARCHITECTURE.md远比 Confluence 里 500 页、无人维护的设计文档有用。邻近性比体量更重要一条信息只有恰好出现在被需要的时刻和地点才真正算数。知识可见性规则必须流进仓库课程用一张流程图概括了知识迁移路径判断你的地图是否够好的唯一标准就是运行一次新会话测试fresh session test打开一个完全干净的新 Agent 会话只给它仓库内容看它能否回答几个基础问题。七问清单System of Record 的验收标准清单原文system-of-record-checklist.md用一句话定义验收标准一个新会话的 Agent 能否仅凭仓库回答以下问题#问题原文中文释义答案应存在于何处1Qual produto está sendo desenvolvido?正在开发什么产品README、AGENTS.md中的项目概述、docs/PRODUCT.md2O que o aplicativo deve fazer para os usuários?应用要为用户做什么docs/PRODUCT.md功能需求、产品文档3Como a base de código está organizada?代码库如何组织ARCHITECTURE.md、模块级文档、目录结构本身4Como iniciar a aplicação?如何启动应用Makefile、init.sh、package.json中的 scripts5Como verificar a integridade/saúde da aplicação?如何验证应用完整性/健康度测试、lint、校验命令npm run check等6Qual trabalho está atualmente em andamento?当前正在进行什么工作PROGRESS.md、feature_list.json、git 历史、session-handoff.md7Quais padrões de qualidade são importantes?哪些质量标准很重要AGENTS.md中的约定、Definition of Done、约束文档课程中的五问版测试与清单一一对应构成完整的新会话启动链路如果 Agent 答不出说明地图有缺口地图不完整的地方Agent 只能猜测——猜错变成 bug过度猜测浪费上下文而且每一次新会话都要把同样的猜测重来一遍。猜错的成本永远高于一开始就把地图画对的成本。支撑清单的六个核心概念Knowledge Visibility Gap知识可见性缺口项目总知识中没有进入仓库的比例。缺口越大Agent 失败率越高。估算方法清点所有存在于人脑中、关于项目的隐性知识再看其中多少真正写进了仓库差值即缺口。System of Record系统记录仓库代码仓库作为项目决策、架构约束、执行状态与验证标准的权威来源。仓库说了算其他地方都不算。这条路封了的信息如果只存在于 João 的脑子里那每个人都要去问 João写进仓库就再也不用问了。Fresh Session Test新会话测试上文七问课程正文为五问。Agent 能答对几题就决定了你的地图有多完整。Discovery Cost发现成本Agent 为找到一条关键信息所消耗的上下文预算。信息藏得越深发现成本越高留给真实任务的预算就越少。关键信息必须放在 Agent 一眼可见的位置而不是埋在目录树十层之下。Knowledge Decay Rate知识衰减率仓库中随时间而过时的知识条目比例。与代码脱节的文档是最大的敌人——没有文档不可怕有文档但过期才最危险因为它会把 Agent 引向错误方向而 Agent 还以为自己走在正路上。ACID AnalogyACID 类比把数据库事务的四个原则原子性、一致性、隔离性、持久性应用到 Agent 状态管理上下文详述。绘制好地图的四项原则原则 1知识住在代码旁边。关于 API 端点认证的规则应放在 API 代码附近而不是藏在一个巨型全局文档里。在每个模块目录放一份短文档说明该模块的职责、接口和特殊约束。模块目录本身就是天然索引——Agent 到达代码的同时就看到了约束无需再四处寻找。原则 2使用标准化的入口文件。AGENTS.md或CLAUDE.md是 Agent 的landing page。它不必包含全部信息但必须让 Agent 快速回答三问这是什么项目如何运行如何验证。50100 行足够。原则 3极简但完整。每条信息都要有明确的使用场景。如果删掉一条规则不会改变 Agent 的决策质量这条规则就不该存在但新会话测试的所有问题都必须有答案。这是一个持续的平衡——不多不少刚刚好。原则 4与代码同步更新。把知识更新绑定到代码变更上。最简单的做法就是把架构文档放在对应模块目录内——改代码时自然会看到文档代码变更后CI 还可以提醒你检查文档是否需同步。课程给出的具体仓库结构project/ ├── AGENTS.md # 入口项目概览、运行命令、硬性约束 ├── src/ │ ├── api/ │ │ ├── ARCHITECTURE.md # API 层的架构决策 │ │ └── ... │ ├── db/ │ │ ├── CONSTRAINTS.md # 数据库操作的硬性约束 │ │ └── ... │ └── ... ├── PROGRESS.md # 当前进度已完成、进行中、受阻 └── Makefile # 标准命令setup、test、lint、校验用 ACID 管理 Agent 状态把数据库事务原则映射到 Agent 状态管理上看似夸张实则提供了一个极其好用的框架原子性Atomicity每个逻辑操作例如新增端点 更新测试必须生成一个 git commit。中途失败就用git stash回退。全有或全无不允许半成品。一致性Consistency为一致状态定义校验谓词——所有测试通过、lint 无错误等。Agent 应在每次操作后执行校验不一致的中间状态不允许被提交。每次操作后系统都必须处于可验证的正确状态。隔离性Isolation多个 Agent 并行工作时设计状态文件以避免竞态条件。简单做法每个 Agent 使用自己的进度文件或各自在独立 git branch 上工作。对同一文件的并发写入是常见问题源。持久性Durability关键项目知识必须存在于 git 版本化的文件中。临时状态可以只留在会话内存里但任何需要跨会话存活的认知都必须写进文件。只在脑子里的不算数——只有被记录下来的才算。一份真实转型案例一个团队维护着约 30 个微服务的电商平台架构决策服务间通信协议、数据一致性策略、API 版本规则散落在Confluence部分过期、Slack难以检索、几位资深工程师的脑子不可扩展、零星的代码注释不成体系。引入 AI Agent 后70% 的任务需要人工介入。几乎所有失败都源于 Agent 违反了某种人人皆知、却从未被记录的隐性约束。Agent 无法知道自己不知道什么——它只能基于现有理解行动然后掉进陷阱。团队执行的转型步骤在仓库根目录创建AGENTS.md包含项目概览、技术栈版本、全局硬性约束在每个微服务目录添加ARCHITECTURE.md描述该服务的职责、接口与依赖创建集中的CONSTRAINTS.md用显式的 MUST / MUST NOT 语言描述关键约束在每个服务目录添加PROGRESS.md跟踪当前工作状态。转型后同一 Agent 能在干净会话中回答所有项目关键问题任务完成质量显著提升。仓库配套工具用脚本量化地图完整度本仓库的课程代码目录提供了两个可直接复用的配套资源。repo-reader.ts可发现性评分器repo-reader.ts 是一个命令行工具扫描仓库目录结构并为可发现性discoverability打分即检验该仓库是否具备 system of record 的信号。运行方式npx tsx docs/pt-BR/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts [路径] # 不传路径时默认扫描当前目录其评分标准满分 100 分逐项对应清单的七问评分项最高分检查内容对应清单问题AGENTS.md / CLAUDE.md15仓库根目录的 Agent 可读指令文件含.claude/CLAUDE.md问题 1、7文档目录10是否存在docs/、documentation/或doc/目录问题 2、3架构文档15architecture.md、ARCHITECTURE.md、docs/architecture/等问题 3feature 追踪15feature_list.json、features.md、tasks.json、TODO.md等问题 6交接/会话连续性15HANDOFF.md、SESSION_NOTES.md、PROGRESS.md等问题 6测试结构10test、tests、__tests__、spec目录问题 5配置文件10package.json、tsconfig.json、pyproject.toml、Cargo.toml、go.mod问题 4、5README10根目录README.md等问题 1工具输出 Markdown 表格报告每项的 PASS/FAIL并按百分比给出等级≥90% 为 A强 system of record、≥70% 为 B良好基础、少量缺口、≥50% 为 C部分结构、明显缺口、≥30% 为 D结构极少、Agent 难以导航、低于 30% 为 F。这给了清单一个可量化的执行方式跑一遍工具把失败的项逐条补上直到拿到 A。repo-knowledge-layout.txt推荐布局样例repo-knowledge-layout.txt 给出了一个兼具「入口 分层文档 计划追踪」的布局范例可作为目录模板AGENTS.md docs/ ARCHITECTURE.md PRODUCT.md RELIABILITY.md references/ electron.md sqlite.md plans/ active/ completed/ src/ scripts/可以看出这套布局同时覆盖了清单七问PRODUCT.md回答做什么/为谁做问题 1、2ARCHITECTURE.md回答如何组织问题 3AGENTS.md与scripts/回答如何运行与验证问题 4、5plans/active/与plans/completed/回答当前进行到哪问题 6而AGENTS.md内的约定回答质量标准问题 7。实战验证Project 02 的 Agent 可读工作区本仓库的 Project 02 正是这套方法论的真实演练场。它的核心机制就是Agent 可读的工作区 持久状态文件用 starter 与 solution 两个版本对比starter 文档更精简、且没有session-handoff.mdsolution 则补齐了ARCHITECTURE.md、PRODUCT.md、feature_list.json与session-handoff.md。对比维度是第二个会话的 Agent 需要做多少重新发现工作。对照清单逐条检验 solution 目录projects/project-02/solution/问题 1/2做什么、为谁做由 docs/PRODUCT.md 回答——管理个人知识库的桌面应用并列出文档管理、文本索引、有引用的问答、持久化等核心功能与约束最大文件 10 MB、支持.txt/.md、无网络请求。问题 3如何组织由 docs/ARCHITECTURE.md 回答——给出 Electron 分层图Renderer → Preload → Main → Services与导入/内容检索两条完整数据流。问题 4如何启动由 AGENTS.md 的 Startup Rules 回答——先完整读本文件 → 读docs/ARCHITECTURE.md→ 读docs/PRODUCT.md→ 运行npm install npm run check→ 读feature_list.json。注意这份文件的启动规则本身就是按可见性优先设计的。问题 5如何验证由 Definition of Done 回答——TypeScript 编译通过npm run check、应用能启动且窗口可见、feature 在feature_list.json中标记为pass并附证据、遵守分层边界、同步更新文档。问题 6进行到哪由 feature_list.json7 项功能全部pass每项含evidence与testedAt字段与 session-handoff.md记录已完成事项、剩余事项、决策、改动文件、阻塞项、下一步共同回答。问题 7质量标准由 AGENTS.md 的 Conventions 回答——TypeScript strict mode、仅命名导出、IPC 通道统一定义在src/shared/types.ts、新通道遵循namespace:action命名模式。session-handoff.md中的决策记录尤其值得注意例如新增GET_DOCUMENT_CONTENTIPC 通道而不是把内容捆绑进GET_DOCUMENT以保持列表视图载荷精简——这类决策如果不记录第二个会话的 Agent 必然踩坑重来。这正是课程反复强调的把隐性知识显性化Agent 才不需要每次猜一遍。关键结论不在仓库里的知识对 Agent 来说就是不存在。把关键决策信息写进仓库是 harness engineering 中最基础的投资——画好地图才不会迷路。用新会话测试评估仓库质量一个全新会话仅凭仓库内容能否回答清单中的七个问题知识要贴近代码、极简但完整、与代码同步更新。这不是写更多文档而是把信息放到正确的位置。用 ACID 管理 Agent 状态原子提交、一致性校验、并发隔离、关键知识持久化。知识衰减是最大的敌人。过期文档比没有文档更危险——它让 Agent 在自认为正确的方向上越走越偏。动手练习新会话测试在你的项目中打开一个完全干净的新 Agent 会话不提供任何口头上下文只允许它查看仓库内容依次问清单中的七个问题记录答不出的题持续改进仓库直到全部通过。知识外化量化列出项目中所有重要决策与约束逐项标记在仓库内或在仓库外计算 knowledge visibility gap仓库外条目占比制定计划把缺口压到 10% 以下。ACID 评估用 ACID 类比审视项目的状态管理——原子性Agent 的操作能否干净回滚、一致性仓库是否有一致状态校验、隔离性多个并发 Agent 会互相干扰吗、持久性跨会话知识是否都妥善落盘。运行评分器对本仓库或你自己的项目运行npx tsx docs/pt-BR/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts对照评分结果补齐缺失信号直至达到 A 级。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐让仓库成为 Agent 的唯一事实来源learn-harness-engineering 中的 System of Record 工程实践让仓库成为 Agent 的唯一事实来源learn harness engineering 中的 System of Record 工程实践 导读 在 AIlearn-harness-engineering 系统记录System of Record实战指南让仓库成为 Agent 的单一真相源learn harness engineering 系统记录System of Record实战指南让仓库成为 Agent 的单一真相源 本指南以 sys为什么仓库必须成为 Agent 的唯一事实来源learn-harness-engineering 中的 System of Record 实践为什么仓库必须成为 Agent 的唯一事实来源learn harness engineering 中的 System of Record 实践 在 harne上一篇终极Euler实战教程5个经典图神经网络模型实现与分布式训练指南下一篇Awesome Cheatsheets缓存策略速查Redis高级特性与最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考