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

name, description

name	description
whaletown-developer	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

  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

  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:

   # ============================================================================
   # 文件名: FeatureName.gd
   # 作用: 简短描述功能
   #
   # 主要功能:
   # - 功能点1
   # - 功能点2
   #
   # 依赖: 列出依赖的管理器/系统
   # 作者: [开发者名称]
   # 创建时间: YYYY-MM-DD
   # ============================================================================
   

3. Verify all public functions have complete documentation:

   # 函数功能描述
   #
   # 参数:
   #   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:

# ✅ 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:

   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:

   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:

# ✅ 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:

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 ✅

   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