为长时运行的 AI 编码代理设计持久化 HarnessOpenAI 风格仓库模板 AGENTS.md 深度解析【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering本文基于learn-harness-engineering仓库中随附的 OpenAI 风格高级仓库模板docs/ar/resources/openai-advanced/repo-template/展开。该模板专门面向“长时运行的编程代理”long-lived coding agents设计它把传统意义上堆在一个巨大提示文件里的全部知识拆解为一张短小精悍的AGENTS.md入口 一套分层文档树。读完本文你将掌握这套模板的完整目录结构、AGENTS.md的七个关键区块启动工作流、路由地图、工作契约、完成定义、会话收尾、配套文档的职责边界以及如何把模板落地到真实仓库的复制顺序与填充策略。背景为什么 Harness 需要一个“入口文件 文档树”而非巨型提示词learn-harness-engineering仓库在 docs/ar/resources/openai-advanced/repo-template/index.md 中明确交代了这套模板的设计动机当你想让仓库的文档表面documentation surface采用“OpenAI 风格、面向代理”的组织方式而不是仅仅放一个简单 harness 时就可以把这份启动模板复制到真实仓库。模板作者在 docs/ar/resources/openai-advanced/repo-template/index.md 中总结了它相比“单文件巨型指令”的五个改进点仓库内持久的本地上下文知识沉淀在代码仓库中而非聊天历史里渐进式披露progressive disclosure入口文件只给地图细节放在按需加载的文档中显式的计划生命周期执行计划有明确的创建、更新、完成、归档规则跨时间追踪质量QUALITY_SCORE.md记录仓库是变强还是变弱对代理和人类都可读的边界依赖方向、权限边界、验收标准都以文件形式固化。这套思路与仓库整体课程如 “为什么单一巨型指令文件会失败”“为什么初始化需要独立阶段”一脉相承与其把全部约束塞进一个 5000 行的指令文件不如让代理在启动时只读 30 行的地图再按需深入。模板目录结构一览模板位于 docs/ar/resources/openai-advanced/repo-template/完整结构如下repo-template/ ├── AGENTS.md # 代理入口保持简短只做路由 ├── ARCHITECTURE.md # 系统总览地图域、分层模型、依赖规则 └── docs/ ├── DESIGN.md # 设计决策入口指向 design-docs/ ├── FRONTEND.md # 前端约束、设计系统规则、可访问性检查 ├── PLANS.md # 执行计划的生命周期与必填章节 ├── PRODUCT_SENSE.md # 无法从代码推断的产品判断 ├── QUALITY_SCORE.md # 领域/层级质量分级与追踪 ├── RELIABILITY.md # 可重启性、黄金旅程、运行时信号 ├── SECURITY.md # 密钥、不可信输入、外部动作、依赖规则 ├── 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/ # 引用型资料LLM 友好的参考文本关键设计原则是所有入口文件AGENTS.md、ARCHITECTURE.md、DESIGN.md都必须保持简短只负责指路真正的细节沉淀在docs/深层文档中。这也正是模板复制顺序里反复强调的“保持文件短小”的落地形式。AGENTS.md代理的启动工作流Startup Workflow模板 AGENTS.md 的第一条指令就点明了文件定位这个仓库是为长时运行的编程代理优化的把本文件保持简短把它当作一层指向系统参考文档的路由层而不是一份巨大的指令文件。紧接着给出“改代码之前”的 7 步启动工作流用pwd确认仓库根目录读取ARCHITECTURE.md掌握当前系统地图与固定依赖规则读取docs/QUALITY_SCORE.md了解哪些领域或层级最弱读取docs/PLANS.md然后打开当前正在推进的活动计划在docs/product-specs/中读取相关产品规格运行本仓库的标准安装与验证路径如果基础验证失败先修复基础再添加新范围。这套顺序体现了“先读地图 → 再读计划 → 再验证 → 修复基础优先”的初始化纪律代理不是一上来就写代码而是先建立对系统现状、质量短板、活跃计划的认知并确保基线可复现。AGENTS.md路由地图Routing Map启动工作流之后AGENTS.md用一张“路由地图”把各个关注点映射到具体文档模板中的对应关系为关注点路由目标架构地图、分层模型、依赖规则ARCHITECTURE.md设计决策与核心信念docs/design-docs/index.md当前产品行为与验收目标docs/product-specs/index.md计划生命周期与执行计划策略docs/PLANS.md领域与层级健康度docs/QUALITY_SCORE.md运行时信号、性能标准、重启预期docs/RELIABILITY.md密钥、沙箱保护、数据与外部动作规则docs/SECURITY.mdUI 约束、设计系统规则、可访问性检查docs/FRONTEND.md这张表是AGENTS.md的“目录页”其存在意义是代理只需要读这一个短文件就知道任何一个问题该去哪个文档深挖从而避免把文档系统设计成“必须全部读完才能动手”的负担。AGENTS.md工作契约Working Contract路由地图之后是“工作契约”即代理在日常工作中必须遵守的行为准则模板共 6 条一次只推进一个明确的计划或特性切片work against a specific plan or a single feature slice at a time不能只靠“读了代码”就宣布完成需要可执行的证据verifiable evidence如果改变了行为必须在同一会话内同步更新对应的产品文档、计划或可靠性文档反复出现的评审意见要沉淀为自动化把常见的 review 反馈转化为自动规则、检查或格式化工具而不是在对话里反复口头解释明确产物分区生成物generated material放在docs/generated/引用型资料放在docs/references/优先新增小而新的文档而不是持续扩张本文件。其中第 4 条“把重复评审意见变成检查而非口头知识”与仓库在 docs/ar/resources/openai-advanced/repo-template/docs/SECURITY.md 中的同类规则“重复的安全评审意见应该变成检查而不是先验知识”相互呼应是整套模板“把知识固化为仓库构件”理念的体现。AGENTS.md完成定义Definition of Done模板明确规定一个变更只有在以下全部成立时才视为完成目标行为已实现要求的验证实际运行过不是假设会通过证据已链接到对应的计划或质量文档受影响的相关文档仍然保持最新仓库可以从标准启动路径干净地重新启动。这套“完成定义”把“写完代码”与“验证通过 文档同步 可重启”区分开直接对应本仓库课程中“为什么代理过早宣布胜利”这一主题验收的标准不是自我感觉而是可复现的验证与可重启的状态。AGENTS.md会话收尾Session Wrap-Up在结束一次会话之前模板要求代理按顺序完成 5 个动作更新当前活动的执行计划如果任何领域或层级发生显著变化更新docs/QUALITY_SCORE.md如果推迟了技术债记录到docs/exec-plans/tech-debt-tracker.md在适当时机把已完成的计划移动到docs/exec-plans/completed/让仓库保持“可重启 有清晰下一步”的状态。这 5 步正是“每次会话都要留下干净状态”的工程化表达计划是活的、质量分是新的、技术债有归处、完成计划可被未来代理发现、仓库随时可继续。配套文档的职责边界与落地要点AGENTS.md依赖整个docs/树才能真正工作。以下是各配套文档的职责与要点均来自模板源码ARCHITECTURE.md系统总览地图ARCHITECTURE.md 被定位为“系统的顶层地图”要求保持简明并指向更深文档。它包含系统形态产品名、主用户工作流、运行面desktop / web / cli / services / workers、产品行为的 truth sourcedocs/product-specs/领域地图以表格列出每个域的目的、主要入口点modules / routes / commands与相关规格路径分层模型固定方向的分层模型Types - Config - Repo - Service - Runtime - UI并要求公共关注点必须通过显式的 provider / adapter 边界进入而不是跨层直接访问固定依赖规则下层不得依赖上层UI 不得绕过运行时契约与服务数据访问必须经过 repository 或等效 adapter共享工具必须保持通用、不得堆积领域逻辑新依赖必须在计划或设计文档中给出理由公共接口表日志与追踪、认证、外部 API、特性开关各自的批准边界当前热点代理最难安全改动的区域、边界薄弱或测试脆弱的区域变更检查清单改动架构时先更新本文件再更新docs/design-docs/中的设计文档必要时把规则升级为自动化检查。DESIGN.md 与 design-docs/设计决策的入口DESIGN.md 是设计入口职责是记录“能跨越单次对话、单个迭代、单个参考记忆存活”的持久产品与系统设计决策。它定义了“何时阅读”需要当前设计哲学、即将引入新模式、需要区分稳定与未决设计决策时并列出批准的设计文档design-docs/index.md已接受/已提议/已弃用文档索引与 design-docs/core-beliefs.md面向代理优先的项目信念。其设计规则强调文档保持小而新、每个决策域一篇文档、计划与规格要链接设计文档、关键规则升级为自动化检查。PLANS.md 与 exec-plans/执行计划的生命周期PLANS.md 规定何时需要计划工作跨越多会话、涉及多个子系统、存在不平凡的验证/发布风险、或依赖需要记录在案的开放决策。计划存放位置docs/exec-plans/active/当前正在推进的计划docs/exec-plans/completed/已完成计划保留给未来代理发现上下文docs/exec-plans/tech-debt-tracker.md被推迟的工作与跟进事项。每个计划至少包含六个章节目标、范围与范围外、验证路径、风险与阻碍、进度日志、开放决策。运行规则包括每个活动计划必须有一名明确所有者的当前步骤计划随进度更新而非当作静态文本路径变更要记录在计划中完成计划移入completed/。PRODUCT_SENSE.md无法从代码推断的产品判断PRODUCT_SENSE.md 捕获“代理无法仅凭代码可靠推断”的持久产品判断模板填充占位包括核心用户、要完成的任务、要消除的主要挫败点、验收质量水平。其产品规则包括优先用户可见的可靠性而非功能数量把模糊行为当作规格缺口而非猜测许可实现改变用户所见或所信任时同步更新规格使用产品规格处理具体流程、本文件处理通用产品优先级。它还列出拒绝模式隐藏的破坏性动作、无用户反馈的静默失败、可见状态缺乏清晰 truth source、无法用一句话解释的特性。QUALITY_SCORE.md跨时间质量追踪QUALITY_SCORE.md 回答“仓库随时间是在变强还是变弱”采用 A/B/C/D 四级评分A已验证、可读、稳定、边界受执行B可用但有轻微缺口C部分可用、存在明显混乱或不稳定D损坏、不安全或结构不清晰。它要求按产品领域列验证、代理可读性、测试稳定性、主要缺口、最近更新与架构层级Types / Services / Runtime / UI分别评分并提供两张追踪表基准快照表日期、harness 变量、完成率、重试次数、评审前缺陷数与简化日志表被移除组件、结果、决策用于记录简化尝试是否造成退化。RELIABILITY.md可重启性与运行时信号RELIABILITY.md 定义“系统如何证明自己健康且可重启”包含标准路径安装、验证、启动应用/服务、调试或运行时检查四条命令占位要求的运行时信号启动与关键流程的结构化日志、关键服务的健康检查、慢路径的追踪/时序数据如可用、可恢复故障的用户可见错误状态黄金旅程每个旅程都必须有可复现的验证路径与清晰的失败信号可靠性规则任何功能完成后系统必须能干净重启运行时故障必须能从仓库内本地信号诊断反复出现的故障模式要增加基准或保护性护栏清理是可靠性的一部分而非独立关注点。SECURITY.md代理不可猜测的安全规则SECURITY.md 规定密钥与凭据不得硬编码进源码或文档、必须在此记录授权的密钥加载路径、日志与截图中要脱敏令牌/API 密钥/个人数据外部内容在验证前视为不可信、记录允许的抓取/执行边界、存在命令/提示注入风险时记录护栏列出需要显式批准的动作、默认不得由代理执行的破坏性/生产命令、优先在沙箱中做调试与验证新依赖需在活动计划中给出理由、安全敏感变更需显式验证步骤、重复的安全评审意见转化为检查。FRONTEND.md 与其余目录FRONTEND.md负责 UI 约束、设计系统规则与可访问性检查docs/generated/存放生成物模板中已有db-schema.md示例docs/references/存放 LLM 友好的参考文本模板已有design-system-reference-llms.txt、nixpacks-llms.txt、uv-llms.txt等docs/product-specs/承载当前产品行为与验收目标模板已有new-user-onboarding.md示例。落地步骤如何把这个模板复制到真实仓库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/下添加第一个活动计划保持入口文件短小把细节推向被链接的文档。模板同时给出强烈提醒把这里的每个文件都当作起点在依赖它们之前必须用真实项目细节替换所有占位符placeholder、示例与示例命令——例如把[domain-a]、[استبدل]类占位换成真实领域与真实产品判断。与当前仓库课程的关联这套 OpenAI 风格模板与learn-harness-engineering的课程体系高度同构启动工作流对应“初始化需要独立阶段”先读地图与计划再动手完成定义与工作契约对应“代理过早宣布胜利”与“代理过度伸手/欠完成”会话收尾 5 步对应“每次会话留下干净状态”路由地图与渐进式披露对应“单一巨型指令文件为何失败”“仓库必须成为系统 of record”。若你想继续深入可以对照仓库中的 docs/zh/lectures/ 课程与 skills/harness-creator/SKILL.md 技能包把本文的模板落地思路与仓库的实战项目如projects/project-03-multi-session-continuity、projects/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 为长时运行的 AI 编码代理设计持久化 Harness：OpenAI 风格仓库模板 AGENTS.md 深度解析
为长时运行的 AI 编码代理设计持久化 HarnessOpenAI 风格仓库模板 AGENTS.md 深度解析【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering本文基于learn-harness-engineering仓库中随附的 OpenAI 风格高级仓库模板docs/ar/resources/openai-advanced/repo-template/展开。该模板专门面向“长时运行的编程代理”long-lived coding agents设计它把传统意义上堆在一个巨大提示文件里的全部知识拆解为一张短小精悍的AGENTS.md入口 一套分层文档树。读完本文你将掌握这套模板的完整目录结构、AGENTS.md的七个关键区块启动工作流、路由地图、工作契约、完成定义、会话收尾、配套文档的职责边界以及如何把模板落地到真实仓库的复制顺序与填充策略。背景为什么 Harness 需要一个“入口文件 文档树”而非巨型提示词learn-harness-engineering仓库在 docs/ar/resources/openai-advanced/repo-template/index.md 中明确交代了这套模板的设计动机当你想让仓库的文档表面documentation surface采用“OpenAI 风格、面向代理”的组织方式而不是仅仅放一个简单 harness 时就可以把这份启动模板复制到真实仓库。模板作者在 docs/ar/resources/openai-advanced/repo-template/index.md 中总结了它相比“单文件巨型指令”的五个改进点仓库内持久的本地上下文知识沉淀在代码仓库中而非聊天历史里渐进式披露progressive disclosure入口文件只给地图细节放在按需加载的文档中显式的计划生命周期执行计划有明确的创建、更新、完成、归档规则跨时间追踪质量QUALITY_SCORE.md记录仓库是变强还是变弱对代理和人类都可读的边界依赖方向、权限边界、验收标准都以文件形式固化。这套思路与仓库整体课程如 “为什么单一巨型指令文件会失败”“为什么初始化需要独立阶段”一脉相承与其把全部约束塞进一个 5000 行的指令文件不如让代理在启动时只读 30 行的地图再按需深入。模板目录结构一览模板位于 docs/ar/resources/openai-advanced/repo-template/完整结构如下repo-template/ ├── AGENTS.md # 代理入口保持简短只做路由 ├── ARCHITECTURE.md # 系统总览地图域、分层模型、依赖规则 └── docs/ ├── DESIGN.md # 设计决策入口指向 design-docs/ ├── FRONTEND.md # 前端约束、设计系统规则、可访问性检查 ├── PLANS.md # 执行计划的生命周期与必填章节 ├── PRODUCT_SENSE.md # 无法从代码推断的产品判断 ├── QUALITY_SCORE.md # 领域/层级质量分级与追踪 ├── RELIABILITY.md # 可重启性、黄金旅程、运行时信号 ├── SECURITY.md # 密钥、不可信输入、外部动作、依赖规则 ├── 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/ # 引用型资料LLM 友好的参考文本关键设计原则是所有入口文件AGENTS.md、ARCHITECTURE.md、DESIGN.md都必须保持简短只负责指路真正的细节沉淀在docs/深层文档中。这也正是模板复制顺序里反复强调的“保持文件短小”的落地形式。AGENTS.md代理的启动工作流Startup Workflow模板 AGENTS.md 的第一条指令就点明了文件定位这个仓库是为长时运行的编程代理优化的把本文件保持简短把它当作一层指向系统参考文档的路由层而不是一份巨大的指令文件。紧接着给出“改代码之前”的 7 步启动工作流用pwd确认仓库根目录读取ARCHITECTURE.md掌握当前系统地图与固定依赖规则读取docs/QUALITY_SCORE.md了解哪些领域或层级最弱读取docs/PLANS.md然后打开当前正在推进的活动计划在docs/product-specs/中读取相关产品规格运行本仓库的标准安装与验证路径如果基础验证失败先修复基础再添加新范围。这套顺序体现了“先读地图 → 再读计划 → 再验证 → 修复基础优先”的初始化纪律代理不是一上来就写代码而是先建立对系统现状、质量短板、活跃计划的认知并确保基线可复现。AGENTS.md路由地图Routing Map启动工作流之后AGENTS.md用一张“路由地图”把各个关注点映射到具体文档模板中的对应关系为关注点路由目标架构地图、分层模型、依赖规则ARCHITECTURE.md设计决策与核心信念docs/design-docs/index.md当前产品行为与验收目标docs/product-specs/index.md计划生命周期与执行计划策略docs/PLANS.md领域与层级健康度docs/QUALITY_SCORE.md运行时信号、性能标准、重启预期docs/RELIABILITY.md密钥、沙箱保护、数据与外部动作规则docs/SECURITY.mdUI 约束、设计系统规则、可访问性检查docs/FRONTEND.md这张表是AGENTS.md的“目录页”其存在意义是代理只需要读这一个短文件就知道任何一个问题该去哪个文档深挖从而避免把文档系统设计成“必须全部读完才能动手”的负担。AGENTS.md工作契约Working Contract路由地图之后是“工作契约”即代理在日常工作中必须遵守的行为准则模板共 6 条一次只推进一个明确的计划或特性切片work against a specific plan or a single feature slice at a time不能只靠“读了代码”就宣布完成需要可执行的证据verifiable evidence如果改变了行为必须在同一会话内同步更新对应的产品文档、计划或可靠性文档反复出现的评审意见要沉淀为自动化把常见的 review 反馈转化为自动规则、检查或格式化工具而不是在对话里反复口头解释明确产物分区生成物generated material放在docs/generated/引用型资料放在docs/references/优先新增小而新的文档而不是持续扩张本文件。其中第 4 条“把重复评审意见变成检查而非口头知识”与仓库在 docs/ar/resources/openai-advanced/repo-template/docs/SECURITY.md 中的同类规则“重复的安全评审意见应该变成检查而不是先验知识”相互呼应是整套模板“把知识固化为仓库构件”理念的体现。AGENTS.md完成定义Definition of Done模板明确规定一个变更只有在以下全部成立时才视为完成目标行为已实现要求的验证实际运行过不是假设会通过证据已链接到对应的计划或质量文档受影响的相关文档仍然保持最新仓库可以从标准启动路径干净地重新启动。这套“完成定义”把“写完代码”与“验证通过 文档同步 可重启”区分开直接对应本仓库课程中“为什么代理过早宣布胜利”这一主题验收的标准不是自我感觉而是可复现的验证与可重启的状态。AGENTS.md会话收尾Session Wrap-Up在结束一次会话之前模板要求代理按顺序完成 5 个动作更新当前活动的执行计划如果任何领域或层级发生显著变化更新docs/QUALITY_SCORE.md如果推迟了技术债记录到docs/exec-plans/tech-debt-tracker.md在适当时机把已完成的计划移动到docs/exec-plans/completed/让仓库保持“可重启 有清晰下一步”的状态。这 5 步正是“每次会话都要留下干净状态”的工程化表达计划是活的、质量分是新的、技术债有归处、完成计划可被未来代理发现、仓库随时可继续。配套文档的职责边界与落地要点AGENTS.md依赖整个docs/树才能真正工作。以下是各配套文档的职责与要点均来自模板源码ARCHITECTURE.md系统总览地图ARCHITECTURE.md 被定位为“系统的顶层地图”要求保持简明并指向更深文档。它包含系统形态产品名、主用户工作流、运行面desktop / web / cli / services / workers、产品行为的 truth sourcedocs/product-specs/领域地图以表格列出每个域的目的、主要入口点modules / routes / commands与相关规格路径分层模型固定方向的分层模型Types - Config - Repo - Service - Runtime - UI并要求公共关注点必须通过显式的 provider / adapter 边界进入而不是跨层直接访问固定依赖规则下层不得依赖上层UI 不得绕过运行时契约与服务数据访问必须经过 repository 或等效 adapter共享工具必须保持通用、不得堆积领域逻辑新依赖必须在计划或设计文档中给出理由公共接口表日志与追踪、认证、外部 API、特性开关各自的批准边界当前热点代理最难安全改动的区域、边界薄弱或测试脆弱的区域变更检查清单改动架构时先更新本文件再更新docs/design-docs/中的设计文档必要时把规则升级为自动化检查。DESIGN.md 与 design-docs/设计决策的入口DESIGN.md 是设计入口职责是记录“能跨越单次对话、单个迭代、单个参考记忆存活”的持久产品与系统设计决策。它定义了“何时阅读”需要当前设计哲学、即将引入新模式、需要区分稳定与未决设计决策时并列出批准的设计文档design-docs/index.md已接受/已提议/已弃用文档索引与 design-docs/core-beliefs.md面向代理优先的项目信念。其设计规则强调文档保持小而新、每个决策域一篇文档、计划与规格要链接设计文档、关键规则升级为自动化检查。PLANS.md 与 exec-plans/执行计划的生命周期PLANS.md 规定何时需要计划工作跨越多会话、涉及多个子系统、存在不平凡的验证/发布风险、或依赖需要记录在案的开放决策。计划存放位置docs/exec-plans/active/当前正在推进的计划docs/exec-plans/completed/已完成计划保留给未来代理发现上下文docs/exec-plans/tech-debt-tracker.md被推迟的工作与跟进事项。每个计划至少包含六个章节目标、范围与范围外、验证路径、风险与阻碍、进度日志、开放决策。运行规则包括每个活动计划必须有一名明确所有者的当前步骤计划随进度更新而非当作静态文本路径变更要记录在计划中完成计划移入completed/。PRODUCT_SENSE.md无法从代码推断的产品判断PRODUCT_SENSE.md 捕获“代理无法仅凭代码可靠推断”的持久产品判断模板填充占位包括核心用户、要完成的任务、要消除的主要挫败点、验收质量水平。其产品规则包括优先用户可见的可靠性而非功能数量把模糊行为当作规格缺口而非猜测许可实现改变用户所见或所信任时同步更新规格使用产品规格处理具体流程、本文件处理通用产品优先级。它还列出拒绝模式隐藏的破坏性动作、无用户反馈的静默失败、可见状态缺乏清晰 truth source、无法用一句话解释的特性。QUALITY_SCORE.md跨时间质量追踪QUALITY_SCORE.md 回答“仓库随时间是在变强还是变弱”采用 A/B/C/D 四级评分A已验证、可读、稳定、边界受执行B可用但有轻微缺口C部分可用、存在明显混乱或不稳定D损坏、不安全或结构不清晰。它要求按产品领域列验证、代理可读性、测试稳定性、主要缺口、最近更新与架构层级Types / Services / Runtime / UI分别评分并提供两张追踪表基准快照表日期、harness 变量、完成率、重试次数、评审前缺陷数与简化日志表被移除组件、结果、决策用于记录简化尝试是否造成退化。RELIABILITY.md可重启性与运行时信号RELIABILITY.md 定义“系统如何证明自己健康且可重启”包含标准路径安装、验证、启动应用/服务、调试或运行时检查四条命令占位要求的运行时信号启动与关键流程的结构化日志、关键服务的健康检查、慢路径的追踪/时序数据如可用、可恢复故障的用户可见错误状态黄金旅程每个旅程都必须有可复现的验证路径与清晰的失败信号可靠性规则任何功能完成后系统必须能干净重启运行时故障必须能从仓库内本地信号诊断反复出现的故障模式要增加基准或保护性护栏清理是可靠性的一部分而非独立关注点。SECURITY.md代理不可猜测的安全规则SECURITY.md 规定密钥与凭据不得硬编码进源码或文档、必须在此记录授权的密钥加载路径、日志与截图中要脱敏令牌/API 密钥/个人数据外部内容在验证前视为不可信、记录允许的抓取/执行边界、存在命令/提示注入风险时记录护栏列出需要显式批准的动作、默认不得由代理执行的破坏性/生产命令、优先在沙箱中做调试与验证新依赖需在活动计划中给出理由、安全敏感变更需显式验证步骤、重复的安全评审意见转化为检查。FRONTEND.md 与其余目录FRONTEND.md负责 UI 约束、设计系统规则与可访问性检查docs/generated/存放生成物模板中已有db-schema.md示例docs/references/存放 LLM 友好的参考文本模板已有design-system-reference-llms.txt、nixpacks-llms.txt、uv-llms.txt等docs/product-specs/承载当前产品行为与验收目标模板已有new-user-onboarding.md示例。落地步骤如何把这个模板复制到真实仓库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/下添加第一个活动计划保持入口文件短小把细节推向被链接的文档。模板同时给出强烈提醒把这里的每个文件都当作起点在依赖它们之前必须用真实项目细节替换所有占位符placeholder、示例与示例命令——例如把[domain-a]、[استبدل]类占位换成真实领域与真实产品判断。与当前仓库课程的关联这套 OpenAI 风格模板与learn-harness-engineering的课程体系高度同构启动工作流对应“初始化需要独立阶段”先读地图与计划再动手完成定义与工作契约对应“代理过早宣布胜利”与“代理过度伸手/欠完成”会话收尾 5 步对应“每次会话留下干净状态”路由地图与渐进式披露对应“单一巨型指令文件为何失败”“仓库必须成为系统 of record”。若你想继续深入可以对照仓库中的 docs/zh/lectures/ 课程与 skills/harness-creator/SKILL.md 技能包把本文的模板落地思路与仓库的实战项目如projects/project-03-multi-session-continuity、projects/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考