これまで誰も挑めなかった理由

Jarred氏が当初Zigを選んだのは、C言語並みのパフォーマンスを出しつつ十分シンプルだったからです。本人の言葉を借りれば、大規模言語モデルがない時代に、オークランドの狭いアパートで一人が1年かけてBunを書くための前提条件でした。シンプルさには代償が伴い、その代償は常に存在していました。BunのCLIツールは現在月間ダウンロード数が1,000万を超え、Claude Code内部でも多用されています。

つい先四半期まで、これらの代償はロードマップを凍結し、複数四半期にまたがるプロジェクトにリソースを注ぐ理由にはなり得ませんでした。

Mike氏のプロジェクトも、まさにこのボトルネックがきっかけでした。彼のチームが開発した内部ツールは単一の実行可能ファイルにパッケージ化してユーザーに配布していました。しかしPythonのツールチェーンはプラットフォームごとのコンパイルに約8分かかり、ビルドマトリクス全体では毎回のリリースに30分待たされていました。TypeScriptへの移行後、同じコンパイルは約2秒になり、実行可能ファイルの起動は6倍高速化、チームは独立したデプロイパイプラインを丸ごと1本退役させることができました。

同じエラーが繰り返し出たら、ルールを変える

この記事全体で最も価値があるのは、この一文です：

The core insight is that you don't fix the code. You fix the process (loop) that produced the code.核心的な認識：コードを直すのではなく、コードを生み出すプロセス（ループ）を直すのです・ClaudeDevs

これを具体的な行動に落とすとこうなります。レビューAgentが数十のファイルで同じエラーを繰り返し検出した場合、あなたの手はそれらのファイルに向かいません。ルールブックに一文追加し、影響を受けるバッチを再生成します。ルールブックはプロセス全体を通してどんどん厚くなっていきます。しかし、コードに手動でパッチを当てることは決してありません。

なぜコード移行にこの方法が特に効くのか

• タスクが自然に並列化できる。ファイルやcrateなど、互いに独立した何千もの単位に分割でき、Agentが互いを待つことなく同時に作業できます。
• コンテキストが明確で完全。旧コード自体が、モデルにとって優れた仕様書になります。
• 判定役が既にいる。ほとんどの大規模コードベースにはテストがあり、Agentはそれを使って自分の作業の正しさを検証できます。
• キューは自然に生成される。コンパイラのエラー、テストの失敗。そのエラーが次のAgentの次のタスクになります。
• 一貫性とエッジケース対応が求められる。レビューは各指摘に対して根拠となるルールを引用するため、一度の違反はプロセスから静かに逸脱するのではなく、キューの1項目になります。

着手前に「判定役」を構築する

コードの翻訳を始める前に、必ずやらなければならないことがあります。それは「判定役」を構築することです。判定役がなければ、終了条件も成功の尺度もなく、いつ移行が完了したのか、正しく移行できたのかが分かりません。

1. 既存テストを分類する：Claudeを使って、外部呼び出しで検証できるテストと、内部実装に依存して移行できないテストを特定する。
2. 移植可能な形に書き換える：外部向けテストを、元のコードでも移行後のコードでも実行できるアサーションへと書き換える。敵対的エージェントを使い、書き換えたアサーションが弱体化していないか確認する。
3. 判定役自体を検証する：まず元のコードで実行し、パスすることを確認。次に意図的に壊したコードで実行し、失敗することを確認する。壊れを検出できない判定役は判定役ではない。

2番目のステップにある「敵対的Agentによるアサーションの弱体化チェック」は、任意ではありません。テスト書き換え時にアサーションを少し緩めると、通過率はすぐに良くなります。しかし、失うのは正しさを判断する物差しそのものです。3番目のステップも同様です。何でも通してしまうテストスイートは、判定役のように見えて、実際はただのゴム印です。

ルールブック、依存関係グラフ、ギャップリスト

この3つの順番は絶対に逆にできません。ルールブックはギャップリストよりも先に作成します。なぜなら、ギャップリストの定義は「ルールブックのデフォルトルールでカバーされない部分」だからです。前者があって初めて後者が意味を持ちます。両者は最終的に同じ合同レビューに入れて一緒に検証します。

ルールブックの形は、着手時に下す決断で決まる

新コードは元の構造を踏襲するのか、それとも完全に再設計するのか。この決断によって、ルールブックの形が決まります。

依存関係グラフとギャップリスト

依存関係グラフは、並行ワークフローを分割するために使います。どのファイルを先に移行すべきか、どのファイルを同じバッチで移行すべきかを把握する必要があります。手作業ではなく、Claude CodeにAgentを指示して決定論的なスクリプトを書かせ、実行してグラフを生成させます。

ギャップリストには別の種類のものを入れます。新しい言語には必須だが、古い言語には存在しない要件です。ZigからRustへの移行におけるギャップは手動メモリ管理（CやC++と同じ流儀）、PythonからTypeScriptへの移行におけるギャップはインターフェースと契約（コントラクト）です。次節で原文のコードを用いて詳しく見ていきます。

Zigが放置していたことを、Rustは強制する

同じ関数、メモリを確保し、値を詰め、呼び出し元に返す。2つの言語での記述の違いは構文ではなく、誰が後片付けをするかにあります。

// Zig

fn readConfig(allocator: std.mem.Allocator) ![]u8 {
const buf = try allocator.alloc(u8, 1024);
// ...fill buf...
return buf; // caller must free this — but only the comment says so
}

// A caller that forgets 'defer allocator.free(buf)' still compiles — the leak only surfaces at runtime.

fn read_config() -> Vec<u8> {
    let buf = vec![0u8; 1024];
    // ...fill buf...
    buf // ownership moves to the caller; memory is freed automatically
}

// Use it after it's moved? Free it twice? Neither compiles.
// Forget to free it? There's no free call to forget — drop is automatic.

PythonからTypeScriptへの移行は、インターフェース契約でつまずきます。Pythonは関数がどんな形のオブジェクトを受け取るか、返すかを宣言する必要がありませんが、TypeScriptは必要です。この情報は元々コードを書いた人の頭の中にしか存在しなかったため、一つずつ掘り起こして書き出す必要があります。これがギャップリストの役割です。

Jarred氏とMike氏は両方ともギャップリストファイルを作成しましたが、タイミングが異なります。Jarred氏は事前にギャップを徹底的に洗い出しました（これは6ステップ法でもステップ1に置かれているプラクティスです）。Mike氏はまず翻訳を進め、その後で振り返って監査し、ギャップを補充しました。あなたも両方のアプローチが必要になるかもしれません。

まず3つのファイルでルールを試す

ルールブックが完成したら、すぐに全体へ展開するのはやめましょう。Jarred氏はこのステップで3つのAgentを起動し、3つのファイルだけを扱わせました。

この3ファイルで、彼は2つの致命的な問題を発見しました。今回の移行は合計1,448ファイルです。もし最初から全体に展開していたら、この2つの問題はコードベースの隅々にコピーされ、後から一つずつ回収することになっていたでしょう。

ステップ2のフローチャート。画像出典：ClaudeDevs原文

このステップが終わった時点で、翻訳されたファイルはすべて破棄します。目的はルールを磨くことであり、進捗を貯めることではありません。

キューをディスクから再構築、中断しても再開可能

ルールブックの検証が終わり、判定役も揃いました。ここからが本格的な全量翻訳です。このステップ以降、残りの全ステップは同じマルチAgentループ、つまり実装・レビュー・修正を繰り返します。

ステップ3「全量翻訳」のマルチAgentループ。画像出典：ClaudeDevs原文

どのモデルがどの役割を担当するか

実装作業は小さなモデルに任せ、レビューは大きなモデルに任せます。Mike氏はメインの移行段階で、実装用に12のClaude Sonnet サブAgentを並列稼働させました。

キューは機械的であるべき

バッチ処理スクリプトが、あるファイルの処理が完了したかどうかを判断する唯一の基準は、ディスク上に翻訳ファイルが存在するかどうかです。その後、残りのタスクをバッチに分割し、実装Agentに渡します。

翻訳Agentは自信がない箇所に遭遇した場合、推測や無理な翻訳はせず、一律マーカーを打って、ステップ4で集中的に処理します：

// TODO(port): <reason>

レビュー側は、2つの敵対的レビューがそれぞれ独立したコンテキストで実装結果を評価し、意見が一致しない場合は第3のAgeが裁定します。レビューが複数のファイルで同じエラーを繰り返し検出した場合、ルールブックの一文を修正し、そのバッチを再生成します。

ステップ4・5・6：コンパイル、実行、挙動の一致

この3つのステップは同じループ構造を共有しており、進むほどに人の判断が必要なくなります。

ステップ4・5・6のループ構造。画像出典：ClaudeDevs原文

Jarred氏はオーケストレーションスクリプトを使用し、ワークスペース全体に対してコンパイラを1回呼び出し、エラーリスト全体を取得しました。「修正Agent」がこのリストを並列で処理し、敵対的レビューを組み合わせて、再ビルド、そして再実行します。

エラーリスト自体を確認することは有用で、プロセスの変更が必要なシステム的な問題を浮き彫りにします。Jarred氏は実際に遭遇しました。循環インポートを修正した後、何千ものRustモジュールエラーが発生したのです。Zigの遅延コンパイルは循環インポートを許容しますが、Rustは許容しません。彼の解決策は、ループにロジックを組み込み、依存関係を削除すべきか、移動すべきか、境界をリファクタリングすべきかを自動で分類させることでした。

ステップ5にも機械的な真実の源があります。スモークテストで発生するクラッシュです。ループレベルでの修正方法は、問題を根本原因別にグループ化し、敵対的サブAgentによるレビューにかけることです。

ステップ6は、両方のプログラムの挙動を一致させることです。ファイル翻訳が完了し、コンパイルが通り、スモークテストもパスしました。次に、それらをシャードに分割し、事前の段階で構築したテストスイートを実行します。失敗したものは「修正Agent」が処理し、失敗したテストを両方のコードベースに対して同時に確認させます。修正後、敵対的レビューによるチェックを受けます。

このステップでは、新しい役割が登場します。ビルドデーモンです。プロセス全体で実行可能ファイルの再ビルドを許可されているのは、このデーモンだけです。修正Agentはパッチを書くだけ。デーモンはパッチをまとめて1回再ビルドし、影響を受けるテストを再実行し、結果をフィードバックします。最も高価な操作が直列化され、十数のAgentがそれぞれトリガーするのを防いでいます。

テストスイートがない場合はどうするか

多くの人は、移植可能な既存テストスイートを持っていません。Mike氏もそうでした。彼はClaudeに小さなスクリプトを書かせ、7つの実シナリオを新しい移植版と元のPython版の両方で実行し、結果をdiffしました。失敗したシナリオごとに修正Agentを配置し、7つ全てがパスするまでループを回しました。

さらに彼は一歩進んで、Claude自身にエンドツーエンドテストの設計をさせました。4晩連続で自律実行させ、失敗を修正し、再実行させたのです。そこで検出されたのは、どのシナリオリストも予測できなかった小さな問題でした。

結論：テストスイートがないことは、移行をブロックする理由にはなりません。判定役を継承できないなら、Claudeに作らせましょう。どちらの道でも、あなたの元のコードベースが事実上の標準です。

移行完了後

Jarred氏のBun移行は現在本番環境で稼働しています。代償も明記されています。Rustコードの約4%がunsafeブロック内にあります。主にC/C++境界上の単一行のポインタ操作です。

どのプロジェクトにも当てはまるプラクティス

• このガイドを盲目的にコピーしない。移行は毎回異なります。これを出発点として、着手前にClaudeと一緒にあなた自身の計画を立ててください。
• 単一の失敗にこだわらない。単一の失敗はループに処理させ、あなたの注意はパターンに向けてください。
• レビューは敵対的に、検証は機械的に。コンパイラ、diff、テストスイートなどのスクリプトに判定役を任せてください。
• 常に最大のモデルを使わない。量が多い実装は小モデルに任せ、最大のモデルはレビュー、そして「他のAgentが従うべきルール」を書く場面に使いましょう。
• 人的工数を前へ。ルールブックとストレステストが最も時間を消費します。その後は基本的にキューが処理を進めます。

6ステッププロセスの全体像。画像出典：ClaudeDevs原文

テンプレートの入手先と、割り引いて読むべき点

この仕組みはゼロから作る必要はありません。Anthropicがテンプレートとプロンプトをオープンソース化しています。

リポジトリ：https://github.com/anthropics/code-migration-kit-with-claude-code
ルールブックテンプレート：templates/RULEBOOK.md
ギャップリスト用プロンプト：prompts/02-gap-inventory.md
ビルドデーモンスクリプト：scripts/build_daemon.sh
Jarred氏による詳細な振り返り：https://bun.com/blog/bun-in-rust

いくつか、言葉を明確にしておきます。約16.5万ドルというのは、未キャッシュ入力トークン59億と出力トークン6.9億を、公開されているAPI価格で換算した結果です。未キャッシュとは、重複コンテンツによる割引が適用されない部分を指します。この計算は、Anthropic社内の実際の支出を表しているわけではありません。Mike氏の移行の主要部分は2,700万トークンでした。

資料では「過去1ヶ月で10個のコードパッケージを移行完了」とありますが、詳細に説明されているのはそのうちの2つだけです。残り8つの内容と結果については、一切言及がありません。Bunのマージ後に発生した19件のリグレッションの深刻度や、影響を受けたユーザー数についても記載はありません。

この2つのケーススタディの主役はどちらもAnthropicの関係者です。1人は自社のテクニカルスタッフ、もう1人は自社ラボの共同責任者です。手法自体は検証可能であり、あなた自身が実行すれば成功するかどうか分かります。ただし、「成功率」が「10パッケージ全て成功」なのか「成功した事例だけを紹介している」のかは、この資料からは検証できません。

同じことを、前の四半期までにやろうとしても、採算が合いませんでした。

Mike Kriegerのプロジェクトも、あるボトルネックがきっかけでした。彼のチームの内部ツールは、ユーザーに単一の実行ファイルとして配布する必要があるのですが、Pythonのツールチェーンでは1プラットフォームのビルドに8分もかかっていました。

バーの長さはおおよその所要時間。約2秒のバーは見えるように拡大しています。これはMike Kriegerが週末1つで達成した結果です。16.5万行のTypeScript、コンパイルは8分→2秒に、実行ファイルの起動は6倍高速化。ついでにデプロイパイプライン全体も退役させました。数字はすべて記事からの引用です。

問題が起きたら、コードに手を伸ばすな。コードを生み出すプロセスに手を伸ばせ。具体的にはこうです。レビュー担当Agentが数十のファイルで同じ間違いを繰り返し見つけたら、ルールブックに一文追加して、影響を受けた分をまとめて再生成する。ルールブックはどんどん分厚くなる。コードのほうを手作業でパッチしてルールに合わせることは、絶対にしない。

判定役とは、移行が正しいかを判断する基準です。これがないと終了条件がなく、いつ完了したのかわかりません。元記事でも、これは最初のステップとして挙げられています。

テンプレートとプロンプトはGitHubの「anthropics/code-migration-kit-with-claude-code」で公開中です。ルールブックのテンプレートとビルドスクリプトが含まれています。手法はそのまま使えます。対照表は以下の通りです。