How Gaode’s Search Frontend Refactor Used Harness to Drive Complex Engineering Evolution

Background

Gaode’s search business comprises a homepage, list pages, detail pages and many secondary pages built on the AJX stack. Over years the codebase grew to 5,463 files (8.2 万 JS/TS lines for the result page, 42.1 万 for the detail page) with numerous large files, tangled dependencies, and undocumented contracts, making any change risky.

Overall Framework: Agent Collaboration and Harness Workflow

A central coordinator (the Coordinator ) orchestrates the process, while specialist agents handle clear‑cut tasks:

Code Analysis Agent : deep scans old code, builds a dependency graph.

Architecture Design Agent : creates design docs, module allocation maps and build plans.

Code Generation Agent : writes modules according to specifications.

Quality Assurance Agent : performs non‑code‑changing verification and fidelity checks.

This separation prevents a single agent from mixing scanning, design, generation and QA, preserving clear responsibilities.

Five‑Stage Workflow

The project‑level refactor is split into Discover → Design → Build → QA → Delivery . Each stage defines explicit inputs, outputs, completion criteria and owners, turning AI work from “generate code” into a traceable sequence of engineering assets.

Context Orchestration: Minimal Sufficient Context

Instead of feeding the model all source files, each agent receives only the evidence needed for its task. For example, the Code Generation Agent gets the module spec, relevant old code snippets, interface contracts and required behavior claims; the QA Agent receives acceptance criteria, the module registry and preservation ledger entries. This reduces noise and enforces boundary checks.

Code Map: Dependency & Behavior Graph

During Discover, a machine‑readable dep-graph.json is produced, capturing file nodes, relationships and clues. The map answers six question categories (module boundaries, dependency direction, behavior contracts, etc.) and serves as the factual foundation for later design, generation and verification.

Controlled Code Generation and Style‑Codex

Generated modules follow a locked style codex ( style-codex.md) that records reusable patterns such as import/export organization, component and use‑case structure, error handling conventions, and module export habits. After three modules are produced, the codex is marked LOCKED and injected into subsequent generation tasks to keep the codebase consistent.

Generation Strategy

Bottom‑up: build from low‑level dependencies upward.

Small module delivery: handle clearly bounded modules one at a time.

Wave‑based rollout: schedule generation waves to avoid depending on unstable lower‑level modules.

Traceable changes: each new module links back to old‑code units, allocation units and preservation claims.

Accounting Mechanism for Auditable Assets

Three ledgers are maintained:

Module Registry : records new module paths, responsibilities, exports and build status.

Preservation Claims : tracks old‑code contracts (mapped, verified, waived) to ensure fidelity.

Build Debt : lists deferred issues needing human confirmation or runtime validation.

This turns AI tasks into spec‑driven, evidence‑backed actions that can be audited.

Runtime Quality Check: Record‑Replay‑Repair Loop

Static checks cannot guarantee runtime correctness, so a five‑step loop is added:

Extract verification scenarios from design artifacts.

Record baseline behavior on the old code using real devices.

Replay scenarios on the new code.

Capture errors, network logs, console output via CDP as evidence.

Automatically feed evidence to the Code Generation Agent for repair, then repeat until the scenario passes or a manual decision is made.

Human operators handle actions that cannot be fully automated (device authorizations, visual verification), while the Coordinator stitches these actions into a recoverable session.

Case Study: Search Result Page Refactor

Key objectives:

Migrate legacy implementation to a new clean architecture.

Output new code to an independent directory, support side‑by‑side deployment via cloud switches.

Replace the Amix framework with FOXPage + function components.

Adopt TypeScript and establish layered clean architecture.

Retain 30 cloud‑switches and deprecate obsolete experiment branches.

Fix PMT protocol misuse.

Results (summarized):

Discover: built a 3,871‑file dependency graph, narrowed scope to 177 files.

Design: reduced 133 potential change files to 16 core files.

Allocation: mapped 444 old‑code units to 63 target modules.

Specification: produced 62 module spec documents.

Build: executed 11 waves delivering 62 modules.

QA: verified all 47 P0 behavior claims, mapped 30 P0 cloud‑switch claims, verified 3 P0 PMT claims.

Fix: Q4 resolved 3 P0, 5 P1, 2 P2 issues.

Delivery: entered delivery stage with completed module registry and experience archive.

Lessons learned:

Large‑model agents can handle massive scanning, decomposition, code generation and QA when constrained by stage gates.

High‑cost verification environments require limiting runtime loops; high‑quality initial generation reduces expensive real‑device cycles.

Explicit contract modeling (preservation ledger) prevents hidden knowledge loss.

Post‑refactor structure is clearer and more amenable to future AI‑assisted maintenance.

Conclusion

AI can be integrated into complex engineering projects when its output is wrapped in a structured, auditable Harness that provides deterministic checks, asset traceability, and continuous feedback. Gaode’s search‑page refactor demonstrates that such a system can tame legacy baggage, preserve implicit contracts, and enable sustainable AI‑driven evolution of large front‑end codebases.