HarmonyOS 应用项目 CLAUDE.md 编写指南基于 ECC 的 ArkTS 开发规则落地方案【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC技术导读本文以 ECC 仓库中 docs/ja-JP/examples/harmonyos-app-CLAUDE.md 为骨架讲解如何为 HarmonyOSArkTS项目编写一份项目级 CLAUDE.md 示例。文章涵盖技术栈约束状态管理 V2、Navigation 路由、MVVM 架构、代码组织与风格、布局与交互规范、构建与验证流程、测试TDD 与 80% 覆盖率、安全权限声明、密钥管理、输入校验、文件结构与可用命令、Git 工作流。读完本文读者将能够基于 ECC 仓库中的示例与 rules/arkts 系列规则为自己的 HarmonyOS 项目落地一份约束明确、可执行、可校验的 Agent 协作基线文件。一、背景为什么 HarmonyOS 项目需要一份 CLAUDE.mdCLAUDE.md 是放在项目根目录、用于约束 AI 编码助手如 Claude Code行为与代码质量的项目级指令文件。对于 HarmonyOS 应用而言由于 ArkTS 是 TypeScript 的严格静态子集不支持any、禁止var、限制解构与展开等直接让 Agent 自由编码极易产生看似正确、实则无法编译的代码。因此在项目根目录放置一份明确的 CLAUDE.md可以固化架构决策状态管理只用 V2、路由只用 Navigation约束代码风格完整类型注解、不可变性、禁止 emoji绑定验证流程每次实现后执行hvigorw assembleHap统一 Git 协作规范conventional commits、PR 评审、main 分支保护。在 ECCThe agent harness performance optimization system的定位中这类项目级 CLAUDE.md 是research-first development的落地载体examples 目录提供了通用示例examples/CLAUDE.md与多个语言/框架特化版本本文聚焦于 HarmonyOS 特化版本。二、项目级 CLAUDE.md 的核心结构一份完整的项目级 CLAUDE.md 至少包含以下小节与 ECC 的 examples/harmonyos-app-CLAUDE.md 一致小节作用关键内容Project Overview项目定位功能、目标设备、API level需自行填写占位符Core Rules核心约束技术栈、代码组织、风格、布局、构建、测试、安全File Structure目录结构src/entry、src/core、src/shared、src/packagesAvailable Commands可用命令/plan、/code-review、/build-fixGit Workflow协作规范conventional commits、PR 评审、测试通过才能合并其中Core Rules是正文主体应细化为可执行、可被校验的硬性规则而不是泛泛而谈的建议。下文逐一展开并给出 ECC 仓库中的实现佐证。三、技术栈约束状态管理 V2、Navigation 路由与 MVVM3.1 状态管理仅用 V2禁用 V1示例文档明确规定状态管理仅 V2ComponentV2、Local、Param、Event、Provider、Consumer、Monitor、ComputedV1 装饰器State、Prop、Link、ObjectLink、Observed、Provide、Consume、Watch、Component禁止使用。ECC 的 rules/arkts/patterns.md 对 V2 装饰器给出了完整对照表装饰器用途ComponentV2将 struct 标记为 V2 组件Local组件内本地状态Param接收自父组件的只读属性Event子组件向父组件回调事件Provider向子孙组件提供状态Consumer消费祖先Provider提供的状态Monitor监听状态变化取代 V1WatchComputed派生/计算值ObservedV2使类可被 V2 状态管理观察Trace在ObservedV2类中标记可观察属性一个典型的 V2 组件示例来自 rules/arkts/patterns.mdObservedV2 class UserModel { Trace name: string Trace age: number 0 } ComponentV2 struct UserCard { Param user: UserModel new UserModel() Event onDelete: () void () {} build() { Column() { Text(this.user.name) .fontSize($r(app.float.font_size_title)) Text(${this.user.age}) .fontSize($r(app.float.font_size_body)) Button($r(app.string.delete)) .onClick(() this.onDelete()) } } }跨组件状态同步使用Provider/ConsumerComponentV2 struct ParentPage { Provider(userState) userModel: UserModel new UserModel() build() { Column() { ChildComponent() // 自动接收 Consumer(userState) } } } ComponentV2 struct ChildComponent { Consumer(userState) userModel: UserModel new UserModel() build() { Text(this.userModel.name) } }实现佐证V1 装饰器被列为Prohibited且配套有 PreToolUse 钩子拦截见 rules/arkts/hooks.md 的 V1 Decorator Guard。3.2 路由仅用 Navigation禁用 ohos.router示例文档规定路由仅用 NavigationNavigationNavPathStackNavDestination。这是因为ohos.router是旧式路由方式能力与类型安全均弱于 Navigation 体系。Navigation 初始化与路由表来自 rules/arkts/patterns.mdComponentV2 struct MainPage { Local navPathStack: NavPathStack new NavPathStack() build() { Navigation(this.navPathStack) { // 首页内容 } .navDestination(this.routerMap) } Builder routerMap(name: string, param: ESObject) { if (name detail) { DetailPage() } else if (name settings) { SettingsPage() } } }页面跳转操作// 压栈新页面 this.navPathStack.pushPath({ name: detail, param: { id: 123 } }) // 替换当前页面 this.navPathStack.replacePath({ name: settings }) // 返回上一页 this.navPathStack.pop() // 返回根页面 this.navPathStack.clear()NavDestination 子页面ComponentV2 struct DetailPage { build() { NavDestination() { Column() { Text($r(app.string.detail_title)) } } .title($r(app.string.detail_nav_title)) } }3.3 架构模块化 MVVM示例文档要求模块型分层 MVVM——View 只负责渲染所有业务逻辑都在 ViewModel 中并给出组件优先级模块内可复用组件 跨模块共享组件 第三方库。ECC 的 rules/arkts/patterns.md 给出 feature 维度目录划分feature/ |-- model/ # 数据模型ObservedV2 类 |-- viewmodel/ # 业务逻辑ViewModel 类 |-- view/ # UI 组件ComponentV2 struct |-- service/ # API 调用、数据访问Viewbuild()中只含渲染逻辑不放业务逻辑ViewModel封装全部业务逻辑Model纯数据类使用ObservedV2与TraceService网络请求、数据库操作、文件 I/O。四、代码组织与代码风格4.1 代码组织示例文档的四条铁律多小文件优于少大文件高内聚、低耦合每文件目标 200400 行上限 800 行按功能/领域组织而不是按类型组织。这与其他 ECC 示例如 examples/CLAUDE.md中的规则一致也与 rules/arkts/coding-style.md 的File Organization保持一致组件文件.ets一个文件一个ComponentV2ViewModel 文件一个文件一个 ViewModel 类Model 文件允许多个相关数据模型共存文件接近 800 行时应抽取辅助函数。4.2 代码风格示例文档的硬性要求代码、注释、文档中不使用 emoji不可变性——不直接修改对象创建新对象字符串使用双引号语句以分号结尾绝不使用var——优先const其次let不使用any类型——所有方法、参数、返回值都要有完整类型注解命名规范变量/函数camelCase类/接口PascalCase常量UPPER_SNAKE_CASE文件头fileauthor所有方法需带param与returns的 JSDoc。从 rules/arkts/coding-style.md 看ArkTS 类型系统的约束远比常规 TypeScript 严格违反即编译失败无any/unknown类型无索引访问类型、无条件类型别名、无infer关键字、无交叉类型、无映射类型不允许解构赋值与解构参数声明需用中间对象 逐字段访问不支持Function.apply/call/bind按传统 OOP 处理this不允许for...in数组用常规for不允许#私有标识符用private关键字不允许Symbol()Symbol.iterator除外所有import语句必须位于其他语句之前。错误处理推荐 try/catch hilog来自 rules/arkts/coding-style.mdtry { const result await riskyOperation() return result } catch (error) { hilog.error(0x0000, TAG, Operation failed: %{public}s, error) throw new Error(User-friendly error message) }不可变性示例// BAD: 直接修改 function updateUser(user: UserModel, name: string): UserModel { user.name name return user } // GOOD: 创建新实例 function updateUser(user: UserModel, name: string): UserModel { const updated new UserModel() updated.id user.id updated.name name updated.email user.email return updated }五、布局与交互规范示例文档关于 UI 布局的要求均等分配使用layoutWeight(1)避免SpaceAround/SpaceBetween使用百分比 / 布局权重 / 自适应单位不使用硬编码固定尺寸图标除外UI 常量定义为资源通过$r()引用新增颜色资源需同时支持亮色与暗色主题。资源引用对比来自 rules/arkts/patterns.md// BAD: 硬编码 Text(Hello) .fontSize(16) .fontColor(#333333) // GOOD: 资源引用 Text($r(app.string.greeting)) .fontSize($r(app.float.font_size_body)) .fontColor($r(app.color.text_primary))动画方面rules/arkts/patterns.md还补充了性能要点优先使用 transformtranslate/scale/rotate与 opacity 做动画绝不在动画过程中频繁修改 width/height/padding/margin复杂子组件动画设置renderGroup(true)以减少渲染批次大列表必须使用LazyForEach。六、构建与验证6.1 构建命令示例文档给出 HAP 包构建命令# 构建 HAP 包 hvigorw assembleHap -p productdefaultECC 的 rules/arkts/hooks.md 扩展了完整命令矩阵# 指定模块构建 hvigorw assembleHap -p moduleentry -p productdefault # 清理构建 hvigorw clean # 查看工具版本 hvigorw --version # 安装依赖 ohpm install # 更新依赖 ohpm update6.2 验证策略示例文档要求每次实现后都运行构建验证编译对不确定的 API 用法查阅华为官方开发者文档绝不猜测。hooks/README.md 与 rules/arkts/hooks.md 描述了如何把构建验证做成自动化钩子。例如编辑.ets/.ts文件后自动触发hvigorw assembleHap{ type: PostToolUse, matcher: { tool: [Edit, Write], filePath: [**/*.ets, **/*.ts] }, hooks: [ { command: hvigorw assembleHap -p productdefault 21 | tail -20, async: true, timeout: 60000 } ] }编辑module.json5后校验权限与 Ability 声明、编辑oh-package.json5后自动ohpm install均有对应钩子模板。每次实现周期结束后的校验清单hvigorw assembleHap无错误完成新增/修改的.ets文件中无 V1 装饰器新增/修改文件中无ohos.router导入所有 API 权限已在module.json5中声明所有依赖已在oh-package.json5中列出资源字符串已加入所有 i18n 目录新颜色资源已提供暗色主题色值。七、测试TDD 与覆盖率门槛示例文档的测试要求TDD先写测试工具函数与 ViewModel 的单元测试关键用户流程的 UI 测试业务逻辑覆盖率最低 80%。ECC 的 rules/arkts/testing.md 给出了完整的 HarmonyOS 测试实践测试目录结构module/ |-- src/ | |-- main/ets/ # 生产代码 | |-- ohosTest/ets/ # 测试代码 | |-- test/ | | |-- Ability.test.ets | | |-- List.test.ets | |-- TestAbility.ets | |-- TestRunner.ets运行测试# 运行模块全部测试 hvigorw testHap -p productdefault # 在连接的设备上运行测试 hdc shell aa test -b com.example.app -m entry_test -s unittest /ets/TestRunner/OpenHarmonyTestRunner单元测试示例import { describe, it, expect } from ohos/hypium; export default function UserViewModelTest() { describe(UserViewModel, () { it(should_initialize_with_empty_state, 0, () { const vm new UserViewModel(); expect(vm.userName).assertEqual(); expect(vm.isLoading).assertFalse(); }); it(should_update_user_name, 0, () { const vm new UserViewModel(); vm.updateUserName(Alice); expect(vm.userName).assertEqual(Alice); }); it(should_handle_empty_input, 0, () { const vm new UserViewModel(); vm.updateUserName(); expect(vm.userName).assertEqual(); expect(vm.hasError).assertFalse(); }); }); }UI 测试示例import { describe, it, expect } from ohos/hypium; import { Driver, ON } from ohos.UiTest; export default function HomePageUITest() { describe(HomePage_UI, () { it(should_display_title, 0, async () { const driver Driver.create(); await driver.delayMs(1000); const title await driver.findComponent(ON.text(Home)); expect(title ! null).assertTrue(); }); it(should_navigate_to_detail_on_click, 0, async () { const driver Driver.create(); const button await driver.findComponent(ON.id(detailButton)); await button.click(); await driver.delayMs(500); const detailTitle await driver.findComponent(ON.text(Detail)); expect(detailTitle ! null).assertTrue(); }); }); }TDD 循环HarmonyOS 适配版RED在ohosTest/ets/test/写失败测试GREEN在main/ets/写最小实现使其通过REFACTOR保持测试通过的前提下重构BUILD运行hvigorw assembleHap验证编译VERIFY在设备/模拟器上运行测试。测试命名规范为should_[expected_behavior]_when_[condition]测试之间保持独立无共享可变状态单测中 mock 网络调用与系统 API额外覆盖边界情况空数据、网络错误、权限被拒。八、安全约束示例文档的安全要求不硬编码密钥使用系统 API 前在module.json5中核对权限校验所有用户输入所有网络请求使用 HTTPS。ECC 的 rules/arkts/security.md 给出了可落地的安全实践权限声明module.json5{ module: { requestPermissions: [ { name: ohos.permission.INTERNET, reason: $string:internet_permission_reason, usedScene: { abilities: [EntryAbility], when: always } } ] } }权限校验清单权限已在module.json5声明面向用户的权限在资源中定义了 reason 字符串敏感权限相机、定位等实现了运行时请求API 调用前做权限检查被拒绝时有优雅降级。运行时权限请求示例import { abilityAccessCtrl, bundleManager, Permissions } from kit.AbilityKit; async function checkAndRequestPermission(permission: Permissions): Promiseboolean { const atManager abilityAccessCtrl.createAtManager(); const bundleInfo await bundleManager.getBundleInfoForSelf( bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION ); const tokenId bundleInfo.appInfo.accessTokenId; const grantStatus await atManager.checkAccessToken(tokenId, permission); if (grantStatus abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { return true; } const result await atManager.requestPermissionsFromUser(getContext(), [permission]); return result.authResults[0] abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED; }密钥管理绝不在.ets/.ts源码中硬编码 API Key、Token 或密码非敏感配置使用 Preferences API敏感凭据使用 HUKSUniversal Keystore加密存储环境相关配置通过构建配置文件管理。输入校验与网络安全处理前校验所有用户输入展示前清洗数据防注入导航前校验深链参数所有网络请求使用 HTTPS校验服务器证书实现超时与重试策略不在请求/响应日志中记录敏感数据Token、用户凭据依赖仅来自可信来源官方 ohpm 仓库在oh-package.json5中锁定版本并定期排查已知漏洞。深链参数校验示例来自 rules/arkts/security.mdfunction handleDeepLink(uri: string): void { const allowedPaths: string[] [detail, settings, profile]; const parsed new URL(uri); const path parsed.pathname.replace(/, ); if (!allowedPaths.includes(path)) { hilog.warn(0x0000, DeepLink, Invalid deep link path: %{public}s, path); return; } navPathStack.pushPath({ name: path }); }九、文件结构与可用命令9.1 建议目录结构src/ |-- entry/ # 应用入口、框架初始化 |-- core/ # 核心框架层 |-- shared/ # 共享契约层 |-- packages/ # 业务功能包9.2 可用命令示例文档推荐三个 Agent 命令命令作用/plan创建实现计划/code-review代码质量评审/build-fix修复构建错误在 ECC 的 docs/COMMAND-AGENT-MAP.md 中这些命令与具体 Agent 一一对应/plan→ planner编码前实现规划、/code-review→ code-reviewer质量与安全评审、/build-fix→ build-error-resolver修复构建/类型错误。命令的完整定义位于 commands/plan.md、commands/code-review.md 等文件。十、Git 工作流示例文档的 Git 规范约定式提交feat:、fix:、refactor:、docs:、test:禁止直接向 main 分支提交PR 必须经过评审合并前所有测试必须通过。examples/CLAUDE.md 与 rules/common/git-workflow.md 补充了 PR 工作流细节分析完整提交历史不只最新提交、用git diff [base-branch]...HEAD查看全部变更、撰写完整 PR 摘要、附带测试计划与 TODO、新分支推送时使用-u标志。完整开发流程规划、TDD、代码评审见 rules/common/development-workflow.md。十一、落地要点与自检清单将本文模板放入 HarmonyOS 项目根目录文件名为CLAUDE.md后应随项目演进持续更新。落地时的关键自检项约束是否可编译验证ArkTS 类型约束无any、无解构、无var应在构建钩子中自动校验状态管理是否 V2 化新代码是否还在使用 V1 装饰器是否被 PreToolUse 钩子提醒路由是否 Navigation 化是否仍存在ohos.router导入资源是否资源化UI 常量是否通过$r()引用新颜色是否同时提供明暗主题安全是否成体系权限声明、密钥存储、输入校验、HTTPS 是否全部覆盖测试是否达标核心业务逻辑覆盖率是否 ≥ 80%关键用户流程是否有 UI 测试Git 协作是否规范conventional commits、PR 评审、main 分支保护是否强制执行。十二、延伸阅读通用项目模板examples/CLAUDE.mdHarmonyOS / ArkTS 规则全集rules/arkts/patterns.md、rules/arkts/coding-style.md、rules/arkts/testing.md、rules/arkts/security.md、rules/arkts/hooks.md命令与 Agent 映射docs/COMMAND-AGENT-MAP.md构建钩子体系hooks/README.mdGit 工作流rules/common/git-workflow.md【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HarmonyOS 应用项目 CLAUDE.md 编写指南：基于 ECC 的 ArkTS 开发规则落地方案
HarmonyOS 应用项目 CLAUDE.md 编写指南基于 ECC 的 ArkTS 开发规则落地方案【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC技术导读本文以 ECC 仓库中 docs/ja-JP/examples/harmonyos-app-CLAUDE.md 为骨架讲解如何为 HarmonyOSArkTS项目编写一份项目级 CLAUDE.md 示例。文章涵盖技术栈约束状态管理 V2、Navigation 路由、MVVM 架构、代码组织与风格、布局与交互规范、构建与验证流程、测试TDD 与 80% 覆盖率、安全权限声明、密钥管理、输入校验、文件结构与可用命令、Git 工作流。读完本文读者将能够基于 ECC 仓库中的示例与 rules/arkts 系列规则为自己的 HarmonyOS 项目落地一份约束明确、可执行、可校验的 Agent 协作基线文件。一、背景为什么 HarmonyOS 项目需要一份 CLAUDE.mdCLAUDE.md 是放在项目根目录、用于约束 AI 编码助手如 Claude Code行为与代码质量的项目级指令文件。对于 HarmonyOS 应用而言由于 ArkTS 是 TypeScript 的严格静态子集不支持any、禁止var、限制解构与展开等直接让 Agent 自由编码极易产生看似正确、实则无法编译的代码。因此在项目根目录放置一份明确的 CLAUDE.md可以固化架构决策状态管理只用 V2、路由只用 Navigation约束代码风格完整类型注解、不可变性、禁止 emoji绑定验证流程每次实现后执行hvigorw assembleHap统一 Git 协作规范conventional commits、PR 评审、main 分支保护。在 ECCThe agent harness performance optimization system的定位中这类项目级 CLAUDE.md 是research-first development的落地载体examples 目录提供了通用示例examples/CLAUDE.md与多个语言/框架特化版本本文聚焦于 HarmonyOS 特化版本。二、项目级 CLAUDE.md 的核心结构一份完整的项目级 CLAUDE.md 至少包含以下小节与 ECC 的 examples/harmonyos-app-CLAUDE.md 一致小节作用关键内容Project Overview项目定位功能、目标设备、API level需自行填写占位符Core Rules核心约束技术栈、代码组织、风格、布局、构建、测试、安全File Structure目录结构src/entry、src/core、src/shared、src/packagesAvailable Commands可用命令/plan、/code-review、/build-fixGit Workflow协作规范conventional commits、PR 评审、测试通过才能合并其中Core Rules是正文主体应细化为可执行、可被校验的硬性规则而不是泛泛而谈的建议。下文逐一展开并给出 ECC 仓库中的实现佐证。三、技术栈约束状态管理 V2、Navigation 路由与 MVVM3.1 状态管理仅用 V2禁用 V1示例文档明确规定状态管理仅 V2ComponentV2、Local、Param、Event、Provider、Consumer、Monitor、ComputedV1 装饰器State、Prop、Link、ObjectLink、Observed、Provide、Consume、Watch、Component禁止使用。ECC 的 rules/arkts/patterns.md 对 V2 装饰器给出了完整对照表装饰器用途ComponentV2将 struct 标记为 V2 组件Local组件内本地状态Param接收自父组件的只读属性Event子组件向父组件回调事件Provider向子孙组件提供状态Consumer消费祖先Provider提供的状态Monitor监听状态变化取代 V1WatchComputed派生/计算值ObservedV2使类可被 V2 状态管理观察Trace在ObservedV2类中标记可观察属性一个典型的 V2 组件示例来自 rules/arkts/patterns.mdObservedV2 class UserModel { Trace name: string Trace age: number 0 } ComponentV2 struct UserCard { Param user: UserModel new UserModel() Event onDelete: () void () {} build() { Column() { Text(this.user.name) .fontSize($r(app.float.font_size_title)) Text(${this.user.age}) .fontSize($r(app.float.font_size_body)) Button($r(app.string.delete)) .onClick(() this.onDelete()) } } }跨组件状态同步使用Provider/ConsumerComponentV2 struct ParentPage { Provider(userState) userModel: UserModel new UserModel() build() { Column() { ChildComponent() // 自动接收 Consumer(userState) } } } ComponentV2 struct ChildComponent { Consumer(userState) userModel: UserModel new UserModel() build() { Text(this.userModel.name) } }实现佐证V1 装饰器被列为Prohibited且配套有 PreToolUse 钩子拦截见 rules/arkts/hooks.md 的 V1 Decorator Guard。3.2 路由仅用 Navigation禁用 ohos.router示例文档规定路由仅用 NavigationNavigationNavPathStackNavDestination。这是因为ohos.router是旧式路由方式能力与类型安全均弱于 Navigation 体系。Navigation 初始化与路由表来自 rules/arkts/patterns.mdComponentV2 struct MainPage { Local navPathStack: NavPathStack new NavPathStack() build() { Navigation(this.navPathStack) { // 首页内容 } .navDestination(this.routerMap) } Builder routerMap(name: string, param: ESObject) { if (name detail) { DetailPage() } else if (name settings) { SettingsPage() } } }页面跳转操作// 压栈新页面 this.navPathStack.pushPath({ name: detail, param: { id: 123 } }) // 替换当前页面 this.navPathStack.replacePath({ name: settings }) // 返回上一页 this.navPathStack.pop() // 返回根页面 this.navPathStack.clear()NavDestination 子页面ComponentV2 struct DetailPage { build() { NavDestination() { Column() { Text($r(app.string.detail_title)) } } .title($r(app.string.detail_nav_title)) } }3.3 架构模块化 MVVM示例文档要求模块型分层 MVVM——View 只负责渲染所有业务逻辑都在 ViewModel 中并给出组件优先级模块内可复用组件 跨模块共享组件 第三方库。ECC 的 rules/arkts/patterns.md 给出 feature 维度目录划分feature/ |-- model/ # 数据模型ObservedV2 类 |-- viewmodel/ # 业务逻辑ViewModel 类 |-- view/ # UI 组件ComponentV2 struct |-- service/ # API 调用、数据访问Viewbuild()中只含渲染逻辑不放业务逻辑ViewModel封装全部业务逻辑Model纯数据类使用ObservedV2与TraceService网络请求、数据库操作、文件 I/O。四、代码组织与代码风格4.1 代码组织示例文档的四条铁律多小文件优于少大文件高内聚、低耦合每文件目标 200400 行上限 800 行按功能/领域组织而不是按类型组织。这与其他 ECC 示例如 examples/CLAUDE.md中的规则一致也与 rules/arkts/coding-style.md 的File Organization保持一致组件文件.ets一个文件一个ComponentV2ViewModel 文件一个文件一个 ViewModel 类Model 文件允许多个相关数据模型共存文件接近 800 行时应抽取辅助函数。4.2 代码风格示例文档的硬性要求代码、注释、文档中不使用 emoji不可变性——不直接修改对象创建新对象字符串使用双引号语句以分号结尾绝不使用var——优先const其次let不使用any类型——所有方法、参数、返回值都要有完整类型注解命名规范变量/函数camelCase类/接口PascalCase常量UPPER_SNAKE_CASE文件头fileauthor所有方法需带param与returns的 JSDoc。从 rules/arkts/coding-style.md 看ArkTS 类型系统的约束远比常规 TypeScript 严格违反即编译失败无any/unknown类型无索引访问类型、无条件类型别名、无infer关键字、无交叉类型、无映射类型不允许解构赋值与解构参数声明需用中间对象 逐字段访问不支持Function.apply/call/bind按传统 OOP 处理this不允许for...in数组用常规for不允许#私有标识符用private关键字不允许Symbol()Symbol.iterator除外所有import语句必须位于其他语句之前。错误处理推荐 try/catch hilog来自 rules/arkts/coding-style.mdtry { const result await riskyOperation() return result } catch (error) { hilog.error(0x0000, TAG, Operation failed: %{public}s, error) throw new Error(User-friendly error message) }不可变性示例// BAD: 直接修改 function updateUser(user: UserModel, name: string): UserModel { user.name name return user } // GOOD: 创建新实例 function updateUser(user: UserModel, name: string): UserModel { const updated new UserModel() updated.id user.id updated.name name updated.email user.email return updated }五、布局与交互规范示例文档关于 UI 布局的要求均等分配使用layoutWeight(1)避免SpaceAround/SpaceBetween使用百分比 / 布局权重 / 自适应单位不使用硬编码固定尺寸图标除外UI 常量定义为资源通过$r()引用新增颜色资源需同时支持亮色与暗色主题。资源引用对比来自 rules/arkts/patterns.md// BAD: 硬编码 Text(Hello) .fontSize(16) .fontColor(#333333) // GOOD: 资源引用 Text($r(app.string.greeting)) .fontSize($r(app.float.font_size_body)) .fontColor($r(app.color.text_primary))动画方面rules/arkts/patterns.md还补充了性能要点优先使用 transformtranslate/scale/rotate与 opacity 做动画绝不在动画过程中频繁修改 width/height/padding/margin复杂子组件动画设置renderGroup(true)以减少渲染批次大列表必须使用LazyForEach。六、构建与验证6.1 构建命令示例文档给出 HAP 包构建命令# 构建 HAP 包 hvigorw assembleHap -p productdefaultECC 的 rules/arkts/hooks.md 扩展了完整命令矩阵# 指定模块构建 hvigorw assembleHap -p moduleentry -p productdefault # 清理构建 hvigorw clean # 查看工具版本 hvigorw --version # 安装依赖 ohpm install # 更新依赖 ohpm update6.2 验证策略示例文档要求每次实现后都运行构建验证编译对不确定的 API 用法查阅华为官方开发者文档绝不猜测。hooks/README.md 与 rules/arkts/hooks.md 描述了如何把构建验证做成自动化钩子。例如编辑.ets/.ts文件后自动触发hvigorw assembleHap{ type: PostToolUse, matcher: { tool: [Edit, Write], filePath: [**/*.ets, **/*.ts] }, hooks: [ { command: hvigorw assembleHap -p productdefault 21 | tail -20, async: true, timeout: 60000 } ] }编辑module.json5后校验权限与 Ability 声明、编辑oh-package.json5后自动ohpm install均有对应钩子模板。每次实现周期结束后的校验清单hvigorw assembleHap无错误完成新增/修改的.ets文件中无 V1 装饰器新增/修改文件中无ohos.router导入所有 API 权限已在module.json5中声明所有依赖已在oh-package.json5中列出资源字符串已加入所有 i18n 目录新颜色资源已提供暗色主题色值。七、测试TDD 与覆盖率门槛示例文档的测试要求TDD先写测试工具函数与 ViewModel 的单元测试关键用户流程的 UI 测试业务逻辑覆盖率最低 80%。ECC 的 rules/arkts/testing.md 给出了完整的 HarmonyOS 测试实践测试目录结构module/ |-- src/ | |-- main/ets/ # 生产代码 | |-- ohosTest/ets/ # 测试代码 | |-- test/ | | |-- Ability.test.ets | | |-- List.test.ets | |-- TestAbility.ets | |-- TestRunner.ets运行测试# 运行模块全部测试 hvigorw testHap -p productdefault # 在连接的设备上运行测试 hdc shell aa test -b com.example.app -m entry_test -s unittest /ets/TestRunner/OpenHarmonyTestRunner单元测试示例import { describe, it, expect } from ohos/hypium; export default function UserViewModelTest() { describe(UserViewModel, () { it(should_initialize_with_empty_state, 0, () { const vm new UserViewModel(); expect(vm.userName).assertEqual(); expect(vm.isLoading).assertFalse(); }); it(should_update_user_name, 0, () { const vm new UserViewModel(); vm.updateUserName(Alice); expect(vm.userName).assertEqual(Alice); }); it(should_handle_empty_input, 0, () { const vm new UserViewModel(); vm.updateUserName(); expect(vm.userName).assertEqual(); expect(vm.hasError).assertFalse(); }); }); }UI 测试示例import { describe, it, expect } from ohos/hypium; import { Driver, ON } from ohos.UiTest; export default function HomePageUITest() { describe(HomePage_UI, () { it(should_display_title, 0, async () { const driver Driver.create(); await driver.delayMs(1000); const title await driver.findComponent(ON.text(Home)); expect(title ! null).assertTrue(); }); it(should_navigate_to_detail_on_click, 0, async () { const driver Driver.create(); const button await driver.findComponent(ON.id(detailButton)); await button.click(); await driver.delayMs(500); const detailTitle await driver.findComponent(ON.text(Detail)); expect(detailTitle ! null).assertTrue(); }); }); }TDD 循环HarmonyOS 适配版RED在ohosTest/ets/test/写失败测试GREEN在main/ets/写最小实现使其通过REFACTOR保持测试通过的前提下重构BUILD运行hvigorw assembleHap验证编译VERIFY在设备/模拟器上运行测试。测试命名规范为should_[expected_behavior]_when_[condition]测试之间保持独立无共享可变状态单测中 mock 网络调用与系统 API额外覆盖边界情况空数据、网络错误、权限被拒。八、安全约束示例文档的安全要求不硬编码密钥使用系统 API 前在module.json5中核对权限校验所有用户输入所有网络请求使用 HTTPS。ECC 的 rules/arkts/security.md 给出了可落地的安全实践权限声明module.json5{ module: { requestPermissions: [ { name: ohos.permission.INTERNET, reason: $string:internet_permission_reason, usedScene: { abilities: [EntryAbility], when: always } } ] } }权限校验清单权限已在module.json5声明面向用户的权限在资源中定义了 reason 字符串敏感权限相机、定位等实现了运行时请求API 调用前做权限检查被拒绝时有优雅降级。运行时权限请求示例import { abilityAccessCtrl, bundleManager, Permissions } from kit.AbilityKit; async function checkAndRequestPermission(permission: Permissions): Promiseboolean { const atManager abilityAccessCtrl.createAtManager(); const bundleInfo await bundleManager.getBundleInfoForSelf( bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION ); const tokenId bundleInfo.appInfo.accessTokenId; const grantStatus await atManager.checkAccessToken(tokenId, permission); if (grantStatus abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { return true; } const result await atManager.requestPermissionsFromUser(getContext(), [permission]); return result.authResults[0] abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED; }密钥管理绝不在.ets/.ts源码中硬编码 API Key、Token 或密码非敏感配置使用 Preferences API敏感凭据使用 HUKSUniversal Keystore加密存储环境相关配置通过构建配置文件管理。输入校验与网络安全处理前校验所有用户输入展示前清洗数据防注入导航前校验深链参数所有网络请求使用 HTTPS校验服务器证书实现超时与重试策略不在请求/响应日志中记录敏感数据Token、用户凭据依赖仅来自可信来源官方 ohpm 仓库在oh-package.json5中锁定版本并定期排查已知漏洞。深链参数校验示例来自 rules/arkts/security.mdfunction handleDeepLink(uri: string): void { const allowedPaths: string[] [detail, settings, profile]; const parsed new URL(uri); const path parsed.pathname.replace(/, ); if (!allowedPaths.includes(path)) { hilog.warn(0x0000, DeepLink, Invalid deep link path: %{public}s, path); return; } navPathStack.pushPath({ name: path }); }九、文件结构与可用命令9.1 建议目录结构src/ |-- entry/ # 应用入口、框架初始化 |-- core/ # 核心框架层 |-- shared/ # 共享契约层 |-- packages/ # 业务功能包9.2 可用命令示例文档推荐三个 Agent 命令命令作用/plan创建实现计划/code-review代码质量评审/build-fix修复构建错误在 ECC 的 docs/COMMAND-AGENT-MAP.md 中这些命令与具体 Agent 一一对应/plan→ planner编码前实现规划、/code-review→ code-reviewer质量与安全评审、/build-fix→ build-error-resolver修复构建/类型错误。命令的完整定义位于 commands/plan.md、commands/code-review.md 等文件。十、Git 工作流示例文档的 Git 规范约定式提交feat:、fix:、refactor:、docs:、test:禁止直接向 main 分支提交PR 必须经过评审合并前所有测试必须通过。examples/CLAUDE.md 与 rules/common/git-workflow.md 补充了 PR 工作流细节分析完整提交历史不只最新提交、用git diff [base-branch]...HEAD查看全部变更、撰写完整 PR 摘要、附带测试计划与 TODO、新分支推送时使用-u标志。完整开发流程规划、TDD、代码评审见 rules/common/development-workflow.md。十一、落地要点与自检清单将本文模板放入 HarmonyOS 项目根目录文件名为CLAUDE.md后应随项目演进持续更新。落地时的关键自检项约束是否可编译验证ArkTS 类型约束无any、无解构、无var应在构建钩子中自动校验状态管理是否 V2 化新代码是否还在使用 V1 装饰器是否被 PreToolUse 钩子提醒路由是否 Navigation 化是否仍存在ohos.router导入资源是否资源化UI 常量是否通过$r()引用新颜色是否同时提供明暗主题安全是否成体系权限声明、密钥存储、输入校验、HTTPS 是否全部覆盖测试是否达标核心业务逻辑覆盖率是否 ≥ 80%关键用户流程是否有 UI 测试Git 协作是否规范conventional commits、PR 评审、main 分支保护是否强制执行。十二、延伸阅读通用项目模板examples/CLAUDE.mdHarmonyOS / ArkTS 规则全集rules/arkts/patterns.md、rules/arkts/coding-style.md、rules/arkts/testing.md、rules/arkts/security.md、rules/arkts/hooks.md命令与 Agent 映射docs/COMMAND-AGENT-MAP.md构建钩子体系hooks/README.mdGit 工作流rules/common/git-workflow.md【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考