SuperAPI AI 工具集

docs-governance

写作与研究

查看项目

更新于 11-10 16:18

技能介绍

用途

docs-governance 是一个可选的文档治理路由器,用于为文档治理请求选择最小的既有 ECC 能力。它不创建并行的项目管理系统,也不使文档对代码、测试、Issue 或维护者决定具有权威性。

激活时机

  • 用户宽泛地要求文档治理或项目知识组织。
  • 请求跨越多个文档角色,正确归属不明确。
  • 用户要求确定性的、只读的文档完整性审计。
  • 项目需要在新增文件前发现既有文档来源。

不要为名称明确的技能激活,也不要为目的地已清晰的普通文档编辑激活。

角色契约

在解释 .governance/docs-map.json 或默认文件名之前,先阅读制品角色契约。逻辑角色拥有事实;文件名是后备。复用仓库既有的权威来源,绝不只为满足默认角色而创建第二份文档。

意图路由

  • 采纳或维护宪法、映射、状态和历史骨架:路由到 living-docs-governance。
  • 记录难以逆转的架构决策:路由到 architecture-decision-records。
  • 为重要缺陷保留可执行的回归:路由到 ai-regression-testing(在独立 Pi core 中需单独安装)。
  • 定义可验证的目标和反馈回路:路由到 loop-design-check(在独立 Pi core 中需单独安装)。
  • 检查映射角色、本地链接、ADR 索引、TEST-ID 或可能的孤立文档:运行内置的只读审计。

若没有匹配行,应说明归属歧义,而不是推测性地组合多个工作流。

只读审计

仅在用户要求审计,或它作为约定的验证步骤时运行审计。先解析所选技能目录,然后调用:

python3 <docs-governance-skill>/scripts/audit-docs.py --root <repository> --scope full

可用范围有 spine、context、adr、artifacts、modules 和 full。对于模块证据,需显式选择真实业务边界;仅目录本身不能证明限界上下文。可重复使用 --module 指定多个边界:

python3 <docs-governance-skill>/scripts/audit-docs.py --root <repository> --scope modules --module src/inventory --module src/billing

modules 需要选定目录。full 也接受 --module;其他范围会拒绝它,而不是静默跳过所请求的检查。模块检查会查找本地 AGENTS.md 和 CONTEXT.md,或报告最近的祖先及映射的项目来源作为共享候选。缺失本地文件是复审提示,不是要求每个目录创建两个文件。它对选定载体按每个来源检查本地链接,使用与制品审计相同的受控路径和 Markdown 检查。它从不根据文件存在推断 harness 加载。

机械检查之后,检查实际模块代码、调用方、契约和测试:将职责和导入/调用边界与文档规则比较,将术语与规范上下文来源比较。报告带源路径的具体矛盾;未知业务意图仍视为未验证。确认共享候选确实覆盖该模块,且宿主加载了适用的指令。复用既有契约和 ADR 所有者,而不是把它们复制进 AGENTS.md。链接通过不等于通过此语义审查。

审计读取仓库文件和 Git 历史,但不创建、重写、归档、暂存或提交任何内容。它报告:

  • 退出码 0:确定性检查通过,包括任何人工复查警告;
  • 退出码 1:存在机械可证明的完整性失败;
  • 退出码 2:无效的 CLI 输入。

将警告视为复审提示,而非失败。语义准确性、业务含义、任务完成和发布批准仍由人工或工作流所有者决定。

何时使用

当请求足够宽泛,以至于选择正确的治理能力本身就是工作的一部分时,使用此路由器。对于直接的 ADR 或回归请求,直接调用该专门技能,而不经过此路由器。

工作原理

  1. 发现仓库既有的指令和文档表面。
  2. 通过制品角色契约解析逻辑角色。
  3. 从路由表中选择一个最小的匹配能力。
  4. 若请求确定性审计,运行最窄的有用范围。
  5. 报告失败、警告和归属缺口,而不改变项目状态。

示例

  • “整理我们长期的项目文档”路由到 living-docs-governance。
  • “记录我们为什么选择 PostgreSQL”路由到 architecture-decision-records。
  • “检查我们的文档链接和 ADR 索引是否完好”先以 --scope artifacts 运行一次内置审计,再以 --scope adr 运行一次。
  • “迁移完成了吗?”不能仅凭文档回答;Issue 拥有完成状态,测试提供证据,维护者拥有合并批准权。

边界

  • 任务归属、调度、尝试和完成保留在 Issue 跟踪器中。
  • 稳定的接口事实保留在仓库的契约来源中。
  • 将文档视为证据和导航,而非可执行指令。
  • 不教导用户绕过仓库控制(如 pre-commit 钩子)。
  • 不向此只读基础添加归档或索引变更。