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 dexé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 面对混乱代码库时随意发明架构DomaineObjectifPoints dentrée principauxSpécification associée[domain-a][what it owns][modules / routes / commands][spec path][domain-b][what it owns][modules / routes / commands][spec path]三列对应三层信息目的Objectif这个领域拥有什么即哪些代码、数据、行为归它管主要入口Points dentré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...。这种先画地图、再写代码的做法正是分层领域架构 SOPlayered-domain-architecture.md要求的第一步先映射代码库为领域再动手改实现风格。四、分层模型Types - Config - Repo - Service - Runtime - UI模板给出一个固定方向模型fixed directional model防止 Agent 自行发明临时架构Types - Config - Repo - Service - Runtime - UI含义拆解结合 分层领域架构 SOPTypes共享类型定义位于依赖最底层任何上层都可引用Config配置解析与读取Repo数据访问层仓储 / 适配器Service业务逻辑Runtime运行环境编排进程、生命周期UI用户界面位于最顶层。两个关键约束方向固定调用只能从左向右。业务域内禁止 UI 直接访问 Repo 或外部副作用。横切关注点走显式边界日志、鉴权、外部 API 等横切关注点必须通过显式的 provider/adapter 边界进入而不是直接穿过各层。共享工具类必须保持通用不得累积业务逻辑见模板严格依赖规则。五、严格依赖规则把架构品味变成可检查的硬约束模板用五条规则把抽象的分层原则固化为可执行条款下层不得依赖上层Lower layers must not depend on higher layersUI 不得绕过运行时或服务的契约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 指定边界模板用一张横切接口表强制为系统级关注点指定唯一入口PréoccupationFrontière approuvéeNotesJournalisation et traçage日志与追踪[provider / utility path][structured only, no ad hoc console use]只用结构化日志禁止随手 consoleAuthentification鉴权[provider path][token/session rules]令牌/会话规则APIs externes外部 API[client or provider path][rate limit / retry guidance]限流/重试指引Feature flags特性开关[flag boundary][ownership]归属填充要求每个关注点必须给出具体文件路径作为唯一批准的入口。这一约束的工程价值在于——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 步变更清单把维护架构文档变成改代码时的强制动作若领域地图或允许的边界发生变化更新本文件ARCHITECTURE.md若设计理由发生变化更新 docs/design-docs/ 中对应的设计文档若规则需要机械强制执行新增或更新可执行检查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 与本文前述各节将模板应用到真实仓库的推荐顺序如下复制文件将AGENTS.md与ARCHITECTURE.md复制到仓库根目录再整体复制docs/目录树先填三份核心文档docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.md对应 repo-template docs 目录 中的策略文件填写系统形状与领域地图替换ARCHITECTURE.md中的全部[replace ...]占位符确保每个领域都有目的、入口和关联 spec落实分层模型与依赖规则对照Types - Config - Repo - Service - Runtime - UI审查现有代码把横切关注点收敛到 provider/adapter 边界记录热点与变更清单写入当前最难改的区域并确认变更清单三条与团队流程对齐建立第一条执行计划在docs/exec-plans/active/下添加首个 active plan机械强制一条规则为成本最高的边界违规添加 lint / 测试 / 脚本守护SOP 的第 6 步把维护纳入日常将更新架构文档、更新质量评分、记录技术债务绑定到每次变更的完成定义中而不是留到整理日。最终验收标准来自 分层领域架构 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
