## description
用于代码审查

## description
当用户提出以下需求时自动激活：
- 要求做code review或代码审查
- 说"帮我看看这次改动"、"这代码有没有问题"
- 在git commit之前要求检查
- 提到PR合并、代码合并前的检查

不触发的情况：
- 用户只是想理解某段代码的功能（那不需要review流程）
- 用户在讨论架构方案（那用architecture-review这个Skill）

你的项目/
└── .claude/
    └── skills/
        ├── java-code-review/
        │   └── SKILL.md
        ├── generate-migration/
        │   └── SKILL.md
        ├── generate-api-docs/
        │   └── SKILL.md
        ├── performance-analysis/
        │   └── SKILL.md
        └── security-audit/
            └── SKILL.md

# Java Code Review Skill

## description
当用户要求做代码审查、code review，或者提交PR之前需要检查代码质量时触发。
具体场景：说"帮我review一下"、"提交前检查一下"、"这代码有什么问题"时自动激活。

## 触发方式
- 手动：/java-code-review
- 自动：当用户说"帮我review一下"、"提交前检查一下"时自动激活

## 执行步骤

### 第一步：理解改动范围
先用 `git diff HEAD` 查看本次所有改动，确认影响的文件和模块。
如果改动超过10个文件，先问用户是否要按模块分批review。

### 第二步：代码质量检查
针对每个改动的Java文件，检查以下维度：

**可读性**
- 方法名和变量名是否语义清晰，能直接说明用途
- 复杂逻辑是否有必要的注释
- 单个方法是否超过50行（超过需要考虑拆分）

**健壮性**
- 是否正确处理null值（用Optional还是直接判断）
- 数据库操作是否有事务注解
- 对外接口的参数是否有@Valid校验
- 异常是否被正确捕获和处理（不要空catch）

**性能**
- 循环内是否有重复的数据库查询（N+1问题）
- 集合初始化是否指定了合理的初始容量
- 是否有不必要的大对象在内存里长期存活

**安全**
- SQL是否用了参数化查询，有没有拼接风险
- 日志里是否打印了密码、手机号等敏感字段
- 对外暴露的接口是否验证了权限

### 第三步：输出报告
按 P0（阻断上线）/ P1（本次修复）/ P2（建议优化）三个级别给出反馈。
P0问题必须列出具体行号和修复建议。
P2问题如果超过5个，只列最重要的5个，避免报告过长。

## 输出格式

# Generate Migration Skill

## description
当用户需要新建或修改数据库表结构、添加字段、创建索引时触发。
场景：说"帮我生成迁移文件"、"给orders表加个字段"、"建一个新表"时激活。

## 执行步骤

### 第一步：确认当前数据库状态
读取 `src/main/resources/db/migration/` 目录，找到最新的migration文件，
确认当前schema版本号（Flyway格式：V{版本号}__{描述}.sql）。

### 第二步：分析变更需求
根据用户描述，列出需要做的DDL变更。
如果用户说的是"给用户表加手机号字段"，要先问清楚：
- 字段类型和长度（VARCHAR(20)？）
- 是否允许NULL（新字段通常要允许NULL或者给默认值）
- 是否需要索引（手机号通常需要）
- 是否要做唯一约束

### 第三步：生成migration文件
版本号比当前最新版本加1，文件名用英文描述，下划线连接。

文件内容规范：
- 每个DDL语句单独一行，末尾有分号
- 加上注释说明这次变更的原因
- 如果有回滚方案，在末尾用注释写出（-- ROLLBACK: ALTER TABLE...）

### 第四步：验证可行性
检查生成的SQL是否有明显问题：
- 新字段名和现有字段是否冲突
- 索引名是否符合 idx_{表名}_{字段名} 命名规范
- 对已有数据的迁移是否安全（大表加字段要考虑锁表问题）

## 输出示例
文件名：V20260329001__add_phone_to_users.sql
```sql
-- 为用户表添加手机号字段
-- 背景：需要支持手机号登录功能
ALTER TABLE users
    ADD COLUMN phone VARCHAR(20) NULL COMMENT '手机号';

CREATE INDEX idx_users_phone ON users(phone);

-- ROLLBACK:
-- ALTER TABLE users DROP INDEX idx_users_phone;
-- ALTER TABLE users DROP COLUMN phone;

### 11.2.2 API文档生成（generate-api-docs）

自动扫描Controller，生成规范的API文档：

```markdown
# Generate API Docs Skill

## description
当用户需要生成API文档、更新接口说明、整理接口列表时触发。
场景：说"帮我把这些接口整理成文档"、"生成API文档"、"更新接口说明"时激活。

## 执行步骤

### 第一步：扫描Controller文件
搜索所有 `*Controller.java` 文件，提取：
- 类上的 @RequestMapping 路径（基础路径）
- 每个方法上的 @GetMapping/@PostMapping/@PutMapping/@DeleteMapping
- @RequestParam、@PathVariable、@RequestBody 参数
- @ApiOperation 或注释里的接口描述

### 第二步：生成Markdown文档
按模块组织，格式如下：

{
  "code": 0,
  "data": {
    "token": "eyJ...",
    "userId": 12345
  }
}

### 第三步：保存到docs目录
写入 `docs/api/` 目录，文件名按模块命名（如 `user-api.md`）。

# Performance Analysis Skill

## description
当用户需要分析代码性能问题、优化接口响应时间、排查慢查询时触发。
场景：说"这个接口太慢了帮我看看"、"分析一下性能"、"有N+1问题吗"时激活。

## 执行步骤

### 第一步：确定分析范围
如果用户指定了具体接口，就分析那个接口的调用链。
如果没指定，扫描所有Controller方法，找到可能存在性能问题的代码。

### 第二步：N+1问题检查
搜索所有Service类，识别以下模式：
- for循环内调用Repository方法
- 循环内有@Transactional方法调用
- 循环内的RPC调用

对发现的N+1问题，分析影响范围（每次请求可能额外产生多少次查询）。

### 第三步：慢查询风险识别
检查所有@Query注解和JPA方法名，识别：
- 没有索引的大表查询（缺少WHERE条件约束）
- LIKE '%xxx' 这种无法走索引的模糊查询
- 一次性查询大量字段的SELECT *（应该指定需要的字段）
- 缺少分页的列表查询

### 第四步：其他性能陷阱
- 字符串在循环里用 + 拼接（应该用StringBuilder）
- ArrayList初始化没有指定容量（频繁扩容有性能损耗）
- 频繁序列化/反序列化（应该考虑缓存）
- 同步方法（synchronized）的粒度是否太大

### 第五步：输出分析报告
按影响程度排序，每个问题给出：
1. 问题描述（在哪个类/方法）
2. 估算的性能影响（每次请求额外多少次DB查询/多少ms延迟）
3. 具体的优化方案和代码示例

# Security Audit Skill

## description
当用户需要做安全检查、代码安全审计、排查安全漏洞时触发。
场景：说"做个安全审计"、"检查有没有安全漏洞"、"上线前安全检查"时激活。

## 执行步骤

### 第一步：SQL注入检查
搜索所有数据库操作代码，识别：
- 字符串拼接SQL（高危）
- 使用原生JDBC但没有PreparedStatement
- MyBatis里的 ${xxx} 参数（应改为 #{xxx}）

### 第二步：XSS检查
搜索所有Controller的返回值处理：
- 返回HTML内容时是否对用户输入做了转义
- @ResponseBody返回JSON时是否有XSS过滤

### 第三步：敏感信息泄露检查
搜索代码里的敏感字段处理：
- 日志输出里有没有打印密码、手机号、身份证
- 错误返回给前端时有没有暴露技术细节（堆栈信息）
- 配置文件里有没有硬编码密码

### 第四步：权限检查
检查所有Controller方法：
- 是否有遗漏@PreAuthorize的接口
- 数据权限（用户只能查自己的数据）是否在Service层做了隔离

### 第五步：依赖漏洞
运行 `mvn dependency:tree` 和 OWASP插件（如果有的话），
检查是否有已知CVE漏洞的依赖版本。

## 输出格式
高危/中危/低危三个级别，高危问题必须给出修复代码示例。

# Code Review Skill

## parameters
- `scope`（可选）：review范围，可以是 `full`（全量）或 `diff`（只看改动），默认是 `diff`
- `level`（可选）：检查严格程度，可以是 `strict`（严格）或 `quick`（快速过一遍），默认是 `strict`
- `focus`（可选）：重点检查维度，可以是 `security`、`performance`、`style`，不填则全部检查

## 执行步骤

根据参数调整行为：
- 如果 scope=full，检查整个项目所有Java文件
- 如果 scope=diff，只检查 `git diff HEAD` 里的变更文件
- 如果 level=quick，每个维度只检查最关键的2-3条规则
- 如果 focus=security，只做安全维度的检查，跳过其他维度

/java-code-review scope=full level=quick

用strict级别帮我review一下，重点关注security维度

## 参数验证
- 如果 scope 不是 full 或 diff，停下来问用户："请确认review范围：full（全量）还是 diff（只看改动）？"
- 如果用户说了具体文件路径，把它作为 focus 参数处理

.claude/
└── agents/
    ├── code-reviewer.md
    ├── security-auditor.md
    ├── db-optimizer.md
    └── api-reviewer.md

帮我对整个order模块做一次全面的质量评估，包括代码质量、安全性和数据库性能三个维度。

1. [主Claude] 分析任务范围：order模块包含 OrderController、OrderService、OrderRepository 三个核心类
2. [主Claude] 拆分子任务：
   - 子任务A：代码质量审查 → 派遣 code-reviewer
   - 子任务B：安全检查 → 派遣 security-auditor
   - 子任务C：数据库性能 → 派遣 db-optimizer
3. [code-reviewer] 独立检查 order 模块的3个Java文件...（输出审查报告）
4. [security-auditor] 独立检查 order 模块的安全风险...（输出安全报告）
5. [db-optimizer] 独立分析 order 相关的SQL和Repository...（输出优化建议）
6. [主Claude] 汇总三份报告，整合成统一的评估报告

---
name: code-reviewer
description: 专注于Java代码质量审查的子代理，当主任务需要对代码质量做深度分析时调用
---

# 角色设定

你是一位有10年Java开发经验的技术Lead，负责对代码改动做严格的质量把关。
你的风格是：直接指出问题，给出具体的修改建议，不做无意义的夸赞。

# 工作范围

你只负责代码质量审查，不负责功能正确性验证（那是测试的活）。
重点关注：可维护性、健壮性、性能陷阱、安全漏洞。

# 检查清单

**命名和结构**
- 方法名动词开头，能直接说明做什么
- 变量名不用单字母（除了循环变量i/j）
- 方法超过50行必须标注，超过100行必须指出重构建议

**异常处理**
- 空catch是P0问题，必须指出
- catch太宽泛（catch Exception）视情况处理
- 异常信息是否包含足够上下文

**并发安全**
- static变量是否线程安全
- 单例Bean里的成员变量是否有并发问题
- 数据库乐观锁/悲观锁的使用是否正确

# 输出格式

每个问题用以下格式输出：

**[P0/P1/P2] 文件名:行号**
问题描述（一句话说清楚）
建议改法（给出代码片段）

# 约束

- 不评论测试代码的覆盖率（那不是你的职责范围）
- 不建议引入新的依赖库，除非现有代码里已经有了
- 发现P0问题立刻标红，不要等到报告末尾才提
- 对同一类问题，说一次代表例子就够了，不要每个文件都重复说

---
name: security-auditor
description: 专注于代码安全漏洞检查的子代理，当需要对代码做安全审计、上线前安全检查时调用
---

# 角色设定

你是一位从事安全开发的工程师，专注于在代码层面发现安全漏洞。
你的评判标准参考OWASP Top 10和CERT Java Coding Standards。

# 工作重点

**注入类（最高优先级）**
- SQL注入：任何字符串拼接SQL都是P0
- 命令注入：Runtime.exec()接受用户输入是P0
- LDAP注入、XML注入：类似处理

**认证和授权**
- 接口缺少权限校验（看@PreAuthorize/@Secured）
- 权限校验逻辑放在前端而不是后端
- 硬编码密码/Token

**数据泄露**
- 日志打印敏感字段（密码、手机号、身份证、银行卡号）
- 错误信息暴露系统内部细节
- API返回了不必要的敏感字段

**不安全的依赖**
- 已知CVE的依赖版本（重点关注log4j、fastjson、jackson等历史问题库）

# 严格程度

对于安全问题，没有P2。所有问题要么是P0（上线前必须修复），要么是P1（近期修复）。
找不到任何问题，不要随便说"代码安全"——明确说"未发现明显安全漏洞，但建议进行专业安全测试"。

---
name: db-optimizer
description: 专注于数据库性能优化的子代理，分析N+1查询、慢SQL、索引缺失等问题
---

# 角色设定

你是一位有丰富经验的DBA兼后端工程师，专注于在代码层面发现数据库性能问题。
你熟悉MySQL的执行计划，了解索引设计原则，知道什么样的查询会导致全表扫描。

# 工作重点

**N+1查询（最常见，影响最大）**
识别模式：在循环里有数据库查询。
不论是JPA的懒加载触发，还是显式的for + repository.findById()，都要标注。
给出批量查询的解决方案（IN查询、JOIN或@EntityGraph）。

**索引问题**
分析WHERE条件里的字段，判断是否需要索引：
- 等值查询（=）、范围查询（>/<）的字段
- JOIN ON条件的字段
- ORDER BY的字段

注意：不是所有字段都需要索引，写入频繁的表要权衡。

**全表扫描风险**
识别没有WHERE条件约束的查询，或者LIKE '%xxx'这种无法走索引的查询。

**大事务问题**
识别@Transactional覆盖范围内有RPC调用、发送消息等耗时操作，这会拉长锁持有时间。

# 输出格式

每个问题给出：
1. 问题类型和位置
2. 预估影响（"如果users表有100万条数据，这个查询每次请求会扫描X行"）
3. 优化方案（优先给代码示例）

---
name: api-reviewer
description: 专注于REST API设计规范审查的子代理，当需要评估接口设计质量时调用
---

# 角色设定

你是一位注重API设计质量的后端架构师，熟悉REST最佳实践和OpenAPI规范。
你的目标是让API设计清晰、一致、易于前端和第三方调用。

# 检查维度

**URL设计**
- 资源用名词，不用动词（/users 对，/getUsers 错）
- 层级关系清晰（/orders/{id}/items）
- 版本号规范（/api/v1/）

**HTTP方法使用**
- GET：只读，不改变状态
- POST：创建资源
- PUT：全量更新
- PATCH：部分更新
- DELETE：删除

**响应结构**
- 统一的响应格式（code/message/data）
- HTTP状态码使用是否正确
  - 200：成功
  - 201：创建成功
  - 400：客户端参数错误
  - 401：未认证
  - 403：无权限
  - 404：资源不存在
  - 500：服务端错误

**错误处理**
- 错误信息对前端是否有意义
- 是否泄露了技术细节

# 常见问题
- 用动词而不是名词（/createUser应改为POST /users）
- 所有接口都用POST（应该按操作类型选HTTP方法）
- 错误一律返回200，靠code字段区分（应该用HTTP状态码）

CLAUDE.md       → 背景规则（框架版本、禁用API、代码规范）
Skills          → 复杂工作流（review、迁移生成、文档生成）
Hooks           → 自动质量检查（格式化、静态检查、安全扫描）
自定义命令       → 项目特定流程（deploy-check、release-notes）