话说回来，

项目的五张图

• 项目架构图
• 内部模块图
• 外部依赖图
• REST 接口清单
• 数据模型 ER 图

架构图

痛点：阅读 README 与目录结构时经常找不到整体层次导致新人上手慢。

读一下这个项目的 README 和顶层目录，绘制一张包含前端、后端、数据库和中间件的分层架构图。主要模块在方框内标注一句话职责，日志、监控、配置等基础设施统一放在一个方框概览即可。保存至 docs/architecture.svg生成后打开检查是否报错，如有报错请及时修复。老实说，

模块图

痛点：模块之间的依赖关系模糊。循环依赖难以定位，

查看项目的 pom.xml绘制仅包含项目自身模块的内部依赖图。若出现循环依赖，请用红色标记。话说回来，保存至 docs/module-deps.svg一样需要检查并修复 SVG 报错。

依赖图

痛点：外部库、middleware、API 的版本冲突导致上线频繁出错。

整体分析 POM.xml。application.yml,还有 README，梳理出三类对外依赖：关键 Java 依赖、中间件、外部 API。每类使用不同颜色绘制依赖关系图并保存为 docs/external-deps.svg完成后检查并修复可能的错误。

REST 接口清单

痛点：接口文档散落各处，接口变更后文档更新不及时引发前后端对齐成本高。

扫描项目所有 Controller，整理一份 REST 接口清单。每条记录需包含 HTTP 方法、方法、一句话说明、主要入参和返回结构，并按模块分组。将结果保存为 Markdown 文件 docs/api-list.md.

数据模型

痛点：实体类与数据库表不一致时容易产生运行时异常，却缺乏统一视图。

- 查看所有 Entity 类、DTO 与建表 SQL；- 列出主要数据模型，每个模型列出字段、类型及一句话说明；- 标注主键、外键及枚举值；- 绘制关键模型之间关系的简易 ER 图。

文档分别保存至 docs/data-model.md,图形保存至 docs/data-model-er.svg.

根据 docs/ 里的五份资产。生成 CLAUDE.md

• "禁区"写什么： 哪些代码动不得、哪些字段受对接方强制约束、哪些配置改动会导致程序不可用。
• "历史包袱"写什么： 看似奇怪但有历史原因的实现细节。

老项目的 SKILL

Pain Point: 团队在改造旧程序时总是重复执行相同检查。 却没有形成可复用流程或自动化脚本，导致效率低下且易出错。

"改造前体检"、"PR 前检查"、“文档同步”、"新增接口前对齐" 等都是每次改造必须走的一遍流程。这些不是常识，而是具体可执行操作，应归类为 SKILL。

怎么判断一件事值不值得写成 SKILL？老实说，

Pain Point: 团队难以辨别哪些工作值得抽象成标准化技能。从而浪费时间在一次性任务上。

• # 可复制： 相同动作序列会被反复执行；例如每次发布前都要跑全套测试。
• # 可参数化： 只有少量变量会变化，而骨架保持一致；如“新增一个接口”的流程，只是接口名和参数不同。
• # 可自动化： 动作序列起止明确，可通过脚本或 AI 自动触发并产出明确结果。

老项目里四类流程

• # 技术文档自动更新： 代码改动后 docs/ 中的接口清单、数据模型或架构图可能漂移。如果不主动同步，这三份资产会逐渐失信任度；不过，最终只能靠“代码即文档”。

# 改造前体检： 怎么说呢，动手改代码之前，需要确认当前测试全部通过、编译成功。还有依赖中间件可连通，否则改动风险极高。每次改造前必须跑一次体检。

# PR 前检查： 提交 PR 前必须走固定 checklist：测试通过 → 代码格式化 → 更新 changelog → 同步相关文档 → 指定 reviewer。拥有明确 checklist 的团队能确保零变化地重复执行此过程。

 #

...

 . . .