React Compiler Rust Port — Workflow Guide

Analysis of 141 Claude Code sessions from 2026-03-13 to 2026-04-10, totaling ~17,460 tool invocations across the Rust compiler port.

1. Project Timeline & Phases

Phase Dates Focus Sessions
Research Mar 13–14 Feasibility study, shared mutability analysis, pass-by-pass research ~10
Planning Mar 14–16 Architecture docs, numbered plans (0001–0005), scope types ~15
Core Implementation Mar 16–25 Babel AST crate, HIR lowering, pass porting, BuildHIR ~50
Testing & Stabilization Mar 25–31 Snap tests, test-rust-port 100%, OXC/SWC frontends ~30
E2E & Diagnostics Apr 1–4 Error formatting, diagnostic events, CI, e2e tests ~20
Internal Validation Apr 6–10 Testing against Meta internal code, minimize-rust-delta, hermes-parser ~10

Key Milestones

2. Custom Skills (Claude Code)

Seven custom skills were created in compiler/.claude/skills/. These are critical to the workflow and should be loaded at the start of each session:

Skill Usage Count Purpose
/compiler-verify 47 Detects TS vs Rust changes, runs appropriate test suites
/compiler-commit 30 Runs verify + review, then commits with [compiler] or [rust-compiler] prefix, updates orchestrator log
/compiler-review 21 Launches a review subagent that compares Rust port against TS originals
/compiler-orchestrator 5 Autonomous loop: discover frontier → fix failures → port next pass → review → commit
/compiler-port 5 Port a single named pass end-to-end (looks up in Pipeline.ts, maps to Rust crate, implements, tests)
/rust-port-status — Reports current test pass rates
/plan-update — Updates numbered plan documents

Typical Workflow Loop

1. /compiler-orchestrator (or manual work)
   └── Discovers current test state
   └── Fixes failures or ports next pass
   └── Calls /compiler-verify internally
   └── Calls /compiler-review internally
   └── Calls /compiler-commit when ready

2. Manual variant:
   > "Fix X"
   > /compiler-verify
   > /compiler-review
   > /compiler-commit

Important Skill Loading Note

The /compiler-orchestrator skill sometimes fails to auto-load. The workaround is:

> load the skill compiler/.claude/skills/compiler-orchestrator/SKILL.md

This happened multiple times in the trajectory history and your team should be aware of it.

3. Test Commands & Infrastructure

Primary Test Scripts (by frequency of use)

Command Invocations Purpose
bash compiler/scripts/test-rust-port.sh 1,345 Compare Rust vs TS compiler output per-pass for all fixtures
bash compiler/scripts/test-e2e.sh 269 End-to-end: code output + diagnostic events across babel/swc/oxc
cargo check 251 Fast Rust compilation check
npx tsx 207 Run TypeScript scripts directly
cargo build 179 Full Rust build
bash compiler/scripts/test-babel-ast.sh 174 Babel AST round-trip serialization tests
yarn snap --rust 121 Snap fixture tests using Rust compiler backend
yarn snap 63 Snap fixture tests using TS compiler
cargo test 46 Rust unit tests

Test Result Formats

test-rust-port.sh supports --json for machine-readable output:

bash compiler/scripts/test-rust-port.sh --json 2>/dev/null
# Returns: { pass, autoDetected, total, passed, failed, frontier, perPass, failures }

test-e2e.sh reports in table format:

| variant | code | events | total |
| babel   | 1725/1725 (100%) | 1725/1725 (100%) | ... |
| swc     | 1723/1725 (99.9%) | ... | ... |

Test Against Internal Codebase

Recent work (Apr 6–10) tested against Meta internal production code. Key patterns:

# Run with specific compilation mode against an external directory
bash compiler/scripts/test-rust-port.sh --mode syntax <path-to-source-dir>

# Use test-internal-files.sh with the production config and source root
bash compiler/scripts/test-internal-files.sh <config-path> <source-root> [flags]

4. Cargo & Rust Workflow

Crate Structure

Crate Purpose
react_compiler Main entrypoint, pipeline orchestration
react_compiler_ast Babel AST types + serde
react_compiler_hir HIR types, environment, visitors
react_compiler_lowering BuildHIR, HIRBuilder (AST → HIR)
react_compiler_inference Mutation/aliasing/type inference
react_compiler_optimization Optimization passes
react_compiler_validation Validation passes
react_compiler_reactive_scopes Reactive scope building + codegen
react_compiler_diagnostics Error types, code frames
react_compiler_e2e_cli E2E test binary
react_compiler_swc SWC frontend
react_compiler_oxc OXC frontend

Common Cargo Patterns

# Fast check (most common, 214 invocations)
cargo check --manifest-path compiler/crates/Cargo.toml

# Build the NAPI binary for JS interop
cargo build --manifest-path compiler/crates/Cargo.toml

# Run Rust unit tests
cargo test --manifest-path compiler/crates/Cargo.toml

5. Agent Patterns

994 total agent invocations across sessions.

Agent Type Count Typical Use
general / general-purpose 748 Implementation, fixing, research
meta_codesearch:code_search 204 Codebase exploration
Plan 20 Architecture/implementation planning
Explore 16 Codebase navigation
statusline-setup 4 Terminal UI configuration

Common Agent Patterns

  1. Parallel pass research: Launch one agent per compiler pass to analyze TS implementation for port feasibility
  2. Review agents: Dedicated "Review Rust port changes" agents (14 invocations)
  3. Fix-specific agents: "Fix AnalyseFunctions failures" (4x), "Fix PruneMaybeThrows validation failures" (2x)
  4. Worktree isolation: 16 worktree entries for isolated implementation work

Worktree Usage

Worktrees were used for larger changes that might need to be abandoned:

6. Key Files (by edit frequency)

Most Frequently Modified Files

File Edits Reads Purpose
rust-port-orchestrator-log.md 135 104 Running log of orchestrator progress
build_hir.rs 112 162 Core HIR lowering from AST
program.rs (entrypoint) 103 173 Main compilation entrypoint
rust-port-research.md 85 47+21 Research & analysis document
test-rust-port.ts 77 90 Primary test comparison script
pipeline.rs 48 64 Compiler pass pipeline
test-e2e.ts 42 27 End-to-end test script
hir_builder.rs 37 53 HIR builder utilities
infer_mutation_aliasing_effects.rs 32 48 Most complex inference pass
runner.ts (snap) 32 35 Snap test runner

7. Repeated Workflow Patterns

Pattern 1: "Analyze → Don't Fix → Report"

Used extensively in recent internal validation work:

> Try running test-rust-port.sh with --mode 'syntax' against <path>. Analyze success/failure to categorize and report back. Do not proactively fix.

Pattern 2: "Research → Plan → Implement → Verify → Review → Commit"

The standard development cycle:

> Do additional research into <topic>
> Create a plan in compiler/docs/rust-port/...
> Implement the work in <plan>
> /compiler-verify
> /compiler-review
> /compiler-commit

Pattern 3: "Team of Agents"

For large implementation tasks:

> Use a team of agents (opus) to implement the remainder of the items in <plan>. Make sure to thoroughly test, verify the implementation against the plan. Use /compiler-verify and /compiler-commit.

Pattern 4: "Orchestrator Loop"

For autonomous progress:

> /compiler-orchestrator
  (or: load the skill compiler/.claude/skills/compiler-orchestrator/SKILL.md)

Pattern 5: "Debug CI"

> debug the GitHub CI failure run at <github-actions-url>
> <paste error output>
> /compiler-commit

Pattern 6: "Minimize Delta"

For finding minimal repros of TS/Rust differences:

> yarn snap minimize-rust-delta <path>

Pattern 7: "Interrupt and Redirect"

Joe frequently interrupts Claude mid-task to correct course:

8. Key Architectural Decisions (from trajectory)

These came up repeatedly in prompts and are important context:

  1. InstructionId over InstructionValue references: Key insight that caches in InferMutationAliasingEffects can use InstructionId (interned) instead of holding references to InstructionValue objects, avoiding Rust borrow conflicts.

  2. Environment is shared mutable: Like HIR, the Environment object is mutably shared. Both needed careful Rust representation.

  3. Error handling convention: env.record_error(...)? — record_error returns Err only for Invariant category errors. Use ? for short-circuit. Only use let _ = ... when both the category is non-Invariant AND you explicitly want to continue.

  4. Keep logic in Rust core: The babel/swc/oxc integrations should be thin wrappers. All interesting logic belongs in the Rust crates.

  5. Commit prefix convention: [rust-compiler] for changes to compiler/crates/, [compiler] for everything else.

  6. No normalization in tests: Minimize output normalization — run code through prettier only, compare directly. Added: reparse with babel → regenerate with compact:true → prettier.

9. Current State & Remaining Work

Test Results (as of latest orchestrator log)

Active Work Streams (as of Apr 10)

  1. Internal validation: Testing against Meta internal production code with production configs
  2. Minimize rust deltas: Using yarn snap minimize-rust-delta to find minimal repro cases for TS/Rust differences
  3. New test-internal-files script: compiler/scripts/test-internal-files.ts — for testing against an external codebase with its production config
  4. compilationMode: 'syntax' support was recently added and validated
  5. hermes-parser integration: For @flow files in the internal codebase

Remaining Gaps

10. Recommendations for Team Picking Up

Getting Started

  1. Read compiler/docs/rust-port/rust-port-research.md and rust-port-notes.md for architectural context
  2. Read all numbered plans in compiler/docs/rust-port/rust-port-0001-* through 0005-*
  3. Review compiler/docs/rust-port/rust-port-orchestrator-log.md for chronological progress
  4. Review compiler/docs/rust-port/rust-port-gap-analysis.md for known gaps

Essential Skill Loading

At the start of each Claude session:

> load the skill compiler/.claude/skills/compiler-orchestrator/SKILL.md

This ensures all six custom skills are available. If a skill isn't recognized, load it explicitly.

Daily Workflow

# Check current state
bash compiler/scripts/test-rust-port.sh
bash compiler/scripts/test-e2e.sh
yarn snap --rust

# After making changes
/compiler-verify
/compiler-review
/compiler-commit <title>

Key Commands to Know

# Fast iteration cycle
cargo check --manifest-path compiler/crates/Cargo.toml
bash compiler/scripts/test-rust-port.sh
yarn snap --rust

# Debug a specific fixture
yarn snap --rust -p <fixture-name> -d

# Compare TS vs Rust for a specific file
npx tsx compiler/scripts/test-rust-port.ts <pass-name>

# Find minimal repro for TS/Rust difference
yarn snap minimize-rust-delta <fixture-path>

# Test against an external codebase with its production config
bash compiler/scripts/test-internal-files.sh <config-path> <source-root> [flags]

# E2E test across all frontends
bash compiler/scripts/test-e2e.sh

Working Style Notes

CI Configuration

GitHub CI workflow: .github/workflows/compiler_rust.yml

Generated 2026-04-10 from analysis of 141 Claude Code conversation trajectories.