The branch name is the story: claude/phase-a-port. The Bun team opened this branch containing a 683-line
PORTING.md
written explicitly as a machine-readable spec for Claude to execute.
The document is not documentation - it’s a contract. It covers filename and crate naming conventions, a full Zig-to-Rust type map, a 100+ entry idiom map (every Zig pattern and its exact Rust equivalent), and a separate LIFETIMES.tsv with pre-computed cross-file ownership analysis for every ?*T field across the codebase. Claude is told to trust the TSV rather than infer locally, because per-file context is insufficient for ownership decisions.
The job split is explicit: Phase A is Claude’s work - produce a .rs file beside every .zig that captures the logic faithfully but doesn’t need to compile. Leave // TODO(port): when uncertain, // PERF(port): when a slower-but-correct substitution was made. Phase B is the human’s work - make it compile and review those markers.
What’s interesting is the investment in the spec itself. The real engineering work here wasn’t the port - it was writing a contract precise enough that the AI could execute without improvising. There’s even a “Forbidden patterns” section listing things Claude might otherwise reach for when stuck (like Box::leak to satisfy a &'static lifetime).
If you’re doing large-scale refactors with Claude Code, do you invest in upfront specs like this or work more incrementally?
submitted by
/u/jimmytoan
Originally posted by u/jimmytoan on r/ClaudeCode