企业官网建设流程全解析

导读

本指南聚焦 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 中的"路由映射表"相呼应）：

1. 需要当前设计哲学时——新会话、新 Agent 加入项目，需要快速理解"这个项目为什么这样设计"；
2. 准备引入新模式时——在动手写代码前，先检查是否已有既定的设计模式可复用，避免场外发明临时架构；
3. 需要确认哪些决策已敲定、哪些仍未决定时——区分"已批准"与"提案中"状态，避免 Agent 重复争论或擅自推翻已定决策。

四、正式设计文档的路由结构

DESIGN.md 只保留两个正式入口，全部落在docs/design-docs/下：

4.1 索引文件：设计历史的可发现地图

design-docs/index.md 将设计文档分成三个状态区：

• 已批准（Approved）：如core-beliefs.md，代表当前生效的约束；
• 提案中（Proposed）：占位模板[新しいデザインドキュメントのパスをここに追加]，供未决决策使用；
• 已废弃（Deprecated）：存放被替换的旧文档，并附替换链接。

同时规定了三条维护规则：

1. 所有设计文档必须有所有者或更新触发器；
2. 过时文档要么删除，要么标记废弃，不许搁置不管；
3. 活跃的执行计划必须链接到其依赖的设计文档。

4.2 核心信念：Agent 优先的项目规范

core-beliefs.md 用七条信念定义了模板的价值观基线：

• 仓库是 Agent 的 system of record；
• AGENTS.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 的路由映射表可以看到完整的信息流：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 给出的复制顺序落地：

1. 将AGENTS.md与ARCHITECTURE.md复制到仓库根目录；
2. 复制整个docs/目录树（包含 DESIGN.md 与 design-docs/）；
3. 先填写docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.md；
4. 在docs/exec-plans/active/添加第一个活跃计划；
5. 保持入口文件短小，细节一律路由到链接文档——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 能独立导航、持续演进、干净重启的工程仓库。