forked from datawhale/whale-town-front
feat：添加whaletown-developer标准开发工作流技能
- 创建whaletown-developer skill自动化7步开发流程 - 添加完整的使用说明文档和质量检查清单 - 更新CLAUDE.md集成标准开发工作流说明 - 新增标准开发工作流详细文档 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
312
.claude/skills/whaletown-developer/使用说明.md
Normal file
312
.claude/skills/whaletown-developer/使用说明.md
Normal file
@@ -0,0 +1,312 @@
|
||||
# WhaleTown Developer Skill 使用说明
|
||||
|
||||
## 📖 简介
|
||||
|
||||
`whaletown-developer` 是 WhaleTown 项目的标准开发工作流自动化技能，确保所有开发任务都遵循统一的项目规范和质量标准。
|
||||
|
||||
## 🎯 适用场景
|
||||
|
||||
在以下情况下使用此 skill：
|
||||
|
||||
- ✅ 实现新功能（"实现玩家二段跳"、"添加存档系统"）
|
||||
- ✅ 修复 Bug（"修复角色碰撞问题"、"解决UI显示错误"）
|
||||
- ✅ 创建场景（"创建商店场景"、"设计背包界面"）
|
||||
- ✅ 开发模块（"开发任务系统"、"构建战斗组件"）
|
||||
- ✅ 任何需要遵循项目规范的代码开发任务
|
||||
|
||||
## 🚀 调用方式
|
||||
|
||||
### 方式一：通过 Claude（推荐）
|
||||
|
||||
```
|
||||
用户：帮我实现一个 NPC
|
||||
Claude：/whaletown-developer 实现一个 NPC
|
||||
```
|
||||
|
||||
### 方式二：直接请求
|
||||
|
||||
```
|
||||
用户：使用 whaletown-developer skill 创建玩家移动系统
|
||||
```
|
||||
|
||||
## 📋 7 步工作流程
|
||||
|
||||
skill 会自动执行以下标准化流程：
|
||||
|
||||
```
|
||||
Step 1: 架构分析
|
||||
↓ 读取架构规范，确定文件位置、通信方式、依赖关系
|
||||
|
||||
Step 2: 功能实现
|
||||
↓ 按照类型安全、命名规范、EventSystem 通信等要求编码
|
||||
|
||||
Step 3: 注释规范检查
|
||||
↓ 验证文件头、函数文档、行内注释是否完整
|
||||
|
||||
Step 4: 命名规范检查
|
||||
↓ 验证 PascalCase/camelCase/UPPER_CASE 命名规范
|
||||
|
||||
Step 5: 测试代码编写
|
||||
↓ 为核心功能创建 GUT 单元测试
|
||||
|
||||
Step 6: 测试验证
|
||||
↓ 运行测试确保功能正常
|
||||
|
||||
Step 7: Git 提交
|
||||
↓ 生成符合规范的提交信息
|
||||
```
|
||||
|
||||
## 💡 使用示例
|
||||
|
||||
### 示例 1：创建玩家控制器
|
||||
|
||||
**用户输入：**
|
||||
```
|
||||
帮我创建一个玩家角色控制器
|
||||
```
|
||||
|
||||
**Skill 执行：**
|
||||
1. 分析架构 → 确定放在 `scenes/Entities/Player/PlayerController.gd`
|
||||
2. 实现功能 → 创建带类型注解的移动、跳跃逻辑
|
||||
3. 检查注释 → 添加完整的文件头和函数文档
|
||||
4. 检查命名 → 确保 `moveSpeed`、`MAX_HEALTH` 等命名正确
|
||||
5. 编写测试 → 创建 `tests/unit/test_player_controller.gd`
|
||||
6. 运行测试 → 验证功能正常
|
||||
7. 生成提交 → `feat：实现玩家角色控制器`
|
||||
|
||||
### 示例 2：修复跳跃 Bug
|
||||
|
||||
**用户输入：**
|
||||
```
|
||||
修复玩家跳跃时的碰撞检测问题
|
||||
```
|
||||
|
||||
**Skill 执行：**
|
||||
1. 分析架构 → 定位到 `scenes/Entities/Player/Player.gd`
|
||||
2. 实现修复 → 修改碰撞检测逻辑
|
||||
3. 检查注释 → 添加修复说明注释
|
||||
4. 检查命名 → 确保变量命名规范
|
||||
5. 编写测试 → 添加碰撞测试用例
|
||||
6. 运行测试 → 确认 Bug 已修复
|
||||
7. 生成提交 → `fix：修复玩家跳跃时的碰撞检测问题`
|
||||
|
||||
### 示例 3：添加事件通信
|
||||
|
||||
**用户输入：**
|
||||
```
|
||||
实现 NPC 对话系统的事件通信
|
||||
```
|
||||
|
||||
**Skill 执行：**
|
||||
1. 分析架构 → 使用 EventSystem 跨模块通信
|
||||
2. 实现功能 → 在 EventNames.gd 添加 `NPC_DIALOG_STARTED` 事件
|
||||
3. 检查注释 → 文档化事件数据格式
|
||||
4. 检查命名 → 确保事件名称符合规范
|
||||
5. 编写测试 → 测试事件发送和接收
|
||||
6. 运行测试 → 验证通信正常
|
||||
7. 生成提交 → `feat：实现NPC对话系统的事件通信`
|
||||
|
||||
## ✅ 质量保证
|
||||
|
||||
每次使用 skill 后，代码都会符合以下标准：
|
||||
|
||||
### 架构层面
|
||||
- ✅ 文件位置符合分层架构（_Core、scenes、UI）
|
||||
- ✅ 使用 EventSystem 实现跨模块通信
|
||||
- ✅ 事件名称已添加到 EventNames.gd
|
||||
- ✅ 遵循"Signal Up, Call Down"原则
|
||||
|
||||
### 代码质量
|
||||
- ✅ 所有变量和函数都有类型注解
|
||||
- ✅ 命名规范正确（PascalCase/camelCase/UPPER_CASE）
|
||||
- ✅ 使用 Godot 4.2+ 语法（await 而非 yield）
|
||||
- ✅ 节点引用使用 @onready 缓存
|
||||
|
||||
### 文档规范
|
||||
- ✅ 文件头注释完整（文件名、作用、功能、依赖）
|
||||
- ✅ 公共函数有完整文档（参数、返回值、示例）
|
||||
- ✅ 复杂逻辑有行内注释说明
|
||||
|
||||
### 测试覆盖
|
||||
- ✅ 核心功能有单元测试
|
||||
- ✅ 测试文件命名规范（test_*.gd）
|
||||
- ✅ 测试通过验证
|
||||
|
||||
### Git 规范
|
||||
- ✅ 提交信息格式正确（类型：描述）
|
||||
- ✅ 遵循"一次提交只做一件事"原则
|
||||
- ✅ 使用中文冒号和动词开头
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
Skill 会自动读取以下规范文档：
|
||||
|
||||
- `docs/02-开发规范/架构与通信规范.md` - 分层架构和 EventSystem
|
||||
- `docs/02-开发规范/代码注释规范.md` - 注释格式要求
|
||||
- `docs/02-开发规范/命名规范.md` - 命名约定
|
||||
- `docs/03-技术实现/测试指南.md` - 测试框架使用
|
||||
- `docs/02-开发规范/Git提交规范.md` - 提交信息格式
|
||||
- `CLAUDE.md` - 项目总体指导
|
||||
|
||||
## ⚙️ 配置文件
|
||||
|
||||
Skill 相关配置文件位置：
|
||||
|
||||
```
|
||||
.claude/skills/whaletown-developer/
|
||||
├── SKILL.md # Skill 定义文件
|
||||
├── 使用说明.md # 本文档
|
||||
└── references/
|
||||
└── checklist.md # 质量检查清单
|
||||
```
|
||||
|
||||
## 🔄 工作流程可视化
|
||||
|
||||
```
|
||||
用户请求
|
||||
↓
|
||||
调用 whaletown-developer skill
|
||||
↓
|
||||
[Step 1] 架构分析
|
||||
├─ 读取架构规范文档
|
||||
├─ 确定文件位置
|
||||
├─ 识别通信方式
|
||||
└─ 设计事件定义
|
||||
↓
|
||||
[Step 2] 功能实现
|
||||
├─ 遵循类型安全
|
||||
├─ 使用 EventSystem
|
||||
├─ 缓存节点引用
|
||||
└─ 使用 Godot 4.2+ 语法
|
||||
↓
|
||||
[Step 3] 注释规范检查
|
||||
├─ 验证文件头注释
|
||||
├─ 验证函数文档
|
||||
└─ 检查行内注释
|
||||
↓
|
||||
[Step 4] 命名规范检查
|
||||
├─ 类名 PascalCase
|
||||
├─ 变量/函数 camelCase
|
||||
├─ 常量 UPPER_CASE
|
||||
└─ 私有成员 _prefix
|
||||
↓
|
||||
[Step 5] 测试代码编写
|
||||
├─ 创建测试文件
|
||||
├─ 编写测试用例
|
||||
└─ 覆盖核心功能
|
||||
↓
|
||||
[Step 6] 测试验证
|
||||
├─ 运行 GUT 测试
|
||||
├─ 验证测试通过
|
||||
└─ 修复失败测试
|
||||
↓
|
||||
[Step 7] Git 提交
|
||||
├─ 确定提交类型
|
||||
├─ 生成提交信息
|
||||
└─ 遵循提交规范
|
||||
↓
|
||||
完成 ✅
|
||||
```
|
||||
|
||||
## 🎓 最佳实践
|
||||
|
||||
### 1. 明确任务描述
|
||||
```bash
|
||||
# ✅ 好的描述
|
||||
"实现玩家二段跳功能"
|
||||
"修复敌人AI路径寻找Bug"
|
||||
"创建商店购买界面"
|
||||
|
||||
# ❌ 模糊描述
|
||||
"改一下玩家"
|
||||
"修复Bug"
|
||||
"做个界面"
|
||||
```
|
||||
|
||||
### 2. 一次处理一个功能
|
||||
```bash
|
||||
# ✅ 推荐
|
||||
用户：实现玩家移动
|
||||
用户：实现玩家跳跃
|
||||
|
||||
# ❌ 不推荐
|
||||
用户：实现玩家移动、跳跃、攻击、技能系统
|
||||
```
|
||||
|
||||
### 3. 信任 Skill 流程
|
||||
- Skill 会按照 7 步流程确保质量
|
||||
- 不需要手动检查命名、注释等细节
|
||||
- 专注于功能需求和业务逻辑
|
||||
|
||||
### 4. 查看生成的提交信息
|
||||
- Skill 会在 Step 7 生成规范的提交信息
|
||||
- 可以直接使用或根据需要微调
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **首次使用**
|
||||
- 确保已阅读 `CLAUDE.md` 了解项目规范
|
||||
- 确认所有规范文档都已存在
|
||||
|
||||
2. **测试环境**
|
||||
- 确保 GUT 测试框架已安装（如需运行测试）
|
||||
- Godot 可执行文件在 PATH 中（Step 6 测试执行）
|
||||
|
||||
3. **中断处理**
|
||||
- 如果工作流被中断，可以继续执行剩余步骤
|
||||
- Skill 使用 TodoWrite 追踪进度
|
||||
|
||||
4. **规范更新**
|
||||
- 项目规范文档更新时，Skill 会自动读取最新版本
|
||||
- 无需手动同步
|
||||
|
||||
## 🤝 反馈与改进
|
||||
|
||||
如果遇到问题或有改进建议：
|
||||
|
||||
1. 检查是否所有规范文档都已更新
|
||||
2. 确认任务描述清晰明确
|
||||
3. 查看 Skill 执行日志定位问题
|
||||
4. 向团队报告问题或建议
|
||||
|
||||
## 📊 效果对比
|
||||
|
||||
### 不使用 Skill
|
||||
```
|
||||
开发者手动：
|
||||
1. 不确定文件放哪里 ❌
|
||||
2. 可能忘记类型注解 ❌
|
||||
3. 注释不完整 ❌
|
||||
4. 命名不一致 ❌
|
||||
5. 没有测试 ❌
|
||||
6. 提交信息格式错误 ❌
|
||||
结果：代码质量参差不齐
|
||||
```
|
||||
|
||||
### 使用 Skill
|
||||
```
|
||||
Skill 自动化：
|
||||
1. 自动确定正确位置 ✅
|
||||
2. 强制类型安全 ✅
|
||||
3. 完整注释文档 ✅
|
||||
4. 统一命名规范 ✅
|
||||
5. 自动生成测试 ✅
|
||||
6. 规范提交信息 ✅
|
||||
结果：高质量、一致性代码
|
||||
```
|
||||
|
||||
## 🎯 总结
|
||||
|
||||
whaletown-developer skill 是你的开发助手，它会：
|
||||
|
||||
- 🤖 **自动化** 7 步标准流程
|
||||
- 📏 **标准化** 代码质量
|
||||
- 🔒 **保证** 规范遵循
|
||||
- ⚡ **加速** 开发效率
|
||||
- 🧪 **确保** 测试覆盖
|
||||
|
||||
**记住：专注于功能实现，让 Skill 处理规范和质量！**
|
||||
|
||||
---
|
||||
|
||||
**开始使用：** 只需告诉 Claude "帮我实现 XXX 功能" 即可！
|
||||
Reference in New Issue
Block a user