Preparing an app for agent-written code

The 12-week rebuild of the Shopify app — React Native to Swift and Kotlin — covered more than 300 screens plus home and lockscreen widgets, an Apple Watch app, complications, and Siri Shortcuts. Agents wrote most of the code. What mattered more, though, was everything we had to change around it: the architecture, tests, code review, machines running emulators, and coordination between people.

The preparation looked backwards at first. A small group of engineers worked on the architecture, tooling, and feedback loop before any screens were migrated. Speed alone produces a lot of code, not a good app; the system around the agent has to tell it when the output is wrong, and the architecture has to steer it toward clean, consistent, performant code. Agents will not get there on their own. Our preparation covered:

  • Business logic that runs without a device for fast feedback loops
  • The Reflex architecture and a CLI that can load any screen in milliseconds
  • One architecture shared by iOS and Android
  • Clear examples and .md files for every new screen to follow
  • Repository guardrails that fail when the code drifts

For humans, architecture can live partly in people's heads. For agents, it cannot. It has to be visible in file structure, architecture.md files, skills, naming, state shapes, method signatures, CLI output, lint rules, test fixtures, and CI failures.

The old feedback loop required building the app, starting an emulator or simulator, navigating to the screen, taking screenshots, and analyzing the result — several minutes per iteration, with steps that depend on visual navigation and context that lives outside the code. After the architecture work, an agent could load a ViewModel from the terminal, trigger actions, inspect state, and run deterministic checks in milliseconds without a device. We got faster not by asking agents to take bigger swings, but by making the work smaller and the feedback loop tighter.

Organizing the rewrite

The rewrite ran with about 30 engineers in pods of two, each pair owning an area of the app across both platforms. The two people in a pod paired most of the day, each steering several agents at once; agents worked overnight and on weekends, so each morning brought a queue of PRs to review. Pods stayed small on purpose: agents supplied the implementation capacity, and what each pair needed was clear ownership, fast decisions, and shared context. We did not split the migration into an iOS team and an Android team. Humans still owned the architecture, product behavior, and the judgment about what was good to ship.

Consistency as infrastructure

Our first principle was consistency: of architecture, so agents could create PRs that follow the same shape; and between Android and iOS, so the same screen exposes the same state, actions, and behavior on both platforms. The Swift ViewModel for the orders screen matches the Kotlin one.

We deliberately chose consistency over platform-specific architecture. Some code is less idiomatic than an iOS or Android purist might write, and we accept that tradeoff for what it returns:

  • Every migrated screen becomes an example for the next one
  • One PR contains the changes for both platforms
  • An engineer who knows one platform can review a PR on the other
  • Architecture guidelines are written once for both platforms
  • Tests can run the same merchant journey across iOS and Android

This is also what makes building for two native platforms possible without double the cost — as long as both sides keep the same shape. In an agentic workflow, consistency is not aesthetic. It is what lets humans compare intent across platforms, lets agents reuse examples, and lets CI catch drift before a reviewer has to find it by hand. CI fails when iOS and Android diverge in ways the architecture doesn't allow.

Guardrails beyond documentation

Asking an LLM to one-shot a rewrite produces a huge amount of code that cannot ship. With a strong architecture and the right checks, agents get clear directions and less room to improvise where improvisation creates maintenance cost. Without those constraints, an agent can produce code that compiles, passes a narrow test, and still leaves a codebase nobody wants to own.

Every agent-written change has to answer three questions:

  1. Does it follow the architecture?
  2. Does it behave like the existing app?
  3. Can a human review the intent without reading a giant diff line by line?

Architecture guidelines, examples, lint rules, and divergence checks answer the first. Helix and the legacy React Native app answer the second. Small checkpoints, cross-platform PRs, and agent-first review answer the third. Crucially, the guardrails live in the workflow, not only in a document: the document explains why the rule exists, and CI decides whether it was followed. Agents need more than instructions; they need a way to discover when they are wrong.

The legacy app as the specification

We tried spec-driven development first: write a spec for a screen, hand it to the agent, review the result. It did not hold up. The specs went stale almost immediately — by the third checkpoint of a screen, the spec for the first was already incomplete or wrong — and nobody wanted to maintain a parallel description of behavior the product already contained.

The existing app proved the better spec. The legacy React Native screen already described states, actions, edge cases, empty states, loading behavior, and navigation. Helix reads that reference, splits the migration into small checkpoints, and verifies each one against the original app rather than a long-lived written spec. For this kind of work, a live reference beats a written spec: we asked agents to converge on an existing product instead of inventing a new one. New features are a different problem — when there is no existing screen to compare against, the rules may be foreign, and that is our next challenge.

The narrower lesson: agents don't need a perfect first attempt. They need a reference, a small next step, and a fast way to check whether they moved closer to the target.

Where the constraints moved

Once code generation stopped being the slow step, the queue relocated forward: machines, CI, review, merging and coordination. Generation speed only exposed the downstream limits. The team's experience resembles Jevons paradox — making implementation more efficient raised consumption of it, adding checkpoints, fixes, parallel migration streams, review and CI runs rather than reducing work. Written code is no longer the scarce resource; deciding which code should exist, and landing it safely, is. The productivity gains went back into the roadmap.

Build machines

Agents still need compute: emulators for UI tests and visual checks, compilers, build caches, disk. One engineer running three agents can saturate a laptop, with compilers and emulators competing for CPU, memory and disk. Shopify built a remote development environment for agents so that the machine does not become the queue.

Review capacity

Human code review remains mandatory on every PR. But a pod of two cannot read 100 times more code line by line, so the order was inverted:

  • Agents review first: every PR gets an adversarial pass against the architecture guidelines before a human sees it, clearing obvious issues.
  • Work is reshaped: a PR is a small checkpoint that the agent is sized against, and one PR carries both platforms so iOS and Android can be compared side by side instead of reviewed twice.
  • The human decides last, judging intent, architecture fit, product behavior and whether the change belongs in a codebase millions of merchants depend on.

Each day of the migration build, an agent folded every review comment into the team's skills and Architecture.md, turning a one-off comment into a rule for subsequent PRs. Changes requested per PR trended down.

Merge queue and coordination

Agents now rebase branches, fix merge conflicts, investigate CI failures, fix flaky tests and push PRs through the last mile. With more PRs in flight, the merge queue is part of the development system — otherwise waiting time simply shifts from implementation to integration.

Tickets also lost their monopoly as the source of truth. A crash report can start its own loop: a self-healing process runs every 15 minutes, looks for new crashes, has Slack agent River reproduce the crash in the remote development environment and opens a PR with a fix — possibly the first a human hears of it. The harder problem is several engineers' agents fixing the same bug in parallel, which the team addresses by splitting into pods of two owning main app areas (orders, products). No tool fully replaces the ticket board yet, but area ownership prevents duplication for now. Every removed bottleneck revealed the next one.

How the engineer's role shifted

Less of the job is manually turning intent into code; much of that mechanical implementation moved to agents, and the responsibility moved with it. Engineers now spend more time shaping architecture, writing the patterns agents copy, designing feedback loops, reviewing intent, debugging the systems around the code and holding the quality bar — typically across ten problems at once. Reflex, Helix, the remote development environment, the review process and the ownership model all serve one goal: a system where agents do useful work without turning the codebase into a mess.

What merchants received

Shopify Mobile moved from React Native on the New Architecture to fully native Swift and Kotlin without user action: sessions stayed logged in and preferences carried over. Under the hood, the change is substantial.

  • Launch time: P50 dropped from 1.71s to 0.87s on Android (~50%) and from 0.70s to 0.60s on iOS (14%).
  • Android binary: 80.4MB down to 47.6MB, 40% smaller.
  • Android memory: P50 from 470MB to 200MB, roughly half the React Native figure.
  • iOS peak memory: P50 from 730MB to 190MB, more than 70% lower.
  • Stability: Android crash-free sessions rose from 99.66% to 99.98%; iOS stayed above the 99.95% target.
Android app download size drops from about 80 MB to about 48 MB. Android memory usage falls over time, shown at P50 and P75. iOS peak memory drops from about 730 MB to about 190 MB across app versions.

The app now uses platform transitions, smoother animations and native page behavior without fighting an abstraction layer, and new platform capabilities can be supported directly — iPhone Duo was supported on day one. The codebase is also agent-ready: every screen exposes state and actions through an introspectable ViewModel, and with Reflex and its CLI agents can test much of the app without launching a simulator, while anyone at Shopify can use River to build and validate a mobile change.

Transferable lessons

  • Invest upfront in a fast way for agents to test the app; device-free business logic plus Reflex and its CLI were foundational.
  • Make architecture executable — examples, Architecture.md, tests, lint rules, CI.
  • Prefer small checkpoints over large agent-generated PRs; reliable convergence beats a perfect first attempt.
  • Share architecture across platforms where product behavior is shared; consistency makes agent output reviewable.
  • Agents review first; humans make the final call.
  • Treat review capacity as a system constraint, and let the diff size a human can understand shape agent work.
  • Expect the bottleneck to move.
  • Be explicit about ownership, or speed turns into duplicate work.

The app was not vibe coded; the team reports its code is more consistent with desired patterns than before, because the architecture was crafted and guardrails placed first. Agents amplify the environment around them — the patterns, architecture, checks and judgment applied before anything ships — and the team expects to share what changes as the picture evolves.