以 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 仓库中 repo-template 模板 的DESIGN.md 设计入口文件讲解如何为长时间运行的编码 Agent 建立一套小而新、可路由、可演进的持久化设计决策记录体系。读完本文你将掌握 DESIGN.md 的定位、目录路由约定、四条设计规则以及它与 ARCHITECTURE.md、PLANS.md、QUALITY_SCORE.md 等文档的联动方式可直接照搬到自己的仓库中实践。一、为什么需要一个设计文档入口在 Agent 驱动的开发模式下单一聊天会话、一次 sprint 甚至单个评审者的记忆都无法承载项目的全部上下文。项目设计决策散落在对话历史里等于从未被记录——这正是模板作者反复强调的仓库是 Agent 的 system of record事实记录系统这一核心信念见 core-beliefs.md。repo-template 采用**渐进式披露progressive disclosure**策略入口文件保持短小只做路由细节交给链接指向的专门文档。DESIGN.md 正是这条设计信息链路的入口节点它的职责是保持简洁并路由到docs/design-docs/下更详细的文件。二、DESIGN.md 的目的与定位原文档开门见山地定义了 DESIGN.md 的使命记录应当跨越单个聊天、sprint 或评审者记忆而存续的、持久的产品与系统设计决策。这包含两层含义持久性设计决策一旦作出就写入仓库成为可检索、可引用的资产而不是依赖人的记忆聚焦性只记录设计决策不重复产品规格、不堆砌实现细节——那些由 product-specs 与代码各自负责。三、何时应该阅读 DESIGN.md原文档给出了三个触发场景这也是 Agent 在启动工作流中的路由依据与 AGENTS.md 中的路由映射表相呼应需要当前设计哲学时——新会话、新 Agent 加入项目需要快速理解这个项目为什么这样设计准备引入新模式时——在动手写代码前先检查是否已有既定的设计模式可复用避免场外发明临时架构需要确认哪些决策已敲定、哪些仍未决定时——区分已批准与提案中状态避免 Agent 重复争论或擅自推翻已定决策。四、正式设计文档的路由结构DESIGN.md 只保留两个正式入口全部落在docs/design-docs/下文件职责docs/design-docs/index.md设计文档索引按已批准 / 提案中 / 已废弃分类登记全部设计文档docs/design-docs/core-beliefs.md项目全体的 Agent 优先agent-first核心信念4.1 索引文件设计历史的可发现地图design-docs/index.md 将设计文档分成三个状态区已批准Approved如core-beliefs.md代表当前生效的约束提案中Proposed占位模板[新しいデザインドキュメントのパスをここに追加]供未决决策使用已废弃Deprecated存放被替换的旧文档并附替换链接。同时规定了三条维护规则所有设计文档必须有所有者或更新触发器过时文档要么删除要么标记废弃不许搁置不管活跃的执行计划必须链接到其依赖的设计文档。4.2 核心信念Agent 优先的项目规范core-beliefs.md 用七条信念定义了模板的价值观基线仓库是 Agent 的 system of recordAGENTS.md是路由器不是百科全书验证证据比自信更重要一个边界清晰的任务胜过多个未完成任务反复出现的人类反馈应固化为可复用的 harness 规则清理与简化是交付的一部分不是事后工作Agent 在仓库内找不到的事实视为运营上不可用。这七条信念与 DESIGN.md 的小而新原则互为表里是后续所有设计决策的价值观依据。五、四条设计规则的逐条解读原文档的核心实操内容在于四条设计规则逐条展开如下规则 1设计文档保持小、保持新設計文書は小さく、最新に保つ。小型文档更易被 Agent 完整读取与维护最新意味着陈旧内容本身就是一种误导。这与模板整体的渐进式披露策略一致——入口只做路由细节按需展开。规则 2每个决策领域优先一个文档意思決定領域ごとに1つの文書を優先する。避免把所有决策塞进单一巨型文件。每份设计文档只聚焦一个决策领域配合 index.md 的状态分类使哪个决策已定、哪个未定一目了然Agent 可以精确加载所需上下文。规则 3变更依赖设计文档时从计划与规格链接回设计文档変更が設計文書に依存する場合、プランや仕様から設計文書にリンクする。设计文档不是孤岛。当某个 执行计划 或产品规格依赖某设计决策时必须在计划/规格中反向链接到设计文档形成计划 → 设计的可追溯链。这也正是 AGENTS.md 工作契约中受影响文档必须同步更新的体现。规则 4规则变得运营关键时升级为自动检查或更新 ARCHITECTURE.md設計ルールが運用上重要になった場合、自動チェックに昇格させるかARCHITECTURE.mdを更新する。设计规则是活的约束当某条规则频繁被违反、成为运营关键时不应继续依赖 Agent 自觉遵守而要将其升级为可执行的机械检查lint / test / CI或同步固化到 ARCHITECTURE.md 的严格依赖规则中。ARCHITECTURE.md 中规则应机械强制时添加或更新可执行检查的变更检查清单正是这条规则的落地呼应。六、设计文档与周边体系的联动DESIGN.md 并非孤立文件它与模板中的其他文档形成完整闭环文档与设计文档的关系AGENTS.md启动工作流第 2 步即路由到 ARCHITECTURE.md 与 design-docs是设计文档的消费入口ARCHITECTURE.md承载已升级为硬约束的架构规则理由变化时反向更新设计文档PLANS.md计划依赖设计文档时必须链接回去形成可追溯链QUALITY_SCORE.md以 AD 评分跟踪仓库健康度设计文档的维护质量也是评分维度之一RELIABILITY.md定义可干净重启的完成标准设计文档过时会直接破坏重启路径从 AGENTS.md 的路由映射表可以看到完整的信息流ARCHITECTURE.md系统地图→docs/design-docs/index.md设计决策→docs/product-specs/index.md产品行为→docs/PLANS.md计划生命周期→docs/QUALITY_SCORE.md健康度→docs/RELIABILITY.md运行时信号。DESIGN.md 是这条链路中为什么这样设计的权威入口。七、如何把这一体系应用到你的仓库按 index.md 给出的复制顺序落地将AGENTS.md与ARCHITECTURE.md复制到仓库根目录复制整个docs/目录树包含 DESIGN.md 与 design-docs/先填写docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.md在docs/exec-plans/active/添加第一个活跃计划保持入口文件短小细节一律路由到链接文档——DESIGN.md 本身就是一个可照抄的短入口范本。落地时的具体操作建议新建设计文档在docs/design-docs/下按决策领域创建单主题文档并在docs/design-docs/index.md的提案中区登记决策敲定将文档移入已批准区并在依赖它的计划或规格中加入反向链接决策被替换旧文档移入已废弃区并附替换链接禁止删除后无人知晓规则被反复违反按规则 4 升级为自动检查或在 ARCHITECTURE.md 中强化依赖边界描述。八、小结DESIGN.md 用不到 25 行定义了一套完整的持久化设计决策管理方式一个短小的路由入口、两个正式设计文档位置、四条可操作的设计规则。它的核心价值在于把设计决策从人的记忆与聊天历史中解放出来变成仓库中可检索、可链接、可升级为机械检查的结构化资产——这正是 Agent 优先agent-first工程实践在文档层面的落地形态。将这套体系与 AGENTS.md、ARCHITECTURE.md、PLANS.md 联动使用即可构建一个 Agent 能独立导航、持续演进、干净重启的工程仓库。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐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 入口与持久化设计决策管理 本文以 leAgent-first 仓库中的设计文档入口模式解析 learn-harness-engineering 的 DESIGN.md 模板Agent first 仓库中的设计文档入口模式解析 learn harness engineering 的 DESIGN.md 模板 本篇文章围绕 lear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考