react/compiler/docs/rust-port/rust-compiler-workflow-guide.md

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

• Mar 25: All 1717/1717 pass-level + code-level tests passing
• Mar 30: Snap tests 1717/1718 (99.9%)
• Mar 31: OptimizeForSSR ported, snap 1725/1725
• Apr 2: E2E babel 1722/1724, diagnostic events aligned
• Apr 4: CI workflow configured, SWC/OXC e2e progress
• Apr 6–10: Internal codebase validation against Meta internal production code

---

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]

• Files with @flow need hermes-parser (recently added to test-rust-port.ts)
• Must pass compilationMode to match production config
• Use yarn snap minimize-rust-delta <path> to find minimal repro for TS/Rust differences

---

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:

• worktree-build-hir-impl — BuildHIR implementation
• worktree-structured-yawning-forest-rust — test-rust-port enhancements
• worktree-ts-to-rust-transpiler — explored mechanical TS→Rust transpilation (abandoned)
• worktree-module-type-provider — module type provider work

---

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:

• [Request interrupted by user] appears ~50+ times
• Common pattern: interrupt → provide specific guidance → continue
• Example: "you should be using env.record_error(...)?."

---

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)

• test-rust-port: 1724/1724 (100%)
• yarn snap --rust: 1725/1725 (100%)
• E2E babel: 1722/1724 (2 inherent platform differences)
• E2E swc: Partial — event matching in progress
• E2E oxc: Partial — event matching in progress

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

• SWC/OXC e2e event differences (structural, not code)
• Some internal codebase fixtures still show code differences between TS and Rust
• Internal skip list exists at compiler/.test-internal-skip-list
• Performance optimization: potential for returning per-function replacements instead of full program

---

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

• Joe used Opus 4.6 as the primary model throughout
• Frequent use of /clear between logical work units
• Heavy use of "analyze and report, don't fix" for investigation phases
• Corrections were provided inline with specific code patterns (e.g., "you should be using env.record_error(...)?")
• Plans were maintained in numbered markdown docs and updated as work progressed
• The orchestrator log (rust-port-orchestrator-log.md) serves as the canonical progress record

CI Configuration

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

• Triggers on changes to compiler/ directory
• Runs: cargo check → cargo build → test-babel-ast.sh → test-rust-port.sh → yarn snap --rust
• Job name appears as "React Compiler (Rust) Tests" in GitHub

---

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