From 05c4f06717e2f0372702e2fd66a9f62e40d98851 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Wed, 18 Mar 2026 09:44:06 +0800
Subject: [PATCH] =?UTF-8?q?docs(guide):=20=E6=B7=BB=E5=8A=A0=20CLAUDE.md?=
 =?UTF-8?q?=20=E6=96=87=E4=BB=B6=E6=8F=90=E4=BE=9B=E9=A1=B9=E7=9B=AE?=
 =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=8C=87=E5=AF=BC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增项目概述说明，介绍 GFramework 框架的核心特性
- 添加构建和测试命令指南，包括 dotnet 构建和测试脚本
- 提供模块依赖关系图，说明各模块之间的依赖结构
- 详细描述架构模式，包括四层结构和关键设计模式
- 添加代码约定说明，涵盖命名空间、隐式引用等规范
- 补充测试框架信息，说明测试结构和基类使用方式
- 介绍源码生成器功能，列出四个主要生成器的作用
- 提供文档站点信息，说明 VitePress 文档的本地预览方法
---
 CLAUDE.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..360d717
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+GFramework 是面向游戏开发的模块化 C# 框架，核心能力与引擎解耦。灵感参考 QFramework，在模块边界和可扩展性方面持续重构。
+
+## Build & Test Commands
+
+```bash
+# 构建整个解决方案
+dotnet build GFramework.sln -c Release
+
+# 运行全部测试
+dotnet test GFramework.sln -c Release
+
+# 运行单个测试项目
+dotnet test GFramework.Core.Tests -c Release
+dotnet test GFramework.Game.Tests -c Release
+dotnet test GFramework.SourceGenerators.Tests -c Release
+dotnet test GFramework.Ecs.Arch.Tests -c Release
+
+# 运行单个测试方法（NUnit filter）
+dotnet test GFramework.Core.Tests -c Release --filter "FullyQualifiedName~CommandExecutorTests.Execute"
+
+# 命名规范验证（CI 中使用）
+bash scripts/validate-csharp-naming.sh
+```
+
+## Module Dependency Graph
+
+```
+GFramework (meta package) ─→ Core + Game
+GFramework.Core ─→ Core.Abstractions
+GFramework.Game ─→ Game.Abstractions, Core, Core.Abstractions
+GFramework.Godot ─→ Core, Game, Core.Abstractions, Game.Abstractions
+GFramework.Ecs.Arch ─→ Ecs.Arch.Abstractions, Core, Core.Abstractions
+GFramework.SourceGenerators ─→ SourceGenerators.Common, SourceGenerators.Abstractions
+```
+
+- **Abstractions projects** (netstandard2.1): 只含接口定义，零实现依赖
+- **Core/Game** (net8.0;net9.0;net10.0): 平台无关实现
+- **Godot**: Godot 引擎集成层
+- **SourceGenerators** (netstandard2.1): Roslyn 增量生成器
+
+## Architecture Pattern
+
+框架核心采用 Architecture / Model / System / Utility 四层结构：
+
+- **IArchitecture**: 顶层容器，管理生命周期（Init → Ready → Destroy）、注册 Model/System/Utility
+- **IContextAware**: 统一上下文访问接口，所有组件通过 `SetContext(IArchitectureContext)` 获得对 Architecture 服务的引用
+- **IModel**: 数据层（状态管理），继承 IContextAware
+- **ISystem**: 业务逻辑层，继承 IContextAware
+- **IUtility**: 无状态工具层
+
+关键实现类：`GFramework.Core/Architectures/Architecture.cs`（主流程编排）
+
+## Key Patterns
+
+**CQRS**: Command/Query 分离，支持同步与异步。Mediator 模式通过 `Mediator.SourceGenerator` 实现。
+
+**EventBus**: 类型安全事件总线，支持优先级、过滤器、弱引用订阅。`IEventBus.Send<T>()` / `Register<T>(handler)` →
+`IUnRegister`。
+
+**BindableProperty**: 响应式属性绑定，`IBindableProperty<T>.Value` 变更自动触发 `OnValueChanged`。
+
+**Coroutine**: 帧驱动协程系统，`IYieldInstruction` + `CoroutineScheduler`，提供 WaitForSeconds/WaitForEvent/WaitForTask
+等指令。
+
+**IoC**: 通过 `MicrosoftDiContainer` 封装 `Microsoft.Extensions.DependencyInjection`。
+
+**Service Modules**: `IServiceModule` 模式用于向 Architecture 注册内置服务（EventBus、CommandExecutor、QueryExecutor 等）。
+
+## Code Conventions
+
+- **命名空间**: `GFramework.{Module}.{Feature}` (PascalCase)，CI 通过 `scripts/validate-csharp-naming.sh` 强制校验
+- **ImplicitUsings: disabled** — 所有 using 必须显式声明
+- **Nullable: enabled**
+- **LangVersion: preview**
+- **GenerateDocumentationFile: true** — 公共 API 需要 XML 文档注释
+- **Analyzers**: Meziantou.Analyzer 在构建时强制代码规范
+
+## Testing
+
+- **Framework**: NUnit 4.x + Moq
+- **测试结构**: 镜像源码目录（如 `Core.Tests/Command/` 对应 `Core/Command/`）
+- **基类**: `ArchitectureTestsBase<T>` 提供 Architecture 初始化/销毁模板；`SyncTestArchitecture` /
+  `AsyncTestArchitecture` 用于集成测试
+- **Target frameworks**: net8.0;net10.0
+
+## Source Generators
+
+四个生成器，均为 Roslyn 增量源码生成器：
+
+- `LoggerGenerator` (`[Log]`): 自动生成 ILogger 字段和日志方法
+- `PriorityGenerator` (`[Priority]`): 生成优先级比较实现
+- `EnumExtensionsGenerator` (`[GenerateEnumExtensions]`): 枚举扩展方法
+- `ContextAwareGenerator` (`[ContextAware]`): 自动实现 IContextAware 接口
+
+测试使用快照验证（Verify + snapshot files）。
+
+## Documentation
+
+VitePress 站点位于 `docs/`，内容为中文 (`docs/zh-CN/`)。修改文档后本地预览：
+
+```bash
+cd docs && bun install && bun run dev
+```