Module Governance(模块治理)是一个编排型技能,用于在实现新业务模块或进行已授权的模块边界变更时,建立或维护该模块的本地智能体指令、领域上下文链接与接口归属。它把模块级工作规则连接到既有的领域语言、契约和决策上,本身不构成第二套 DDD 方法论,也不是自动文档生成器。
【何时启用】 用户要求实现一个新的业务模块(无需点名本技能);用户要求为现有模块编写文档,或维护已确认的职责变更;已授权的模块变更需要本地指令和规范知识指针。普通缺陷修复、样式调整、边界不变的内部重构,以及仅继承父级约定的新目录或 UI 组件,都不应启动本技能。若仅为设计讨论或审计,应只检查并报告,不创建文件。基于意图的选择不是后台钩子,也不授予对无关代码、提交、推送或业务选择的权限。
【工作方式】
- 创建文档前先发现边界:阅读适用的项目及祖先 harness 指令、现有地图、需求、相关代码与契约,识别模块的职责、非职责、状态归属和实际消费方。仅凭目录名不能确立限界上下文,遇到实质歧义应提出而非编造业务规则。对既有边界变更,先用 change-impact,其只读与授权约束同样适用,不要跑无关的开发流程。
- 区分项目级规则与本地规则:项目级指令源负责全局约束、模块导航和跨模块协作;本地 AGENTS.md 只负责额外的模块约束,如职责、状态归属、公共接口指针和验证入口。本地规则不能豁免项目级约束。已有 CLAUDE.md 或其他生效的 harness 表面应复用,不要强制改名或维护两份副本。若父级指令已覆盖该模块且无缺失本地规则,则链接该来源,不创建冗余本地文件。遵循既有的显式本地入口要求。不要声称 harness 会自动加载每个嵌套指令文件。
- 复用现有知识归属:稳定术语与概念关系归 context-and-decisions(使用现有术语表或上下文角色);难以逆转的决策及理由归 architecture-decision-records(通过现有上下文交接);跨边界可机器校验的接口归 contract-first;文档导航与生命周期归 living-docs-governance;受影响消费方与边界变更证据归 change-impact。需要时加载对应技能,不要在此重复其方法。术语保存在相关的现有 CONTEXT.md 或等价物中,而非 AGENTS。同一业务上下文中的前端与后端可共享该术语表;UI 特定工作规则可以本地化,而不必为每个页面建术语表。复用现有契约和 ADR 时应引用而非复制其正文。
- 只维护已授权的记录:在用户请求的模块工作范围内,更新最小缺失的本地规则和已确认的上下文条目。受影响导航与生命周期更新使用 living-docs-governance,并保留其对新建顶层产物的审批要求。不要为凑“两文件配额”创建空文件。实现尚不存在时,将边界标注为“已确认设计、代码未验证”,不要仅凭文字宣称文档与代码一致。
- 同时校验语义与链接:将每项声称的归属、接口和约束与代码、规范契约及可执行证据对比;发现矛盾应上报由归属方解决,不要为迁就偶然实现而改写规则。相对链接应基于各引用文档所在目录解析,而非终端工作目录。解析已安装的 docs-governance 技能路径,并运行其现有只读链接检查作为约定的验证步骤: python3 <docs-governance-skill>/scripts/audit-docs.py --root <repository> --scope modules --module <module-directory> 确认审计扫描了变更的本地指令、上下文和导航,检查链接结果与退出码;修复失效引用后重跑,不创建空目标。脚本不可用或排除某目标时,将该目标报告为未验证。业务测试通过不能证明链接正确,同名已有文件也可能不是正确的知识归属。
【示例】 “实现一个库存模块”:检查现有边界;仅为真正新增的约束添加本地规则;复用领域术语表和 API 契约;从现有导航链接它们;验证代码与源相对链接。 “支付是否应拆为独立模块?”:解释边界选项与证据,不写文件,也不把讨论视为实施批准。 “修复库存徽章颜色”:阅读适用指令并修复所请求的 UI 行为;不生成 AGENTS、CONTEXT 或 ADR 文档。 “审计模块文档”:使用现有只读审计与语义审查;缺少本地文件本身不构成创建许可。
【反模式】 为每个目录或前端页面强制配 AGENTS/CONTEXT 对;重复全局约束、术语表定义、契约或 ADR 理由;把文档检查当作业务实现完成的证明;在没有真实 harness 接线的情况下安装钩子或断言自动加载嵌套文件。
【交付】 报告规范记录路径、其项目/模块范围、实际变更、验证证据和未解决的归属问题。模块治理交付的是工作规则与知识入口,而非完整的 DDD 改造。
【相关技能】 context-and-decisions、architecture-decision-records、contract-first、change-impact、living-docs-governance、docs-governance。