【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读在 Harness Engineering 实践中代码库不仅服务于人类工程师还需要被 Agent 快速、准确地理解。quality-document.md质量文档正是为此设计的轻量级快照工具它以统一评分体系为每个产品领域与架构层打分让人与 Agent 一眼看清代码库哪里强、哪里需要返工。本文以仓库中的质量文档模板docs/de/resources/templates/quality-document.md同构英文版见 docs/en/resources/templates/quality-document.md为骨架结合 project-06 结业项目 的真实填充示例与底层源码完整讲解该模板的结构、评分标准、填写方法与验证闭环。读完本文你将掌握如何在任意 Agent 协作项目中落地一份可维护、可验证、可被 Agent 引用的质量文档。一、模板定位面向 Agent 与人类的质量快照模板开篇即定义了它的核心作用一份针对每个产品领域product domain与架构层architectural layer的质量快照。Agent 与人类都可以使用这份文档快速理解代码库哪里强、哪里需要改进。这决定了质量文档的三个特性快照而非报告它不追求冗长的过程叙述而是某一时刻对代码库质量的浓缩定格双读者既要人类可读也要 Agent 可读agent-legible因此表格结构统一、评分标准明确、字段语义稳定高频更新模板明确规定了更新节奏——每次重要的 Agent 会话之后或开始新一阶段工作之前。这与仓库中 session-handoff.md、claude-progress.md 等会话留痕文件的定位一致让上一阶段的质量认知能够无损传递给下一阶段的工作者无论它是人类还是 Agent。二、评分体系A 到 D 的判定标准模板定义了四级评分德语版原文与英文版语义一致这是整个文档的量化基础等级判定标准英文版原文通俗解读AAll verification passing, clean architecture, agent-legible, stable tests全部验证通过、架构干净、Agent 可读、测试稳定BVerification passing, mostly clean, minor gaps in legibility or test coverage验证通过、大体干净、可读性或测试覆盖有轻微缺口CPartially working, known gaps, some code areas hard for agents to understand部分可用、存在已知缺口、部分代码区域难以被 Agent 理解DNot working, or major structural issues不可用或存在重大结构问题注意等级判定中反复出现的两个关键词Verification验证与agent-legibleAgent 可读性。这并非偶然——质量文档的评分不是凭感觉而是要求有验证动作作为证据支撑同时Agent 能否读懂这段代码被提升为与测试是否稳定并列的一等公民指标这正是 Harness 工程区别于传统软件质量评估的核心视角。从仓库的实际实现看验证并非虚设。在 project-06 的评估者评分标准 中每一项能力都以 1-5 分给出可核查的证据描述而 clean-state-checklist.md 则把验证拆解为 30 个可勾选的检查项横跨 Build、Architecture、Runtime、Logging、Data Integrity、Performance、Repository、Scripts 八类。质量文档中的验证列指向的正是这类可以实际执行的检查动作。三、产品领域表按业务域横向打分模板的第一张核心表格是产品领域表固定列出五个领域领域Domäne / Domain对应列文档导入Dokumentenimport / Document Import等级、验证、Agent 可读性、测试稳定性、关键缺口、最后更新文档管理Dokumentenverwaltung / Document Management同上文档索引Dokumentenindexierung / Document Indexing同上QA 流程QA-Flow / QA Flow同上有依据的回答Begründete Antworten / Grounded Answers同上这张表回答的是**每个业务能力现在处于什么状态**。六列含义如下Grade等级A-D 之一Verification验证该领域通过哪些检查验证过对应构建、脚本、运行验证Agent LegibilityAgent 可读性代码/文档是否容易被 Agent 理解Test Stability测试稳定性相关测试是否稳定通过Key Gaps关键缺口当前已知的短板Last Updated最后更新该行评分的时间戳。这五个领域并非模板作者凭空罗列而是与项目真实功能一一对应。以 project-06 结业项目 的 15 项 feature 为例文档导入对应document-import含文件校验、10MB 大小限制、元数据创建文档索引对应text-indexing段落边界感知的分块、单文档/批量两种模式QA 流程与有依据的回答对应grounded-qa关键词检索、引用与置信度评分。换言之模板中的每一行领域都应当能在 feature 清单中找到其功能实现与之映射这样评分才有据可依。四、架构层表按分层纵向检查第二张核心表格是架构层表固定四层层Schicht / Layer对应列主进程Main-Prozess / Main Process等级、边界执行、Agent 可读性、关键缺口、最后更新预加载Preload同上渲染进程Renderer同上服务层Services同上与产品领域表相比这里把测试稳定性换成了Boundary Enforcement边界执行这是一个更偏架构的指标检查分层边界是否被严格执行。从源码结构可以印证这一点src/main/ipc-handlers.ts 与 src/main/main.ts 属于主进程层src/preload/preload.ts 是唯一的 IPC 桥接层src/renderer/ 下是 React 组件src/services/ 下是 document、indexing、qa、persistence、logger 五个服务。边界执行的检查内容在 clean-state-checklist.md 中被明确为四条架构红线渲染进程代码src/renderer/不得 importfs或path服务层src/services/不得直接使用 Electron IPC服务与主进程不得引入 React所有 IPC 通道统一在 src/shared/types.ts 中定义所有新 API 必须在 preload 中暴露。这些红线恰好解释了模板中边界执行这一列要回答的问题每一层是否只通过约定好的方式与相邻层通信若某层出现越界依赖如 Renderer 直接读写文件系统即构成边界违规该层评分应被下调。五、变更历史让质量演化可追溯模板末尾是变更历史Änderungsverlauf / Change History区块按日期组织固定五个记录维度Changes变更本次会话的整体改动Domains promoted领域升级哪些领域评分上调Demoted降级哪些领域/层评分下调New gaps identified新缺口新暴露的问题Gaps closed已关闭缺口本次修复的问题。这个区块与 claude-progress.md 形成互补进度日志记录做了什么变更历史则沉淀质量认知发生了什么变化。它让多会话协作中的质量走向可回看——新会话的 Agent 不必重新推断整个代码库的优劣只需读取最近的变更历史即可建立起点认知。六、从模板到实践project-06 的完整填充示例模板的价值在于被认真填写。仓库中 projects/project-06/solution/quality-document.md 给出了一个高质量的实战范例恰好对应模板中产品领域 × 架构层的量化框架只是在结业场景下细化为 15 个能力维度。我们可以对照学习模板的填写思路6.1 评分摘要逐维度打分示例将每个能力独立成行给出等级与一句话依据维度等级依据摘要构建与编译A干净编译无错误无警告功能完整度A15 项功能全部实现并通过会话历史A聊天气泡、可展开引用、反馈按钮、置信度配色结构化日志AJSON 格式、日志级别、服务标签、全部服务带数据载荷带引用的 QAA8 种回答模式、关键词检索、置信度评分测试覆盖B构建期检查通过运行时由基准脚本验证………………这种维度 等级 一句话证据的写法正是模板产品领域表的实战化变体——每一行都必须能被一句话说清凭什么给这个分。6.2 质量证据验证必须可执行示例文档专门列出Evidence of Quality质量证据区块分四类给出可复现的验证动作Build构建npm run check干净通过npm run build输出正确bash init.sh校验所有文件齐备Runtime运行时窗口以 1200x800 启动且安全项配置正确结构化 JSON 日志从首次启动即可见文档导入生成元数据并存储内容批量索引处理全部文档并输出指标QA 返回带引用的有依据回答Observability可观测性每个 IPC 通道调用都被记录导入日志携带 documentId、filename、sizeBytes索引日志携带 chunkCount、durationMs、throughputQA 日志携带 confidence、citationCount、answerLength、durationMs干净状态重置以 WARN 级别记录Performance性能以示例数据为基准导入 3 份文档 200ms、批量索引 3 份 100ms、带引用查询 300ms、干净状态重置 20ms。这些证据并非形容词而是指向可重复执行的命令与脚本。例如 scripts/benchmark.sh 就是性能证据的直接来源它定义 4 个基准任务Import、Indexing、Query、Verify对示例文档逐文件计时、统计关键词匹配数、校验文件大小一致性最后汇总PASS/FAIL计数并输出结构化结果。质量文档中的性能数据正是这类脚本的产物。6.3 验证依据与检查清单形成闭环示例结尾的Verified Against区块展示了质量文档与周边 harness 文件的引用关系clean-state-checklist.md30 项检查全部通过evaluator-rubric.md总分 5.0/5feature_list.json15/15 项功能状态为 passbash scripts/benchmark.sh全部任务完成bash scripts/cleanup-scanner.sh无残留产物。这构成了一个完整的质量验证链功能清单feature_list.json→ 检查清单clean-state-checklist.md→ 评分标准evaluator-rubric.md→ 自动化脚本benchmark.sh / cleanup-scanner.sh→ 质量文档quality-document.md。质量文档不是孤立的表格而是这条链的汇总出口。七、反面对照从 D 到 A 的演化路径projects/project-06/starter/quality-document.md 提供了同一份文档的起点形态与 solution 版形成鲜明对照起点总体等级D构建有未使用导入警告C、缺少反馈收集/干净状态/基准测试D、会话历史只是无样式的平面列表D、结构化日志未覆盖全部服务C、测试覆盖为零F终点总体等级A15 个维度中 14 个达到 A1 个测试覆盖为 B。更值得注意的是起点文档的Action Items行动项区块7 条待办以复选框形式列出新增 FeedbackEntry 类型与反馈服务、通过 IPC 实现干净状态重置、编写 benchmark.sh、会话历史增强为聊天气泡、为全部服务增加结构化 JSON 日志、为服务编写测试、补齐完整 harness 文件。这揭示了质量文档的另一重用法它不仅是状态快照还是下一阶段工作的路线图——评分低的维度直接映射为待办行动项。从源码看这些行动项在 solution 中逐一落地结构化日志由 src/services/logger.ts 实现LogLevel 枚举、forService()子日志器、JSON 序列化输出反馈收集由qa-service.ts的submitFeedback()与FeedbackEntry类型支撑干净状态重置由PersistenceService.resetAll()与IPC_CHANNELS.RESET_DATA通道实现。质量文档中每个被勾除的缺口都能在源码中找到对应的实现证据。八、模板落地要点与使用建议综合模板设计意图与仓库实践使用质量文档时有几点建议以下基于仓库现有结构推断总结每次会话结束必须触碰模板明确要求每次重要会话后、开始新阶段前更新。宁可更新一行Last Updated也不要在多阶段工作中放任文档过期评分必须附带验证动作等级旁边写清通过什么检查得到的结论让人类和 Agent 都能复现验证过程避免主观打分领域行与功能清单保持映射产品领域表中的每个领域都应能在 feature_list.json 或对应功能文档中找到实现评分才有落点架构层行与分层红线联动评分前先跑架构边界检查如scripts/check-architecture.sh与 clean-state-checklist 中的四条红线再用结果填充Boundary Enforcement列变更历史逐条对应缺口每次Domains promoted都应在变更历史中注明依据新缺口要及时登记形成完整的质量演化档案与周边 harness 文件配合使用质量文档应与其他 harness 文件保持一致性——feature_list.json 的功能状态、clean-state-checklist.md 的勾选结果、evaluator-rubric.md 的评分都应与质量文档中的等级互相印证。结语一份被认真维护的 quality-document 让代码库的质量状态从隐性知识变成显性数据人类工程师可以快速定位返工区域Agent 可以在会话开始时用几秒钟建立对代码库质量的完整认知评估者可以用统一尺度横向比较不同模块。模板本身极其精简——两张表格、一套 A-D 评分、一段变更历史——但正如 project-06 从 D 到 A 的演化所证明的它的价值完全取决于填写者是否以可验证的方式持续记录。让质量文档成为每个 Agent 会话的固定收尾动作你的代码库质量轨迹将第一次变得清晰、可量化、可传承。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Quality Document 模板实战用质量快照文档为 Agent Harness 建立可追踪的代码库健康度体系Quality Document 模板实战用质量快照文档为 Agent Harness 建立可追踪的代码库健康度体系 质量快照文档Quality DocumLearn Harness Engineering 质量文档模板实战用评分快照追踪代码库健康度让 Agent 与人类快速对齐Learn Harness Engineering 质量文档模板实战用评分快照追踪代码库健康度让 Agent 与人类快速对齐 质量文档Quality Do如何使用Flow构建完整的JavaScript代码质量评估体系如何使用Flow构建完整的JavaScript代码质量评估体系 Flow是GitHub加速计划中的一个强大工具它为JavaScript添加静态类型检查帮助开开发工具静态分析代码质量创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考