【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本指南围绕 learn-harness-engineering 仓库中docs/de/resources/openai-advanced/repo-template/提供的“扩展 Repo 模板”展开讲解如何在真实项目中落地 OpenAI 文章《Harness engineering: leveraging Codex in an agent-first world》所倡导的 agent-first 仓库结构。读完本文你将掌握模板的复制顺序、每一份系统记录文档System of Record的职责与填写要点以及如何让AGENTS.md从“巨型指令文件”蜕变为短小精悍的路由层从而让长周期 Coding-Agent 协作具备可持续的上下文与质量基线。一、模板定位当最小 Harness 不再够用时learn-harness-engineering 仓库整体讲授“Harness Engineering”入门从 0 到 1而 OpenAI Advanced Pack 则把 OpenAI 文章中“更有主见more opinionated”的仓库结构封装为可直接复制的启动文件starter files。其中的 repo-template/index.md 就是整套扩展模板的入口文档。模板的使用时机非常明确当你的仓库已经不能只靠一个最小 Harness 支撑而需要以下能力时一份简短、具备路由性质的AGENTS.md而非百科全书式的巨型指令文件仓库内部持久化的 System-of-Record 文档让 Agent 不必依赖聊天历史显式的计划生命周期active / completed / tech-debt管理独立的产品、可靠性、安全、前端策略文件按**产品领域Product Domain与架构分层Architecture Layer**追踪的质量评分模型友好LLM 友好的参考材料目录面向架构、知识编码、运行时验证的标准作业程序SOP。模板的优化目标可归纳为五点原文明确列出持久化的 repo 本地上下文durable repo-local context渐进式披露progressive disclosure代替单一巨型指令文件显式的计划生命周期explicit plan lifecycle随时间推移的质量追踪quality tracking over time对 Agent 和人类都可读的边界readable boundaries for agents and humans。同时模板自带重要告诫其中每一份文件都应视为“启动器starter”——在依赖它们之前必须用自己的真实项目细节替换掉占位符、示例和示例命令。二、复制顺序五步把模板搬进真实仓库repo-template/index.md 给出了明确的“Kopierreihenfolge”复制顺序这是落地模板的第一步必须严格遵循将AGENTS.md和ARCHITECTURE.md复制到仓库根目录复制整个docs/目录树优先填写docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md和docs/RELIABILITY.md三份文件在docs/exec-plans/active/下添加第一个活跃计划保持入口文件短小把细节路由route到被链接的深层文档。第 5 步是整个模板的设计哲学核心入口文件如AGENTS.md、DESIGN.md只做“路由”真正的细节下沉到docs/下的各专项文档以此实现渐进式披露。在动手复制前建议先阅读 docs/de/resources/openai-advanced/index.md 的“如何采用Wie Sie es übernehmen”建议仓库还小时先用最小 Pack等需要更强结构时再引入本模板质量、可靠性与计划文档的更新应作为日常工作的组成部分而不是单独留出一个“清理日”生成产物generated artifacts与外部参考要显式存放让 Agent 无需依赖聊天历史即可找到它们。三、模板目录结构总览OpenAI Advanced Pack 概述 给出了模板的完整目录树实际文件与之一致AGENTS.md ARCHITECTURE.md docs/ ├── design-docs/ │ ├── index.md │ └── core-beliefs.md ├── exec-plans/ │ ├── active/ │ ├── completed/ │ └── tech-debt-tracker.md ├── generated/ │ └── db-schema.md ├── product-specs/ │ ├── index.md │ └── new-user-onboarding.md ├── references/ │ ├── design-system-reference-llms.txt │ ├── nixpacks-llms.txt │ └── uv-llms.txt ├── DESIGN.md ├── FRONTEND.md ├── PLANS.md ├── PRODUCT_SENSE.md ├── QUALITY_SCORE.md ├── RELIABILITY.md └── SECURITY.md整个结构遵循五条设计原则来自 index.md短入口、深链接short entry point, deeply linked docs仓库即 System of Record机械化检查优于被记住的规则mechanical checks beat remembered rules计划与质量历史与代码共存plans and quality history live next to the code清理与简化是一等公民任务cleanup and simplification are first-class tasks。下面按功能分组逐一讲解各文件的职责与填写要点。四、AGENTS.md路由器而非百科全书repo-template/AGENTS.md 是整个模板中最重要的文件之一。它的定位是“为长周期 Coding-Agent 工作而优化”的路由层明确声明保持文件简短把它当作通向 System-of-Record 文档的路由层而不是巨大的指令仓库。模板给出了四个组成部分1. 开始工作流Start-Workflow——改代码前必须依次执行用pwd确认处于仓库根目录读取ARCHITECTURE.md获取当前系统概览与硬性依赖规则读取docs/QUALITY_SCORE.md了解哪些领域/分层最薄弱读取docs/PLANS.md然后打开正在进行的活跃计划阅读docs/product-specs/中相关的产品规格执行本仓库的标准启动与验证路径bootstrap verification若基线验证失败先修复基线再添加新范围。2. 路由地图Routing-Map——把每类知识定位到具体文件需要的内容去哪里读领域地图、分层模型、依赖规则ARCHITECTURE.md设计决策与核心信念docs/design-docs/index.md当前产品行为与验收目标docs/product-specs/index.md计划生命周期与执行计划策略docs/PLANS.md产品领域与分层健康度docs/QUALITY_SCORE.md运行时信号、基准、重启期望docs/RELIABILITY.mdSecrets、沙箱、数据与外部动作规则docs/SECURITY.mdUI 约束、设计系统规则、可访问性检查docs/FRONTEND.md3. 工作契约Arbeitsvertrag——Agent 的行为准则同一时间只从一个有边界bounded的计划或功能切片上工作不能仅凭代码检查就宣布工作完成必须提供可执行的证据executable proof若改变了行为必须在同一 Session内更新相关的产品、计划或可靠性文档若反复看到同类评审反馈应把它提升为机械规则、检查或 Linter而不是在聊天里再次解释生成材料放入docs/generated/外部源参考放入docs/references/添加小且新的文档而不是让AGENTS.md本身不断膨胀。4. 完成定义Definition of Done——一项变更只有在全部满足时才视为完成目标行为已实现要求的验证确实执行过证据已链接到相关计划或质量文档受影响的文档保持最新仓库可通过标准启动路径干净地重启。5. 会话结束Session-Ende——退出 Session 前更新活跃执行计划若领域/分层显著变化则更新QUALITY_SCORE.md被推迟的新债务记入docs/exec-plans/tech-debt-tracker.md适当时把已完成计划移入docs/exec-plans/completed/让仓库处于可重启状态并留下清晰的下一个动作。这套“开始 → 路由 → 契约 → 完成定义 → 会话结束”的闭环与本仓库讲座系列中 lecture-12 关于 Session 必须留下干净状态 的理念一脉相承——模板把教训固化成可复制的文件结构。五、ARCHITECTURE.md系统的顶层事实源repo-template/ARCHITECTURE.md 是“系统的顶层概览”同样要求保持精炼并在必要时指向更深文档。它包含以下必填区块系统形态Systemform——用占位符声明产品名、主要用户工作流、运行时界面Desktop / Web / CLI / Services / Worker、产品行为的 Truth Source指向docs/product-specs/。领域地图Domänen-Map——表格列出每个领域Domäne的用途owns what、主要入口模块/路由/命令、关联 Spec 路径。分层模型Schichtenmodell——模板直接给出一条固定的有向分层链Types - Config - Repo - Service - Runtime - UI其意图是“让 Agent 不要发明 ad-hoc 架构”横切关注点必须通过显式的 Provider 或 Adapter 边界进入而不是直接越层。硬依赖规则Harte Abhängigkeitsregeln下层不得依赖上层UI 不得绕过 Runtime 或 Service 契约数据访问必须经由 Repository 或等价 Adapter公共工具必须保持通用不得囤积领域逻辑新依赖应在相应计划或设计文档中给出理由。横切接口Querschnittsschnittstellen——表格登记 Logging/Tracing、Auth、外部 API、Feature Flags 各自的“被允许的边界”与备注如结构化日志、Token 规则、限流/重试指引。当前热点Aktuelle Hot Spots——记录“对 Agent 来说最难安全修改的区域”和“边界薄弱或测试脆弱的区域”让新 Session 一开始就避开雷区。变更检查清单——触碰架构相关代码时更新领域地图/允许边界设计理由变化时更新docs/design-docs/对应文档若规则需要机械执行则新增或更新一个可执行检查。六、docs/ 下的系统记录文档族6.1 DESIGN.md 与 design-docs/设计决策的持久化Docs/DESIGN.md 是设计入口文件作用同样是“保持简短、路由到细节”。它明确设计文档用于记录应当超越单个聊天、Sprint 或评审者记忆而长期存续的产品与系统设计决策当你需要当前设计哲学、准备引入新模式、或需要判断哪些设计决策已定稿/仍开放时就该读它。规范的设计文档包括 docs/design-docs/index.md已接受/建议/已废弃三区索引与 docs/design-docs/core-beliefs.md项目级 agent-first 信念。设计规则包括保持文档小而新、一个决策领域一个文档、计划与规格中链接相关设计文档、设计规则一旦变得操作上关键就应提升为自动化检查或写入ARCHITECTURE.md。核心信念文件core-beliefs.md列出了七条贯穿项目的主张堪称模板的“价值观层”仓库是 Agent 的 System of RecordAGENTS.md是路由器不是百科全书验证证据比自信更重要一个有边界bounded的任务好过一堆半成品任务反复出现的人类反馈应固化为可复用的 Harness 规则清理与简化是交付的一部分不是事后想法如果 Agent 无法在仓库中找到某个事实就把该事实视为“操作上不可用operationally unavailable”。6.2 product-specs/用户可见行为的规格层docs/product-specs/index.md 规定此目录存放当前用户侧行为规格规格应描述用户可见行为与验收标准若实现偏离规格须在同一 Session 内更新其中一方索引必须保持最新让新 Agent 能快速把握产品范围。示例规格 docs/product-specs/new-user-onboarding.md 展示了每个规格的最小骨架目标Ziel、起始条件Startbedingungen、用户流程Benutzerablauf、验收标准Akzeptanzkriterien、错误状态Fehlerzustände含可恢复错误与阻塞状态及退路。这份骨架可以直接复用到任何用户流程的规格化。6.3 PLANS.md 与 exec-plans/计划生命周期docs/PLANS.md 定义计划的创建、更新、完成与归档规则何时需要计划工作跨多个 Session、改动多个子系统、存在非平凡的验证/发布风险、或依赖需要被记录的未决决策存放位置docs/exec-plans/active/正在控制工作的计划、docs/exec-plans/completed/保留给未来 Agent 上下文的已完成计划、docs/exec-plans/tech-debt-tracker.md被推迟的工作与后续任务计划的最小章节目标设定Zielsetzung、范围与非范围Umfang und Nicht-Umfang、验证路径Verifikationspfad、风险与阻塞Risiken und Blocker、进度日志Fortschrittslog、未决决策Offene Entscheidungen运营规则活跃计划应有一个明确负责的当前步骤计划要随工作推进持续更新而非当作静态文本决策改变实现方向时记入计划完成的计划移入completed/以便 Agent 继续找到历史上下文。active/index.md 给出活跃计划的文件命名建议YYYY-MM-DD-kurzes-thema.md如2026-09-22-observability-stack.md并强调每个活跃计划应足够新让新 Agent 仅凭仓库即可续接工作。tech-debt-tracker.md 规定只记录“真实、被承认、且被有意推迟”的债务每行包含日期、领域、债务描述、推迟原因、风险、下次复核触发条件。6.4 QUALITY_SCORE.md随时间推移的健康度追踪docs/QUALITY_SCORE.md 回答“仓库是变强还是变弱”的问题提供了一套可直接落地的评分机制评分标尺A已验证、可读、稳定、边界被强制执行、B可用但有少量缺口、C部分可用、存在明显混乱或不稳定、D损坏、不安全或结构不清产品领域表每个领域记录 评分 / 验证方式 / Agent 可读性 / 测试稳定性 / 关键缺口 / 最后更新时间架构分层表Types / Services / Runtime / UI 各层记录 评分 / 边界执行情况 / Agent 可读性 / 关键缺口 / 最后更新时间基准快照表Benchmark-Momentaufnahmen日期 / Harness 变体Baseline / verbessert / vereinfacht/ 完成率 / 重复次数 / Review 前错误数 / 备注——这正是本仓库 lecture-10 关于端到端测试改变结果 强调的“以可执行证据说话”的具体化简化协议Vereinfachungsprotokoll记录每次移除组件后的结果恶化/不变与决策恢复/保持移除让“减法”也留下审计痕迹。6.5 RELIABILITY.md证明系统健康且可重启docs/RELIABILITY.md 定义“系统如何证明自己健康且可重启”标准路径StandardpfadeBootstrap 命令、验证命令、启动应用/服务命令、调试或运行时检视命令全部显式写出必需运行时信号启动与关键流程的结构化日志、关键服务的健康检查、慢路径的 Trace/计时数据若可用、用户可见的故障状态针对可恢复故障黄金旅程Golden Journeys每条旅程都应有可重复的验证路径与清晰的错误信号可靠性规则系统在变更后无法干净重启则功能不算完成运行时错误应能由 repo 本地信号诊断反复出现的错误模式应固化为基准或护栏清理是可靠性的组成部分而不是独立的关注点。6.6 SECURITY.md不允许 Agent 猜测的安全边界docs/SECURITY.md 规定 Agent“不得猜测”的安全规则Secrets 与凭据绝不硬编码 Secrets 到源码或文档在此文件登记允许的 Secrets 加载路径日志与截图中遮蔽 Token、API Key 与个人数据不可信输入外部内容在验证前一律视为不可信登记允许的 Fetch/执行边界存在 Prompt 注入或命令注入风险时记录护栏外部动作列出需要显式批准的动作记录默认不允许 Agent 执行的生产/破坏性命令调试与验证优先采用沙箱安全工作流依赖与评审规则新依赖需在活跃计划中给出理由安全敏感变更要求显式验证步骤反复出现的 Security 评审意见应固化为检查而不是隐含知识。6.7 FRONTEND.md可预测的 UI 期望docs/FRONTEND.md 定义稳定的前端期望防止 Agent 发明不可预测的 UI 模式UI 原则清晰优先于新奇交互流程要可发现、可重启优先少量可复用组件而非一次性变体可访问性检查是正常验证的一部分而不是打磨工作护栏设计系统/组件库文档放在docs/references/捕获关键用户状态空、加载、成功、错误、重试文本、键盘行为与视觉层级在全部流程中保持一致修复 UI Bug 时同步新增/更新对应验证步骤验证期望为关键用户旅程保留证据浏览器/运行时验证步骤写入对应计划视觉回归频繁时标准化截图或 DOM 检查。6.8 generated/ 与 references/显式的生成物与参考docs/generated/db-schema.md 用于存放生成或推导出的产物让 Agent 无需从代码反推即可检视如数据库 Schema。要求记录“生成自哪个命令/源路径”与“最后更新时间”并声明“不要手工编辑生成段底层 Schema 变化时重新生成”。docs/references/含design-system-reference-llms.txt、nixpacks-llms.txt、uv-llms.txt用于存放供模型读取的外部参考材料把重复查阅的外部文档固化进仓库减少 Agent 对外部查询的依赖。七、PRODUCT_SENSE.mdAgent 无法从代码推演出的产品判断docs/PRODUCT_SENSE.md 解决一个真实痛点有些产品判断Agent 仅凭代码无法可靠推导必须持久化记录。它包含产品核心Produktkern主要用户、要完成的任务、要解决的主要挫败点、验收的质量标尺Quality bar产品规则Produktregeln用户可见的可靠性优先于功能数量把模糊行为视为规格缺口而不是“可以乱猜的许可”若实现改变了用户所见或所信更新对应规格产品规格管具体流程本文件管跨产品的优先级No-Go 模式隐藏的破坏性动作、无用户反馈的静默失败、可见状态缺乏清晰 Truth Source、无法用一句话解释的功能。这份文件与 SOP把不可见知识编码进仓库 直接呼应。该 SOP 建议当 Agent 频繁询问系统如何工作、人类说“我们在 Slack 里已经定了”、评审引用仓库外的规则、新 Session 重复已解决的探索时就应当触发知识编码动作。编码时按知识类型落到对应文件架构 →ARCHITECTURE.md产品行为 →docs/product-specs/设计理由 →docs/design-docs/执行状态 →docs/exec-plans/反复用到的外部参考 →docs/references/质量/可靠性期望 →docs/QUALITY_SCORE.md或docs/RELIABILITY.md“完成定义”是新 Agent 无需问人就能找到相关规则同一事实不散落在多个相互矛盾的文件中新产物紧邻它所要控制的代码或工作流。八、设计原则与采用建议总结综合整套模板可以提炼出五条可迁移的设计原则来自 OpenAI Advanced Pack短入口、深链接所有顶层文件AGENTS.md、ARCHITECTURE.md、DESIGN.md都刻意保持短小细节交给docs/下的专项文档仓库即 System of Record所有关键事实架构、产品、质量、计划都必须能在仓库内找到机械化检查优于被记住的规则反复出现的反馈要固化为检查/Linter/基准而不是依赖记忆计划与质量历史与代码共存exec-plans/与QUALITY_SCORE.md紧邻代码演进随日常提交同步更新清理与简化是一等公民tech-debt 追踪、简化协议、Session 结束清单都是交付的一部分。采用时的三条关键建议渐进引入仓库还小的时候先从最小 Harness 起步需要更强结构时再复制本模板见 index.md 的采用指引先填三件套复制后优先填写PRODUCT_SENSE.md、QUALITY_SCORE.md、RELIABILITY.md因为它们是后续所有 Agent 工作的判断基线把文档更新当作日常工作模板明确反对“单独留一个清理日”质量、可靠性与计划文档应随正常开发持续更新并遵守AGENTS.md中“同一 Session 内同步更新受影响文档”的工作契约。九、适用前提与限制需要明确的是这套模板是有主见的opinionated官方文档也强调“应针对你的项目做适配而不是盲目复制”。落地时请注意所有占位符[mit Produktnamen ersetzen]、[domäne-a]、YYYY-MM-DD等必须在投入使用前替换为真实项目内容示例命令与示例路径如docs/references/下的nixpacks-llms.txt、uv-llms.txt反映的是示例项目的技术栈需按你的实际构建工具链调整分层链Types - Config - Repo - Service - Runtime - UI是针对该模板设想的典型分层实际项目应根据自身架构在ARCHITECTURE.md中重写评分体系A/B/C/D与基准快照的价值取决于团队是否持续维护——模板只提供机制不保证结果。本仓库中的 讲座系列尤其是“仓库必须成为 System of Record”“巨型指令文件为何失败”“每个 Session 必须留下干净状态”等主题为这套模板提供了完整的理论背景OpenAI Advanced Pack 概述 与 SOP 库 则给出了逐层深入的操作指引适合作为本模板的配套阅读材料。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐OpenAI 风格 Agent-First 仓库模板为 learn-harness-engineering 构建渐进式披露的 Harness 文档体系OpenAI 风格 Agent First 仓库模板为 learn harness engineering 构建渐进式披露的 Harness 文档体系 这篇技从最小 Harness 到 OpenAI 风格 Agent 优先仓库learn-harness-engineering repo-template 模板实战指南从最小 Harness 到 OpenAI 风格 Agent 优先仓库learn harness engineering repo template 模板实战指learn-harness-engineering 实战用 OpenAI 风格高级仓库模板repo-template搭建 Agent 友好的系统记录仓库learn harness engineering 实战用 OpenAI 风格高级仓库模板repo template搭建 Agent 友好的系统记录仓库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考