分层领域架构 SOP：为 AI Agent 建立可强制执行的分层依赖边界（learn-harness-engineering 实战指南）

导读

本文围绕仓库中 分层领域架构 SOP（Standard Operating Procedure，标准操作流程）展开，讲解如何在 AI Agent 驱动的开发流程中，用显式的领域分层模型（Types -> Config -> Repo -> Service -> Runtime -> UI）解决 Agent 反复越界、跨层复制逻辑、几轮会话后代码难以评审的问题。读完本文，你将掌握一套可直接落地的"目标模型 + 设置清单 + 执行步骤 + 完成定义 + 仓库工件更新"流程，并理解如何把架构规则写进ARCHITECTURE.md、用QUALITY_SCORE.md追踪质量、借助 lint / 测试 / 脚本把最贵的一条边界机械化强制执行。

何时使用这份 SOP

SOP 开篇直接给出了适用信号：当 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 -> UI

• Types：领域类型与数据结构定义，是依赖链的最底层；
• Config：配置读取与解析；
• Repo：数据访问层（repository / adapter）；
• Service：业务服务逻辑；
• Runtime：运行时装配、进程/环境适配；
• UI：用户界面，处于依赖链顶端。

ARCHITECTURE.md 模板 对这套模型的定位解释得很清楚："使用一个固定的方向模型，让 Agent 不要发明 ad-hoc 架构（do not invent ad hoc architecture）"。也就是说，层模型本身就是一种"默认值"——Agent 遇到不确定的归属问题时，先回到这条固定链路判断，而不是临场发挥。

同时还有两条重要的补充规则：

1. 横切关注点通过显式 Provider 或 Adapter 进入。Auth、日志、遥测、外部 API 这类跨领域能力，不允许 UI 直接fetch或 Service 直接打日志，而要走命名清晰的 provider/adapter 边界。
2. 共享 utils 留在领域之外，且不得积累领域逻辑。utils应当保持真正通用（generic），一旦某个函数开始包含业务规则，就说明它放错了位置。

在 英文版 ARCHITECTURE.md 中，这套模型被进一步落实为五条"硬性依赖规则（Hard Dependency Rules）"：

• 下层不得依赖上层（Lower layers must not depend on higher layers）；
• UI 不得绕过 runtime 或 service 契约（UI must not bypass runtime or service contracts）；
• 数据访问必须经由 repositories 或等价 adapter 进入；
• 共享工具必须保持通用，不得积累领域逻辑；
• 新增依赖应在对应的 plan 或 design doc 中说明理由。

设置清单：把边界写进仓库

SOP 的 "Einrichtungs-Checkliste"（设置清单）要求在动手改代码风格之前，先完成五项文档化工作：

1. 在ARCHITECTURE.md中定义当前领域（define the current domains）；
2. 在ARCHITECTURE.md中写明允许的依赖方向；
3. 记录横切接口：如 Auth、Telemetry、外部 API；
4. 为当前最严重的一处边界违规写一句简短备注（Hot Spot）；
5. 决定哪些规则要用 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（横切接口）：一张"关注点 / 批准边界 / 备注"表格，模板内置了四类最常见的横切关注点：

• Current Hot Spots（当前热点）：列出"对 Agent 而言最难安全改动"与"边界薄弱或测试脆弱"的区域；
• Change Checklist（变更清单）：触碰架构相关代码时必须执行的三步（更新领域地图 / 更新 design doc / 新增可执行检查）。

这套模板的价值在于：设置清单里的每一项，都能在模板里找到落点，Agent 和人都能按图索骥。

执行 SOP：七步落地法

SOP 的 "Ausführungs-SOP"（执行流程）给出七步操作顺序，强调"先划分领域地图，再谈实现风格"：

1. 把代码库映射为领域（Map the codebase into domains）——在动任何实现风格之前完成；
2. 为每个领域识别允许的层序列——默认使用目标模型，特殊领域可微调但必须记录；
3. 识别所有横切关注点，并通过 provider 或 adapter 路由；
4. 把模糊的共享逻辑归位：要么下沉到拥有它的领域，要么变成真正通用的 utils，二选一，不留灰色地带；
5. 把规则写进ARCHITECTURE.md；
6. 为代价最高的违规加一条可执行护栏（executable guardrail）；
7. 变更后更新质量评分（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 Done）

SOP 用四个验收标准界定"什么时候算真正完成"：

• 新 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 编排在一起，形成一个完整的工作流：

1. 选择与当前瓶颈匹配的 SOP；
2. 用检查清单补上缺失的工件或工具；
3. 把产出的规则编码进你复制的repo-template/文档；
4. 把重复出现的 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 应用到自己的仓库，可以按如下顺序验证落地情况：

1. 对照模板补齐文档：复制 repo-template 的AGENTS.md、ARCHITECTURE.md与docs/树，按 Kopierreihenfolge（复制顺序）先填PRODUCT_SENSE.md、QUALITY_SCORE.md、RELIABILITY.md，再加入第一个活动计划；
2. 跑一次机械审计：对仓库执行 audit-harness.sh（./tools/audit-harness.sh [repo路径]，零依赖、仅需 bash），观察 CRITICAL 项是否全绿，架构相关检查（check-arch、.harness/arch-rules.json、make check-arch）是否齐备；
3. 验证文档链接与路径：本仓库的 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 都是一份低门槛、高杠杆的起点。