spellforge/CLAUDE.md

CLAUDE.md

本文件为 Claude Code 在本工程中工作时的约定与规范。

项目简介

Spellforge（万法熔炉）—— Godot 4.6 (Mono) 弹幕射击 Roguelite，SoA / ECS-Lite 架构，法术管道系统。工程概览见 README.md。

Git 提交规范

• 及时提交：完成一个逻辑完整的改动（一个功能点、一处修复、一批相关文档更新）后应立即提交，不要将多个无关改动堆积在一个大提交里。
• 提交信息使用中文，简明说明「做了什么、为什么」。
• 仅在用户要求时才 push；如当前在主分支（main / master）上进行功能开发，先切分支。
• 提交前确认改动范围符合预期（git status / git diff），不要顺手提交无关文件。

文档存放规范

工程文档分两处存放，新增或修改文档时按用途归位：

• docs/ —— 项目指导 / 架构设计等权威文档。面向产品的设计规范、技术架构、机制细节、开发手册。这是跨切片实现约束的权威来源（含关键规范速查表 P6-N* / ADR-*）。索引见 docs/README.md。
• docs_dev/ —— 开发过程中产生的文档。开发计划、进度追踪、审计报告、平台认证清单、历史归档草案等过程性文档。索引见 docs_dev/README.md。

判断依据：若文档是「项目应当如何设计/实现」的权威规范 → docs/；若是「开发过程中的计划、记录、追踪、归档」→ docs_dev/。

编辑器插件 / 游戏设计器开发规范

面向 addons/game_designer/ 等 @tool 编辑器插件（可视化配置工具）。用户手册见 docs/handbook/07_game_designer.md。

• 字段化，禁止手写 JSON：凡是可结构化的数据都用输入控件（SpinBox / OptionButton / CheckBox / 行编辑器），不要用 TextEdit 让用户手写 JSON —— 易配置错、可读性差。
  • 可变长的小整数元组列表（如 Core edges、balance aether_thresholds）用共享组件 addons/game_designer/tuple_list_editor.gd（setup/set_values/get_values，行 + ➕加/🗑删）。
  • 唯一例外：专门收纳「schema 之外的未知键」的逃生舱（如法术 meta 的「其它(JSON)」），因键不可预知才保留文本框，且正常应为空。
• 复用 designer_ui.gd 辅助：控件一律经 UI.spin/line/opt/btn/cell_label/header/status_label/set_status/load_json/save_json 创建；元素标签用共享常量 UI.ELEM_LABELS/UI.ELEM_TAGS。不要自建裸控件绕过。
• 输入框须完整显示内容：输入/下拉控件设 size_flags_horizontal = Control.SIZE_EXPAND_FILL（designer_ui.gd 的 line/opt/spin 工厂已内置），撑满面板宽度，长文本/长选项不截断。
• 标签中英双语，中文在前：所有枚举/选项显示用「中文 English」序（如 动作 ACTION、火 Fire、矩阵 MATRIX、每 N 次 every_n_shots）。
• 显示与存储解耦：OptionButton 存整数 index 或 key，绝不把双语显示串写进 JSON。显示标签数组与存储值数组分离（如 LOGIC_OPS 存 key、LOGIC_OP_LABELS 仅供下拉显示，二者 index 对齐）。
• 数据往返一致 / 防丢键：_on_select 回读 → _on_apply 应用应语义等价；未知键用逃生舱保留不丢；可选键为默认值时可省略以保持 JSON 简洁。
• 改动后验证：用 godot-mcp-pro validate_script 校验语法；对真实 data/*.json 跑回读往返（execute_editor_script 断言 FAILS=0）。⚠️ dock 里驻留的旧 GDScript 类需 EditorInterface.restart_editor(true) 清缓存后才测得到新代码（reload_project/reload_plugin 不重编译已加载类）。
• 纯数据驱动：内容只存在于 res://data/*.json，代码不含硬编码副本或回退；文件缺失/格式错误应 push_error 明确报错，不静默用旧值。
• 新增 .gd 记得提交同名 .gd.uid（与既有组件一致）。
• 新增分页 3 步：@tool extends VBoxContainer 标签脚本（复用 designer_ui.gd）→ 在 designer_panel.gd 的 _init() 里 _add_tab(...) 注册 → 对应 Manager 加 _load_json_xxx() 于 _ready() 调用。