@llryiop/avatar-boot-cli 1.0.0

package/templates/.claude/skills/ai-tool-guide/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: ai-tool-guide
+description: 当需要了解 AI 辅助开发工具使用方法时使用此技能 - 涵盖 Claude Code、Cursor 等 AI 工具的团队使用规范和最佳实践。触发条件：AI工具, Claude Code使用, Cursor使用, AI辅助开发, 工具指南
+---
+
+# AI 工具使用指南
+
+> 团队级培训材料 - Avatar Boot 项目组
+
+## 1. 概述
+
+AI 辅助开发工具是团队提升研发效率的核心手段之一。在 Avatar Boot 项目中，我们主要使用以下两款 AI 工具：
+
+- **Claude Code**：Anthropic 官方 CLI 工具，擅长大规模代码理解、多文件重构和自动化流程
+- **Cursor**：AI-native IDE，擅长日常编码、实时补全和小范围修改
+
+两者定位互补，分别覆盖不同的开发场景。本指南旨在帮助团队成员快速上手这些工具，并建立统一的使用规范，确保 AI 辅助开发的质量和一致性。
+
+### 核心价值
+
+- 加速 CRUD 等重复性编码工作，将开发者精力聚焦于业务逻辑设计
+- 提供代码审查的辅助视角，降低人工 CR 的遗漏率
+- 快速生成测试用例，提升测试覆盖率
+- 辅助技术方案设计和文档撰写
+
+## 2. Claude Code 使用指南
+
+### 2.1 安装与配置
+
+```bash
+# 安装 Claude Code
+npm install -g @anthropic-ai/claude-code
+
+# 在项目根目录启动
+cd /path/to/avatar-scaffold-project
+claude
+```
+
+**权限设置（settings.local.json）**：
+
+Claude Code 通过 `settings.local.json` 控制工具权限。团队建议配置：
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash(git *)",
+      "Bash(mvn *)",
+      "Bash(java *)"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Bash(git push --force *)"
+    ]
+  }
+}
+```
+
+建议将高危操作（如强制推送、删除文件）设为需要确认或禁止，避免误操作。
+
+### 2.2 核心工作流
+
+**代码生成**：
+- 提供明确的需求描述、技术栈约束和输出格式要求
+- 示例：「基于 Avatar Boot 框架，为用户模块生成 CRUD REST API，使用 Result<T> 统一返回，Service 层用接口+实现分离」
+
+**代码审查**：
+- 让 Claude Code 先读取目标文件，再执行审查
+- 示例：「审查 UserService.java，关注安全性、性能和编码规范」
+
+**重构**：
+- 先描述当前问题，再给出期望目标
+- 示例：「将 OrderService 中的订单状态流转逻辑提取为独立的状态机类」
+
+**测试生成**：
+- 提供被测类和关键业务逻辑说明
+- 示例：「为 PaymentService.processPayment() 生成单元测试，覆盖正常支付、余额不足、重复支付场景」
+
+### 2.3 Rules 和 Skills 机制
+
+Claude Code 通过项目中的 `.claude/` 目录实现团队定制化：
+
+- **CLAUDE.md**：项目级上下文注入文件，Claude Code 启动时自动读取。包含项目技术栈、架构约束、编码规范等核心信息
+- **Rules（.claude/rules/）**：编码规则文件，定义代码风格、命名规范、架构约束等。Claude Code 在生成代码时会自动遵循
+- **Skills（.claude/skills/）**：技能文件，针对特定场景的详细指导文档。按需加载，提供深度上下文
+
+团队成员可以通过提交 PR 来完善这些配置文件，持续优化 AI 输出质量。
+
+### 2.4 常用命令
+
+| 命令 | 说明 |
+|------|------|
+| `/compact` | 压缩对话上下文，释放 Token 空间 |
+| `/clear` | 清空当前对话，重新开始 |
+| `/cost` | 查看当前会话的 Token 消耗 |
+| `Shift+Tab` | 在对话中切换执行计划模式 |
+
+**多 Agent 协作**：
+
+对于大规模任务，可以使用多 Agent 模式：
+- 主 Agent 负责整体规划和任务拆分
+- 子 Agent 并行执行独立的子任务（如同时生成多个模块的代码）
+- 适合场景：初始化项目、批量生成 CRUD、全量重构
+
+### 2.5 CLAUDE.md 的作用
+
+`CLAUDE.md` 是项目级上下文注入文件，位于项目根目录。Claude Code 启动时自动读取其内容作为背景知识。
+
+典型内容包括：
+- 项目简介和技术栈（Spring Boot 3.5.3, Java 21, Avatar Boot 框架）
+- 项目结构说明
+- 核心架构约束（统一返回 Result<T>、分层架构等）
+- 编码规范摘要
+- 常用命令（构建、测试、部署）
+
+### 2.6 最佳实践
+
+1. **提供足够上下文**：告诉 AI 你的技术栈、项目约束和期望输出格式
+2. **分阶段任务**：复杂任务拆分为多个小步骤，逐步完成
+3. **先读后改**：让 AI 先读取现有代码，理解上下文后再进行修改
+4. **明确范围**：指定要修改的文件、方法或模块，避免 AI 过度修改
+5. **验证输出**：AI 生成的代码必须经过编译、测试和人工审查
+6. **善用 /compact**：当对话过长时及时压缩，保持上下文质量
+
+### 2.7 注意事项
+
+- **代码审查仍需人工确认**：AI 审查是辅助手段，不能替代人工 CR
+- **敏感信息不要粘贴**：数据库密码、API Key、内部 IP 等不要出现在对话中
+- **不要盲目信任 AI 输出**：特别是涉及安全、并发、事务等关键逻辑
+- **注意 Token 消耗**：大文件和长对话会快速消耗 Token 配额
+
+## 3. Cursor 使用指南
+
+### 3.1 安装与配置
+
+1. 从 [cursor.com](https://cursor.com) 下载并安装 Cursor IDE
+2. 登录账号并配置模型（推荐使用 Claude 系列模型）
+3. 安装必要的 Java 扩展（Extension Pack for Java、Spring Boot Extension Pack）
+4. 配置 JDK 21 路径
+
+### 3.2 核心交互方式
+
+**Tab 补全**：
+- 实时代码补全，根据当前上下文自动建议
+- 适合日常编码，快速补全方法体、参数、注释
+- 按 Tab 接受建议，按 Esc 忽略
+
+**Cmd+K 内联编辑**：
+- 选中代码后按 Cmd+K，输入修改指令
+- 适合小范围修改：重命名、添加注解、调整逻辑
+- 示例：选中一个方法 → Cmd+K → 「添加参数校验和 Javadoc」
+
+**Chat 面板（Cmd+L）**：
+- 侧边栏对话窗口，支持多轮对话
+- 适合复杂问题讨论、代码解释、方案设计
+- 可通过 @file 引用项目文件作为上下文
+
+### 3.3 .cursorrules 文件配置
+
+类似于 Claude Code 的 `.claude/` 目录，Cursor 通过项目根目录的 `.cursorrules` 文件注入项目级规则。
+
+建议配置内容：
+- 项目技术栈描述
+- 编码规范要点
+- 架构约束（分层结构、统一返回格式等）
+- 常用的代码模板和模式
+
+### 3.4 常用场景
+
+- **函数编写**：描述函数功能和签名，让 Cursor 生成实现
+- **Bug 修复**：粘贴错误堆栈，让 Cursor 分析原因并建议修复
+- **重构**：选中代码，描述重构目标（提取方法、消除重复等）
+- **文档生成**：选中类或方法，让 Cursor 生成 Javadoc
+- **SQL 编写**：描述查询需求，生成 MyBatis XML 或注解 SQL
+
+### 3.5 最佳实践
+
+1. **精确选中上下文**：只选中与任务相关的代码，避免上下文噪音
+2. **使用 @file 引用**：在 Chat 中通过 @file 引用相关文件，提供完整上下文
+3. **分步骤提问**：复杂任务拆分为多步，逐步引导 Cursor 完成
+4. **利用内联编辑**：小修改优先使用 Cmd+K，避免切换到 Chat 面板
+5. **检查 Diff**：接受 Cursor 的修改前，仔细查看 Diff 视图
+
+## 4. 工具选型建议
+
+### Claude Code 适合的场景
+
+- **大范围重构**：跨多个文件的架构调整、模式迁移
+- **多文件修改**：需要同时修改多个类的关联变更
+- **自动化流程**：批量生成代码、自动化脚本编写
+- **代码审查**：系统性地审查模块代码，生成审查报告
+- **技术方案设计**：基于现有代码分析，输出设计文档
+
+### Cursor 适合的场景
+
+- **日常编码**：编写新功能、实现业务逻辑
+- **快速补全**：方法体补全、参数补全、注释补全
+- **小范围修改**：修改单个文件中的局部逻辑
+- **实时辅助**：编码过程中的即时建议和解答
+- **学习理解**：理解不熟悉的代码片段
+
+### 组合使用策略
+
+推荐的工作流：
+1. **需求分析阶段**：使用 Claude Code 分析需求，生成技术方案
+2. **编码阶段**：使用 Cursor 进行日常编码，利用实时补全提效
+3. **重构阶段**：使用 Claude Code 执行跨文件重构
+4. **审查阶段**：使用 Claude Code 进行 AI 预审，再进行人工 CR
+5. **测试阶段**：使用 Claude Code 批量生成测试用例
+
+## 5. 团队协作规范
+
+### 5.1 AI 生成代码必须经过 CR
+
+所有 AI 生成或辅助生成的代码，必须经过至少一位团队成员的 Code Review。重点关注：
+- 业务逻辑正确性
+- 安全性（SQL 注入、XSS、权限校验等）
+- 性能影响（N+1 查询、不必要的循环等）
+- 是否符合团队编码规范
+
+### 5.2 提交信息中标注 AI 辅助
+
+使用 AI 辅助生成的代码，在 Git 提交信息中添加 Co-Authored-By 标记：
+
+```
+feat(user): add user CRUD API
+
+Co-Authored-By: Claude Code <noreply@anthropic.com>
+```
+
+这有助于后续统计 AI 辅助代码的比例和质量。
+
+### 5.3 共享有效的 Prompt 到团队知识库
+
+发现高质量的 Prompt 模板后，提交到项目的 `.claude/skills/` 或团队知识库中，供其他成员复用。
+
+### 5.4 定期回顾 AI 输出质量
+
+每月进行一次 AI 辅助开发效果回顾：
+- 分析 AI 代码采纳率和缺陷率
+- 收集团队成员的使用反馈
+- 优化 Rules 和 Skills 配置
+- 更新 Prompt 模板库
+
+## 6. 上下文管理
+
+### Compact 规则
+
+- **触发条件**: 上下文超过 150K tokens 时主动执行 `/compact`
+- **保留内容**: 已修改文件列表、测试命令和结果、当前阶段进度、架构决策记录
+- **重新加载**: compact 后必须重新读取 `CLAUDE.md`
+
+### 分阶段工作
+
+每个阶段必须有明确的:
+- **输入**: 需要哪些信息和资源
+- **目标**: 要完成什么任务
+- **验收标准**: 如何判断任务完成
+
+### 文件读取约束
+
+- 优先使用 `.claudeignore` 排除无关目录（target/、.idea/、node_modules/、logs/）
+- 明确指定读取范围（如"只读 src/login/ 目录"）
+- 禁止无目的的全局搜索
+- 使用 subagent 探索陌生代码库
+
+## 7. 常见问题
+
+### Q: Context 过长怎么办？
+
+**A**：
+1. 使用 `/compact` 命令压缩对话上下文
+2. 使用 `/clear` 重新开始新对话
+3. 将大任务拆分为独立的小任务，每个任务一个新对话
+4. 在 Prompt 中只提供必要的上下文，避免粘贴大量无关代码
+
+### Q: AI 生成代码不符合规范怎么办？
+
+**A**：
+1. 检查并完善 `.claude/rules/` 中的规则文件，确保规范被正确注入
+2. 在 Prompt 中明确指定要遵循的规范（如"使用 Result<T> 统一返回"）
+3. 提供符合规范的代码示例作为 Few-shot
+4. 生成后使用 Checkstyle/SpotBugs 等工具自动检查
+
+### Q: 如何提升 AI 输出质量？
+
+**A**：
+1. **提供精确上下文**：技术栈、约束条件、现有代码结构
+2. **明确输出格式**：告诉 AI 你期望什么样的输出（代码、文档、Checklist）
+3. **使用 Chain-of-Thought**：让 AI 先分析问题，再给出解决方案
+4. **迭代优化**：根据输出结果调整 Prompt，逐步逼近期望结果
+5. **参考 Prompt 模板**：使用团队积累的 Prompt 模板库（见 prompt-engineering Skill）
+
+### Q: Claude Code 和 Cursor 都可以用，怎么选？
+
+**A**：参考第 4 节「工具选型建议」。简单规则：
+- 需要修改 3 个以上文件 → Claude Code
+- 单文件日常编码 → Cursor
+- 代码审查和方案设计 → Claude Code
+- 快速补全和小修改 → Cursor
+
+### Q: 团队新人如何快速上手？
+
+**A**：
+1. 阅读本指南，了解工具定位和基本用法
+2. 阅读 `prompt-engineering` Skill，学习 Prompt 编写技巧
+3. 从简单场景开始（如生成 CRUD），逐步尝试复杂任务
+4. 参考团队 Prompt 模板库中的示例
+5. 遇到问题在团队群中讨论，积累经验

package/templates/.claude/skills/api-design/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: api-design
+description: |
+  API 接口设计技能。当用户提到以下关键词时触发：
+  API design, RESTful, 接口设计, URL规范, 接口规范, 端点设计, endpoint design
+
+  本技能提供 Avatar Boot 框架下的 RESTful API 设计规范、URL命名约定、
+  请求响应结构、分页设计和错误处理等完整指导。
+---
+
+# API 接口设计技能
+
+## 适用场景
+
+- 设计新的 RESTful API 接口
+- 审查现有接口的规范性
+- 统一项目接口风格
+- 制定接口文档结构
+
+## 设计工作流
+
+1. **需求理解** — 明确接口的业务目的和调用方
+2. **资源识别** — 确定核心资源及其层级关系
+3. **URL 设计** — 遵循 RESTful 命名规范
+4. **方法选择** — 映射合适的 HTTP 方法
+5. **请求/响应定义** — 设计 DTO 结构
+6. **错误处理** — 定义异常响应格式
+7. **文档编写** — 补充接口说明和示例
+
+## URL 命名规范
+
+### 基本规则
+
+- 使用 **kebab-case**（短横线分隔），禁止 camelCase 或 snake_case
+- 面向资源命名，使用名词而非动词
+- 统一前缀 `/api`
+- 资源名使用复数形式
+
+### 示例
+
+```
+正确:
+  GET    /api/user-infos          # 查询用户信息列表
+  GET    /api/user-infos/{id}     # 查询单个用户信息
+  POST   /api/user-infos          # 创建用户信息
+  PUT    /api/user-infos/{id}     # 更新用户信息
+  DELETE /api/user-infos/{id}     # 删除用户信息
+
+  GET    /api/order-items         # 查询订单项列表
+  GET    /api/system-configs      # 查询系统配置列表
+
+错误:
+  GET    /api/getUserInfo         # 动词命名
+  GET    /api/user_info           # snake_case
+  GET    /api/userInfo            # camelCase
+```
+
+### 嵌套资源
+
+```
+GET  /api/users/{userId}/orders          # 用户的订单列表
+GET  /api/users/{userId}/orders/{id}     # 用户的某个订单
+POST /api/users/{userId}/addresses       # 为用户添加地址
+```
+
+## HTTP 方法映射
+
+| 方法     | 用途       | 幂等性 | 请求体 | 典型状态码        |
+|----------|-----------|--------|--------|------------------|
+| `GET`    | 查询资源   | 是     | 无     | 200              |
+| `POST`   | 创建资源   | 否     | 有     | 200              |
+| `PUT`    | 全量更新   | 是     | 有     | 200              |
+| `DELETE` | 删除资源   | 是     | 无     | 200              |
+
+> 注意：Avatar Boot 统一使用 `Result<T>` 封装，HTTP 状态码始终返回 200，业务状态通过 Result.code 区分。
+
+## 强制 Result<T> 封装
+
+> 所有接口响应必须使用 `Result<T>` 统一封装。Result 结构定义和代码示例详见 [architecture-redlines.md](../../rules/architecture-redlines.md#result-响应格式)
+
+```java
+@GetMapping("/{id}")
+public Result<UserInfoVO> getById(@PathVariable Long id) {
+    return Result.success(userInfoService.getById(id));
+}
+```
+
+## 请求/响应 DTO 约定
+
+### 命名规范
+
+| 类型       | 命名格式                | 示例                      |
+|-----------|------------------------|--------------------------|
+| 创建请求   | `XxxCreateDTO`         | `UserInfoCreateDTO`      |
+| 更新请求   | `XxxUpdateDTO`         | `UserInfoUpdateDTO`      |
+| 查询请求   | `XxxQueryDTO`          | `UserInfoQueryDTO`       |
+| 响应对象   | `XxxVO`                | `UserInfoVO`             |
+| 分页查询   | `XxxPageQueryDTO`      | `UserInfoPageQueryDTO`   |
+
+### DTO 示例
+
+```java
+@Data
+public class UserInfoCreateDTO {
+    @NotBlank(message = "用户名不能为空")
+    @Size(max = 50, message = "用户名长度不超过50")
+    private String username;
+
+    @NotBlank(message = "手机号不能为空")
+    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
+    private String phone;
+
+    @Email(message = "邮箱格式不正确")
+    private String email;
+}
+```
+
+## 分页设计
+
+### 请求参数
+
+```java
+@Data
+public class UserInfoPageQueryDTO {
+    @Min(value = 1, message = "页码最小为1")
+    private Integer pageNum = 1;
+
+    @Min(value = 1, message = "每页条数最小为1")
+    @Max(value = 100, message = "每页条数最大为100")
+    private Integer pageSize = 10;
+
+    /** 业务查询条件 */
+    private String username;
+    private Integer status;
+}
+```
+
+### Controller 使用
+
+```java
+@PostMapping("/page")
+public Result<IPage<UserInfoVO>> page(@RequestBody @Valid UserInfoPageQueryDTO dto) {
+    IPage<UserInfoVO> page = userInfoService.page(dto);
+    return Result.success(page);
+}
+```
+
+### Service 层
+
+```java
+public IPage<UserInfoVO> page(UserInfoPageQueryDTO dto) {
+    Page<UserInfo> page = new Page<>(dto.getPageNum(), dto.getPageSize());
+    LambdaQueryWrapper<UserInfo> wrapper = new LambdaQueryWrapper<UserInfo>()
+        .like(StringUtils.isNotBlank(dto.getUsername()), UserInfo::getUsername, dto.getUsername())
+        .eq(dto.getStatus() != null, UserInfo::getStatus, dto.getStatus())
+        .orderByDesc(UserInfo::getCreateTime);
+    Page<UserInfo> result = userInfoMapper.selectPage(page, wrapper);
+    return result.convert(this::convertToVO);
+}
+```
+
+## 错误响应约定
+
+```json
+{
+  "code": 10001,
+  "message": "用户名已存在",
+  "data": null
+}
+```
+
+### 常用错误码段
+
+| 错误码范围       | 含义               |
+|-----------------|--------------------|
+| 0               | 成功               |
+| 10000 - 19999   | 通用业务错误        |
+| 20000 - 29999   | 用户模块错误        |
+| 30000 - 39999   | 订单模块错误        |
+| 40000 - 49999   | 系统级错误          |
+
+## 最佳实践
+
+1. **接口幂等性** — POST 创建接口考虑幂等设计（Token 机制或唯一约束）
+2. **参数校验** — 使用 `@Valid` + JSR 303 注解，不要在 Controller 中手写校验逻辑
+3. **版本管理** — 大版本变更使用 URL 路径版本 `/api/v2/users`
+4. **批量操作** — 批量删除使用 `DELETE /api/users/batch`，请求体传 ID 列表
+5. **敏感数据** — 响应 VO 中脱敏处理手机号、身份证等字段
+6. **接口文档** — 每个接口配合 SpringDoc 注解生成文档
+
+## 设计检查清单
+
+- [ ] URL 是否使用 kebab-case 和资源名词
+- [ ] HTTP 方法是否正确映射 CRUD 操作
+- [ ] 是否使用 `Result<T>` 统一封装响应
+- [ ] 请求参数是否添加 `@Valid` 校验
+- [ ] DTO 命名是否符合 `XxxCreateDTO/XxxVO` 约定
+- [ ] 分页接口是否限制最大 pageSize
+- [ ] 错误码是否在约定范围内
+- [ ] 敏感字段是否脱敏处理