★ FEATURED ARTICLE 【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本指南围绕 learn-harness-engineering 仓库中的docs/ja/resources/openai-advanced高级包展开它把 OpenAI 文章 Harness engineering: leveraging Codex in an agent-first world 所描述的、更具观点倾向opinionated的仓库结构打包为可直接复制的模板。读者将掌握何时从最小 harness 升级到高级包、如何按顺序导入repo-template/目录、如何把AGENTS.md当作路由层而非百科全书写、以及如何用 4 份 SOP 建立可强制、可复现的 Agent 工作流。1. 高级包的定位最小 harness 不够用时的升级路径learn-harness-engineering 项目整体遵循渐进式披露progressive disclosure理念先以最小 harness 起步等仓库规模与协作复杂度增长后再引入更厚重的结构。docs/ja/resources/openai-advanced/index.md明确给出了从最小包升级到高级包的判断标准——当你的仓库出现以下需求时就该启用本包需要一个短小精悍的路由型AGENTS.md而非巨型指令文件需要仓库内的持久化系统记录文档system of record需要**活跃与已完成的执行计划exec-plans**目录需要明确的产品、可靠性、安全、前端策略文件需要按产品领域与架构分层进行质量评分需要面向模型的参考资料文件夹需要架构、知识捕获、运行时验证的标准操作程序SOP。这与仓库内 lecture-04-why-one-giant-instruction-file-fails 所讲的巨型单文件指令必然失败一脉相承高级包的解决方案不是写更长指令而是把知识拆进多个深度链接的文档由入口文件负责路由。2. 模板总览repo-template 目录结构与职责高级包的核心资产位于docs/ja/resources/openai-advanced/repo-template/index.md它是一份可直接拷入实际仓库的起始骨架。整体结构如下摘自原文档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模板的目录设计各司其职从仓库实际文件如docs/ja/resources/openai-advanced/repo-template/docs/PLANS.md、QUALITY_SCORE.md、RELIABILITY.md、SECURITY.md等可以看出它优化的目标是持久的仓库本地上下文Agent 每次会话都能从仓库文件恢复状态不依赖聊天历史渐进式披露入口文件只给地图细节通过链接逐层展开显式的计划生命周期exec-plans/active/、exec-plans/completed/与tech-debt-tracker.md形成闭环随时间追踪质量QUALITY_SCORE.md让仓库在变强还是变弱可量化对 Agent 与人类都友好的边界每个文件有明确主题避免互相吞噬职责。3. 导入步骤5 步把模板落地到自己的仓库docs/ja/resources/openai-advanced/repo-template/index.md给出了明确的复制顺序copy order复制入口层把AGENTS.md与ARCHITECTURE.md复制到仓库根目录复制文档树整个docs/目录树整体复制先填充三份策略文档优先填写docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.md——它们是质量与可靠性追踪的起点建立第一个活跃计划在docs/exec-plans/active/中加入第一份进行中的执行计划保持入口简短所有入口文件保持精炼把细节导向链接文档。原文档还特别强调模板中的所有文件都应视为起点而不是终点。占位符[domain-a]、[command]、[产品名に置き換え]之类、示例与示例命令必须在投入真实项目前替换成实际内容。高级包虽然故意带有观点但应当适配你的项目而不是盲目照搬。4. 入口层把 AGENTS.md 写成路由层而非百科全书仓库内的docs/ja/resources/openai-advanced/repo-template/AGENTS.md是整套高级包设计哲学的最佳示范。它开篇就申明这个文件要短作为指向系统记录文档的路由层而不是巨型指令转储。文件本体由四部分组成。4.1 启动工作流Startup Workflow在改动任何代码之前Agent 必须按固定顺序执行用pwd确认仓库根目录读ARCHITECTURE.md确认系统地图与严格依赖规则读docs/QUALITY_SCORE.md判断哪个领域或层最薄弱读docs/PLANS.md打开正在进行的活跃计划读docs/product-specs/中相关的产品规格执行本仓库标准的引导bootstrap与验证路径若基线验证失败先修复基线再增加新范围。这条路径把初始化固化成了每个会话的强制动作呼应仓库 lecture-06-why-initialization-needs-its-own-phase 的核心观点——初始化必须是一个独立阶段而不是可有可无的铺垫。4.2 路由映射Routing Map路由表把每一个关注点映射到唯一文档避免哪都写了等于哪都没写ARCHITECTURE.md领域地图、分层模型、依赖规则docs/design-docs/index.md设计决策与核心信念docs/product-specs/index.md当前产品行为与验收标准docs/PLANS.md计划生命周期与执行计划策略docs/QUALITY_SCORE.md产品领域与层的健康度docs/RELIABILITY.md运行时信号、基准测试与重启预期docs/SECURITY.md密钥、沙箱、数据与外部动作规则docs/FRONTEND.mdUI 约束、设计系统规则、可访问性检查。4.3 工作契约Working Contract一次只处理一个有边界的计划或功能切片仅凭阅读代码不能标记为完成必须有可运行的证据改变行为的同时必须在同一会话内更新对应的产品、计划或可靠性文档若反复收到同类评审反馈把口头解释升级为机械规则、检查或 lint而不是再次在聊天中解释生成产物放docs/generated/来源参考放docs/references/优先新增小而新的文档而不是让本文件膨胀。4.4 完成定义与会话收尾Definition of Done / End of Session变更只有在全部满足时才视为完成目标行为已实现、必要验证已实际运行、证据已链接到相关计划或质量文档、受影响文档已更新、仓库能从标准启动路径干净重启。会话结束前还有一套强制收尾动作更新活跃执行计划领域或层有实质变化则更新docs/QUALITY_SCORE.md有推迟的债务则记入docs/exec-plans/tech-debt-tracker.md适时把结束的计划移入docs/exec-plans/completed/最终让仓库停留在下一步动作清晰、可重启的状态。这与仓库 lecture-12-why-every-session-must-leave-a-clean-state 的主张完全一致。5. 架构层用 ARCHITECTURE.md 固化系统地图docs/ja/resources/openai-advanced/repo-template/ARCHITECTURE.md定义了系统最顶层的地图文件包含六个板块系统构成产品名、主用户工作流、运行时表面desktop / web / cli / services / workers、产品行为的可信来源docs/product-specs/领域地图表格列出每个领域的目的、主入口点与关联规格层模型使用固定方向模型Types - Config - Repo - Service - Runtime - UI防止 Agent 即兴发明临时架构横切关注点应通过显式的 provider 或 adapter 边界加入而不是直接跨层严格依赖规则下层不得依赖上层UI 不得绕过 Runtime/Service 契约数据访问必须经由 Repository 或等价适配器共享工具类保持通用、不得堆积领域逻辑新依赖需在计划或设计文档中给出理由横切接口表格列出日志与追踪、认证、外部 API、特性开关各自的批准边界与约束变更清单触碰架构相关代码时更新领域地图/边界 → 更新docs/design-docs/→ 对可机械强制的规则增加可执行检查。分层边界与禁止跨层依赖的要求与仓库 lecture-14-graph-engineering 以及 SOP 中的 layered-domain-architecture.md 形成呼应架构不再靠 Agent 自觉而是靠文档 可执行检查双重约束。6. 策略文档族计划、质量、可靠性与安全如何配合高级包把一次性写不完的策略拆成一组聚焦文档模板目录中实际存在并定义了以下角色内容分别摘自仓库中的对应文件6.1 PLANS.md执行计划的生命周期PLANS.md 定义了计划从创建到归档的规则。需要创建执行计划的场景跨会话的工作、涉及多个子系统的改动、存在非平凡验证或发布风险、依赖尚未决断的决策。计划存放位置分三处exec-plans/active/正在推进、exec-plans/completed/为未来 Agent 保留上下文、tech-debt-tracker.md推迟的工作与跟进。每份计划必须包含目的、范围与范围外、验证路径、风险与阻塞、进度日志、未决事项。运行规则强调计划是活的文档——随进展持续更新、方向被决策改变时记入计划、结束的计划移入completed/。6.2 QUALITY_SCORE.md让仓库健康度可追踪QUALITY_SCORE.md 用四个评分等级追踪仓库随时间的强弱变化A已验证、可读、稳定、边界被强制、B有轻微缺口但可用、C部分可用、有明显混乱或不稳定、D损坏、不安全或结构不清。它按产品领域评估、Agent 可读性、测试稳定性、主要缺口、最后更新与架构层Types/Services/Runtime/UI 的边界强制与可读性分别打分并提供基准快照表日期、harness 变体、完成率、重试次数、评审前缺陷数与简化日志删除的组件、结果、决定让简化是否值得也有据可查。这与仓库 lecture-11-why-observability-belongs-inside-the-harness 中的 evaluator-rubric.md 思路一致给评估设定显式标准。6.3 RELIABILITY.md如何证明系统可重启RELIABILITY.md 定义系统健康且可重启的证明方式标准路径bootstrap / 验证 / 启动 / 运行时调试命令、必需运行时信号结构化日志、健康检查、慢路径 trace、用户可见错误状态、黄金旅程golden journeys清单以及四条硬性规则——无法干净重启的功能不算完成运行时故障应能由仓库本地信号诊断反复出现的故障模式要固化为基准或护栏清理本身就是可靠性的一部分。6.4 SECURITY.md让 Agent 不必猜测安全规则SECURITY.md 规定 Agent 不得自行猜测的安全底线密钥不得硬编码、需文档化受批准的密钥加载路径、日志与截图中的令牌/API 密钥/个人数据必须脱敏外部内容在验证前一律视为不可信记录允许的 fetch/执行边界对提示注入与命令注入风险建立护栏列出需要显式批准的外部动作、默认禁止的生产/破坏性命令优先沙箱安全的工作流新依赖需在活跃计划中给出理由安全敏感变更必须有显式验证步骤重复出现的评审意见应固化为检查而非隐式知识。6.5 其余策略文件FRONTEND / PRODUCT_SENSE / DESIGN模板还包含docs/FRONTEND.mdUI 约束、设计系统规则与可访问性检查、docs/PRODUCT_SENSE.md产品感知与产品领域判断与docs/DESIGN.md设计文档入口。从 AGENTS.md 的路由映射可以看到FRONTEND.md被明确指定为 UI 相关规则的唯一来源它们与docs/design-docs/core-beliefs.md核心信念、docs/product-specs/new-user-onboarding.md产品规格示例一起构成策略可路由、细节可追溯的文档体系。7. SOP 库把文章图表演化成可执行的运行手册高级包的第二个资产是 sops/ 目录它把文章中的运行模式转化为 4 份可遵循或可适配的逐步执行剧本layered-domain-architecture.md建立显式分层与横切关注点边界encode-knowledge-into-repo.md把散落在聊天、文档与记忆中的隐性知识迁移为仓库内文件observability-feedback-loop.md为 Agent 提供日志、指标、trace 与可复现的调试回路chrome-devtools-validation-loop.md用浏览器自动化与快照验证 UI 行为直到变干净clean。使用方法是四步循环按当前瓶颈选择匹配的 SOP → 用其清单补齐缺失产物或工具 → 把产出的规则编码进已复制的repo-template/文档 → 把反复出现的评审意见转化为检查、脚本或护栏。sops 目录的定位声明也很关键这些 SOP 不是让人盲目照做而是为了让 harness 更可读、更可强制、更可复现。8. 设计原则总结与适配建议高级包在docs/ja/resources/openai-advanced/index.md末尾归纳了五条设计原则可作为评估任何 Agent 工作区的判断标尺短入口、深链接的文档入口文件只路由不灌输把仓库当作系统记录system of record知识必须落盘机械检查胜过记忆规则能用 lint/检查强制就别靠提示词约束计划与质量历史放在代码旁上下文就近可得清理与简化是一等公民简化不是事后补课而是常规工作的一部分。最后提醒高级包故意带有观点使用时应结合自身项目裁剪——它给出的是可复制、可强制、可复现的 Agent-first 仓库范式而不是一份放之四海而皆准的教条。若想进一步动手实践可结合仓库的 projects 系列项目如 project-02-agent-readable-workspace 与 project-06-runtime-observability-and-debugging在真实任务中验证这套高级包的效果。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering 高级 OpenAI Pack面向 Codex 的 agent-first 仓库模板与 SOP 实战指南learn harness engineering 高级 OpenAI Pack面向 Codex 的 agent first 仓库模板与 SOP 实战指南 本用 AGENTS.md 搭建 Agent-First 仓库learn-harness-engineering 的 OpenAI 高级路由模板实战指南用 AGENTS.md 搭建 Agent First 仓库learn harness engineering 的 OpenAI 高级路由模板实战指南 导读 本Agent-First 仓库的四大标准操作流程SOPlearn-harness-engineering 中的 OpenAI Advanced SOP 实战手册Agent First 仓库的四大标准操作流程SOPlearn harness engineering 中的 OpenAI Advanced SOP 实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
