本文件是项目唯一的 AI 协作规则入口，重点约束「如何改」，不描述项目结构细节。
项目结构、分层、时序与模块关系请查看 ARCHITECTURE.md。
- 新增组件或者模块时，优先查看是否已有功能类似的，避免多个组件实现同样的功能。
- 改动代码时，需要从全局出发，避免代码零散，重复实现同样的功能。
- 改动代码后需要维护文档
- 不要主动生成单元测试，除非明确要求
- 风格引导：职责单一，责任内聚，结构简洁，边界清晰，依赖明确
- 优先不可变数据与显式依赖传递，谨慎引入全局可变状态。
- 明确所有权和生命周期，避免不必要的共享所有权。
- 日志聚焦当前函数行为；关键路径保留可定位问题的日志。
- 错误处理优先健壮性与显式检查，避免把异常当作常规流程。
- Rust 代码使用
rustfmt，C/C++ 代码遵循clang-format。 - 不过度抽象，避免使用 Java 的代码风格；组合优于继承。
- 注释应解释设计意图或关键实现点，调用者需要知道什么
- 注释不重复显而易见的代码行为。
- 注释不仅包含局部信息，还需要让读者知道代码在全局中的上下文和作用。
- 注释使用中文，除非是特定领域术语或代码片段需要英文。
- 对于关键的生命周期，依赖，同步，线程安全以及契约等，注释需要格外注意
- 模块级别的文档或者注释需要说明：职责边界，非职责，主要抽象，对外契约，重要不变量，依赖关系等
- 运行渲染示例前参考 justfile，里面有项目可用命令。
- 保持现有坐标系约定与渲染管线边界，不随意修改基础约定。
- 触及 shader / C++ FFI / RenderGraph 时，优先复用现有模式而非发明新模式。
README.md：面向 GitHub 用户，介绍亮点与上手方式。ARCHITECTURE.md：记录总体架构、设计思路、模块约束。- 模块内
README.md：说明模块职责、依赖与常见入口。 docs/brain-strom/：记录设计讨论与方案评估。其中brain-storm/archive属于归档，无需维护。