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），仅供参考
企业数字化 ERP 产品动态
相关推荐
企业级智能体效能管理：从可度量到可治理的实战指南 1. 企业级智能体效能管理到底在解决什么问题1.1 从“能跑起来”到“跑得可控”的转折点过去一年，我参与过好几个企业内部的智能体落地项目，从最早的“搭个Demo给领导看”到后来真正接入业务系统，中间踩的坑几乎都指向同一个问题：智… · 2026/9/23 9:14:33
什么样的网站项目算复杂项目？从产品、后台、多语言到服务器来看 很多企业在询网站建设项目时会发现一个现象：有的网站页面不算多，但开发周期长、报价高；有的网站页面很多，两三万元就能完成。原因在于，网站复杂不复杂，不能只看页面数量。先看两份询价单。B 的页面更少&… · 2026/9/23 9:14:33
开源自托管AI代码审查工具：从零搭建到落地实践 周一早上打开 GitHub，列在 Assign 给我的 PR 有 40 多个，排在最上面的是一个改了 600 行的 Python 后端重构，下面还有一个改到一半的前端组件，CI 倒是全绿，但里面到底有没有隐藏问题，我只能凭肉眼一屏一屏往… · 2026/9/23 9:14:27
3个坑搞懂上twitter：实战项目从零到一 3个坑搞懂上twitter：实战项目从零到一 官方文档翻了三遍还是觉得像天书？别急，这种“文档太长抓不住重点”的焦虑，在搞后端和自动化脚本的同行里太常见了。很多人想搞个自动发推的 实战项目 ，结果卡在API密钥配置上，或者被Rate… · 2026/9/23 10:53:57
基于Python协同过滤的电影推荐系统毕业设计实战指南 简介：这份资源是面向计算机相关专业毕业设计场景的完整项目包，主题为基于Python与协同过滤算法的电影推荐系统，适合需要完成毕设、课程设计或自学推荐算法与Web开发的学生参考。项目采用Django框架搭配MySQL数据库，区分管理员与用… · 2026/9/23 10:53:57
炸裂，ICONIP也来一篇GraphRAG 今天分享一篇被 ICONIP 2026 接收、来自墨尔本理工学院的论文GRASP。
一句话方案：学生把n道题的答案混写成一段无标记文字，系统用图增强检索GRAG从参考库里捞回全部黄金参考、匈牙利算法一对一配对后逐段打分——零训练数据，n3时黄金参考捞回… · 2026/9/23 10:53:51
通信工程面试避坑：3个高频API陷阱与新手实战指南 通信工程面试避坑：3个高频API陷阱与新手实战指南 刚拿到通信工程offer的应届生，最崩溃的时刻往往不是八股文背不完，而是面试时面试官轻描淡写问一句：“说说你对TCP握手握手的理解？”你张嘴就来三次握手，结果对方追问：“如果第三次ACK丢… · 2026/9/23 10:53:51
Atlas 300V 24G上跑通YOLOv5：环境搭建、模型转换与ACL推理实战 1. 先搞明白Atlas 300V 24G接手的是一张什么卡我在昇腾生态里摸爬滚打两年多，说句实在话，Atlas系列卡是目前市面上极少数能“自研芯片完整工具链”走通AI推理落地的产品线。很多朋友第一次接触Atlas 300V 24G时，习惯性把它当成一张“类GPU”的… · 2026/9/23 10:53:44
Atlas 300V 24G推理卡部署YOLO实战：从模型转换到MindX流水线 当同事把一块Atlas 300V 24G加速卡递到我手里，开口就问“这卡能不能跑YOLO”的时候，我愣了一下。不是因为问题难，而是因为“能跑”和“跑得好”在昇腾生态里完全是两码事。再加上“Atlas 300V 24G到底是不是运算加速卡”这种最基础的问题&… · 2026/9/23 10:53:38
3招搞定手机怎么下载微信面试难题实战项目解析 3招搞定手机怎么下载微信面试难题实战项目解析 面试被问“手机怎么下载微信”背后的原理，90%的人答不上来。别笑，这看似弱智的问题，实则是考察你对移动应用分发机制、安全校验及网络协议理解的试金石。我带过不少校招新人，他们背了八股文，却连一个A… · 2026/9/23 0:00:03
你有新短消息请注意查收：3个新手避坑指南搞定消息系统选型 你有新短消息请注意查收：3个新手避坑指南搞定消息系统选型 面试被问“高并发下如何保证消息不丢失”，你张口就是“用Redis”，结果面试官追问“如果Redis宕机了怎么办”，你瞬间卡壳。这种场景太常见了，很多新手在背八股文时，只记住了技术名词… · 2026/9/23 0:00:29
