How AI‑Native Refactoring Revamped a Massive Store Front‑End System

Why AI‑Native Refactoring Was Needed

Gaode store front‑end system is a critical entry for commercial POI data. After years of evolution it grew to 192 k lines of code, 530 files and about 200 React components. From a clean‑architecture perspective the main problem was collapsed responsibility boundaries: pages mixed API calls, field conversion, business decisions, workflow orchestration, form state and view rendering. From a component perspective the interaction complexity was absorbed by heavy form components, making maintenance difficult.

Refactor Effects

Added 325 layered files (~30 k LOC) for Domain (153 files), UseCase (105 files) and Infra (67 files); 50 Domain modules, 44 Infra services, 178 use cases and 722 domain rules.

Identified and resolved ~6000 architecture anti‑patterns; dependency violations reduced to zero.

Component governance on ~200 React components, focusing on 47 core form components, raised compliance from 0% to 100%.

Props type coverage increased from 30% to 100%.

View‑layer line count reduced by 50%‑69%.

Core smoke‑test pass rates: PC 90.32%, H5 91.46%; zero new compile errors.

Completed 10 rounds of automated governance in a 27‑day window, generating 624 commits.

Tool Requirements and Selection

The large‑scale refactor required CLI/TUI automation, multi‑agent collaboration, extensible plugins, file‑based context management and integration with lint, TypeScript checks, build logs and PR workflows. Open‑source and commercial CLI coding agents were chosen as the execution core because they satisfy these engineering needs.

Solution Architecture

1. Clean‑Architecture Refactor

Separate responsibilities into View, Controller, UseCase, Domain and Infra. Interfaces, business rules, workflow orchestration, page state and rendering each reside in their proper layer, eliminating cross‑layer coupling.

2. Component Refactor

Split View/Controller, remove implicit Context, stop direct Form instance manipulation and reduce cross‑page duplication, making component interaction and data flow maintainable.

Key Technologies

FilePlan (Target Planner) – Uses AST analysis to generate a verifiable file‑level task list; persists task states (pending, in‑progress, done, failed, skipped, review) outside the model context, enabling reliable progress tracking and recovery.

Task Orchestrator – Wraps CLI agents into concurrent, observable pipelines with scriptable execution, session isolation, failure retry and centralized result collection; supports up to 74 parallel agents for 44‑hour runs.

Clean‑Spec + Layered Codegen – Encodes clean‑architecture contracts as executable specifications; AI agents generate code for a single layer at a time, ensuring rule compliance and reducing cross‑layer errors.

Knowledge‑Loop + Governance Funnel – Dual‑agent system where a Knowledge‑Base agent extracts problem IDs, severity and remediation patterns, while a Governance agent applies them; feedback continuously evolves the knowledge base.

Engineering Practices and Pitfalls

Context Management

Progress is stored in FilePlan, while rules and knowledge reside in Clean‑Spec and the knowledge base, keeping in‑session context minimal and enabling task recovery.

Self‑Correction

Failures are recorded with detailed fields (what failed, which rule was violated, why, and what constraint to add) and fed back into the rule set for subsequent rounds.

Cross‑Page Reuse Timing

Reuse is postponed until individual pages reach a stable, layered state; premature abstraction can hide differences and increase complexity.

Human‑AI Boundary

Humans define boundaries, rules and handle exceptions; AI executes high‑throughput batch identification, migration and self‑checking, combining speed with architectural consistency.

Detailed Metrics

Clean‑architecture code added: 325 files, ~30 k LOC (Domain 153, UseCase 105, Infra 67).

Architecture anti‑patterns resolved: ~6000 items; dependency violations 0.

Component governance: 47 core form components, compliance 0%→100%.

Props type coverage: 30%→100%.

View layer line count reduction: 50%‑69%.

Smoke‑test pass rates: PC 90.32%, H5 91.46%; zero new compile errors.

Governance process: 10 rounds, 27 days, 624 commits.

Before‑After Comparison

Architecture boundary : before – pages mixed API calls, business rules, workflow and rendering; after – clear View / Controller / UseCase / Domain / Infra layers.

Business logic : before – extensive if‑else in pages; after – rules placed in Domain, orchestration in UseCase.

External capabilities : before – API, storage, SDK scattered; after – unified in Infra.

Component structure : before – View, state, Form methods and Context tightly coupled; after – View/Controller separated, responsibilities clearer.

Form data flow : before – getFieldValue, setFieldsValue scattered; after – controlled value / onChange pattern.

AI participation : before – AI could only generate local snippets; after – AI can reliably participate using task lists, contracts and the knowledge base.

Business Benefits

Scope convergence : demand changes narrowed from whole‑file level to module level; clear layer boundaries speed up impact analysis.

Shared logic reuse : core business rules consolidated under shared/cleanArch/, making reuse boundaries clearer and testing easier.

AI‑friendly baseline : engineering structure became stable and verifiable, allowing AI to assist in analysis, code generation, rule checking and regression.

Key Technology Details

FilePlan

Problem: progress management via model memory becomes unreliable when tasks span hundreds of files. Solution: AST static analysis produces a file‑level task list; each task persists its state. Agents pull tasks, operate on minimal context, write back results. Failures are re‑queued with reasons, enabling retry and audit.

Task Orchestrator

Problem: multi‑agent dialog incurs high token cost for many independent file tasks. Solution: wrap each file analysis as an independent CLI session; scheduler slices FilePlan into batches based on file count, LOC and complexity; low‑coupling tasks receive higher concurrency, high‑risk tasks lower concurrency. Results are collected, verified and archived; failed tasks are retried or blocked for manual review. Achieved up to 74 parallel agents, 44‑hour runs, 353 intermediate artifacts per round.

Clean‑Spec + Layered Codegen

Problem: AI lacks a stable contract for where code belongs. Solution: define executable specifications for each layer (View renders, Controller adapts state, UseCase orchestrates, Domain holds pure rules, Infra provides external services). Anti‑patterns (e.g., Domain depending on UI) are encoded; code generation is performed per layer, reducing cross‑layer errors. Each generation round includes a review of common failures (import path errors, field mapping mistakes, dependency violations) which are fed back into the specs.

Knowledge‑Loop + Governance Funnel

Problem: component governance cannot be a one‑time scan because the structure evolves. Solution: Knowledge‑Base agent extracts problem IDs, severity and remediation patterns (e.g., View/Controller not split, hidden Context, scattered Form methods). Governance agent applies fixes; execution records are fed back to the Knowledge‑Base, updating patterns. Governance Funnel defines four layers: (1) structure – split View/Controller; (2) logic placement – move business logic out of View; (3) data flow – adopt controlled value / onChange; (4) cross‑file redundancy – extract shared fields after pages stabilize.

Engineering Experience

Progress as engineering state : externalize task list and status once task size exceeds a single‑round context.

AST + AI complementarity : AST determines deterministic scope; AI handles semantic migration.

Task list as governance asset : FilePlan retains structure info, risk points and failure samples for future anti‑corrosion checks.

Concurrency prerequisite : tasks must be sliceable, have minimal context and verifiable output.

Scripting = AI engineering : scripts handle scheduling, state, logging and retry; agents focus on reasoning.

Lightweight orchestration beats heavy multi‑agent dialogue for large numbers of independent tasks.

Architecture specs for AI : rules must be machine‑executable, not only human prose.

Layered code generation improves stability : handling one layer at a time simplifies failure diagnosis.

Anti‑pattern library essential : explicit “Domain must not depend on UI” rule enables automation.

Component governance workflow : first split structure, then clean logic, then normalize data flow, finally extract cross‑page reuse.

Knowledge base over one‑off prompts : persistent problem‑pattern repository yields reliable decisions.

Dual‑agent separation : one agent curates knowledge, another performs code changes; feedback loop continuously refines rules.

Future Outlook

Planned steps include embedding continuous anti‑corrosion checks into PR pipelines, productizing the refactor workflow as reusable templates and quality metrics, and building intelligent regression testing that validates both functional and semantic correctness of core business flows.