whale-town-front/docs/AI_docs/workflows/standard_development_workflow.md

WhaleTown 标准开发工作流

AI 编程助手专用：本文档定义了 WhaleTown 项目的标准化开发流程，确保所有开发者遵循统一的规范和质量标准。

---

🎯 工作流概览

┌─────────────────────────────────────────────────────────────────┐
│                    WhaleTown 7步标准开发流程                      │
└─────────────────────────────────────────────────────────────────┘

Step 1: 架构分析        →  读取架构规范，确定文件位置和通信方式
   ↓
Step 2: 功能实现        →  按规范编码，遵循类型安全和事件驱动
   ↓
Step 3: 注释规范检查     →  验证文件头、函数注释的完整性
   ↓
Step 4: 命名规范检查     →  验证PascalCase/camelCase/UPPER_CASE
   ↓
Step 5: 测试代码编写     →  创建GUT单元测试，覆盖核心功能
   ↓
Step 6: 测试验证        →  运行测试，确保所有测试通过
   ↓
Step 7: Git 提交        →  生成符合规范的提交信息并提交

总耗时：约 20-40 分钟（根据功能复杂度）

---

📖 使用方式

方式一：使用 Skill（推荐）⭐

最简单、最高效的方式是使用 whaletown-developer skill：

/whaletown-developer 实现玩家二段跳功能

Skill 会自动执行全部 7 步流程，确保不遗漏任何步骤。

方式二：手动执行流程

如果需要手动控制流程，请按照以下步骤逐步执行，并参考本文档的详细说明。

---

📋 详细步骤说明

Step 1: 架构分析（5分钟）

目标: 理解功能在项目中的位置和通信方式

规范文档: docs/02-开发规范/架构与通信规范.md

执行清单

• 读取架构规范文档
• 确定文件位置（_Core, scenes, UI）
• 确定通信方式（EventSystem）
• 列出依赖的管理器/系统
• 设计事件定义（如需要）

分层架构决策树

功能是核心系统（管理器/全局系统）？
├─ 是 → 放在 _Core/managers/ 或 _Core/systems/
└─ 否 → 功能是游戏场景相关？
    ├─ 是 → 放在 scenes/Maps/, scenes/Entities/, scenes/Components/
    └─ 否 → 功能是UI界面？
        ├─ 是 → 放在 scenes/ui/
        └─ 否 → 重新分析功能定位

通信方式决策

• 同模块内通信: 父调用子方法（向下），子发出信号（向上）
• 跨模块通信: MUST 使用 EventSystem
• 事件定义位置: 所有事件名称定义在 _Core/EventNames.gd

示例：玩家二段跳功能

# 架构分析结果
文件位置: scenes/Entities/Player/Player.gd  # 游戏场景层
通信方式: EventSystem.emit_event()          # 跨模块通信
依赖: EventSystem, Input                     # 系统依赖
事件: PLAYER_DOUBLE_JUMPED                  # 需要在 EventNames.gd 中定义

---

Step 2: 功能实现（10-20分钟）

目标: 按照规范实现功能代码

规范文档: docs/02-开发规范/架构与通信规范.md, claude.md

执行清单

• 创建或修改文件在正确位置
• 所有变量和函数有类型注解
• 使用 Godot 4.2+ 语法（await, @onready）
• 通过 EventSystem 进行跨模块通信
• 如有新事件，添加到 EventNames.gd
• 使用 Nearest 滤镜（Sprite2D/TileMap）

核心规范要点

1. 严格类型安全

# ✅ 正确
var speed: float = 200.0
var currentHealth: int = 100
func move(delta: float) -> void:
func getHealth() -> int:

# ❌ 错误
var speed = 200.0           # 缺少类型注解
func move(delta):           # 缺少参数和返回值类型

2. Godot 4.2+ 语法

# ✅ 正确
await get_tree().create_timer(1.0).timeout
@onready var sprite: Sprite2D = $Sprite2D

# ❌ 错误
yield(get_tree().create_timer(1.0), "timeout")  # Godot 3.x
var sprite = get_node("Sprite2D")               # 应在 _ready 外缓存

3. EventSystem 通信

# 发送事件
EventSystem.emit_event(EventNames.PLAYER_DOUBLE_JUMPED, {
    "position": global_position,
    "direction": velocity.normalized()
})

# 监听事件
func _ready() -> void:
    EventSystem.connect_event(EventNames.INTERACT_PRESSED, _on_interact_pressed)

func _on_interact_pressed(data: Dictionary = {}) -> void:
    # 处理交互逻辑
    pass

4. 自动加载限制

# ✅ 正确：在高层组件中访问
func _ready() -> void:
    var current_state = GameManager.get_game_state()

# ❌ 错误：在底层实体（Player, NPC）中直接访问
func _ready() -> void:
    GameManager.register_player(self)  # 不应该这样做

# ✅ 正确：底层实体使用事件
func _ready() -> void:
    EventSystem.emit_event(EventNames.PLAYER_SPAWNED, {"player": self})

---

Step 3: 注释规范检查（3-5分钟）

目标: 确保代码注释完整且符合规范

规范文档: docs/02-开发规范/代码注释规范.md

执行清单

• 文件头注释完整
• 所有公共函数有完整注释
• 复杂逻辑有行内注释
• 使用 TODO/FIXME/NOTE 标记（如需要）

文件头注释模板

# ============================================================================
# 文件名: PlayerController.gd
# 作用: 玩家角色控制器，处理玩家输入和移动逻辑
#
# 主要功能:
# - 处理键盘和手柄输入
# - 控制角色移动和跳跃
# - 管理角色状态切换
# - 实现二段跳功能
#
# 依赖: EventSystem, InputManager
# 作者: [开发者名称]
# 创建时间: 2025-01-03
# ============================================================================

extends CharacterBody2D
class_name PlayerController

函数注释模板

# 执行二段跳
#
# 在玩家空中时允许执行一次额外的跳跃
# 二段跳的力度为普通跳跃的80%
#
# 参数: 无
#
# 返回值: 无
#
# 使用示例:
#   if Input.is_action_just_pressed("jump") and canDoubleJump:
#       performDoubleJump()
#
# 注意事项:
# - 只能在空中且 canDoubleJump 为 true 时调用
# - 执行后会将 canDoubleJump 设置为 false
# - 落地时会重置 canDoubleJump 为 true
func performDoubleJump() -> void:
    velocity.y = JUMP_FORCE * 0.8
    canDoubleJump = false
    EventSystem.emit_event(EventNames.PLAYER_DOUBLE_JUMPED, {
        "position": global_position
    })

---

Step 4: 命名规范检查（2-3分钟）

目标: 验证所有命名符合项目规范

规范文档: docs/02-开发规范/命名规范.md

执行清单

• 类名使用 PascalCase
• 变量/函数使用 camelCase
• 常量使用 UPPER_CASE
• 私有成员使用下划线前缀
• 文件命名符合规范

命名规范速查表

元素类型	命名规范	示例
类名	PascalCase	class_name PlayerController
变量	camelCase	var moveSpeed: float
私有变量	_camelCase	var _velocity: Vector2
函数	camelCase	func updateMovement()
私有函数	_camelCase	func _calculateDamage()
常量	UPPER_CASE	const MAX_HEALTH: int = 100
枚举类型	PascalCase	enum PlayerState
枚举值	UPPER_CASE	IDLE, WALKING, RUNNING
脚本文件	PascalCase.gd	PlayerController.gd
场景文件	snake_case_scene.tscn	main_scene.tscn
预制体	snake_case_prefab.tscn	player_prefab.tscn

常见错误检查

# ✅ 正确
class_name PlayerController
const MAX_JUMPS: int = 2
var moveSpeed: float = 200.0
var canDoubleJump: bool = true
var _velocity: Vector2 = Vector2.ZERO
func performDoubleJump() -> void:
func _calculateJumpForce() -> float:

# ❌ 错误
class_name player_controller      # 应使用 PascalCase
const maxJumps: int = 2           # 常量应使用 UPPER_CASE
var MoveSpeed: float = 200.0      # 变量应使用 camelCase
var can_double_jump: bool = true  # 不要使用 snake_case
func PerformDoubleJump():         # 函数应使用 camelCase

---

Step 5: 测试代码编写（5-10分钟）

目标: 为实现的功能创建单元测试

规范文档: docs/03-技术实现/测试指南.md

执行清单

• 创建测试文件 tests/unit/test_[name].gd
• 测试文件继承自 GutTest
• 实现 before_each 和 after_each
• 编写核心功能测试
• 编写边界条件测试

测试文件模板

# tests/unit/test_player_double_jump.gd
extends GutTest

## PlayerController 二段跳功能单元测试

var player: PlayerController

func before_each():
    # 每个测试前创建新的 Player 实例
    player = preload("res://scenes/Entities/Player/PlayerController.gd").new()
    add_child(player)
    player.initialize()

func after_each():
    # 每个测试后清理
    player.queue_free()

func test_can_double_jump_after_first_jump():
    # 测试：第一次跳跃后可以二段跳
    player.performJump()
    assert_true(player.canDoubleJump, "Should be able to double jump after first jump")

func test_cannot_triple_jump():
    # 测试：不能三段跳
    player.performJump()
    player.performDoubleJump()
    assert_false(player.canDoubleJump, "Should not be able to triple jump")

func test_reset_double_jump_on_ground():
    # 测试：落地后重置二段跳
    player.performJump()
    player.performDoubleJump()
    player._on_landed()  # 模拟落地
    assert_true(player.canDoubleJump, "Double jump should reset when landing")

func test_double_jump_emits_event():
    # 测试：二段跳发出事件
    watch_signals(EventSystem)
    player.performDoubleJump()
    assert_signal_emitted(EventSystem, "event_raised")

测试覆盖建议

1. 正常流程: 功能的标准使用场景
2. 边界条件: 极限值、特殊输入
3. 错误处理: 异常情况、错误输入
4. 事件通信: 验证事件正确发送和接收
5. 状态管理: 状态转换的正确性

---

Step 6: 测试验证（2-3分钟）

目标: 运行测试确保代码质量

规范文档: docs/03-技术实现/测试指南.md

执行清单

• 运行 GUT 测试命令
• 所有测试通过
• 如有失败，修复并重新测试
• 确认测试覆盖核心功能

运行测试

# 运行所有测试
godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs

# 运行特定测试文件
godot --headless -s addons/gut/gut_cmdline.gd -gtest=res://tests/unit/test_player_double_jump.gd

测试结果分析

所有测试通过：

========================
= PASSED: 4 of 4 tests =
========================

✅ 进入下一步

部分测试失败：

==========================
= FAILED: 1 of 4 tests  =
==========================
FAILED: test_cannot_triple_jump
  Expected: false
  Got: true

❌ 修复问题后重新测试

---

Step 7: Git 提交（3-5分钟）

目标: 生成符合规范的 Git 提交信息

规范文档: docs/02-开发规范/Git提交规范.md

执行清单

• 确定提交类型（feat/fix/docs/refactor等）
• 生成规范的提交信息
• 使用中文冒号（：）
• 描述简洁明了
• 遵循"一次提交只做一件事"

提交类型选择

改动类型	提交类型	示例
新功能	feat	feat：实现玩家二段跳功能
Bug修复	fix	fix：修复跳跃碰撞检测问题
文档更新	docs	docs：更新架构规范文档
代码重构	refactor	refactor：重构移动系统逻辑
性能优化	perf	perf：优化物理计算性能
测试相关	test	test：添加二段跳单元测试
场景文件	scene	scene：创建战斗场景
UI界面	ui	ui：设计暂停菜单界面

提交示例

# 示例1：新功能（完整流程）
git add scenes/Entities/Player/PlayerController.gd
git add _Core/EventNames.gd
git add tests/unit/test_player_double_jump.gd
git commit -m "feat：实现玩家二段跳功能"

# 示例2：Bug修复
git add scenes/Entities/Player/PlayerController.gd
git commit -m "fix：修复二段跳状态未重置的问题"

# 示例3：测试添加
git add tests/unit/test_player_movement.gd
git commit -m "test：添加玩家移动系统单元测试"

# 示例4：带详细描述的提交
git commit -m "feat：实现玩家二段跳功能

- 添加二段跳核心逻辑
- 在空中允许执行一次额外跳跃
- 二段跳力度为普通跳跃的80%
- 发送 PLAYER_DOUBLE_JUMPED 事件
- 落地时重置二段跳能力"

多类型改动处理

⚠️ 如果同时有多种类型改动，必须拆分提交：

# ❌ 错误：混合提交
git commit -m "fix + feat：修复Bug并添加新功能"

# ✅ 正确：拆分提交
git add PlayerController.gd  # 只暂存 Bug 修复部分
git commit -m "fix：修复跳跃碰撞检测问题"

git add PlayerController.gd  # 暂存新功能部分
git commit -m "feat：实现玩家二段跳功能"

---

✅ 完整工作流检查清单

在完成开发任务后，使用此清单验证是否执行了全部流程：

总览检查

• ✅ Step 1: 架构分析完成
• ✅ Step 2: 功能实现完成
• ✅ Step 3: 注释规范检查通过
• ✅ Step 4: 命名规范检查通过
• ✅ Step 5: 测试代码编写完成
• ✅ Step 6: 测试验证通过
• ✅ Step 7: Git 提交完成

详细检查

• 文件位置符合分层架构（_Core, scenes, UI）
• 使用 EventSystem 进行跨模块通信
• 新事件已添加到 EventNames.gd
• 所有变量和函数有类型注解
• 使用 Godot 4.2+ 语法（await, @onready）
• 命名规范正确（PascalCase/camelCase/UPPER_CASE）
• 文件头注释完整
• 公共函数有完整文档注释
• 创建了单元测试文件
• 所有测试通过
• Git 提交信息符合规范
• Sprite2D/TileMap 使用 Nearest 滤镜
• 未违反自动加载限制

---

🚀 最佳实践

使用 TodoWrite 追踪进度

在执行工作流时，使用 TodoWrite 工具追踪每个步骤：

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

每完成一步，立即标记为 completed。

常见错误避免

1. 跳过测试: 测试不是可选项，必须为核心功能编写测试
2. 混合提交: 不要在一次提交中混合 fix 和 feat
3. 命名不一致: 严格遵循 PascalCase/camelCase/UPPER_CASE
4. 缺少注释: 公共函数必须有完整注释
5. 直接访问单例: 底层实体使用事件，不直接访问 GameManager

提升效率技巧

1. 使用 Skill: 调用 /whaletown-developer 自动执行全流程
2. 模板复用: 参考现有代码的结构和注释模板
3. 增量提交: 不要等所有功能完成才提交，完成一个逻辑单元就提交
4. 快速参考: 使用 .claude/skills/whaletown-developer/references/checklist.md 快速自检

---

📚 相关文档索引

核心规范文档

• 架构与通信: docs/02-开发规范/架构与通信规范.md
• 代码注释: docs/02-开发规范/代码注释规范.md
• 命名规范: docs/02-开发规范/命名规范.md
• Git 提交: docs/02-开发规范/Git提交规范.md
• 测试指南: docs/03-技术实现/测试指南.md
• 项目指令: claude.md (根目录)

辅助文档

• Skill 指令: .claude/skills/whaletown-developer/SKILL.md
• 快速检查清单: .claude/skills/whaletown-developer/references/checklist.md
• 功能开发流程: docs/AI_docs/workflows/feature_development.md

---

💡 示例：完整开发流程

任务：实现玩家二段跳功能

Step 1: 架构分析 (3分钟)

读取: docs/02-开发规范/架构与通信规范.md
分析结果:
  - 文件位置: scenes/Entities/Player/PlayerController.gd
  - 通信方式: EventSystem
  - 依赖: EventSystem, Input
  - 事件: PLAYER_DOUBLE_JUMPED (需添加到 EventNames.gd)

Step 2: 功能实现 (15分钟)

# scenes/Entities/Player/PlayerController.gd
extends CharacterBody2D
class_name PlayerController

const JUMP_FORCE: float = -400.0
const MAX_DOUBLE_JUMPS: int = 1

var canDoubleJump: bool = true
var doubleJumpCount: int = 0

func performDoubleJump() -> void:
    if not canDoubleJump or doubleJumpCount >= MAX_DOUBLE_JUMPS:
        return

    velocity.y = JUMP_FORCE * 0.8
    doubleJumpCount += 1
    canDoubleJump = false

    EventSystem.emit_event(EventNames.PLAYER_DOUBLE_JUMPED, {
        "position": global_position
    })

func _on_landed() -> void:
    doubleJumpCount = 0
    canDoubleJump = true

Step 3-4: 注释和命名检查 (5分钟)

✅ 文件头注释完整
✅ 函数注释完整
✅ 类名 PascalCase: PlayerController
✅ 变量 camelCase: canDoubleJump
✅ 常量 UPPER_CASE: MAX_DOUBLE_JUMPS

Step 5: 编写测试 (8分钟)

# tests/unit/test_player_double_jump.gd
extends GutTest

var player: PlayerController

func before_each():
    player = PlayerController.new()
    add_child(player)

func test_can_double_jump():
    assert_true(player.canDoubleJump)

func test_double_jump_resets_on_landing():
    player.performDoubleJump()
    player._on_landed()
    assert_true(player.canDoubleJump)

Step 6: 测试验证 (2分钟)

$ godot --headless -s addons/gut/gut_cmdline.gd
========================
= PASSED: 2 of 2 tests =
========================

Step 7: Git 提交 (3分钟)

git add scenes/Entities/Player/PlayerController.gd
git add _Core/EventNames.gd
git add tests/unit/test_player_double_jump.gd
git commit -m "feat：实现玩家二段跳功能"

总耗时: 约 36 分钟 结果: ✅ 功能实现完整，符合所有规范

---

🎓 总结

遵循此 7 步标准开发工作流，可以确保：

1. 代码质量: 符合项目的所有规范和标准
2. 团队一致: 所有开发者使用相同的流程和规范
3. 可维护性: 清晰的注释、规范的命名、完整的测试
4. 高效协作: 规范的 Git 提交历史，便于追溯和回滚
5. 质量保证: 测试驱动开发，确保功能正确性

记住: 使用 /whaletown-developer skill 可以自动化执行此流程！🚀