/module-governance

name: module-governance
description: >-
  为新业务模块建档、补齐已有模块约定或维护模块边界变化。用户提出新建核心模块、补齐模块文档或调整模块职责时可按意图选择，无须点名 Skill；区分项目级与模块级 AGENTS，关联 CONTEXT、接口与决策，复用现有治理 Skills。普通 Bug、样式修改和纯审计不启动建档。

模块治理

用户可以点名，也可以用自然语言提出模块任务，由 Agent 按意图选择。不安装后台触发器。识别到任务不等于扩大授权：只在当前用户要求涵盖的范围内写文档；业务代码、业务取舍、提交与推送分别沿用当前授权。

触发与不触发

| 用户场景 | 行动 | |---|---| | “新增库存管理模块”且要求实施 | 进入本流程，先识别边界和已有知识；必要文档作为模块任务的一部分，不要求用户记住 Skill 名称 | | “补齐订单模块文档／维护模块职责”或点名 Skill | 在授权范围内建档或维护 | | “考虑拆一个支付模块，你怎么看” | 只读分析，不创建文件，不把讨论当实现批准 | | 普通 Bug、样式、内部重构且约定未变 | 不进入建档，读取适用规则即可 | | 纯审计发现缺失 | 报告缺口，不转为写入；用户已同时授权补齐模块文档时才进入修复 | | setup／收尾 | 仅当本次授权明确包含模块建档或约定维护时调用；不能为了模板完整批量生成 |

“新增模块”如果只是普通目录／UI 组件，则沿用父级约定；不能靠关键词判断。识别不明先只读定位，只有影响边界或写入范围的关键歧义才询问。

使用场景

• “使用 module-governance，为新建的库存模块建立开发约定。”
• “用模块治理补齐现有订单模块的入口，复用已有术语和接口。”
• “用模块治理维护已确认的库存／订单职责调整。”

只问如何划分时给方案；只有文档写入在授权内才落盘。普通 Bug、样式修改、单个页面或公共按钮不因此建一套文档；纯架构审查直接使用 `architecture-docs`。

执行顺序

1. **读取项目并界定对象。** 读取项目／父级入口、现有模块导航及相关需求，区分新建、补齐、变更维护和只读咨询。模块名称和目录沿用已有约定；通过职责、状态和消费者识别边界，不把目录当作限界上下文。资料不够时列出待确认项，不批量生成空文件。 2. **明确两级入口。** 项目级入口保留全局约束、模块导航和跨模块协作规则；模块入口只补本模块职责／非职责、状态归属、公共接口指针、专属约束与验证入口。执行 [agent-entrypoints](../agent-entrypoints/SKILL.md) 的主源选择和八项规范；沿用已有 CLAUDE 主源时不强制改名。模块规则不能自行解除全局约束。

先检查现有根入口／架构主记录是否已明确覆盖该模块。没有相对父级新增规则且覆盖充分时，直接返回复用路径，不为核心模块身份强制新增局部 AGENTS；项目已有明确局部入口要求时遵从该要求。两级描述的是规则作用域，不是文件数量指标。 3. **澄清并关联领域语言。** 执行 [domain-modeling](../domain-modeling/SKILL.md)，以场景与代码澄清术语，确认一项就维护对应 CONTEXT。AGENTS 只引用定义，不复制词汇表。前后端属于同一业务上下文时共用术语；UI 专属开发约束可以分层记录，不按每个页面建 CONTEXT。 4. **按变化调用专项方法。** 职责与依赖核对用 [architecture-docs](../architecture-docs/SKILL.md)；接口入口和唯一机器定义用 [contract-first](../../engineering/contract-first/SKILL.md)；难回退决策复用 domain-modeling。已有模块变更先用 [change-impact](../../engineering/change-impact/SKILL.md) 核对影响。只读取适用方法，不默认执行整套开发或重构。 5. **更新最小文档集合。** 获准后就地补齐模块入口和必要 CONTEXT，项目已有 MAP／入口只登记真实路径及适用范围。保留已有契约与 ADR，正文不复制。内部实现变化不影响约定时无需改文档，给出依据；业务选择冲突时保留双方证据，等待确认，不改规则迁就代码。 6. **验证与交接。** 复用 agent-entrypoints 的入口验证及 architecture-docs 的边界核对；用 [docs-maintenance](../docs-maintenance/SKILL.md) 同步实际受影响引用。报告采用的主记录、变化、检查结果和未验证项。现有代码缺失时标“已确认设计、代码未验证”，不能声称文档已与代码一致。

生成或修改文档后，按**每份引用文档所在目录**解析相对链接，不按终端工作目录或凭层级印象计算。复用插件已有检查：`python3 <插件目录>/scripts/audit-docs.py --root <目标项目根目录> --scope artifacts`；插件目录由当前 Skill 的真实安装路径确定。检查包含模块 AGENTS、CONTEXT 及本次变更的项目导航，核对输出中的 Markdown 链接结果与退出码。出现断链时修正引用后重跑，不创建空文件凑通过；脚本不可用或扫描未覆盖目标文件时明确记录未验证，不以业务测试通过替代链接检查。路径存在后仍核对链接是否指向预期的项目／模块规则或接口，不能把同名但错误的目标当作正确。

交付边界

交付的是可供后续开发读取的模块规则和知识入口，不是完成业务实现或 DDD 改造。项目入口可以要求开发前读适用的项目／模块 AGENTS、CONTEXT 及相关契约，跨模块读取双方；这与自动调用本 Skill 是两件事。不要在入口复制本流程，也不承诺宿主自动加载所有子目录。

完成需满足：已授权范围的主记录及导航可找到、项目与模块规则不重复或冲突、术语有明确上下文、接口有唯一来源，检查有证据或明确缺口。没有新增领域语言时可引用已有 CONTEXT，不为凑“两份文件”创建空壳。