模块分析简报

你要解决的问题

接手一个陌生后端模块时，常见的两种坏结果：要么靠目录猜测拼凑心智模型，要么花半天读代码、整理出一份没人维护的文档。更麻烦的是 AI 代写常自信地编出不存在的类名和 SQL，而没人有精力逐条核对。

它如何工作

module-brief 一次只处理一个模块，全程单上下文：自己读、自己写、自己核对，不外包给子 agent。

四步流程：

• Step 1 定位确认：归一化模块名并在后端源码中做存在性校验；边界模糊时用一次 AskUserQuestion 敲定范围，产物写入 docs/module-brief/<module>/。
• Step 2 蒸馏与写作：识别技术栈特征、按 {{MODULE_SCOPE}} 圈定类范围，直接产出两份文档。
• Step 3 grep 自核：提取 design.md 里所有代码标识（类型名、表名、方法名），逐个用 rg -i 与 find -iname 反查仓库，查无就地标 [待确认]，不删条目。
• Step 4 报告：返回文档路径、概况与核验统计（标识总数/命中数/命中率）。

两份产物，两种视角：

• requirements.md：业务视角，禁止出现任何代码标识，面向 PM、测试和业务新人。
• design.md：技术白盒视角，允许类名、方法、SQL、路径，末尾必须含「陷阱与护栏」小节，供接手维护的人避坑。

反幻觉纪律：每条事实附代码证据（如 ClassName.method() 或 mapper.xml#id），拿不准就标 [待确认]；扫描时排除 target/、build/ 等目录，避免读到编译副本产生过期事实。

适用边界

这份技能只写简报，不写规范：穷举字段、全量状态机、跨模块接缝校验、完整性对账一概不做——那是 module-spec-baseline 的活；找 bug 用 code-review。简报一气写完、可随时重生成、够用即止。