---
name: moma-check
description: 'moma-soft-dev 子技能 —— 文档一致性检查。当用户消息以 /moma-check 开头时使用本技能， 只读比对 01~07 文档与实际代码，找出"文档有代码无、代码有文档无、两者不一致"的双向漂移， 输出检查报告到 check-reports/ 目录并给出后续指令建议。本指令不修改任何代码与既有文档。'
---

# /moma-check —— 文档一致性检查

文档驱动模式的"防腐层"：定期检测文档与代码的双向漂移，防止文档腐烂导致约束失效。

> 共享约定见 `${CLAUDE_PLUGIN_ROOT}/skills/moma-soft-dev/references/common-conventions.md`。本文件中 `dev-docs/` 路径均遵循共享约定的文档存放规则。

## 上下文范围

加载 `dev-docs/` 下 01~07 全套文档 + 项目源码结构、依赖清单、数据模型定义（ORM 模型、迁移文件、建表脚本）与接口定义（路由、控制器签名）。不加载插件内置模板，不加载会话历史。

## 步骤

1. **登记**
   - 按"多会话并行规约"生成会话 ID，读取花名册 `<docs-root>/.moma-state/roster.md`（不存在则创建），登记本会话条目（指令 `/moma-check`、工作范围"只读检查 + check-reports/"、状态"进行中"）。
   - 本指令只读代码与文档、只新增检查报告文件，不构成任何工作范围冲突，可与其他指令（含独占指令）并行执行；无需 checkpoint 提交。
2. **文档预检**：按共享约定"文档预检规则"检查：`<docs-root>` 或阶段1文档缺失则中止，提示先执行 `/moma-init`（新项目）或 `/moma-sync`（已有代码）。仅部分文档缺失（如有 01/02 但缺 03~07）时继续执行，跳过缺失文档对应的检查项并在报告中注明。
3. **逐项双向检查**：
   - **需求 ↔ 代码（02）**：文档定义的功能是否已实现（查漏实现）；代码中是否存在无需求依据的功能（查超范围实现）；
   - **数据模型 ↔ 代码（04）**：表、字段、类型、索引与模型定义/迁移文件是否一致；
   - **接口 ↔ 代码（05）**：接口路径、方法、参数、响应结构与路由/控制器签名是否一致；
   - **技术栈 ↔ 依赖（03）**：架构选型的组件与实际依赖清单是否一致（重点查大版本漂移与擅自引入的新框架）；
   - **规约 ↔ 代码（06）**：抽查命名、目录结构、错误处理等是否符合规约；
   - **测试策略 ↔ 测试代码（07）**：测试层次与 P0 场景是否有对应测试代码。
4. **漂移定级**：
   - **高**：违反 `⚠️ AI 约束`、接口不兼容、数据模型不一致——直接影响正确性或集成；
   - **中**：功能缺失或文档缺失——约束开始失效；
   - **低**：措辞过时、非关键描述不一致。
5. **写入检查报告**：在 `<docs-root>/check-reports/`（不存在则创建）新建 `check-YYYYMMDD-HHmm.md`，使用文末模板。
6. **后续指令建议**（逐项给出）：
   - 代码落后于文档 → `/moma-coding`（补齐实现）或 `/moma-fix`（行为偏差）；
   - 文档落后于代码且漂移较小 → `/moma-modify`（逐项更新）；大面积缺失 → `/moma-sync`（整体补全）；
   - 发现违反 `⚠️ AI 约束` 的代码 → 优先 `/moma-fix`。
7. **收尾**：将花名册中本会话状态改为"已完成"，向用户输出漂移摘要（按严重度排序）。

## 检查报告模板

```markdown
# 文档一致性检查报告 {{YYYY-MM-DD HH:mm}}

- **会话 ID：** {{会话 ID}}
- **检查范围：** {{已检查的文档与代码范围；缺失跳过的项在此注明}}

## 漂移清单

### [{{高/中/低}}] {{漂移标题}}
- **类别：** {{需求/数据模型/接口/技术栈/规约/测试}}
- **文档侧：** {{文档与章节}}
- **代码侧：** {{文件/位置}}
- **差异描述：**
- **建议指令：** {{/moma-coding、/moma-fix、/moma-modify、/moma-sync}}

## 总览

| 严重度 | 数量 |
|--------|------|
| 高 | |
| 中 | |
| 低 | |

## 结论
{{文档体系健康度简评与建议的检查频率}}
```

此指令除检查报告外**不写入任何文件**、不修改任何代码与既有文档；所有修复动作由用户依据建议指令发起。