codebase-module-design

name	codebase-module-design
description	基于源码分析为 Maven/Gradle 多模块项目的单个模块生成 Story/AR 风格的实现设计文档。当用户说"为 XX 模块出设计文档"、"基于代码生成模块设计"、"给 modules/agent-core 写一份 AR 文档"、"分模块生成设计文档"、"反向写设计"、"补设计文档"，或在多模块仓库里要求把某个模块的代码逆向写成设计文档时触发。区别于 story-ar-design（围绕一个需求/Story 收集信息后产出）：本 skill 的输入是**模块的现有代码**，输出是回归到 AR 模板的"代码即文档"产物。

Codebase Module Design

为既有模块的代码"逆向"产出一份 AR 实现设计文档。和 [[story-ar-design]] 的区别：那个 skill 的起点是一个待开发的 Story，章节内容来自用户访谈；这个 skill 的起点是一坨已存在的代码，章节内容来自对源码、pom、依赖图、关键类、配置文件的静态分析——用户的输入只是"哪个模块"。

何时触发

• 用户给了一个模块路径（modules/agent-core、mate-campusclaw/、backend/order-service）并要求出设计文档
• 用户说"分模块生成设计文档"、"为每个模块写一份 AR 文档"——多模块批量
• 用户给了一个 Maven/Gradle 多模块仓库的根目录，要"补齐设计文档"
• 已有模块想沉淀技术资产、对外交付、归档

不适用的情况

• 用户起点是需求/Story 描述（尚未编码或刚开始）→ 用 [[story-ar-design]]
• 用户要的是模块架构/依赖概览（不需要 AR 七章结构）→ 直接读 docs/module-architecture.md 类的文件即可，本 skill 太重
• 单文件、单类的说明 → 写注释/Javadoc 即可

工作流程

Step 1: 确认范围与输出位置

询问（如已在上下文里给出，跳过）：

1. 目标模块：单个路径，还是多模块批量（给一个根目录 + 模块列表）
2. 输出位置：默认 docs/designs/<module-name>.md；用户可指定其他目录
3. 是否覆盖已存在的文档：若目标文件存在，默认追加 _v2 后缀避免覆盖；用户确认后再覆盖

批量模式下，逐个模块顺序处理——不要试图一轮 LLM 调用塞完所有模块，章节质量会被稀释。

Step 2: 扫描模块基本盘

对每个目标模块，按下面的顺序读取（用项目自带的工具，不要预设 grep/find 模式，先看构建文件再决定后续）：

1. 构建描述：pom.xml / build.gradle.kts / build.gradle — 拿到模块 artifactId、依赖列表、JDK 版本、插件
2. 模块 README / 设计文档：README.md、*-design.md、docs/ — 如果已有部分文档，复用而不是重写
3. 包结构：列 src/main/java 一级/二级包目录树，识别核心包 vs 工具包
4. 入口与门面：找类名以 *Service、*Facade、*Application、*Manager、*Engine、*Loop、*Runner 结尾的；找 @SpringBootApplication、@Configuration、public static void main
5. 公共 API：public 类的清单（特别是 interface、sealed interface、record、抽象类）
6. 配置与资源：src/main/resources/application*.yml、META-INF/spring/*.imports、schema.sql
7. 测试结构：src/test/java 关键测试类——能反推核心使用场景

不需要把每个文件读完；目标是搭出"模块在做什么"的骨架。

Step 3: 读 references/template.md 与 references/code-to-section-mapping.md

template.md 是输出的目标格式（AR 七章）。code-to-section-mapping.md 告诉你每个章节该从代码的哪里取信息——这是本 skill 的核心知识，比 AR 模板本身重要。

Step 4: 逐章填写

按 mapping 文档指示填写。关键原则：

0. 关键章节必出 Mermaid 图，且与正文细节对齐

下面三个位置必须画 Mermaid 图，且图里出现的所有名字（类名、模块名、流程步骤名）必须和同一章节的正文表格/列表里的名字逐字一致——不一致就是失败。

位置	Mermaid 类型	内容要求
2.1 Story 上下文	flowchart LR 或 graph LR	本模块为中心节点，左侧是上游依赖（pom 内项目模块），右侧是下游消费者（grep import 反查），外部依赖单独标注。和 1.3 关联需求表的模块名字必须 1:1 对齐
3.2 功能实现设计	sequenceDiagram（有 Loop/Engine/Pipeline 主流程时）；否则 flowchart TD 描述核心数据流	步骤名要和正文 step 列表的措辞一致；时序图的 actor 必须是真实类名，不要写"User"/"System"这种泛词
3.6 代码设计	classDiagram（首选）或 flowchart	列出每个包内的关键类 + 类间关系（继承/实现/依赖），类名必须和该章节正文表/列表中的类名严格一致——少一个、多一个、拼错都算失败

如果模块特别小（< 5 个核心类），3.6 用 flowchart 代替 classDiagram 也行；模块没有明显的主流程（纯类型库），3.2 可标"不涉及单一主流程"并跳过图。

Mermaid 代码块的语法约束：

• 用 ```mermaid 围栏
• 节点标识符避免空格和特殊字符；中文标签放在 ["中文"] 里
• 别画超过 ~15 个节点的图——超过 reviewer 一眼看不过来，拆成多张

示例（agent-core 模块的 2.1）：

flowchart LR
    ai[campusclaw-ai]
    tui[campusclaw-tui]
    core[campusclaw-agent-core]
    cron[campusclaw-cron]
    cli[campusclaw-coding-agent]
    ai --> core
    tui --> cli
    core --> cron
    core --> cli

此图的 5 个模块名必须和 1.3 关联需求表里出现的模块名完全一致。

1. Section 1-2 是"为什么"，要写代码看不出来的东西

• 需求来源/价值：从 README、commit message、git log、模块在依赖图里的位置推断；推不出来的标"待补充"，不要编造业务背景
• 关联需求：列出该模块依赖谁、被谁依赖（从 pom.xml 的 <dependency> 反查上游、grep 谁 import 它反查下游）
• 功能点分解：把"公开 API 上的动词"作为功能点——Agent.run()、CronEngine.start()、SkillLoader.load() 等

2. Section 3 是"是什么"，应当 95% 来自代码

• 实现思路 (3.1)：一两段话总结模块如何解决问题。从入口类的方法编排可看出
• 实现设计 (3.2)：核心流程——如果有 *Loop/*Engine/*Pipeline，那就是流程主干，按它的 step 列
• GUI (3.3)：纯后端模块标"本模块不涉及前端界面"；TUI 模块要把核心组件类列出
• 接口描述 (3.4)：
  • HTTP 接口：找 @RestController、@GetMapping/@PostMapping、OpenAPI yaml
  • 程序接口：列出 public interface 的方法签名作为接口表
  • LLM Tool 接口：找 AgentTool 子类
• 持久化 (3.5)：找 schema.sql、@Entity、MyBatis mapper xml；都没有就标"本模块不涉及持久化"
• 代码设计 (3.6)：按包列出关键类清单（每包 2-5 个），每个类一行职责。不要把所有类都列——只列对外、入口、核心抽象
• 安装部署 (3.7)：模块独立可启动吗？需要哪些环境变量/配置？application.yml 里的关键配置项；不涉及就标"本模块作为 lib 被上游聚合，不单独部署"

3. Section 4 (DFX) 是"代码暗示了什么非功能特性"

• 性能 (4.1)：找 @Async、CompletableFuture、Reactor Mono/Flux、线程池配置；推断并发模型
• 兼容性 (4.2)：JDK 版本、对外接口的稳定性（看 @Deprecated、版本号）
• 可维护性 (4.3)：日志框架（SLF4J 还是别的）、Micrometer 指标、健康检查
• 全球化 (4.4)：找 Locale、ResourceBundle、i18n properties；都没有就标"不涉及"
• 产品资料 (4.5)：列出该模块产生/依赖的 docs/openapi/asyncapi 等

4. Section 5 (安全 Checklist) 逐项实证

不要默认填"不涉及"。每一行都要搜代码：

检查项	怎么实证
5.1 认证	grep @PreAuthorize、Authentication、SecurityFilterChain、Bearer/JWT 关键字
5.4 SQL 注入	grep executeQuery、String.format + SQL、JPQL 拼接；用 PreparedStatement / MyBatis #{} 视为不涉及
5.7 命令注入	grep ProcessBuilder、Runtime.exec——本仓的 BashTool 必涉及，要详写防护
5.11 文件上传下载	grep MultipartFile、Files.copy、InputStream 文件流处理
5.12 硬编码	看 application.yml 是否把密钥写入；用 @Value("${...}") 才合规

实证后填"是/否/不涉及" + 一句话说明（指向具体类名）。

5. Section 6-7 留空模板

转测 Checklist 默认全"否"待开发者勾选；讨论与决策记录留表头让后续填写。

Step 5: 写文件 + 收尾

• 默认路径 docs/designs/<module-name>.md，目录不存在则创建
• 写完每个模块后，向用户汇报一行：✓ docs/designs/agent-core.md (xxx 行)
• 批量结束后给一个总览：本次产出了几个文件，建议人工 review 的章节（1.1 需求来源、1.2 背景价值 是最容易需要人补的，因为代码看不出来）

重要原则

别造背景

模块的"需求来源、业务价值"代码里通常没有。写不出来就写"待开发者补充"，不要把"为了提升用户体验" 这种万能填充塞进去——审稿人一眼看出是 AI 占位文字，整份文档的可信度就崩了。

优先复用已有文档

如果模块已有 *-design.md、README 详细段落，复用原文，不要重写。本 skill 是补齐缺失，不是覆盖已有。

章节"不涉及"也要给原因

本模块不涉及 GUI（纯后端 lib） 比 不涉及 多两个字，但能让 reviewer 看出"已经判断过"而不是"忘了写"。

输出 Markdown 即可

不需要转 docx——用户如果要 docx 自行 pandoc 或调用 docx skill。AR 模板里的表格在 Markdown 渲染下足够阅读。

别一次塞所有模块

批量场景按模块串行处理：分析模块 A → 写 A 的 design.md → 分析模块 B …。一轮上下文塞多个模块会让章节内容相互"窜味"（cron 的 5.7 命令注入说明误填到 ai 的章节里）。