HarmonyOS 应用项目 CLAUDE.md¶

这是面向 HarmonyOS 应用的项目级 CLAUDE.md 示例。请将其放置在项目根目录中。

项目概述¶

[应用的简要说明 - 功能、目标设备、API 级别]

基本规则¶

1. 技术栈约束¶

• 平台: HarmonyOS（ArkTS/TypeScript），优先使用最新稳定的官方 API
• 状态管理: 仅 V2 (@ComponentV2, @Local, @Param, @Event, @Provider, @Consumer, @Monitor, @Computed)
• 路由: 仅 Navigation (Navigation + NavPathStack + NavDestination)
• 架构: 具有模块化分层的 MVVM - 视图仅负责渲染，所有业务逻辑放在 ViewModel 中
• 组件优先级: 模块内可复用组件 > 跨模块共享组件 > 第三方库

2. 代码结构¶

• 优先使用多个小文件，而不是少数大文件
• 高内聚、低耦合
• 每个文件目标 200 至 400 行，最多 800 行
• 按功能/领域组织，而不是按类型组织

3. 代码风格¶

• 不要在代码、注释或文档中使用表情符号
• 不可变性 - 不要直接修改对象
• 字符串使用双引号，并且需要分号
• 绝对不要使用 var - 优先使用 const，其次使用 let
• 不要使用 any 类型 - 为所有方法、参数和返回值添加完整的类型注解
• 命名: 变量/函数使用 camelCase，类/接口使用 PascalCase，常量使用 UPPER_SNAKE_CASE
• 文件头: @file + @author。所有方法都需要包含 @param 和 @returns 的 JSDoc

4. 布局与交互¶

• 均分使用 layoutWeight(1) - 避免使用 SpaceAround/SpaceBetween
• 使用百分比/布局权重/自适应单位 - 不要使用硬编码的固定尺寸（图标除外）
• UI 常量应定义为资源，并通过 $r() 引用
• 新的颜色资源需要同时支持浅色和深色主题

5. 构建与验证¶

# HAPパッケージをビルド
hvigorw assembleHap -p product=default

• 每次实现后运行构建以确认编译
• 对于不确定的 API 使用，请查阅官方 Huawei 开发者文档 - 不要猜测

6. 测试¶

• TDD: 先编写测试
• 工具函数和 ViewModel 的单元测试
• 关键用户流程的 UI 测试
• 业务逻辑覆盖率最低 80%

7. 安全¶

• 不要硬编码密钥
• 使用系统 API 前，在 module.json5 中确认权限
• 验证所有用户输入
• 所有网络请求使用 HTTPS

文件结构¶

src/
|-- entry/            # アプリエントリー、フレームワーク初期化
|-- core/             # コアフレームワークレイヤー
|-- shared/           # 共有コントラクトレイヤー
|-- packages/         # ビジネス機能パッケージ

可用命令¶

• /plan - 创建实现计划
• /code-review - 审查代码质量
• /build-fix - 修复构建错误

Git 工作流¶

• 约定式提交: feat:, fix:, refactor:, docs:, test:
• 禁止直接提交到 main 分支
• PR 需要审查
• 合并前所有测试必须通过