Skip to content

CLAUDE.md

Latest commit

 

History

History
170 lines (125 loc) · 9.97 KB

CLAUDE.md

File metadata and controls

170 lines (125 loc) · 9.97 KB
Raw

CLAUDE.md

请使用中文写提案和回答 这个文件为 Claude Code (claude.ai/code) 提供指导，用于处理此代码库中的代码。

TEngine 基于 HybridCLR + YooAsset + UniTask + Luban 构建。

⚡ 强制工作流（所有任务必须遵守）

禁止跳过 — 无论任务大小，必须按此顺序执行：

第零步：判断任务等级

在执行任何操作前，先判断任务等级：

等级 判断标准 知识查询策略
L1 简单 typo 修正、注释修改、日志输出、单行变量改名（前提：不涉及框架 API 名称、UI 节点前缀、事件定义或资源路径） ❌ 跳过查询，直接编码
L2 调用 调用已知 API、单一模块的局部修改 ✅ 触发 tengine-dev skill（只查该主题）
L3 功能 新功能开发、跨文件修改、新增 UI/资源/事件逻辑 ✅ 触发 tengine-dev skill（全量相关主题）
L4 架构 模块设计、系统重构、多模块协作、架构决策 ✅ 触发 tengine-dev skill（并行多主题）

判断原则：宁可高估等级，不可低估——不确定时上调一级。

第一步：按等级获取规范（使用 tengine-dev skill）

L1 任务直接跳到第二步。L2-L4 必须先触发 tengine-dev skill。

知识源：.claude/skills/tengine-dev/references/（AI 专用精炼文档，唯一权威来源）

调用方式

使用 Skill 工具，skill = "tengine-dev"
描述需要查询的技术问题或功能点

会话内缓存（避免重复查询）

同一会话中已查询过的主题无需重复触发 skill：

  • 直接引用本次会话已获取的规范摘要
  • 仅当任务涉及本次会话未覆盖的新主题时才重新触发

触发时机

场景 必须查询主题
UI 开发 ui-lifecycle.md — UIWindow 生命周期、UIWidget 规范
MVE 数据绑定 mve-patterns.md — BindableProperty、DataContext、MapProperty、MVE 四层架构
FancyScrollView 列表 ui-patterns.md（FancySelectionContext/Cell 生成）+ mve-patterns.md 第八章（carrier 列表模式）
MCP 生成 UI 绑定脚本（_Gen） mcp-tools.md「MCP 自动生成 UI 绑定脚本」（execute_code 反射 ScriptGenerator + 5 陷阱）
资源加载 resource-api.md — LoadAssetAsync API、释放时机
热更代码 hotfix-workflow.md — 程序集划分、GameApp 入口、热更边界
事件系统 event-system.md — GameEvent 用法、AddUIEvent 规范
模块使用 modules.md — GameModule.XXX API、模块生命周期
Luban 配置 luban-config.md — 配置表生成流程、访问方式
代码规范 naming-rules.md — 命名约定、节点前缀、设计模式

第二步：输出代码/方案

基于 tengine-dev skill 返回的规范编写实现。

当 references 规范与代码实际 API 冲突时：

  1. 使用 Grep 搜索实际方法签名验证（例：Grep "ForceUnloadUnusedAssets" 确认参数名）
  2. 优先信任代码中的实际实现
  3. 在输出中标注冲突点，并记录到 .claude/memory/ 供后续修正

核心原则（编码红线）

  1. 异步优先：IO 操作用 UniTask，禁止同步加载/Coroutine
  2. 模块访问：通过 GameModule.XXX 访问，而非 ModuleSystem.GetModule<T>()
  3. 资源必须释放：LoadAssetAsync 对应 UnloadAsset，GameObject 用 LoadGameObjectAsync
  4. 热更边界：GameScripts/Main 不热更，GameScripts/HotFix/ 全部热更
  5. 事件解耦：模块间用 GameEvent，UI 内部用 AddUIEvent

📚 References 参考文档

AI 唯一权威来源：.claude/skills/tengine-dev/references/

文档 内容 层级
architecture.md 项目结构/启动流程 核心
modules.md 模块 API（Timer/Scene/Audio/Fsm） 核心
ui-lifecycle.md UI 开发（生命周期/层级/属性） 核心
event-system.md 事件系统（两种模式/核心接口） 核心
resource-api.md 资源加载/卸载 核心
hotfix-workflow.md 热更代码（HybridCLR/程序集划分/热更包） 核心
luban-config.md 配置表 核心
naming-rules.md 代码规范/命名约定/节点前缀 核心
ui-patterns.md UI 进阶（Widget 模板/节点绑定/FancyScrollView 列表） 进阶
mve-patterns.md MVE 数据绑定（四层架构/BindableProperty/DataContext/MapProperty/carrier 列表模式） 核心
mve-antipatterns.md MVE 避坑（绑定泄漏/回调循环/时序问题/集合约束） 进阶
event-antipatterns.md 事件避坑（内存泄漏/接口无响应/风暴） 进阶
resource-patterns.md 资源管理模式/生命周期/泄漏根因 进阶
mcp-tools.md MCP 场景/GameObject/UI Prefab/脚本/Editor/测试 MCP
mcp-visual.md MCP 材质/Shader/VFX/动画 MCP
troubleshooting.md 问题排查 排障

🔧 自我优化机制

问题记录

触发条件（满足任一即记录）：

  1. 发现 references 文档描述与实际代码 API 不符（通过 Grep/Read 验证）
  2. AI 生成的代码在编译/运行时报错，根因是知识库描述有误
  3. 用户明确指出某文档描述有误

记录规范：

  • 文件名：problem_YYYY-MM-DD.md（如 problem_2026-04-21.md）
  • 必填字段：
    • 问题现象：错误表现或报错信息
    • 文档位置：哪篇 reference 文档哪一节
    • 正确 API：经代码验证后的正确用法
    • 建议修正：文档应改成什么表述

Superpowers-ZH 中文增强版

本项目已安装 superpowers-zh 技能框架（20 个 skills）。

核心规则

  1. 收到任务时，先检查是否有匹配的 skill — 哪怕只有 1% 的可能性也要检查
  2. 设计先于编码 — 收到功能需求时，先用 brainstorming skill 做需求分析
  3. 测试先于实现 — 写代码前先写测试（TDD）
  4. 验证先于完成 — 声称完成前必须运行验证命令

可用 Skills

Skills 位于 .claude/skills/ 目录，每个 skill 有独立的 SKILL.md 文件。

  • brainstorming: 在任何创造性工作之前必须使用此技能——创建功能、构建组件、添加功能或修改行为。在实现之前先探索用户意图、需求和设计。
  • chinese-code-review: 中文 review 沟通参考——话术模板、分级标注（必须修复/建议修改/仅供参考）、国内团队常见反模式应对。仅在用户显式 /chinese-code-review 时调用，不要根据上下文自动触发。
  • chinese-commit-conventions: 中文 commit 与 changelog 配置参考——Conventional Commits 中文适配、commitlint/husky/commitizen 中文模板、conventional-changelog 中文配置。仅在用户显式 /chinese-commit-conventions 时调用，不要根据上下文自动触发。
  • chinese-documentation: 中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。
  • chinese-git-workflow: 国内 Git 平台配置参考——Gitee、Coding.net、极狐 GitLab、CNB 的 SSH/HTTPS/凭据/CI 接入差异与镜像同步配置。仅在用户显式 /chinese-git-workflow 时调用，不要根据上下文自动触发。
  • dispatching-parallel-agents: 当面对 2 个以上可以独立进行、无共享状态或顺序依赖的任务时使用
  • executing-plans: 当你有一份书面实现计划需要在单独的会话中执行，并设有审查检查点时使用
  • finishing-a-development-branch: 当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾
  • mcp-builder: MCP 服务器构建方法论 — 系统化构建生产级 MCP 工具，让 AI 助手连接外部能力
  • receiving-code-review: 收到代码审查反馈后、实施建议之前使用，尤其当反馈不明确或技术上有疑问时——需要技术严谨性和验证，而非敷衍附和或盲目执行
  • requesting-code-review: 完成任务、实现重要功能或合并前使用，用于验证工作成果是否符合要求
  • subagent-driven-development: 当在当前会话中执行包含独立任务的实现计划时使用
  • systematic-debugging: 遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行
  • test-driven-development: 在实现任何功能或修复 bug 时使用，在编写实现代码之前
  • using-git-worktrees: 当需要开始与当前工作区隔离的功能开发，或在执行实现计划之前使用——通过原生工具或 git worktree 回退机制确保隔离工作区存在
  • using-superpowers: 在开始任何对话时使用——确立如何查找和使用技能，要求在任何响应（包括澄清性问题）之前调用 Skill 工具
  • verification-before-completion: 在宣称工作完成、已修复或测试通过之前使用，在提交或创建 PR 之前——必须运行验证命令并确认输出后才能声称成功；始终用证据支撑断言
  • workflow-runner: 在 Claude Code / OpenClaw / Cursor 中直接运行 agency-orchestrator YAML 工作流——无需 API key，使用当前会话的 LLM 作为执行引擎。当用户提供 .yaml 工作流文件或要求多角色协作完成任务时触发。
  • writing-plans: 当你有规格说明或需求用于多步骤任务时使用，在动手写代码之前
  • writing-skills: 当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用

如何使用

当任务匹配某个 skill 时，使用 Skill 工具加载对应 skill 并严格遵循其流程。绝不要用 Read 工具读取 SKILL.md 文件。

如果你认为哪怕只有 1% 的可能性某个 skill 适用于你正在做的事情，你必须调用该 skill 检查。