Skip to content

INSTACART 2026-02-03 Tier 2

Read original ↗

Instacart — Migrating to Jetpack Compose: How AI Accelerated Our Journey at Caper

Summary

Instacart Engineering post (2026-02-03, author Matt Kranzler) on migrating the Android app powering Caper smart carts — AI- plus-computer-vision in-store scan-and-pay carts, stability- critical because "a crash can lead to cart abandonment" — from Fragments + XML layouts to Jetpack Compose. Scoped as a multi-quarter effort; AI coding assistants "made our refactoring significantly faster than anticipated." The post's four-phase migration strategy and its evolving AI workflow — manual → git-diff-as-context → markdown migration guide → structured AI skill — are the architecturally load-bearing content. Phase 1 removed explicit Fragment wrappers using Google's navigation-fragment-compose library (implicit Fragment hosts for Composables); established the outer-parameterless / inner-testable Composable split (MyFeatureScreen() binds deps + navigation, MyFeatureScreenInternal(...) is pure Compose) that makes the eventual Compose-Navigation reimplementation cheap — completed manually, without AI, deliberately: "essential for understanding the migration patterns, edge cases, and conventions that would later inform our AI-assisted approach." Phase 2 migrated 30+ sub-navigation graphs and 130+ destinations from XML resource-ID navigation to type-safe Kotlin DSL (@Serializable route objects + NavGraphBuilder extensions + Kotlin-DSL graph); started manually, then an iterative AI workflow emerged: "Learn by doing → Use Git History as Context → Correct and Refine → Update the Migration Guide → Repeat." Reported 5–7× speed increase, saving an estimated 300–350 engineering hours, "migrations that were previously too tedious to justify" became feasible; AI also "reduced variance across migrations." Phase 3 converts 100+ Fragment features to pure Compose following the Phase-1 pattern; AI workflow is a 17-step engineer-verification checkpoint skill across four stages — (1) Analysis + Baselining (identify Fragment vs DialogFragment, baseline screenshot via Paparazzi), (2) Compose Implementation (build the View, follow Phase-1 Screen / Dialog + parameterless / internal pattern, DI wiring, previews), (3) Verification + Integration (automated visual-parity diff Paparazzi baseline vs new Compose screenshots, nav-graph update, full test run), (4) Cleanup (remove old Fragment, final verification) — formalised from markdown migration guide into a structured Agent Skill that enables "progressive disclosure of information, allowing the AI to access exactly what it needs at each step without overwhelming the context window." Phase 4 (Compose Navigation, underway in parallel with Phase 3, feature-flagged for dual-system support) is claimed "significantly simpler" because Phase 2's type-safe routes are in place. Four named Principles for AI-Assisted Refactoring are the post's transferable thesis: (1) the economics of technical debt have changed — AI "excels at repetitive, mechanical refactoring" so previously-untenable ROI becomes feasible; (2) treat AI instructions as code — the 325+ line migration guide is "effectively a program that the AI executes," triple-duty (AI executes, humans check-list, reviewers verify), iterated like code over 5–6 migrations; (3) incrementalism mitigates AI risk — decoupling nav refactor (Phase 2) from UI refactor (Phase 3) meant small AI-generated changes validated in production before the next phase; (4) invest in the workflow, not just the tool — when Agent Skills emerged mid-project, workflow evolved to capture the gains. Engineering-role shift named explicitly: "the engineer's primary responsibility moves from execution to definition and validation" — architecture + pattern definition + oversight, not hand-writing the thousands of mechanical edits. Scaling claim: "other engineering teams across Instacart are now using AI skills to tackle their own large-scale refactoring challenges." Fourth Instacart source on the wiki after PIXEL (2025-07-17), PARSE (2025-08-01), Maple (2025-08-27), and Intent Engine (2025-11-13); first Instacart mobile-platform source and first wiki instance canonicalising AI-skill-driven mobile UI framework migration as a reusable pattern.

Key takeaways

  1. Four-phase migration strategy deliberately decouples orthogonal refactors. Rather than "big bang" Fragments-to-Compose-Navigation, the team sequenced: Phase 1 remove Fragment wrappers via implicit hosts; Phase 2 type-safe Kotlin-DSL navigation (still Fragment-based); Phase 3 Fragments → Compose screens; Phase 4 Compose Navigation. Each phase ships small, validated changes. "By decoupling the navigation refactor (Phase 2) from the UI refactor (Phase 3), we were able to ship small, AI-generated changes incrementally. Each phase had clear success criteria and could be validated in production before moving forward, reducing the blast radius of any potential errors." Canonical instance of patterns/phased-framework-migration — AI risk managed by making the unit of change small. (Source: sources/2026-02-03-instacart-migrating-to-jetpack-compose)

  2. Phase 1 was deliberately done without AI — manual work that seeded the AI workflow. "We completed this phase manually without AI assistance. We adopted this pattern for new features while gradually migrating existing ones. This manual work was essential for understanding the migration patterns, edge cases, and conventions that would later inform our AI-assisted approach in subsequent phases." First-wiki instance of the "learn-by-hand-before-you-automate" framing applied to AI-assisted refactoring — the engineer's context of migration patterns, edge cases, and naming conventions is what makes the subsequent AI instruction guide load-bearing. (Source: sources/2026-02-03-instacart-migrating-to-jetpack-compose)

  3. The outer-parameterless / inner-testable Composable split is the Phase-1 load-bearing pattern. Phase 1 established MyFeatureScreen() (parameterless, binds DI, navigation, scaffold — "tied to Fragment world") separate from MyFeatureScreenInternal(viewModel, scaffold, navigateBack, navigateToDetails, ...) (pure Compose, takes callbacks). "The split between the parameterless MyFeatureScreen() and internal MyFeatureScreenInternal() was intentional. The outer function handles navigation and dependencies (tied to Fragment world), while the inner function is pure Compose with callbacks, preparing us for eventual Compose Navigation." This anticipatory decoupling is what makes Phase 4's eventual Compose-Navigation migration "significantly simpler" — the inner function doesn't change, the outer just gets rebuilt. Sibling of hexagonal-style separation applied at the Composable granularity. (Source: sources/2026-02-03-instacart-migrating-to-jetpack-compose)

  4. Phase 2 disclosed 5–7× AI speed increase saving 300–350 engineering hours. "The 5–7x speed increase we observed in Phase 2 saved an estimated 300–350 engineering hours and made migrations feasible that were previously too tedious to justify." At 30+ sub-navigation graphs and 130+ destinations, this is the post's strongest quantified claim — the economics are what the thesis turns on. "AI reduced variance across migrations, improving quality and predictability. Parallelization amplified speed gains: migrations continued while feature development stayed unblocked. Migration time still varied by graph complexity, but the AI workflow dramatically reduced the long tail. Improvements compounded as the migration guide improved over time." Canonical wiki number for the shifted economics of technical debt — previously-deprioritised tech debt becomes addressable. (Source: sources/2026-02-03-instacart-migrating-to-jetpack-compose)

  5. The five-step iterative AI workflow emerged in Phase 2 and persisted. "(1) Learn by Doing: Complete a few migrations manually to understand patterns and edge cases. (2) Use Git History as Context: Provide the AI with commit diffs showing complete transformations. (3) Correct and Refine: Watch changes in real-time and immediately correct anything that doesn't match conventions. (4) Update the Migration Guide: Capture learnings in markdown (naming conventions, edge cases, common mistakes). (5) Repeat with Improved Context: Each iteration used updated guides and examples from previous successes." First-wiki instance of git-commit-diff as AI context for mechanical-refactoring tasks — a form of few-shot exemplar that's already in a format the AI can directly generalise from. (Source: sources/2026-02-03-instacart-migrating-to-jetpack-compose)

  6. Phase 3 formalised the workflow into a 17-step AI skill with engineer verification checkpoints. Unlike Phase 2's "fully automated approach," Phase 3 has engineer verification checkpoints — Paparazzi screenshots of the original Fragment view inform the AI's Compose build, then engineers compare screenshots of both versions to verify visual parity "ensuring pixel-perfect matches." The 17 steps cluster into four stages: Analysis + Baselining (Fragment-vs-DialogFragment identification, XML analysis, Paparazzi baseline screenshot); Compose Implementation (identical-UI Compose view, Screen/Dialog structure following Phase-1 patterns, DI wiring, preview composables); Verification + Integration (automated visual-parity check, nav-graph update, full test run); Cleanup (remove old Fragment, final verify). Canonical AI-migration-skill + Paparazzi-gated instance. (Source: sources/2026-02-03-instacart-migrating-to-jetpack-compose)

  7. Markdown migration guide → structured Agent Skill is the capability-discovery arc. "Eventually, we formalized this migration guide into an AI skill, a reusable module that packages the entire 17-step workflow with context and conventions. Skills enable progressive disclosure of information, allowing the AI to access exactly what it needs at each step without overwhelming the context window. This evolution from markdown guide to structured skill dramatically improved migration effectiveness and consistency." First-wiki in-house mobile-refactoring instance of Agent Skills (Cloudflare/vinext instance was web-framework migration; EmDash instance was CMS plugin authoring; Instacart's is Android UI framework migration) — extends the pattern from web/CMS to mobile-platform refactoring. Also names the progressive-disclosure property as a context-window-budget mitigation — aligns with concepts/context-window-as-token-budget framing. (Source: sources/2026-02-03-instacart-migrating-to-jetpack-compose)

  8. "Treat AI instructions as code" — the 325+ line migration guide is triple-duty. "We achieved the most consistency and highest accuracy when we stopped writing documentation for humans and started writing instructions specifically for AI consumption. Our 325+ line migration guide is effectively a program that the AI executes. Documentation written for AI agents must be far more explicit. It forces you to articulate conventions, edge cases, and decision points that human developers may or may not intuit. This documentation serves triple duty: AI agents execute it autonomously, human developers use it as a checklist, and code reviewers verify that the steps were followed. Like code, these guides require investment and must be iterated upon. After 5–6 migrations, we refined the guide until the process became highly predictable." Canonical concepts/ai-instructions-as-code instance — instructions have versioning, review, iteration cost, and are the load-bearing artefact not the model prompt. (Source: sources/2026-02-03-instacart-migrating-to-jetpack-compose)

  9. The engineer role shifts from execution to definition + validation. "The 5–7x speed increase we observed in Phase 2 saved an estimated 300–350 engineering hours and made migrations feasible that were previously too tedious to justify. This shifts the engineering role. Previously, the engineer's time was spent executing the changes. Now, the engineer's primary responsibility moves from execution to definition and validation: (1) Architecture and Planning — Defining the migration phases and the desired end-state architecture. (2) Pattern Definition — Establishing the explicit conventions the AI must follow. (3) Validation and Oversight — Reviewing the AI-generated code for correctness, performance, and subtle runtime errors that the AI might miss." Consistent with Cloudflare's vinext framing — engineer is architect + verifier, not typist — extended with the concrete Instacart-specific claim that the mechanical part was migrations "previously too tedious to justify", now tractable. (Source: sources/2026-02-03-instacart-migrating-to-jetpack-compose)

  10. Scaling claim: AI skills are spreading across Instacart engineering. "The learnings from this migration extend far beyond our Caper team. We've shared our approach through internal tech talks and documentation, and other engineering teams across Instacart are now using AI skills to tackle their own large-scale refactoring challenges. Teams have adopted the same patterns we developed: treating AI instructions as code, building structured skills for repetitive migrations, and establishing iterative workflows with human oversight. Engineers across the company are applying these techniques to address technical debt that had been deprioritized for years. The fundamental shift is this: the economics of technical debt have changed. Projects that previously had poor ROI due to high manual labor costs are now feasible. With significant efficiency gains and the ability to run migrations in parallel with feature development, teams can maintain velocity on their roadmap while systematically paying down technical debt. This isn't just about our Fragment-to-Compose migration. It's about establishing a repeatable playbook for how engineering teams at Instacart can leverage AI to modernize our codebase at a pace that was unimaginable just a year ago." The claim is self-reported at one company at a single point-in-time — treat as directional, not quantified — but it locates this post as playbook-level rather than single-migration retrospective. (Source: sources/2026-02-03-instacart-migrating-to-jetpack-compose)

Architecture — the four-phase migration

Phase Goal Starting point AI involvement Key artefact
1. Implicit Fragment hosts Remove explicit Fragment wrapper classes while keeping Fragment nav Fragments + XML layouts; BaseComposeFragment wrappers Manual (deliberate — seeds pattern knowledge for later phases) MyFeatureScreen() parameterless + MyFeatureScreenInternal(...) pure-Compose split; Google's navigation-fragment-compose library
2. Type-safe navigation Migrate XML nav graphs + resource IDs to Kotlin DSL XML-inflated NavGraph with R.id.* destinations Late 2024 manual start → 2025 iterative AI workflow (5-step) @Serializable route objects, NavGraphBuilder extensions, Kotlin-DSL navController.createGraph { ... }; 30+ sub-graphs, 130+ destinations migrated
3. Fragments → Compose screens Convert Fragments to pure Compose following Phase-1 patterns 100+ Fragment features (mix XML-view + Compose-in-Fragment) 17-step AI skill with engineer checkpoints; Paparazzi visual-parity gate Markdown migration guide → structured Agent Skill; Paparazzi baseline screenshots; Compose Previews
4. Compose Navigation Migrate Fragment-based Kotlin-DSL nav to Compose Navigation Type-safe routes in Fragment-based nav Agent Skill (early experiments); feature-flag dual-system rollout Parallelised with Phase 3; "significantly simpler" because routes already type-safe

Operational numbers disclosed

  • Phase 2 speed: 5–7× faster than manual migration.
  • Phase 2 savings: 300–350 engineering hours estimated.
  • Phase 2 scope: 30+ sub-navigation graphs, 130+ destinations.
  • Phase 3 scope: 100+ Fragment features pending conversion.
  • Migration guide size: 325+ lines of markdown ("effectively a program").
  • Migration iterations: 5–6 migrations to refine the guide to "highly predictable".
  • AI-skill workflow steps: 17 steps across 4 stages (Analysis + Baselining, Compose Implementation, Verification + Integration, Cleanup).
  • AI skill progressive disclosure: "access exactly what it needs at each step without overwhelming the context window" — no specific token counts.
  • Verification technology: Paparazzi screenshot tests for visual parity ("pixel-perfect").

Caveats

  • Self-reported speed multipliers with no independent measurement. The 5–7× and 300–350 hours are engineering-team estimates, not externally validated. The methodology for counting "engineering hours saved" isn't disclosed (e.g., vs. what baseline migration rate?). Directionally consistent with other AI-assisted-refactoring reports (Cloudflare's vinext: ~1 week for a framework rewrite) but on a fundamentally different task shape (mechanical migration at scale vs. creative framework reimplementation).
  • AI model identity / tooling stack not disclosed. Which coding assistant? Which model family (Claude / GPT-4 / Gemini / other)? Which IDE integration (Cursor / Claude Code / Copilot / …)? Which Agent Skill runtime? None specified. This is a material omission for reproducibility.
  • "AI skill" vocabulary overlap with external standards is not resolved. The post uses "AI skill" / "structured skill" language consistent with both Anthropic's skills format and Cloudflare's Agent Skills draft standard (per the Agent Skills page) but doesn't cite either. Whether Instacart's skill is a proprietary in-house format or conforms to an external spec isn't stated.
  • Paparazzi visual-parity claim is "pixel-perfect" but no false-positive / false-negative data. Paparazzi generates deterministic screenshots on the JVM, so pixel diffing is well-understood, but the practical question of whether the AI's Compose implementation commonly passes the gate on first attempt vs. requires iteration isn't reported. No "first-pass success rate" or "average iteration count per migration" disclosed.
  • No complexity / failure distribution disclosed. "Migration time still varied by graph complexity, but the AI workflow dramatically reduced the long tail" — but what did the long tail look like, and did any migrations need to be manually rescued? Failure modes aren't enumerated.
  • Scaling claim is announcement-voice. "Engineers across the company are applying these techniques to address technical debt that had been deprioritized for years" is aspirational framing; no specific cross-team case studies, no N teams / X migrations / Y hours saved numbers in aggregate. This is a playbook-pitch, not a platform retrospective.
  • Phase 4 (Compose Navigation) is in-progress. Early experiments are described as "promising" but no outcomes reported. The "significantly simpler" claim is architectural hypothesis, not a shipped datum.
  • Stability-critical context implies conservative rollout but specific guardrails not disclosed. The Caper smart cart is described as stability-critical ("a crash can lead to cart abandonment") and Phase 4 uses feature flags for dual-system support — but the crash-rate / field-stability pre/post-migration numbers, if any, are not shared.
  • No cost disclosure. LLM API tokens / developer-seat cost / tool subscription cost are not broken out against the 300–350-hour savings. The ROI framing is one-sided (savings without costs).
  • Engineering-role-shift framing is a thesis, not a longitudinal measurement. "The engineer's primary responsibility moves from execution to definition and validation" is authorial framing; whether team sizing / composition / hiring profiles changed as a consequence isn't reported.

Source

Last updated · 319 distilled / 1,201 read