以 DESIGN.md 建立 Agent 优先仓库的设计文档体系：learn-harness-engineering 仓库模板实践

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本篇文章围绕 learn-harness-engineering 开源仓库中 OpenAI 高级仓库模板docs/es/resources/openai-advanced/repo-template/的设计入口文件 DESIGN.md 展开讲解如何在面向长周期编码 Agent 的仓库中建立一套“小而美、可持续演进、可被 Agent 自动发现”的设计文档体系。读完本文你将掌握设计入口文件DESIGN.md的定位与写法、设计文档索引与核心信念的组织方式、设计与执行计划的联动机制以及如何将该模板复制到真实项目中落地。一、DESIGN.md仓库设计系统的入口而非百科全书在 OpenAI 风格的高级仓库模板中DESIGN.md 被定位为设计的入口文件design entrypoint。模板原文明确要求“Keep it brief and use it to route into the more detailed files underdocs/design-docs/”保持简短并用它路由到docs/design-docs/下更详细的文件。这意味着DESIGN.md 本身不承载设计细节它只回答“设计决策记录在哪里、什么时候该读、有哪些规则”详细内容被下沉到docs/design-docs/目录下的独立文档中实现“渐进式披露”progressive disclosure避免出现巨型指令文件——这正是仓库模板所优化的核心目标之一见模板说明。1.1 目的让设计决策比一次会话活得更久DESIGN.md 的开篇即声明其目的Propósito记录应该超越单次对话、单个冲刺或评审者记忆而存续的产品与系统设计决策durable product and system design decisions。这句话点出了设计文档体系存在的根本原因LLM 会话的上下文是有损且易失的。如果设计决策只存在于某一次聊天、某一段评审记录或某个开发者的记忆中那么当新会话启动、新 Agent 加入或人员流动时这些决策就会丢失或被迫重新争论。将决策落盘为文档等于把“知识编码进仓库”这与仓库中 sops 目录下 encode-knowledge-into-repo.md 的思路一脉相承。1.2 何时阅读 DESIGN.md三个触发场景原文档给出了三个“读到它的时候”Lee esto cuando的明确场景这三个场景构成了 Agent 与人类开发者共同的判断条件需要当前的设计哲学necesites la filosofía de diseño actual——例如进入新模块开发前先确认项目的设计取向即将引入新模式estés a punto de introducir un nuevo patrón——任何新的架构模式、编码范式都应先对照既有设计决策避免拍脑袋引入与仓库相悖的实践需要区分“已解决”与“仍开放”的设计决策necesites saber qué decisiones de diseño están resueltas frente a las que aún están abiertas——这是设计文档体系最具价值的能力它让 Agent 不必反复向人类确认早已定案的问题只需查看文档状态。这三个触发条件写清楚后Agent 在启动阶段就能通过阅读入口文件自行判断“现在是否需要碰设计层”从而减少无效探索。二、设计文档体系的骨架索引 核心信念DESIGN.md 作为入口指向两份“规范设计文档”Documentos de diseño canónicos文档作用docs/design-docs/index.md已接受、已提议、已废弃设计文档的索引docs/design-docs/core-beliefs.md项目级 agent-firstAgent 优先核心信念下面结合仓库中的实际文件逐一展开。2.1 设计文档索引可发现的设计历史地图design-docs/index.md 被定义为“设计历史的可发现地图”el mapa descubrible del historial de diseño采用三段式生命周期分类Aceptados已接受当前有效的设计决策模板中示例为core-beliefs.md——即项目的长期信念与规范性约束Propuestos已提议正在讨论、尚未定案的设计提案模板占位符为[add new design doc paths here]等待真实项目填入Deprecados已废弃被新决策取代的旧文档模板要求“连同替代链接一起移入”[move old or superseded design docs here with replacement links]。索引还附带三条维护规则它们直接决定了这套体系能否长期存活每份设计文档应有明确的所有者或更新触发器un propietario o un disparador de actualización过时文档应删除或标记为废弃而不是放任其偏离现状Elimina documentos obsoletos o márcalos como deprecados en lugar de dejar que se desvíen将活跃执行计划链接到其依赖的设计文档Vincula los planes de ejecución activos a los documentos de diseño de los que dependen。这三条规则可以看作设计文档体系的“垃圾回收机制”没有所有者的文档会腐烂没有链接的计划会脱离设计约束没有被废弃标记的旧决策会与现状产生冲突。2.2 核心信念agent-first 的七条仓库级规范core-beliefs.md 是整个模板中最凝练、也最值得逐条落实的内容共七条仓库是 Agent 的系统记录system of record——一切事实以仓库内文档为准AGENTS.md是路由器不是百科全书——入口文件只负责路由不堆积指令验证证据比自信更重要Verification evidence matters more than confidence——完成任务的判定依据是可执行证据而非 Agent 的自我声明一个有边界bounded的任务好过许多半途而废的任务——单任务交付优于多任务摊大饼重复出现的人类反馈应转化为可复用的 harness 规则——把口头经验机械化而不是每次在对话里重讲一遍清理与简化是交付的一部分而非事后想法——代码与文档的整洁度属于验收范围如果 Agent 无法在仓库内发现某个事实就视该事实为“操作上不可用”——仓库之外的信息对 Agent 而言等于不存在。这七条信念不仅是设计文档的内容更是整套 harness 工作流启动流程、完成定义、会话收尾的指导思想。可以将其视为“设计文档的上游宪法”所有具体设计决策都应在这些信念的约束下作出。三、四条设计规则如何让设计文档体系不腐烂DESIGN.md 在末尾给出了四条设计规则Reglas de diseño这是本文档最具操作性的部分也是模板对使用者的直接要求保持设计文档小而新Mantén los documentos de diseño pequeños y actualizados——大文档必然滞后小文档才容易被维护每个决策领域一个文档Prefiere un documento por área de decisión——按决策领域拆分避免把所有设计塞进一个文件当变更依赖某设计文档时从计划plans和规格specs中链接它——建立“计划 → 设计文档”的可追踪引用关系当一条设计规则变得操作上关键时将其提升为自动化检查或更新ARCHITECTURE.mdpromuévela a una verificación automatizada o actualizaARCHITECTURE.md。第四条规则体现了“文档 → 机械化”的演进路径设计规则最初是文档中的文字约束随着其重要性上升最终应固化为 linter、测试或 CI 检查由机器强制执行而不再依赖 Agent 自觉遵守。这与 AGENTS.md 工作契约中“把重复评审反馈提升为机械规则、检查或 linter”的要求完全一致。3.1 规则的上游ARCHITECTURE.md 中的依赖纪律当设计规则“操作上关键”时它们的落点之一是 ARCHITECTURE.md。该文件作为系统顶层地图提供了可被 Agent 直接引用的架构纪律包括系统形态Forma del sistema产品名、主用户流程、执行面桌面/Web/CLI/服务/Worker、产品行为唯一真相源docs/product-specs/领域地图Mapa de dominios用表格列出各领域、职责、主要入口点与关联规格固定方向的分层模型Modelo de capasTypes - Config - Repo - Service - Runtime - UI横向关注点必须经由显式的 Provider/Adapter 边界进入禁止跨层直取严格依赖规则Reglas estrictas de dependencia下层不得依赖上层、UI 不得绕过运行时与服务契约、数据访问必须经由 Repository 或等价适配器、共享工具必须保持通用、新依赖须在计划或设计文档中说明理由变更检查清单改动架构相关代码时依次更新ARCHITECTURE.md、更新docs/design-docs/中相关文档、为需要机械化执行的规则补充可执行检查。可见DESIGN.md 与 ARCHITECTURE.md 的分工是清晰的前者记录“为什么这样设计”的决策历史后者记录“系统现在长什么样”的静态地图前者演进后者同步。四、与执行计划联动设计决策如何进入日常开发DESIGN.md 的规则 3 要求“从计划与规格中链接设计文档”这意味着设计体系必须与计划体系对接。模板中的 PLANS.md 定义了执行计划的生命周期是设计文档的下游消费方何时需要计划工作跨越多个会话、改动多个子系统、存在非平凡的验证/部署风险、或依赖需记录在案的开放决策时计划存放位置docs/exec-plans/active/正在指导工作的计划、docs/exec-plans/completed/已完成、为未来 Agent 保留上下文的计划、docs/exec-plans/tech-debt-tracker.md被推迟的工作与后续事项计划的最少章节目标、范围与范围外、验证路径、风险与阻塞、进度日志、开放决策运行规则活跃计划必须有明确指派的当前步骤计划随工作推进而更新不能当作静态文本若某个决策改变实现方向必须记入计划完成后移入completed/让 Agent 能发现历史上下文。在真实工作流中Agent 的典型路径是启动时读ARCHITECTURE.md与AGENTS.md→ 按路由表进入docs/design-docs/index.md确认相关设计决策 → 打开docs/exec-plans/active/中的活跃计划 → 若变更依赖某项设计决策则在计划中链接对应设计文档 → 实施 → 更新计划与受影响文档 → 移入 completed。这一闭环保证了“设计决策 → 执行计划 → 代码变更 → 文档同步”全程可追踪。五、在 harness 工作流中落地从路由到完成定义设计文档体系只有在被 Agent 实际“走通”时才产生价值。模板的 AGENTS.md 把设计文档纳入了启动与收尾流程启动流程7 步确认仓库根目录pwd→ 读ARCHITECTURE.md获取系统地图与依赖规则 → 读docs/QUALITY_SCORE.md了解薄弱领域 → 读docs/PLANS.md并打开活跃计划 → 读docs/product-specs/相关规格 → 执行标准启动与验证路径 → 若基线验证失败先修复基线再扩展范围路由表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 约束完成定义Definition of done目标行为已实现、所需验证真实执行过、证据已从计划或质量文档链接、受影响文档保持更新、仓库能从标准启动路径干净重启——注意“仅凭代码审查通过”不算完成必须有可执行证据这正是核心信念第 3 条“验证证据比自信更重要”的落地会话收尾5 步更新活跃计划 → 若领域/层有显著变化则更新docs/QUALITY_SCORE.md→ 将推迟的工作记入tech-debt-tracker.md→ 适时把完成的计划移入completed/→ 让仓库处于可重启、有明确下一步的状态。这套流程与 lecture-12-why-every-session-must-leave-a-clean-state 系列课程的主题相互印证每次会话都要留下干净、可重启的状态设计文档的更新正是“干净状态”的一部分。六、把模板引入真实项目复制顺序与填充优先级最后模板说明 index.md 给出了将该设计文档体系复制到真实仓库的具体操作顺序将AGENTS.md与ARCHITECTURE.md复制到仓库根目录复制整个docs/目录树先填充docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.md在docs/exec-plans/active/添加第一个活跃计划保持入口文件简短把细节路由到被链接的文档中。同时模板明确提醒模板中所有占位符如设计索引中的[add new design doc paths here]、架构文档中的[replace with product name]等都必须替换为真实项目内容后才能投入使用。模板优化的目标包括仓库内持久上下文、渐进式披露而非巨型指令文件、显式的计划生命周期、随时间跟踪的质量、对 Agent 与人类都可读的边界。如果你希望对比设计文档体系的原始英文表述可参阅英文原版 DESIGN.md (en) 与 core-beliefs.md (en)。结语DESIGN.md 虽短却是一套可运转的设计文档体系的“启动器”它以入口文件定位自身以索引index.md管理设计决策生命周期以核心信念core-beliefs.md确立 agent-first 的价值观以四条设计规则防止体系腐烂并通过 AGENTS.md、PLANS.md、ARCHITECTURE.md 与执行计划和会话生命周期紧密联动。对于任何希望让长周期编码 Agent 稳定、可预测地工作的仓库这套“小入口 深文档 机械化规则”的模板都值得直接复制并按上述顺序落地。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐在 learn-harness-engineering 的 OpenAI 高级仓库模板中建立 Agent 优先的设计文档体系DESIGN.md 设计入口全解在 learn harness engineering 的 OpenAI 高级仓库模板中建立 Agent 优先的设计文档体系DESIGN.md 设计入口全解learn-harness-engineering 仓库模板的设计文档体系以 DESIGN.md 为入口的 Agent 友好设计决策档案learn harness engineering 仓库模板的设计文档体系以 DESIGN.md 为入口的 Agent 友好设计决策档案 导读 本文围绕 leAgent-first 仓库中的设计文档入口模式解析 learn-harness-engineering 的 DESIGN.md 模板Agent first 仓库中的设计文档入口模式解析 learn harness engineering 的 DESIGN.md 模板 本篇文章围绕 lear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考