【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本文围绕仓库中 分层领域架构 SOPStandard Operating Procedure标准操作流程展开讲解如何在 AI Agent 驱动的开发流程中用显式的领域分层模型Types - Config - Repo - Service - Runtime - UI解决 Agent 反复越界、跨层复制逻辑、几轮会话后代码难以评审的问题。读完本文你将掌握一套可直接落地的目标模型 设置清单 执行步骤 完成定义 仓库工件更新流程并理解如何把架构规则写进ARCHITECTURE.md、用QUALITY_SCORE.md追踪质量、借助 lint / 测试 / 脚本把最贵的一条边界机械化强制执行。何时使用这份 SOPSOP 开篇直接给出了适用信号当 Agent 不断违反边界violates boundaries、在层与层之间重复逻辑duplicating logic across layers、或者只经过几次会话就产出难以 review 的代码时就应当引入分层领域架构 SOP。这些信号在 Agent 长期驻留的仓库里尤其常见没有显式边界时Agent 倾向于就近实现——UI 组件里直接写数据访问、Service 里混入外部 API 调用、共享 utils 慢慢膨胀成垃圾桶。SOP 的核心立场是与其靠提示词临时约束不如把边界变成仓库里可读、可查、可执行的显式事实。这与本仓库repo-template中 core-beliefs.md 的第一条信念一脉相承仓库是 Agent 的 System of Record事实系统。目标模型一个固定方向的依赖流SOP 给出的目标模型极其精炼——在单个业务领域内代码依赖应当遵循一个固定的方向流Types - Config - Repo - Service - Runtime - UITypes领域类型与数据结构定义是依赖链的最底层Config配置读取与解析Repo数据访问层repository / adapterService业务服务逻辑Runtime运行时装配、进程/环境适配UI用户界面处于依赖链顶端。ARCHITECTURE.md 模板 对这套模型的定位解释得很清楚使用一个固定的方向模型让 Agent 不要发明 ad-hoc 架构do not invent ad hoc architecture。也就是说层模型本身就是一种默认值——Agent 遇到不确定的归属问题时先回到这条固定链路判断而不是临场发挥。同时还有两条重要的补充规则横切关注点通过显式 Provider 或 Adapter 进入。Auth、日志、遥测、外部 API 这类跨领域能力不允许 UI 直接fetch或 Service 直接打日志而要走命名清晰的 provider/adapter 边界。共享 utils 留在领域之外且不得积累领域逻辑。utils应当保持真正通用generic一旦某个函数开始包含业务规则就说明它放错了位置。在 英文版 ARCHITECTURE.md 中这套模型被进一步落实为五条硬性依赖规则Hard Dependency Rules下层不得依赖上层Lower layers must not depend on higher layersUI 不得绕过 runtime 或 service 契约UI must not bypass runtime or service contracts数据访问必须经由 repositories 或等价 adapter 进入共享工具必须保持通用不得积累领域逻辑新增依赖应在对应的 plan 或 design doc 中说明理由。设置清单把边界写进仓库SOP 的 Einrichtungs-Checkliste设置清单要求在动手改代码风格之前先完成五项文档化工作在ARCHITECTURE.md中定义当前领域define the current domains在ARCHITECTURE.md中写明允许的依赖方向记录横切接口如 Auth、Telemetry、外部 API为当前最严重的一处边界违规写一句简短备注Hot Spot决定哪些规则要用 lint、测试或脚本机械化强制mechanically enforced。对照 repo-template 的 ARCHITECTURE.md模板本身就为这五项预留了对应章节System Shape系统形态产品名、主用户工作流、运行时表面desktop / web / cli / services / workers、产品行为的事实来源docs/product-specs/Domain Map领域地图一张四列表格领域 / 目的 / 主要入口点 / 关联 Spec逐行声明这个领域拥有什么Layer Model层模型即上文的方向流Hard Dependency Rules硬依赖规则五条 MUST/NOT 级别的规则Cross-Cutting Interfaces横切接口一张关注点 / 批准边界 / 备注表格模板内置了四类最常见的横切关注点关注点批准边界占位备注占位日志与追踪[provider / utility 路径]仅结构化日志禁止 ad-hoc consoleAuth[provider 路径]token/session 规则外部 API[client 或 provider 路径]限流 / 重试指引功能开关[flag 边界]归属方Current Hot Spots当前热点列出对 Agent 而言最难安全改动与边界薄弱或测试脆弱的区域Change Checklist变更清单触碰架构相关代码时必须执行的三步更新领域地图 / 更新 design doc / 新增可执行检查。这套模板的价值在于设置清单里的每一项都能在模板里找到落点Agent 和人都能按图索骥。执行 SOP七步落地法SOP 的 Ausführungs-SOP执行流程给出七步操作顺序强调先划分领域地图再谈实现风格把代码库映射为领域Map the codebase into domains——在动任何实现风格之前完成为每个领域识别允许的层序列——默认使用目标模型特殊领域可微调但必须记录识别所有横切关注点并通过 provider 或 adapter 路由把模糊的共享逻辑归位要么下沉到拥有它的领域要么变成真正通用的 utils二选一不留灰色地带把规则写进ARCHITECTURE.md为代价最高的违规加一条可执行护栏executable guardrail变更后更新质量评分update quality scoring。第 6 步可执行护栏是本 SOP 区别于普通文档的地方规则不能只停留在 markdown 里至少要有一条被机器强制执行。仓库中的 audit-harness.sh 提供了一个零依赖的 shell 审计示例——它把 CRITICAL / RECOMMENDED 两档检查组织成check_critical/check_recommended函数逐项检查 AGENTS.md 是否在头 10 行回答这是什么系统、是否列出验证命令、是否声明 MUST/MUST NOT 约束等全部命中时退出码为 0否则为 1。这种规则即脚本、脚本即退出码的模式就是第 6 步想达到的效果。另外audit 脚本中的 L10 区块提示了架构边界的机械化手段make check-arch调用scripts/check-arch.sh规则注册在.harness/arch-rules.json每条规则必须包含what/why/fix三个字段——违规时输出哪里错了 / 为什么错 / 怎么修让 Agent 能直接按修复指引行动。这正是把反复出现的 review 意见提升为规则的落地方案SOP 索引页也强调了这一点把重复的 review 评论变成检查、脚本或护栏。完成定义Definition of DoneSOP 用四个验收标准界定什么时候算真正完成新 Agent 能判断一次改动归属哪一层——结构可读性是可验证的UI 代码不再直接触碰 repo 或外部副作用——边界禁令有明确的观察对象横切关注点都有命名入口点——不再是谁需要谁自己调至少一条重要边界被机械化强制——文档之外有脚本/测试兜底。这四个标准全部可被自动或半自动检查第一条靠ARCHITECTURE.md的 Domain Map 与 Layer Model 是否清晰第二条靠代码搜索与 review第三、四条则依赖 lint / 测试 / CI 脚本。完成定义的意义在于给 Agent 一个不自欺的截止信号——它不能仅凭我改完了就宣告胜利而要能指出哪一层拥有这次改动。需要同步更新的仓库工件SOP 明确列出改动之后必须同步维护的四个仓库工件ARCHITECTURE.md领域地图或允许边界变化时必改docs/QUALITY_SCORE.md每次结构性变更后更新质量评分docs/design-docs/当设计理由rationale发生变化时更新docs/PLANS.md或当前活动执行计划依赖关系变化要反映在计划中。模板仓库中的 QUALITY_SCORE.md 给出了具体的评分机制用A/B/C/D四档A已验证、可读、稳定、边界被强制B可用但有小的缺口C部分可用、有明显混乱或不稳定D损坏、不安全或结构不清分别按产品领域和架构层两张表格打分每行记录验证方式、Agent 可读性、测试稳定性、关键缺口与最近更新时间。此外还预留了 Benchmark 快照表和简化日志Simplification Log后者专门记录删掉了某个组件后结果变好还是变坏用于防止过度简化。计划侧则由 PLANS.md 模板 管理跨会话、跨子系统、有验证/发布风险、依赖未决决策的工作必须创建执行计划计划存放在docs/exec-plans/active/进行中、docs/exec-plans/completed/已完成保留供后续 Agent 参考、docs/exec-plans/tech-debt-tracker.md技术债跟踪三个位置每个计划至少包含目标、范围与范围外、验证路径、风险与阻碍、进度日志、未决决策六个小节。这与 DESIGN.md 模板 的规则互相呼应——当一条设计规则变得操作关键时就把它提升为自动化检查或更新到ARCHITECTURE.md。与相邻 SOP 的配合使用OpenAI Advanced SOPs 索引 把分层领域架构 SOP 与其他三条 SOP 编排在一起形成一个完整的工作流选择与当前瓶颈匹配的 SOP用检查清单补上缺失的工件或工具把产出的规则编码进你复制的repo-template/文档把重复出现的 review 评论转化为检查、脚本或护栏。其中encode-knowledge-into-repo.md把不可见知识编码进仓库与分层领域架构 SOP 是天然的上下游关系架构类知识写入ARCHITECTURE.md、设计理由写入docs/design-docs/、执行状态写入docs/exec-plans/、质量/可靠性期望写入QUALITY_SCORE.md或RELIABILITY.md而 observability-feedback-loop.md可观测性反馈环则确保 Agent 能基于运行时证据论证而不是只靠读代码——两者共同保证结构边界与行为验证都不再依赖人的口头记忆。在真实仓库中的验证路径如果你想把本文的 SOP 应用到自己的仓库可以按如下顺序验证落地情况对照模板补齐文档复制 repo-template 的AGENTS.md、ARCHITECTURE.md与docs/树按 Kopierreihenfolge复制顺序先填PRODUCT_SENSE.md、QUALITY_SCORE.md、RELIABILITY.md再加入第一个活动计划跑一次机械审计对仓库执行 audit-harness.sh./tools/audit-harness.sh [repo路径]零依赖、仅需 bash观察 CRITICAL 项是否全绿架构相关检查check-arch、.harness/arch-rules.json、make check-arch是否齐备验证文档链接与路径本仓库的 validate-project-docs.ts 展示了如何程序化校验文档中的仓库相对路径是否存在——这正是文档即事实的工程化保障写进文档的每个路径都能被脚本验证防止文档与代码脱节。前提说明以上验证步骤以本仓库当前内容为准audit-harness.sh针对的是按本课程模式搭建的 Agent 仓库包含 AGENTS.md/CLAUDE.md、PROGRESS.md、feature_list.json 等五类子系统应用于其他形态的仓库时需按需裁剪。小结分层领域架构 SOP 的核心是一句话让领域边界显式到 Agent 可以快速前进、却无法悄悄破坏结构的程度。它用一条固定依赖流Types - Config - Repo - Service - Runtime - UI提供默认架构用ARCHITECTURE.md固化领域地图与硬规则用 provider/adapter 收拢横切关注点用QUALITY_SCORE.md追踪结构健康度最后用至少一条机械化边界把最重要的规则从文档变成可执行护栏。对任何想让 Agent 长期安全地修改代码库的团队这份 SOP 都是一份低门槛、高杠杆的起点。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐学习 Harness Engineering分层领域架构 SOP——让 Agent 不再跨层越界的可执行边界治理方案学习 Harness Engineering分层领域架构 SOP——让 Agent 不再跨层越界的可执行边界治理方案 分层领域架构Layered Domailearn-harness-engineering 分层领域架构 SOP让 Agent 不再越界、重复与退化learn harness engineering 分层领域架构 SOP让 Agent 不再越界、重复与退化 导读 本文讲解 learn harness enLearn Harness Engineering 实战指南为 AI 编码 Agent 构建可靠的 Harness 运行环境Learn Harness Engineering 实战指南为 AI 编码 Agent 构建可靠的 Harness 运行环境 导读 本文基于 learn h创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考