用途
Architecture governance 是用于 ZCode 仓库的架构治理技能,在编辑代码前使用。它既是设计指南也是检查关口:目的是在生成代码之前让目标架构变得明确,使检查器确认既定决策,而不是首次发现架构问题。
主要能力
- 基线检查:运行
pnpm architecture:check --changed获取当前变更的架构基线。资料说明,干净的 diff 并不能识别出尚未编辑的文件。 - 有界上下文生成:对跨模块改动、归属变更或契约不清的情况,运行
pnpm architecture:context <module-id>(或node .agents/skills/architecture-governance/scripts/context-package.mjs <module-id>)生成阅读包。对契约已知的本地改动,只阅读相关契约、规格和受影响的测试,在出现具体依赖或证据缺口时再扩展。 - 规格与回归证据规则:遵循 AGENTS.md 中的规则。新行为在实现前需要规格;恢复已规定行为需要回归证据,而不是重复的功能文档;纯重构仅在契约变化时更新文档。
- 设计决策要求:对可变状态、异步行为或模块边界的改动,在编码前作出决策,包括:
- 单一所有者:为每份可变状态命名唯一的所属组件,其他层通过其契约读取并发送命令,不得保留第二份队列、缓存或派生真值。
- 单一路径:若已有命令、服务、钩子、适配器或契约表达了该行为,就复用;不要为同一职责创建并行辅助组件。
- 显式边界:为每个新文件选择层级,为每条跨模块边编写公共契约。层级由低到高为 contract < domain < app < adapters < ui;文件只能导入自身层级或更低层级,且须通过其公共接口。domain 是纯的(无 IO、不 await 外部世界),app 通过端口决定副作用,adapters 执行它们,ui 仅依赖本模块的 contract.ts。快速判断:需要 await 吗?需要则不是 domain。知道自己是 sqlite / MessagePort / 计时器吗?知道则是 adapters。
- 显式时序:对异步或远程行为,在实现前写明事件顺序、所有者/租约、幂等键、过期结果规则、重放/恢复边界,以及桌面端与移动端的投递类型。
- 有界上下文:使用相关契约、规格和测试。依赖不清时生成阅读包有帮助;不要对每次本地编辑都要求整模块通读。
- 决策记录:若改动改变公共契约、所有权或允许的依赖,在实现前把该决策记录到相关规格/契约中。仅在两个模块中编辑文件本身不需要新文档。根任务边界用于决定何时咨询用户;普通的已授权实现选择可自主进行。
设计草图
资料给出的规划有状态变更的紧凑设计草图:
input → single owner → command admission → state transition → contract/event
└── persistence / replay / projection are derived from the owner
对远程或流式改动,需明确投递边界:
desktop: continuous ── direct live stream ──┐
├─ same owner and sequence
mobile: replayable ─ snapshot + gap repair ┘
使用方式(编辑中与编辑后)
- 把改动限制在声明的模块及其允许的层级方向内;在引入跨模块边之前,先添加模块依赖或公共契约。
- 编辑后运行
pnpm architecture:check --changed。将新违规与基线违规分开报告;受影响时包含所有者和事件顺序假设。 - 遵循根验证矩阵,在所需检查通过后结束;仅因新编辑、失败或未解决风险扩展检查。
- 可执行策略位于
architecture-policy.yaml,详细规则定义保留在其中。在声称关口验证了某边界前,检查实际受管模块覆盖情况:通过结果并不能证明未配置模块或运行时语义正确。 - 仅当经过评审的改动有意变更已接受的遗留基线时,才使用
pnpm architecture:baseline:update。CI 不会自动刷新基线。
新模块注册
packages/ 或 apps/ 下的每个新源文件都必须属于受管模块(规则 unmanaged-new-file)。当改动需要尚未受管的目录时,先注册:
pnpm architecture:adopt <module-id> --root <dir> [--root <dir2>] --layer <domain|app|adapters|ui> [--owner <group>]
adopt 会从实际导入推断 requires,在缺失时搭建四个工件,并在 architecture-policy.yaml 中注册模块,不触碰现有注释。在添加行为前填写 contract.ts 和 CONTRACT.md;让模块公共接口保持每个方法一个意图。
对于新的受管模块,需提供 module.ts、contract.ts、contract.example.ts 和简短的 CONTRACT.md。应用单元测试已退役,不要搭建 contract.test.ts;CLI/CUA 保留各自的测试规则。将运行时与持久化细节藏在契约之后。一对一交互优先使用类型化服务调用,状态变更使用命令,广播事实使用类型化事件。
当改动需要详细指导时,参阅 policy-schema.md、module-contract.md 和 rule-catalog.md;golden-module fixture 是最小的合规示例。参见 ai-guidance.md 了解此工作流旨在防止的反模式,以及代理在提出代码前必须回答的问题。
适用场景
- 在 ZCode 仓库中修改代码前的架构规划与边界确认。
- 跨模块改动、归属变更或契约不清时的有界上下文生成。
- 新增模块的注册与契约搭建。
- 涉及可变状态、异步行为或模块边界的设计决策记录。
限制
- 不适用于纯文档工作。
- 仅面向 ZCode 仓库,依赖该仓库的 pnpm 脚本、架构策略文件和目录约定。
- 资料未提供支持的操作系统、版本要求或性能数据。