企业官网建设流程全解析

learn-harness-engineering 仓库实战：为 Agent 编写可执行、可路由的 ARCHITECTURE.md 系统地图

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering

导读：本指南以 learn-harness-engineering 仓库中内置的repo-template/ARCHITECTURE.md模板（法语版位于 docs/fr/resources/openai-advanced/repo-template/ARCHITECTURE.md）为核心，讲解如何为 Agent-first 项目编写一份"系统级地图"。文章完整剖析模板的七大构成（系统形状、领域地图、分层模型、严格依赖规则、横切接口、当前热点、变更清单），并借助仓库内的配套 SOP 与真实落地示例（project-06 架构文档），让你掌握从占位模板到可运行架构文档的完整方法。

一、ARCHITECTURE.md 在 Agent-first 仓库中的定位

在 OpenAI 提出的 "Harness engineering: leveraging Codex in an agent-first world" 思路中，仓库本身就是 Agent 的"系统记录"（system of record）。而ARCHITECTURE.md是这个系统的顶层地图（top-level map）：它必须保持简洁（stay concise），只回答"系统长什么样、允许哪些依赖方向"，并把更深的细节路由到docs/下的专项文档。

仓库的 repo-template 入口文档 明确列出了该模板优化的目标：

• 持久的仓库本地上下文（durable repo-local context）
• 渐进式披露（progressive disclosure），而不是一个巨型指令文件
• 显式的计划生命周期（explicit plan lifecycle）
• 随时间追踪的质量记录（quality tracking over time）
• 对 Agent 和人类都可读的边界（readable boundaries）

这意味着ARCHITECTURE.md不是给人看的"宣传册"，而是每一轮新会话开始时 Agent 的强制阅读物。配套的 AGENTS.md 在"启动工作流"中规定：改代码之前必须先读ARCHITECTURE.md，以确认"当前系统地图和硬性依赖规则"（第 2 步）。两者一个负责"给规则"，一个负责"路由到规则"，形成闭环。

二、模板解剖：系统形状（System Shape）

模板开头用四个字段勾勒系统全貌，填充后让 Agent 在 10 秒内建立系统直觉：

## Forme du système <!-- 系统形状 --> - Produit : `[replace with product name]` <!-- 产品名 --> - Flux utilisateur principal : `[replace with main workflow]` <!-- 主用户工作流 --> - Surfaces d'exécution : `[desktop / web / cli / services / workers]` <!-- 运行表面 --> - Source de vérité pour le comportement produit : `docs/product-specs/` <!-- 产品行为的事实来源 -->

填写建议：

• 产品名：一句话说清产品，例如 "Knowledge Base Electron App (Capstone)"。
• 主用户工作流：用一个动词短语描述核心链路，如"导入文档 → 索引 → 提问 → 得到带引用的回答"。
• 运行表面：从desktop / web / cli / services / workers中勾选，明确"代码跑在哪"。
• 行为事实来源：模板默认指向docs/product-specs/，与 repo-template 的 docs 目录结构 保持一致——产品行为的验收目标必须写在 spec 里，而不是散落在聊天记录中。

三、领域地图（Domain Map）：让每个模块有明确的"业主"

模板用一张表划分领域，避免 Agent 面对混乱代码库时"随意发明架构"：

三列对应三层信息：

• 目的（Objectif）：这个领域"拥有什么"，即哪些代码、数据、行为归它管；
• 主要入口（Points d'entrée）：模块路径、路由、命令名，让 Agent 知道"改这块从哪里进"；
• 关联规格（Spécification associée）：链接到docs/product-specs/下的具体文档。

落地示例可参考 project-06 架构文档，其中按 Electron 进程划分了四个领域：Renderer (React)、Preload Script、Main Process、Services Layer，每个领域都标注了入口模块（如App.tsx -> DocumentList, DocumentDetail, ImportPanel...）。这种"先画地图、再写代码"的做法，正是分层领域架构 SOP（layered-domain-architecture.md）要求的第一步：先映射代码库为领域，再动手改实现风格。

四、分层模型：Types -> Config -> Repo -> Service -> Runtime -> UI

模板给出一个固定方向模型（fixed directional model），防止 Agent 自行发明临时架构：

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

含义拆解（结合 分层领域架构 SOP）：

• Types：共享类型定义，位于依赖最底层，任何上层都可引用；
• Config：配置解析与读取；
• Repo：数据访问层（仓储 / 适配器）；
• Service：业务逻辑；
• Runtime：运行环境编排（进程、生命周期）；
• UI：用户界面，位于最顶层。

两个关键约束：

1. 方向固定：调用只能从左向右。业务域内禁止 UI 直接访问 Repo 或外部副作用。
2. 横切关注点走显式边界：日志、鉴权、外部 API 等横切关注点必须通过显式的 provider/adapter 边界进入，而不是直接"穿过"各层。共享工具类必须保持通用，不得累积业务逻辑（见模板"严格依赖规则"）。

五、严格依赖规则：把"架构品味"变成可检查的硬约束

模板用五条规则把抽象的分层原则固化为可执行条款：

• 下层不得依赖上层（Lower layers must not depend on higher layers）；
• UI 不得绕过运行时或服务的契约（UI must not bypass runtime or service contracts）；
• 数据访问必须通过仓储或等价适配器进入（Data access must enter through repositories or equivalent adapters）；
• 共享工具必须保持通用，不得累积领域逻辑（Shared utilities must remain generic）；
• 新依赖必须在对应的计划或设计文档中说明理由（New dependencies should be justified in the matching plan or design doc）。

最后一条尤其重要：它把"引入新库"这个动作与 docs/exec-plans/ 的计划生命周期绑定，要求任何依赖变更都有书面理由。

SOP 进一步给出落地顺序：先确定当前"成本最高的边界违规"，再决定哪一条必须机械强制（lint / 测试 / 脚本），而不是靠提醒。这正是 repo-template 设计原则 中"机械检查优于记忆规则"（Les vérifications mécaniques优于 les règles mémorisées）的体现。

六、横切接口表：为日志、鉴权、外部 API、Feature Flags 指定边界

模板用一张"横切接口表"强制为系统级关注点指定唯一入口：

填充要求：每个关注点必须给出具体文件路径作为唯一批准的入口。这一约束的工程价值在于——Agent 需要记日志时只能调指定 provider，需要调外部 API 时只能走指定 client，从根源上避免"各写各的"。

仓库中有现成的结构化日志实践：在 project-06 架构文档 的 Logging 一节，所有日志统一为 JSON 结构（timestamp / level / service / message / data），并按 DEBUG / INFO / WARN / ERROR 分级。这正是横切接口表"structured only, no ad hoc console use"的落地样例。

七、当前热点：主动标记"最难改的区域"

模板要求显式记录两类高风险区域：

• [zone la plus difficile à modifier en toute sécurité pour les agents]：对 Agent 来说最难安全修改的区域；
• [zone avec des limites faibles ou des tests fragiles]：边界薄弱或测试脆弱的区域。

为什么要写这个？因为架构文档的读者是"每轮会话可能失忆"的 Agent。把已知痛点写在地图上，能让新会话直奔风险区做防御，而不是先踩一遍坑。SOP 的检查清单也要求"为当前最难处理的边界违规添加一条简短注释"，并同步更新docs/QUALITY_SCORE.md中对应领域/层的评分。

八、变更清单：架构文档要随代码一起更新

模板末尾用 3 步变更清单，把"维护架构文档"变成改代码时的强制动作：

1. 若领域地图或允许的边界发生变化，更新本文件（ARCHITECTURE.md）；
2. 若设计理由发生变化，更新 docs/design-docs/ 中对应的设计文档；
3. 若规则需要机械强制执行，新增或更新可执行检查（lint / 测试 / 脚本）。

配套的 AGENTS.md 工作契约 呼应了这一要求："如果你改变了行为，必须在同一会话中更新对应的产品、计划或可靠性文档"，并在会话结束时更新QUALITY_SCORE.md、把延期债务记入 tech-debt-tracker.md。

九、与 AGENTS.md 的配合：谁是指南，谁是路由器

需要澄清：ARCHITECTURE.md只是系统地图，不是指令大全。模板的设计哲学是"入口文件保持短小，细节路由到链接文档"（Keep the entrypoint files short and route detail into the linked docs）。

AGENTS.md 的角色是路由层：它提供一张路由表，告诉 Agent 每个问题去哪份文档——架构问题去ARCHITECTURE.md，设计决策去 design-docs/index.md，产品行为去 product-specs/index.md，质量状态去QUALITY_SCORE.md，可靠性信号去RELIABILITY.md。而ARCHITECTURE.md则是路由表里被引用最多的"地图文件"。两者共同构成 knowledge-encoding SOP 所说的"仓库即唯一可发现的事实源"——让新会话不依赖任何历史聊天记录即可行动。

十、完整采用步骤：从占位模板到真实架构文档

综合 repo-template 入口文档 的 Copy Order 与本文前述各节，将模板应用到真实仓库的推荐顺序如下：

1. 复制文件：将AGENTS.md与ARCHITECTURE.md复制到仓库根目录，再整体复制docs/目录树；
2. 先填三份核心文档：docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.md（对应 repo-template docs 目录 中的策略文件）；
3. 填写系统形状与领域地图：替换ARCHITECTURE.md中的全部[replace ...]占位符，确保每个领域都有目的、入口和关联 spec；
4. 落实分层模型与依赖规则：对照Types -> Config -> Repo -> Service -> Runtime -> UI审查现有代码，把横切关注点收敛到 provider/adapter 边界；
5. 记录热点与变更清单：写入当前最难改的区域，并确认变更清单三条与团队流程对齐；
6. 建立第一条执行计划：在docs/exec-plans/active/下添加首个 active plan；
7. 机械强制一条规则：为成本最高的边界违规添加 lint / 测试 / 脚本守护（SOP 的第 6 步）；
8. 把维护纳入日常：将"更新架构文档、更新质量评分、记录技术债务"绑定到每次变更的完成定义中，而不是留到"整理日"。

最终验收标准（来自 分层领域架构 SOP 的"Definition of done"）：一个新 Agent 拿到仓库后，能直接说出某个变更属于哪一层；UI 代码不再直连数据仓库或外部副作用；每个横切关注点都有具名入口；至少有一条重要边界被机械强制执行。做到这四点，你的ARCHITECTURE.md就从"一张图"升级为"一套可执行的架构约束系统"。

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering