企业官网建设流程全解析

本指南围绕 learn-harness-engineering 仓库中docs/de/resources/openai-advanced/repo-template/提供的“扩展 Repo 模板”展开，讲解如何在真实项目中落地 OpenAI 文章《Harness engineering: leveraging Codex in an agent-first world》所倡导的 agent-first 仓库结构。读完本文，你将掌握模板的复制顺序、每一份系统记录文档（System of Record）的职责与填写要点，以及如何让AGENTS.md从“巨型指令文件”蜕变为短小精悍的路由层，从而让长周期 Coding-Agent 协作具备可持续的上下文与质量基线。

一、模板定位：当最小 Harness 不再够用时

learn-harness-engineering 仓库整体讲授“Harness Engineering”入门（从 0 到 1），而 OpenAI Advanced Pack 则把 OpenAI 文章中“更有主见（more opinionated）”的仓库结构封装为可直接复制的启动文件（starter files）。其中的 repo-template/index.md 就是整套扩展模板的入口文档。

模板的使用时机非常明确：当你的仓库已经不能只靠一个最小 Harness 支撑，而需要以下能力时：

• 一份简短、具备路由性质的AGENTS.md（而非百科全书式的巨型指令文件）；
• 仓库内部持久化的 System-of-Record 文档，让 Agent 不必依赖聊天历史；
• 显式的计划生命周期（active / completed / tech-debt）管理；
• 独立的产品、可靠性、安全、前端策略文件；
• 按**产品领域（Product Domain）与架构分层（Architecture Layer）**追踪的质量评分；
• 模型友好（LLM 友好）的参考材料目录；
• 面向架构、知识编码、运行时验证的标准作业程序（SOP）。

模板的优化目标可归纳为五点（原文明确列出）：

1. 持久化的 repo 本地上下文（durable repo-local context）；
2. 渐进式披露（progressive disclosure）代替单一巨型指令文件；
3. 显式的计划生命周期（explicit plan lifecycle）；
4. 随时间推移的质量追踪（quality tracking over time）；
5. 对 Agent 和人类都可读的边界（readable boundaries for agents and humans）。

同时，模板自带重要告诫：其中每一份文件都应视为“启动器（starter）”——在依赖它们之前，必须用自己的真实项目细节替换掉占位符、示例和示例命令。

二、复制顺序：五步把模板搬进真实仓库

repo-template/index.md 给出了明确的“Kopierreihenfolge”（复制顺序），这是落地模板的第一步，必须严格遵循：

1. 将AGENTS.md和ARCHITECTURE.md复制到仓库根目录；
2. 复制整个docs/目录树；
3. 优先填写docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md和docs/RELIABILITY.md三份文件；
4. 在docs/exec-plans/active/下添加第一个活跃计划；
5. 保持入口文件短小，把细节路由（route）到被链接的深层文档。

第 5 步是整个模板的设计哲学核心：入口文件（如AGENTS.md、DESIGN.md）只做“路由”，真正的细节下沉到docs/下的各专项文档，以此实现渐进式披露。

在动手复制前，建议先阅读 docs/de/resources/openai-advanced/index.md 的“如何采用（Wie Sie es übernehmen）”建议：仓库还小时先用最小 Pack，等需要更强结构时再引入本模板；质量、可靠性与计划文档的更新应作为日常工作的组成部分，而不是单独留出一个“清理日”；生成产物（generated artifacts）与外部参考要显式存放，让 Agent 无需依赖聊天历史即可找到它们。

三、模板目录结构总览

OpenAI Advanced Pack 概述 给出了模板的完整目录树，实际文件与之一致：

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

整个结构遵循五条设计原则（来自 index.md）：

• 短入口、深链接（short entry point, deeply linked docs）；
• 仓库即 System of Record；
• 机械化检查优于被记住的规则（mechanical checks beat remembered rules）；
• 计划与质量历史与代码共存（plans and quality history live next to the code）；
• 清理与简化是一等公民任务（cleanup and simplification are first-class tasks）。

下面按功能分组逐一讲解各文件的职责与填写要点。

四、AGENTS.md：路由器，而非百科全书

repo-template/AGENTS.md 是整个模板中最重要的文件之一。它的定位是“为长周期 Coding-Agent 工作而优化”的路由层，明确声明：保持文件简短，把它当作通向 System-of-Record 文档的路由层，而不是巨大的指令仓库。

模板给出了四个组成部分：

1. 开始工作流（Start-Workflow）——改代码前必须依次执行：

1. 用pwd确认处于仓库根目录；
2. 读取ARCHITECTURE.md获取当前系统概览与硬性依赖规则；
3. 读取docs/QUALITY_SCORE.md了解哪些领域/分层最薄弱；
4. 读取docs/PLANS.md，然后打开正在进行的活跃计划；
5. 阅读docs/product-specs/中相关的产品规格；
6. 执行本仓库的标准启动与验证路径（bootstrap + verification）；
7. 若基线验证失败，先修复基线，再添加新范围。

2. 路由地图（Routing-Map）——把每类知识定位到具体文件：

3. 工作契约（Arbeitsvertrag）——Agent 的行为准则：

• 同一时间只从一个有边界（bounded）的计划或功能切片上工作；
• 不能仅凭代码检查就宣布工作完成，必须提供可执行的证据（executable proof）；
• 若改变了行为，必须在同一 Session内更新相关的产品、计划或可靠性文档；
• 若反复看到同类评审反馈，应把它提升为机械规则、检查或 Linter，而不是在聊天里再次解释；
• 生成材料放入docs/generated/，外部源参考放入docs/references/；
• 添加小且新的文档，而不是让AGENTS.md本身不断膨胀。

4. 完成定义（Definition of Done）——一项变更只有在全部满足时才视为完成：

• 目标行为已实现；
• 要求的验证确实执行过；
• 证据已链接到相关计划或质量文档；
• 受影响的文档保持最新；
• 仓库可通过标准启动路径干净地重启。

5. 会话结束（Session-Ende）——退出 Session 前：更新活跃执行计划；若领域/分层显著变化则更新QUALITY_SCORE.md；被推迟的新债务记入docs/exec-plans/tech-debt-tracker.md；适当时把已完成计划移入docs/exec-plans/completed/；让仓库处于可重启状态并留下清晰的下一个动作。

这套“开始 → 路由 → 契约 → 完成定义 → 会话结束”的闭环，与本仓库讲座系列中 lecture-12 关于 Session 必须留下干净状态 的理念一脉相承——模板把教训固化成可复制的文件结构。

五、ARCHITECTURE.md：系统的顶层事实源

repo-template/ARCHITECTURE.md 是“系统的顶层概览”，同样要求保持精炼并在必要时指向更深文档。它包含以下必填区块：

系统形态（Systemform）——用占位符声明：产品名、主要用户工作流、运行时界面（Desktop / Web / CLI / Services / Worker）、产品行为的 Truth Source（指向docs/product-specs/）。

领域地图（Domänen-Map）——表格列出每个领域（Domäne）的：用途（owns what）、主要入口（模块/路由/命令）、关联 Spec 路径。

分层模型（Schichtenmodell）——模板直接给出一条固定的有向分层链：

Types -> Config -> Repo -> Service -> Runtime -> UI

其意图是“让 Agent 不要发明 ad-hoc 架构”：横切关注点必须通过显式的 Provider 或 Adapter 边界进入，而不是直接越层。

硬依赖规则（Harte Abhängigkeitsregeln）：

• 下层不得依赖上层；
• UI 不得绕过 Runtime 或 Service 契约；
• 数据访问必须经由 Repository 或等价 Adapter；
• 公共工具必须保持通用，不得囤积领域逻辑；
• 新依赖应在相应计划或设计文档中给出理由。

横切接口（Querschnittsschnittstellen）——表格登记 Logging/Tracing、Auth、外部 API、Feature Flags 各自的“被允许的边界”与备注（如结构化日志、Token 规则、限流/重试指引）。

当前热点（Aktuelle Hot Spots）——记录“对 Agent 来说最难安全修改的区域”和“边界薄弱或测试脆弱的区域”，让新 Session 一开始就避开雷区。

变更检查清单——触碰架构相关代码时：更新领域地图/允许边界；设计理由变化时更新docs/design-docs/对应文档；若规则需要机械执行，则新增或更新一个可执行检查。

六、docs/ 下的系统记录文档族

6.1 DESIGN.md 与 design-docs/：设计决策的持久化

Docs/DESIGN.md 是设计入口文件，作用同样是“保持简短、路由到细节”。它明确：设计文档用于记录应当超越单个聊天、Sprint 或评审者记忆而长期存续的产品与系统设计决策；当你需要当前设计哲学、准备引入新模式、或需要判断哪些设计决策已定稿/仍开放时，就该读它。

规范的设计文档包括 docs/design-docs/index.md（已接受/建议/已废弃三区索引）与 docs/design-docs/core-beliefs.md（项目级 agent-first 信念）。设计规则包括：保持文档小而新、一个决策领域一个文档、计划与规格中链接相关设计文档、设计规则一旦变得操作上关键就应提升为自动化检查或写入ARCHITECTURE.md。

核心信念文件（core-beliefs.md）列出了七条贯穿项目的主张，堪称模板的“价值观层”：

• 仓库是 Agent 的 System of Record；
• AGENTS.md是路由器，不是百科全书；
• 验证证据比自信更重要；
• 一个有边界（bounded）的任务好过一堆半成品任务；
• 反复出现的人类反馈应固化为可复用的 Harness 规则；
• 清理与简化是交付的一部分，不是事后想法；
• 如果 Agent 无法在仓库中找到某个事实，就把该事实视为“操作上不可用（operationally unavailable）”。

6.2 product-specs/：用户可见行为的规格层

docs/product-specs/index.md 规定：此目录存放当前用户侧行为规格；规格应描述用户可见行为与验收标准；若实现偏离规格，须在同一 Session 内更新其中一方；索引必须保持最新，让新 Agent 能快速把握产品范围。

示例规格 docs/product-specs/new-user-onboarding.md 展示了每个规格的最小骨架：目标（Ziel）、起始条件（Startbedingungen）、用户流程（Benutzerablauf）、验收标准（Akzeptanzkriterien）、错误状态（Fehlerzustände，含可恢复错误与阻塞状态及退路）。这份骨架可以直接复用到任何用户流程的规格化。

6.3 PLANS.md 与 exec-plans/：计划生命周期

docs/PLANS.md 定义计划的创建、更新、完成与归档规则：

• 何时需要计划：工作跨多个 Session、改动多个子系统、存在非平凡的验证/发布风险、或依赖需要被记录的未决决策；
• 存放位置：docs/exec-plans/active/（正在控制工作的计划）、docs/exec-plans/completed/（保留给未来 Agent 上下文的已完成计划）、docs/exec-plans/tech-debt-tracker.md（被推迟的工作与后续任务）；
• 计划的最小章节：目标设定（Zielsetzung）、范围与非范围（Umfang und Nicht-Umfang）、验证路径（Verifikationspfad）、风险与阻塞（Risiken und Blocker）、进度日志（Fortschrittslog）、未决决策（Offene Entscheidungen）；
• 运营规则：活跃计划应有一个明确负责的当前步骤；计划要随工作推进持续更新而非当作静态文本；决策改变实现方向时记入计划；完成的计划移入completed/以便 Agent 继续找到历史上下文。

active/index.md 给出活跃计划的文件命名建议：YYYY-MM-DD-kurzes-thema.md（如2026-09-22-observability-stack.md），并强调每个活跃计划应足够新，让新 Agent 仅凭仓库即可续接工作。

tech-debt-tracker.md 规定只记录“真实、被承认、且被有意推迟”的债务，每行包含：日期、领域、债务描述、推迟原因、风险、下次复核触发条件。

6.4 QUALITY_SCORE.md：随时间推移的健康度追踪

docs/QUALITY_SCORE.md 回答“仓库是变强还是变弱”的问题，提供了一套可直接落地的评分机制：

• 评分标尺：A（已验证、可读、稳定、边界被强制执行）、B（可用但有少量缺口）、C（部分可用、存在明显混乱或不稳定）、D（损坏、不安全或结构不清）；
• 产品领域表：每个领域记录 评分 / 验证方式 / Agent 可读性 / 测试稳定性 / 关键缺口 / 最后更新时间；
• 架构分层表：Types / Services / Runtime / UI 各层记录 评分 / 边界执行情况 / Agent 可读性 / 关键缺口 / 最后更新时间；
• 基准快照表（Benchmark-Momentaufnahmen）：日期 / Harness 变体（Baseline / verbessert / vereinfacht）/ 完成率 / 重复次数 / Review 前错误数 / 备注——这正是本仓库 lecture-10 关于端到端测试改变结果 强调的“以可执行证据说话”的具体化；
• 简化协议（Vereinfachungsprotokoll）：记录每次移除组件后的结果（恶化/不变）与决策（恢复/保持移除），让“减法”也留下审计痕迹。

6.5 RELIABILITY.md：证明系统健康且可重启

docs/RELIABILITY.md 定义“系统如何证明自己健康且可重启”：

• 标准路径（Standardpfade）：Bootstrap 命令、验证命令、启动应用/服务命令、调试或运行时检视命令，全部显式写出；
• 必需运行时信号：启动与关键流程的结构化日志、关键服务的健康检查、慢路径的 Trace/计时数据（若可用）、用户可见的故障状态（针对可恢复故障）；
• 黄金旅程（Golden Journeys）：每条旅程都应有可重复的验证路径与清晰的错误信号；
• 可靠性规则：系统在变更后无法干净重启，则功能不算完成；运行时错误应能由 repo 本地信号诊断；反复出现的错误模式应固化为基准或护栏；清理是可靠性的组成部分，而不是独立的关注点。

6.6 SECURITY.md：不允许 Agent 猜测的安全边界

docs/SECURITY.md 规定 Agent“不得猜测”的安全规则：

• Secrets 与凭据：绝不硬编码 Secrets 到源码或文档；在此文件登记允许的 Secrets 加载路径；日志与截图中遮蔽 Token、API Key 与个人数据；
• 不可信输入：外部内容在验证前一律视为不可信；登记允许的 Fetch/执行边界；存在 Prompt 注入或命令注入风险时记录护栏；
• 外部动作：列出需要显式批准的动作；记录默认不允许 Agent 执行的生产/破坏性命令；调试与验证优先采用沙箱安全工作流；
• 依赖与评审规则：新依赖需在活跃计划中给出理由；安全敏感变更要求显式验证步骤；反复出现的 Security 评审意见应固化为检查，而不是隐含知识。

6.7 FRONTEND.md：可预测的 UI 期望

docs/FRONTEND.md 定义稳定的前端期望，防止 Agent 发明不可预测的 UI 模式：

• UI 原则：清晰优先于新奇；交互流程要可发现、可重启；优先少量可复用组件而非一次性变体；可访问性检查是正常验证的一部分，而不是打磨工作；
• 护栏：设计系统/组件库文档放在docs/references/；捕获关键用户状态（空、加载、成功、错误、重试）；文本、键盘行为与视觉层级在全部流程中保持一致；修复 UI Bug 时同步新增/更新对应验证步骤；
• 验证期望：为关键用户旅程保留证据；浏览器/运行时验证步骤写入对应计划；视觉回归频繁时，标准化截图或 DOM 检查。

6.8 generated/ 与 references/：显式的生成物与参考

• docs/generated/db-schema.md 用于存放生成或推导出的产物，让 Agent 无需从代码反推即可检视（如数据库 Schema）。要求记录“生成自哪个命令/源路径”与“最后更新时间”，并声明“不要手工编辑生成段，底层 Schema 变化时重新生成”。
• docs/references/（含design-system-reference-llms.txt、nixpacks-llms.txt、uv-llms.txt）用于存放供模型读取的外部参考材料，把重复查阅的外部文档固化进仓库，减少 Agent 对外部查询的依赖。

七、PRODUCT_SENSE.md：Agent 无法从代码推演出的产品判断

docs/PRODUCT_SENSE.md 解决一个真实痛点：有些产品判断，Agent 仅凭代码无法可靠推导，必须持久化记录。它包含：

• 产品核心（Produktkern）：主要用户、要完成的任务、要解决的主要挫败点、验收的质量标尺（Quality bar）；
• 产品规则（Produktregeln）：用户可见的可靠性优先于功能数量；把模糊行为视为规格缺口而不是“可以乱猜的许可”；若实现改变了用户所见或所信，更新对应规格；产品规格管具体流程，本文件管跨产品的优先级；
• No-Go 模式：隐藏的破坏性动作、无用户反馈的静默失败、可见状态缺乏清晰 Truth Source、无法用一句话解释的功能。

这份文件与 SOP：把不可见知识编码进仓库 直接呼应。该 SOP 建议：当 Agent 频繁询问系统如何工作、人类说“我们在 Slack 里已经定了”、评审引用仓库外的规则、新 Session 重复已解决的探索时，就应当触发知识编码动作。编码时按知识类型落到对应文件：

• 架构 →ARCHITECTURE.md
• 产品行为 →docs/product-specs/
• 设计理由 →docs/design-docs/
• 执行状态 →docs/exec-plans/
• 反复用到的外部参考 →docs/references/
• 质量/可靠性期望 →docs/QUALITY_SCORE.md或docs/RELIABILITY.md

“完成定义”是：新 Agent 无需问人就能找到相关规则；同一事实不散落在多个相互矛盾的文件中；新产物紧邻它所要控制的代码或工作流。

八、设计原则与采用建议总结

综合整套模板，可以提炼出五条可迁移的设计原则（来自 OpenAI Advanced Pack）：

1. 短入口、深链接：所有顶层文件（AGENTS.md、ARCHITECTURE.md、DESIGN.md）都刻意保持短小，细节交给docs/下的专项文档；
2. 仓库即 System of Record：所有关键事实（架构、产品、质量、计划）都必须能在仓库内找到；
3. 机械化检查优于被记住的规则：反复出现的反馈要固化为检查/Linter/基准，而不是依赖记忆；
4. 计划与质量历史与代码共存：exec-plans/与QUALITY_SCORE.md紧邻代码演进，随日常提交同步更新；
5. 清理与简化是一等公民：tech-debt 追踪、简化协议、Session 结束清单都是交付的一部分。

采用时的三条关键建议：

• 渐进引入：仓库还小的时候先从最小 Harness 起步，需要更强结构时再复制本模板（见 index.md 的采用指引）；
• 先填三件套：复制后优先填写PRODUCT_SENSE.md、QUALITY_SCORE.md、RELIABILITY.md，因为它们是后续所有 Agent 工作的判断基线；
• 把文档更新当作日常工作：模板明确反对“单独留一个清理日”，质量、可靠性与计划文档应随正常开发持续更新，并遵守AGENTS.md中“同一 Session 内同步更新受影响文档”的工作契约。

九、适用前提与限制

需要明确的是，这套模板是有主见的（opinionated），官方文档也强调“应针对你的项目做适配，而不是盲目复制”。落地时请注意：

• 所有占位符（[mit Produktnamen ersetzen]、[domäne-a]、YYYY-MM-DD等）必须在投入使用前替换为真实项目内容；
• 示例命令与示例路径（如docs/references/下的nixpacks-llms.txt、uv-llms.txt）反映的是示例项目的技术栈，需按你的实际构建工具链调整；
• 分层链Types -> Config -> Repo -> Service -> Runtime -> UI是针对该模板设想的典型分层，实际项目应根据自身架构在ARCHITECTURE.md中重写；
• 评分体系（A/B/C/D）与基准快照的价值取决于团队是否持续维护——模板只提供机制，不保证结果。

本仓库中的 讲座系列（尤其是“仓库必须成为 System of Record”“巨型指令文件为何失败”“每个 Session 必须留下干净状态”等主题）为这套模板提供了完整的理论背景，OpenAI Advanced Pack 概述 与 SOP 库 则给出了逐层深入的操作指引，适合作为本模板的配套阅读材料。