whale-town-front/.claude/skills/whaletown-developer/SKILL.md

---
name: whaletown-developer
description: Automate WhaleTown project's standard development workflow. Use this skill when implementing features, fixing bugs, creating scenes, or any code development tasks. Guides through 7-step process - architecture analysis, implementation, comment/naming validation, testing, and Git commit generation following project conventions.
---

# WhaleTown Standard Development Workflow Skill

This skill automates the standard development workflow for the WhaleTown project, ensuring all developers follow unified specifications and quality standards.

## When to Use This Skill

Activate this skill when:
- Implementing new features ("实现XX功能", "添加XX系统")
- Fixing bugs ("修复XX Bug", "解决XX问题")
- Creating scenes ("创建XX场景", "设计XX界面")
- Developing modules ("开发XX模块", "构建XX组件")
- Any code development task requiring adherence to project standards

## Development Workflow Overview

```
Step 1: Architecture Analysis (读取架构规范)
   ↓
Step 2: Implementation (按规范编码)
   ↓
Step 3: Comment Validation (注释规范检查)
   ↓
Step 4: Naming Validation (命名规范检查)
   ↓
Step 5: Test Writing (编写测试代码)
   ↓
Step 6: Test Execution (运行测试验证)
   ↓
Step 7: Git Commit (生成规范提交信息)
```

## Step-by-Step Workflow

### Step 1: Architecture Analysis

Read and apply the architecture specifications before implementation.

**Actions:**
1. Read `docs/02-开发规范/架构与通信规范.md`
2. Determine file location based on feature type:
   - Core systems → `_Core/managers/` or `_Core/systems/`
   - Game scenes → `scenes/Maps/`, `scenes/Entities/`, `scenes/Components/`
   - UI components → `scenes/ui/`
3. Identify communication method (MUST use EventSystem for cross-module communication)
4. List dependencies (required managers and systems)
5. Design event definitions (add to `_Core/EventNames.gd`)

**Layered Architecture:**
```
UI Layer (界面层)        → scenes/ui/
    ↑
Scenes Layer (游戏层)    → scenes/Maps/, scenes/Entities/
    ↑
_Core Layer (框架层)     → _Core/managers/, _Core/systems/
```

**Communication Principle:** "Signal Up, Call Down"
- Parents call child methods (downward calls)
- Children emit signals to notify parents (upward signals)
- Cross-module communication MUST use EventSystem

### Step 2: Implementation

Implement the feature following strict project conventions.

**Requirements:**
- **Type Safety**: All variables and functions MUST have type annotations
  ```gdscript
  var speed: float = 200.0
  func move(delta: float) -> void:
  ```
- **Godot 4.2+ Syntax**: NO `yield()`, use `await`
- **Node Caching**: Use `@onready` to cache node references, avoid `get_node()` in `_process()`
- **EventSystem Communication**: Use EventSystem for cross-module messaging
  ```gdscript
  EventSystem.emit_event(EventNames.PLAYER_MOVED, {"position": global_position})
  EventSystem.connect_event(EventNames.INTERACT_PRESSED, _on_interact_pressed)
  ```
- **Nearest Filter**: All Sprite2D/TileMap resources MUST use Nearest filter (no Linear filter)
- **AutoLoad Restrictions**: Only GameManager, SceneManager, EventSystem, NetworkManager, ResponseHandler allowed as autoloads
- **Low-level Entities**: Do NOT directly reference GameManager in Player/NPC entities, use events instead

### Step 3: Comment Validation

Ensure code comments meet project standards.

**Actions:**
1. Read `docs/02-开发规范/代码注释规范.md`
2. Verify file header comment is complete:
   ```gdscript
   # ============================================================================
   # 文件名: FeatureName.gd
   # 作用: 简短描述功能
   #
   # 主要功能:
   # - 功能点1
   # - 功能点2
   #
   # 依赖: 列出依赖的管理器/系统
   # 作者: [开发者名称]
   # 创建时间: YYYY-MM-DD
   # ============================================================================
   ```
3. Verify all public functions have complete documentation:
   ```gdscript
   # 函数功能描述
   #
   # 参数:
   #   param_name: Type - 参数说明
   #
   # 返回值:
   #   Type - 返回值说明
   #
   # 使用示例:
   #   var result = function_name(param)
   func function_name(param: Type) -> ReturnType:
   ```
4. Ensure complex logic has inline comments explaining WHY, not WHAT

### Step 4: Naming Validation

Verify all naming follows project conventions.

**Actions:**
1. Read `docs/02-开发规范/命名规范.md`
2. Validate naming conventions:
   - **Class names**: PascalCase (`class_name PlayerController`)
   - **Variables/Functions**: camelCase (`var moveSpeed: float`, `func updateMovement()`)
   - **Constants**: UPPER_CASE (`const MAX_HEALTH: int = 100`)
   - **Private members**: Underscore prefix (`var _velocity: Vector2`)
   - **Scene files**: snake_case with suffix (`player_scene.tscn`, `enemy_prefab.tscn`)
   - **Script files**: PascalCase.gd (`PlayerController.gd`, `GameManager.gd`)

**Common Patterns:**
```gdscript
# ✅ Correct
const MAX_SPEED: float = 300.0
var currentHealth: int
var _isInitialized: bool = false
func getPlayerPosition() -> Vector2:
func _calculateDamage(baseDamage: int) -> int:

# ❌ Incorrect
const maxSpeed: float = 300.0        # Constants must be UPPER_CASE
var CurrentHealth: int                # Variables must be camelCase
var is_initialized: bool = false      # No snake_case for variables
func GetPlayerPosition() -> Vector2:  # Functions must be camelCase
```

### Step 5: Test Writing

Create unit tests for the implemented functionality.

**Actions:**
1. Read `docs/03-技术实现/测试指南.md`
2. For _Core/ managers/systems, MUST create corresponding test file in `tests/unit/`
3. Test file naming: `test_[name].gd`
4. Test file structure:
   ```gdscript
   extends GutTest

   ## [FeatureName] 单元测试

   var feature: FeatureName

   func before_each():
       feature = preload("res://_Core/managers/FeatureName.gd").new()
       add_child(feature)

   func after_each():
       feature.queue_free()

   func test_initialization():
       var result = feature.initialize()
       assert_true(result, "Feature should initialize successfully")

   func test_core_functionality():
       # Test core functionality
       pass
   ```

### Step 6: Test Execution

Run tests to ensure code quality.

**Actions:**
1. Run GUT tests using Bash tool:
   ```bash
   godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs
   ```
2. Verify all tests pass
3. If tests fail:
   - Identify the root cause
   - Fix the implementation or test
   - Re-run tests until all pass

### Step 7: Git Commit

Generate standardized Git commit message.

**Actions:**
1. Read `docs/02-开发规范/Git提交规范.md`
2. Determine commit type based on changes:
   - `feat` - New features
   - `fix` - Bug fixes
   - `docs` - Documentation updates
   - `refactor` - Code refactoring
   - `perf` - Performance optimization
   - `test` - Test additions/modifications
   - `scene` - Scene file changes
   - `ui` - UI related changes
3. Generate commit message using Chinese colon (：):
   ```
   <类型>：<简短描述>

   [可选的详细描述]
   ```
4. Follow principles:
   - **One commit, one change** - Most important rule
   - Use imperative verbs (添加, 修复, 更新)
   - Keep description concise (< 50 characters)
   - If multiple types of changes, split into separate commits

**Examples:**
```bash
# ✅ Good commits
git commit -m "feat：实现玩家二段跳功能"
git commit -m "fix：修复角色跳跃时的碰撞检测问题"
git commit -m "test：添加角色控制器单元测试"

# ❌ Bad commits
git commit -m "fix + feat：修复Bug并添加新功能"  # Mixed types
git commit -m "update player"                    # Vague, English
```

## Progress Tracking

Use TodoWrite tool to track workflow progress:

```gdscript
TodoWrite.create_todos([
  "Step 1: 架构分析 - 读取架构规范",
  "Step 2: 功能实现 - 按规范编码",
  "Step 3: 注释规范检查",
  "Step 4: 命名规范检查",
  "Step 5: 测试代码编写",
  "Step 6: 测试验证 - 运行测试",
  "Step 7: Git 提交 - 生成提交信息"
])
```

Mark each step as `completed` immediately after finishing.

## Quality Checklist

Before completing the workflow, verify:

- [ ] File location follows layered architecture (_Core, scenes, UI)
- [ ] Uses EventSystem for cross-module communication
- [ ] Event names added to EventNames.gd
- [ ] All variables and functions have type annotations
- [ ] Naming conventions correct (PascalCase/camelCase/UPPER_CASE)
- [ ] File header comment complete
- [ ] Public functions have complete documentation
- [ ] Unit tests created and passing
- [ ] Git commit message follows specification
- [ ] No Godot 3.x syntax (yield → await)
- [ ] Node references cached with @onready
- [ ] Sprite2D/TileMap use Nearest filter

## Reference Documents

The skill automatically reads these documents at appropriate steps:

- Architecture: `docs/02-开发规范/架构与通信规范.md`
- Comments: `docs/02-开发规范/代码注释规范.md`
- Naming: `docs/02-开发规范/命名规范.md`
- Testing: `docs/03-技术实现/测试指南.md`
- Git: `docs/02-开发规范/Git提交规范.md`
- Project Instructions: `claude.md` (root directory)

For detailed checklist reference, see `references/checklist.md` in this skill directory.

## Example Workflow

User request: "实现玩家二段跳功能"

1. **Architecture Analysis** ✅
   - Read architecture spec
   - Target: `scenes/Entities/Player/Player.gd`
   - Communication: Emit `PLAYER_DOUBLE_JUMPED` event
   - Dependencies: EventSystem, Input
   - Event: Add `PLAYER_DOUBLE_JUMPED` to EventNames.gd

2. **Implementation** ✅
   - Create double jump logic with type annotations
   - Use EventSystem.emit_event() for notifications
   - Cache references with @onready
   - Use await instead of yield

3. **Comment Validation** ✅
   - Add file header with feature description
   - Document double jump function parameters
   - Add inline comments for jump logic

4. **Naming Validation** ✅
   - Verify: `var canDoubleJump: bool` (camelCase)
   - Verify: `const MAX_DOUBLE_JUMPS: int` (UPPER_CASE)
   - Verify: `func performDoubleJump()` (camelCase)

5. **Test Writing** ✅
   - Create `tests/unit/test_player_double_jump.gd`
   - Test initialization, jump execution, limits

6. **Test Execution** ✅
   - Run: `godot --headless -s addons/gut/gut_cmdline.gd`
   - All tests pass ✅

7. **Git Commit** ✅
   ```bash
   git add scenes/Entities/Player/Player.gd _Core/EventNames.gd tests/unit/test_player_double_jump.gd
   git commit -m "feat：实现玩家二段跳功能"
   ```

## Notes

- This skill enforces quality standards through automated validation
- Each step builds upon the previous, ensuring comprehensive quality control
- Skipping steps will result in incomplete or non-compliant code
- The 7-step workflow is designed for team consistency and maintainability