AI-Driven HarmonyOS Migration: 4 Standards for Reliable Delivery

Introduction

Haokan Video's HarmonyOS development work splits into migrating existing Android/iOS features and building new HarmonyOS features. Migration dominates current workload because the HarmonyOS codebase is young. Legacy features have deep call chains and much implicit logic, making migration hard. While AI Coding boosts coding speed, many steps from requirement to delivery still rely on manual effort—identifying all required behaviors, confirming consistency with source or requirements, and verifying functional correctness. These steps are limited by developer bandwidth and familiarity with historical requirements, leading to long cycles and errors. Therefore, a full-process HarmonyOS AI R&D delivery process is needed to guarantee delivery quality through process rather than individual experience.

Four Questions to Measure Delivery

Migration is more complex than generation because the input baseline is unclear. Generation's expected behaviors are documented; migration requires understanding goals, defining boundaries, and proving consistency from source code. Before designing the R&D pipeline, the team clarified four questions: what to migrate, how to migrate, how to prove correctness, and how to sustain migration.

What to Migrate

Migration must first scope all source behaviors to reproduce on HarmonyOS. Main functions are easy to spot; omissions often hide in branch paths, boundary conditions, exception handling, state transitions, data flows, and tracking points. These implicit behaviors usually lack documentation and are invisible in main flows and UIs, yet directly affect cross-platform consistency. The identification target is behavior; source code only serves as evidence. Every in-scope behavior must be reproduced; out-of-scope behaviors are excluded.

How to Migrate

Migration may use new implementations, but observable behavior must equal the source. If source-dependent platform capabilities lack HarmonyOS equivalents, equivalent redesign is needed. HarmonyOS-specific form factors (foldables, tablets, multi-window) must also be adapted. Large requirements are vertically split into independently verifiable increments, implemented and accepted phase by phase to control change scope.

How to Prove Correctness

Code completion does not equal correct migration. Results must be proven via a verification loop: verify HarmonyOS implementation against the behavior baseline, fix gaps, re-verify. Designing this loop requires defining behavioral equivalence and balancing verification depth vs. cost. Real-device verification is expensive, so verification is scheduled in cost layers. Delivery completion is judged by traceable verification results.

How to Sustain Migration

A full migration often spans multiple phases with interruptions and rework. The process must resume from breakpoints. The source side keeps evolving; subsequent migrations only handle changed portions. Accumulated platform constraints, common patterns, and failure cases must be reusable in later tasks, improving efficiency and stability over time—a migration flywheel.

These four questions also apply to new feature generation: without a source reference, the requirement document becomes the baseline; implementation targets shift from behavioral equivalence to requirement satisfaction; verification and sustainability requirements stay the same. Together they yield four standards: Complete, Correct, Verifiable, Sustainable.

Engineering Implementation of the Four Standards

The four standards serve as engineering requirements and constraints, embedded into understanding, planning, implementation, verification, correction, and continuous improvement. Each standard maps to a set of designs:

Complete: Source code understanding and behavior modeling produce a behavior baseline; requirement matrix and full-chain reconciliation check every behavior point.

Correct: Cross-platform semantic mapping converts source semantics into HarmonyOS implementations; multi-device adaptation covers HarmonyOS-specific form factors.

Verifiable: Quality gates demand objective evidence for each behavior point; layered testing organizes verification by cost, balancing coverage and overhead; verification starts at planning.

Sustainable: Process state is persisted throughout, enabling resume from breakpoints; the migration flywheel reuses each task's experience in later requirements.

These designs share a common process foundation; most serve multiple standards and span multiple stages. They connect sequentially by R&D order, forming an end-to-end delivery process anchored by the requirement matrix.

3.1 Unified Foundation

Migration/Generation Mode Determination

When a reference source implementation exists, the process runs in migration mode with source behavior as baseline; otherwise generation mode uses the requirement document. Both modes share the main pipeline—understanding, planning, implementation, verification, continuous improvement—and the same acceptance gate. Migration-specific behavior baseline construction and equivalence checking are embedded inside existing stages and only activated in migration mode. The system auto-determines mode from requirement description and reference source; if evidence is insufficient, the user decides. A typical ambiguity: requirement text mentions "Android already has this feature" as background, not a mandate for behavioral equivalence. Misclassifying as migration mode would trigger costly source behavior analysis. The system lists its reasoning and lets the user choose.

Complexity Tiering

Migration requests may involve a single feature point; generation may build a multi-module page from scratch. To match process overhead to request size, the system auto-judges complexity by scope: concentrated changes that can be accepted in one go follow a single-round process; larger scopes are vertically split into independently verifiable phases. Phase splitting is also system-proposed, with user override for trade-offs. Finer phases increase fixed per-phase overhead; merging phases expands review scope and may reduce review precision—no conclusion yet, so the process does not auto-merge, only suggests merging for overly small phases.

Dry Run Mode

Some requests need no coding—only feasibility, approach, and cost estimation (e.g., technical spikes, effort estimation, scope definition). These run in Dry Run mode: the process completes understanding and planning, outputting proposal, scope, cost, and acceptance criteria, then stops before execution. Process state is still persisted; resume after interruption won't mistakenly enter execution. When greenlit, the process continues from the persisted state.

Cross-Cutting Concerns

Requirement reconciliation, multi-device adaptation, layered testing, migration flywheel, state persistence, interaction discipline (directional decisions only at requirement clarification, plan confirmation, final acceptance), and cost guardrails (high-cost actions require prior authorization) are distributed across stages. They follow a shared rhythm: establish standards upfront, continuously check during execution, verify item-by-item before delivery. This prevents late-stage discovery without prevention: if standards aren't set early, acceptance has no baseline to judge omissions. All mechanisms ultimately converge at the acceptance gate; failure returns to execution for fix.

3.2 Complete: From Behavior Baseline to Requirement Matrix

Source Code Understanding and Behavior Modeling

The challenge is finding all behaviors to migrate, especially implicit logic outside the main flow. The most easily missed are code with mismatched names, no obvious entry points, or triggered via switches/redirects—unsearchable by feature name. Step one: locate behavior-carrying code, then trace back via entry registration, tracking reporting, and other name-agnostic clues to recover code that belongs to the feature despite naming mismatches. After code collection, behaviors are restored point by point from trigger conditions, exception handling, etc., under two constraints: align behavior, not line-by-line code; key data and tracking must match character-for-character. Timing, concurrency, and A/B experiment branches undecidable by static analysis are marked "pending real-device verification" and not counted as covered.

Identified source behaviors are organized into a behavior baseline and entered into the requirement matrix, making unimplemented items traceable. This only guarantees no omissions inside the baseline: missing a baseline item blocks the acceptance gate; omissions outside the baseline rely on multi-angle cross-checks and real-device verification as safety nets.

Requirement Matrix and Full-Chain Reconciliation

Before this mechanism, a typical pitfall occurred: a cross-view interaction was only verified with the cheapest test and marked covered, while the critical path was never actually verified. Three problem categories emerged: source behavior not in baseline (omission), verification depth below required level (shallow), cheapest verification substituting for required verification (fake). The solution: build a requirement matrix per delivery. Each requirement splits into behavior points, each mapped to tasks, implementation, and verification records. Acceptance proceeds in fixed order: after behavior registration, three checks run sequentially—any behavior missing from matrix, verification depth matching behavior importance, every conclusion backed by real runtime evidence. These three checks correspond to omission, shallow, fake, with non-overlapping responsibilities. All must pass for the acceptance gate to release.

After reconciliation, every behavior point must resolve to one of three conclusions:

Behavioral Equivalence: Implemented and point-by-point verified against source; intentional deviations per requirement are documented with rationale and counted here.

Active Exclusion: Platform-specific or explicitly not required by requirement, with reason; platform-specific items must also note HarmonyOS alternative.

Explicit Abandonment: Cannot migrate or ROI doesn't justify risk, with reason, and user confirms each.

Any behavior point without a conclusion blocks acceptance and returns to execution. The requirement matrix thus becomes the process's master ledger: completeness, correctness, verifiability are all audited here; incremental re-migration also starts from it.

3.3 Correct: Semantic Mapping and Multi-Device Adaptation

Ensuring migration correctness requires behavioral equivalence with source—implementation can differ but observable behavior must match, verified point-by-point via the requirement matrix, achieved through semantic mapping. Additionally, the migrated feature must work correctly on HarmonyOS-heavy form factors: foldables, split-screen, multi-window.

Semantic Mapping

Differences across HarmonyOS, Android, iOS go beyond language: UI paradigms, lifecycles, component reuse, and system capability organization all differ. Migration cannot simply replace source symbols with ArkTS line-by-line. Source business semantics must be mapped from UI, business logic, data flow, state transitions, and platform capabilities into HarmonyOS implementations. Practice shows two mapping categories: explicit logic (API calls, page structure, business branches) clearly written in source with mature HarmonyOS equivalents, translated by unified principles; implicit differences that pass compile and unit tests but surface only on real devices—e.g., source framework auto-cleans subscriptions while HarmonyOS requires manual removal, or lifecycle/reuse differences cause stale data bindings after view reuse.

Two mechanisms handle these. Explicit logic follows unified translation principles: translate mechanisms, not syntax—source callbacks, observation, concurrency become HarmonyOS native equivalents, aligned with target project conventions; each behavior point's source-to-HarmonyOS correspondence is recorded back for equivalence checking and incremental re-migration. Implicit differences are preempted by experience accumulation: encountered issues are progressively codified; cross-request recurring root causes attributed to platform constraints become platform rules, automatically avoided during coding.

Multi-Device Adaptation

Beyond semantic mapping, the feature must adapt to HarmonyOS-specific form factors. The same code must run on straight phones, foldables, tri-fold, tablets, and 2-in-1/PC, handling fold switching, hover split-screen, crease avoidance, and screen rotation. Writing for a single source form factor makes multi-device debugging complex and time-consuming. Three principles constrain layout implementation:

Layout depends only on window size and breakpoints, not device type, because folding, split-screen, and free-form windows make device type unreliable.

Fold state and screen orientation only drive feature branches like hover split-screen, crease avoidance, fold-state persistence—not layout decisions.

All system dimensions are fetched dynamically at runtime, never hardcoded.

These principles are not just documented; they are enforced at every process stage. During requirement clarification, covered form factors and pass criteria per form factor are defined and written into acceptance standards. During execution, the three principles act as default constraints for code generation. During acceptance, verification proceeds from previewer → simulator → real device, lightest to heaviest, per form factor; any form factor failure returns to fix.

3.4 Verifiable: Quality Gates and Layered Testing

Each behavior point's delivery conclusion cannot rely on the model's subjective judgment; it must have objective, auditable evidence—enforced via quality gates and independent review. Verification cost must also be controlled: not every test point can run all test methods. Real-device execution is expensive and often requires manual attendance, making full runs per acceptance impractical. Layered testing advances verification from low to high cost, reserving high-cost methods for when necessary.

Quality Gates

Later defect discovery increases rework cost. Quality gates start at planning and continue through acceptance. At planning, the generated plan first validates key premises (e.g., state write points, data sources) and records them in the plan, eliminating directional errors before coding. At acceptance, compilation & static checks, requirement-bound tests, requirement coverage audit run in increasing cost order; migration mode adds behavioral equivalence check. Any gate failure returns to execution for fix. Gates that cannot run are annotated with reason and not counted as passed.

These gates judge objectively verifiable facts. Subjective aspects—design soundness, uncovered branches, timing issues—require review. Independent reviews run after plan finalization and after code completion, performed by a context-isolated Agent in read-only mode; plan review also checks premise completeness. Review-confirmed issues become gate items that must be resolved before passing. Gates deliberately exclude complex interactions and subjective experience, which remain manual acceptance; gate passage does not guarantee a bug-free feature.

Layered Testing

Post-implementation verification must cover pure logic, multi-device layout, real interaction, foldable form factors, and real hardware—each indispensable but with vastly different costs. Real-device execution is slow and often manual, impossible to run fully for every behavior point every acceptance; running only cheapest logic tests misses layout misplacement, fold reflow, sensor anomalies.

The team structures automated testing as a cost pyramid. Bottom layer: low cost, stable, runs every acceptance. Higher layers approach real device, higher cost, run only at final sign-off or with user authorization. Apex: unscripted exploratory verification—model reads live UI structure on real device, decides next action, covering paths not anticipated in designed cases. Exploratory runs have execution caps; successful trajectories are solidified into deterministic cases for replay.

In the R&D process, planning binds each test case to specific requirements or behavior points; case failure blocks acceptance just like unimplemented requirements. Acceptance executes layers from low to high cost. Passed cases become regression assets for continuous reuse. Unexecuted layers are annotated with reason and excluded from pass rate.

3.5 Sustainable

Migration is a long task, often interrupted by session breaks or acceptance rework. State persistence lets the process resume from the breakpoint; each migration's accumulated experience and the requirement matrix feed back into later requirements, making tasks progressively faster—forming a migration flywheel.

State Persistence

In complex long migrations, session interruptions, context compression, and acceptance rework are common. If progress lives only in conversation, resumption relies on Agent memory, risking misalignment and redoing confirmed conclusions. Therefore, stage progress, artifact locations, and pending confirmations are written to a state file in real time; conversation does not bear progress-tracking duty.

Resumption follows fixed priority: first handle pre-interruption items awaiting user confirmation, then unpassed plan reviews, then incomplete execution. Before resuming, the state file is validated: structural corruption or missing artifacts halt resumption with reason reported to user; mere formatting irregularities warn but don't block; indeterminate cases ask user—execution never proceeds with ambiguous state.

Migration Flywheel

HarmonyOS migration and generation requests keep arriving; different requests often hit similar issues; a single request split into phases may see earlier-phase issues reappear later. Without experience reuse, these issues are repeatedly solved, keeping costs high. The migration flywheel design lets each task's accumulated experience, patterns, and solutions continuously reuse in later requirements and phases.

Reuse requires trustworthy experience; erroneous experience actively adopted misleads later implementations, worse than no experience. Thus, experience entry and activation are managed by confidence levels. After a fix, the system judges if it has沉添 value—only technical issues enter the experience base. New entries are reference-only; after user confirms effectiveness, they become actively adopted. Issues recurring across multiple requests with platform-layer root causes solidify into auto-effective platform rules. Existing experience can be downgraded: if acceptance proves mismatch with reality, it becomes reference-only; if disproven or superseded, it's marked deprecated with record retained for future debugging.

Beyond experience, the requirement matrix itself is retained for reuse. Source features evolve continuously; full re-migration each time would re-analyze already-verified behaviors. After each migration, the requirement matrix is saved alongside the source version it was verified against. Next migration only diffs against that version—changed parts get incremental re-migration; unchanged behaviors reuse prior conclusions. Thus the requirement matrix becomes not just a single-delivery checklist but a long-term cross-version asset.

End-to-End Delivery and Practice

Chapter 3 detailed capabilities per standard; this chapter reassembles them in actual delivery order. The main flow passes through seven stages: Project Detection, Requirement Reading, Requirement Clarification (including cross-end reference), Planning, Execution, Acceptance, Experience Precipitation. Mapping to Chapter 3: first three stages belong to Understanding; Planning (including plan review) to Planning; Execution to Implementation; Acceptance to Verification; Experience Precipitation serves Continuous Improvement.

Stage order is dictated by data dependencies: Requirement Clarification outputs mode determination and baseline source; in migration mode, behavior baseline is produced here. Planning allocates behavior points to phases, producing task list and requirement matrix. Execution writes code per task list, recording source-to-HarmonyOS correspondences and non-migratable items. Acceptance verifies point-by-point against behavior baseline. Missing upstream artifacts means downstream has no input, so stages cannot be skipped or reordered.

Directional decisions concentrate at three user checkpoints: requirement clarification confirmation, plan confirmation, final functional acceptance. High-cost action authorization and non-migratable item handling are confirmed on demand; other stages advance automatically by Agent. Failed acceptance returns to execution for fix; re-acceptance follows fix; only passing advances to next stage.

4.1 Case Study: Suiting Channel Migration

Validating the mechanism in a real migration: using iOS source code as baseline, the "Listen to Music / Listen to Military" feature of Suiting Channel was migrated to HarmonyOS. The entire process was recorded on a requirement tracking sheet, traceable from scope definition, decomposition, implementation to final acceptance:

Migration first locked 6 requirements, then derived 52 behavior points and 17 acceptance criteria against iOS implementation, covering normal flows, branches, boundaries, and exceptions. After scoping, complexity tiering split work into 6 independently verifiable phases and 30 tasks, executed sequentially. The migration spanned multiple sessions with frequent interruptions; each resumption continued from breakpoint per tracking sheet and persisted state.

During implementation, every behavior point mapped to code with source relationship noted on the tracking sheet. Most points achieved behavioral equivalence via different implementation paths; a few intentionally diverged per requirement, documented with rationale, not counted as omissions. Missing HarmonyOS capabilities got custom equivalent designs; foldable, tablet, and other form factors were adapted in parallel. Ultimately, all 52 behavior points had explicit conclusions: 46 behavioral equivalence, 5 active exclusion with reasons, 1 explicit abandonment after user confirmation. This result is enforced by acceptance rules: any behavior point without a conclusion blocks acceptance and returns to execution.

Verification advanced by cost layers. 12 device suites, 65 test cases, each bound to specific requirements, acceptance criteria, and behavior points. Pure logic layer had some cases unrun due to test environment limits; foldable and tablet form factors were manually confirmed. Real-device layer execution was recorded on video, with Agent driving cases on device and retaining screenshots and logs as runtime evidence.

Layered verification caught issues invisible in single-pass runs. The same callback defect appeared three times, each caught by real-device cases and independent review, finally precipitating an experience: handling logic triggered at the same timing must converge to a single unified execution point. Another real-device suite's pass was found dependent on test material duration, not the tested behavior; that suite was downgraded in credibility and no longer counted as reliable. At acceptance, all 6 phases passed; every requirement and acceptance criterion mapped to code evidence and runtime results. Unfinished items were documented alongside passed items in the acceptance report. The designs introduced earlier—behavior baseline, requirement matrix reconciliation, layered testing, state persistence—all originated from similar real migrations: discover problems in practice, then incrementally reason and build mechanisms, then validate in subsequent practice.

4.2 Capability Boundaries

It must be stated: omissions outside the baseline cannot be fully eliminated, only minimized via cross-checks and real-device verification. Timing, concurrency, and which A/B experiment branch hits in production cannot be determined by static analysis—left to real-device verification. Usability and subjective experience are beyond gate judgment—require manual acceptance.

Conclusion

In the AI Coding era, coding is no longer the delivery bottleneck, but whether delivery meets standards cannot be left to the model's subjective judgment. The process decomposes this judgment into objectively checkable rules: every behavior point gets a conclusion; every conclusion carries runtime evidence; gates that fail to execute don't count as passed; flaky cases are downgraded. The model produces; the process judges.

This approach is not limited to HarmonyOS migration. Whenever expected behaviors can be enumerated point-by-point and results verified point-by-point, the same method applies to other platforms and requirement types.