HN 日本語サマリー

← 一覧へ戻る
プログラミング

リファクタリングの経済的メリット

The Economic Benefit of Refactoring (martinfowler.com)

267 pointsby javaeeeee115 コメント

要約

この記事は、AIエージェントによって生成された大規模なコードベースにおけるリファクタリングの経済的メリットを検証しています。大規模なデータアクセス層をリファクタリングした結果、同じタスクを実行するためのトークン消費量が83%削減され、将来的な開発コストの低減につながることが示されました。これは、エージェントが過去の学習に依存せず、毎回同じタスクを再実行できるため、リファクタリングの効果を実験的に測定できたことによります。

全文翻訳

リファクタリングの経済的メリット

エージェントエンジニアリングの新世界に慣れる一環として、私は自分の仕事​​をサポートするアプリケーションを構築しました。これは洗練されたアプリです。ダイナミックなリフレッシュとルックアップを備えた高品質なWeb UI、モーダルと自動保存、外部システムとの統合、機械学習とテキスト分析、バックグラウンドジョブ、そして完全に自動化されたデプロイメントを備えた適切な環境設定が含まれています。コード量は約15万行で、主にRust(約12万行)で、残りはTypeScriptとTerraformです。

これは完全にエージェントによって書かれました。ほとんどがClaude Codeで、一部Cursorを使用しました。興味本位で時折確認した以外は、コードを読んだりレビューしたりすることは一切ありませんでした。

アプリケーションを構築している間、いくつかの問題が発生していることに気づきました。ターミナルでファイル内の4,000行目への編集が表示されるのを見た後、詳しく見てみました。データアクセス層は6,000行以上に成長していました。機能が増えるにつれて、これは成長し続けました。すべてのクエリ、読み取りまたは書き込みで、同じHTTPリクエストの設定、同じJSONエンコードとデコードが繰り返されました。最終的に、それは17,155行に達しました。単一のRustファイルでです。

リファクタリングによる実験

17,155行のファイルは、データアクセス層全体でした。単一の自己完結型モジュールです。コードをレビューしたところ、重複排除がなく、内部言語がなく、関数の抽出が限定的で、クラスの抽出はほとんどありませんでした。インターフェースを維持するための明確な境界はありました。リファクタリングの素晴らしいターゲットでした。

エージェントコードベースをリファクタリングする目標は、将来の作業のトークン消費を減らすために、今リファクタリングにトークンを費やすことです。実験は、このファイルがリファクタリングされるにつれて、このコードベースでの個別の機能実装のトークンコストが減少することを示すことができるはずです。

エージェントは決して学習しないため、これは実験として実行可能になりました。リファクタリングの各段階の後で、まったく同じ変更を加えるように、新しいエージェントに指示できます。人間のエンジニアとは異なり、実験は以前のステップからの学習によって汚染されません。

  1. 厳格なリファクタリング規律に従って、全体的なリファクタリング計画を作成します。
  2. 単一のプロンプトで説明された代表的な変更を作成します。
  3. 変更のベースラインコストを確立します。サブエージェントで、そのプロンプトを実行し、サブエージェントにトークン消費量を報告するように依頼します。
  4. 変更を破棄します。
  5. ループで:
    1. 全体的なリファクタリングの単一ステップを適用します。
    2. サブエージェントで、まったく同じ変更を実行し、変更のトークンコストを受け取ります。
    3. 変更を破棄します。
  6. ベースラインを含め、リファクタリングの各ステップの後で、すべてのトークンコスト、変更実行時間、およびコード行数を記録します。

代表的な変更に使用されたプロンプトと、適用されたリファクタリングステップは、以下の付録に示されています。

1つの注意点:Claudeは、トークン数を表示し、セッションあたりの消費トークンを報告し、トークンに対して請求しているにもかかわらず、ライブでトークンをカウントするための信頼できる方法を提供していません。これは一時的な問題であり、時間とともに改善されると想定しています。代わりに、サブエージェントは受信および送信された文字数を報告し、文字数を4で割ることによってトークンを近似するためにtiktokenを使用しました。

結果

ステップデータアクセス層 LoC最大ファイル LoC総 Rust LoC変更あたりの入力トークン変更あたりの出力トークン変更あたりの時間 (秒)
ベースライン17,15517,15550,359159,5641,705342
ステップ 1 (FirestoreClient)16,70616,70649,910155,2051,723530
ステップ 2 (extract_doc_id, new_link)16,56216,56249,766159,2272,105574
ステップ 3 (link-query helpers)16,56716,56749,771154,0542,105524
ステップ 4 (FakeStore predicates)16,57716,57749,781154,1462,060654
ステップ 5 (value ctors)16,46916,46949,673171,2512,0361,353
ステップ 6 (FieldsBuilder)16,46916,46949,673171,2512,0361,353
ステップ 7 (queries.rs)16,47415,67049,678151,8501,800587
ステップ 8 (traits.rs)16,50813,84549,712132,5581,723446
ステップ 9 (traits/ split)16,50813,84549,712132,5581,723446
ステップ 10 (codec.rs)16,52112,84649,725131,8711,750540
ステップ 11 (fake_store.rs)16,53511,12249,739133,0162,460600
ステップ 12 (store/ split)16,5509,26949,754104,0802,050490
ステップ 13 (co-locate tests)16,5509,26949,754104,0802,050490
ステップ 14 (complete fake_store.rs)16,5537,22549,757107,2052,453523
ステップ 15 (store/ split)16,6083,69549,81227,3602,113454

ここで興味深いメトリクスは、データアクセス層全体の総コード行数、データアクセス層の単一の最大ファイルのコード行数、および変更の作成中に消費された入力トークンです。

[画像]

このチャートは4つのことを示しています。最初の点はベースライン(ステップ0)であり、その後、各リファクタリングステップが適用された後に同じメトリクスが繰り返されます。

  1. データアクセス層全体の総コード行数。当初は、私が開始した単一ファイルのみでした。リファクタリングが適用されるにつれて、これは多くのファイルになります。最終的には19個のRustファイルになります。
  2. データアクセス層の単一の最大ファイルのコード行数。これは、単一の初期ファイルにあったデータ層全体から始まりました。最終的には、単一の最大ファイルはテストライブラリになります。さらなるリファクタリングパスで、これに同じアプローチを適用できる可能性があります。
  3. 代表的な変更の適用中にサブエージェントによって消費された総入力トークン。
  4. 代表的な変更の適用中にサブエージェントによって生成された総出力トークン。

リファクタリングはトークン消費を削減する

結果は明らかです。入力トークンは、最大ファイルが減少し始めるまで比較的安定しており、その後、Claudeの言葉を借りれば、崖から落ちるように減少します。

ベースラインと最終リファクタリングの間で、同じタスクの入力トークンは159,564から27,360に減少しました。132,204トークン、つまり83%の節約です。そして、その節約は一度きりではありません。この時点からデータアクセス層に触れるすべての変更は、大幅にコストが削減されます。

どれくらいの節約になるでしょうか?執筆時点でのSonnet 3の価格を1MTokあたり3ドルと仮定すると、39.7セントです。それほど多くはありません。これは倍増するでしょうか?デバッグではどのように展開されるでしょうか?より複雑な機能では?これはコードベースの1つの部分のみをリファクタリングしていますが、コードベース全体を積極的にリファクタリングして、どこでも節約を見つけることができるでしょうか?それらのリファクタリングはどれくらいコストがかかるでしょうか?

この節約は、エージェントが読むコードが少なくなったためです。しかし、読むコードが少なくなったからではありません。データアクセス層全体の総コード量は比較的一定のままです。したがって、この節約を計上するためには、エージェントは読む必要がある最小限のファイルサブセットを特定できる必要があります。結果は、これが起こっていたように見えます。変更が適用されるにつれて、Claude Codeの思考出力とファイル読み取りサマリーを読むと、サブエージェントが毎回ますます小さなコードセクションを正常に読み取っていたことも示唆しています。

言い換えれば、ファイルをランダムに小さなファイルに分割しても、それほど助けにならないでしょう。各ファイルが小さくなったとしても、エージェントは関連コードを探して多くのファイルを読み取ることを余儀なくされるでしょう。最も大きな影響を与えるステップは最後ですが、以前のステップはこの節約を設定するためのリファクタリングでした。これは計画されていませんでした。これは単に、リファクタリングが通常どのように進むかの結果でした。重複を抽出するためのローカルファイル変更、その後、繰り返しの中核が現れたら小さなファイルに分解します。

リファクタリングは代表的な変更を小さくしませんでした。コードを書き込む際に生成されたトークンの数はほとんど影響を受けませんでした。出力トークンはあまり変動しません。それらのトークンは入力トークンの5倍の価格です。しかし、それらはずっと少なくなっています。出力トークン生成を削減するために適用できるリファクタリングはありますか?これらの質問を探求するために、より複雑なサンプル変更が必要です。非決定的なコード生成プロセスのノイズが、コードのファクタリングの変化によって引き起こされる変動を隠しています。

プロセスに関する注記

Claudeはリファクタリングが得意ではありませんでした。プロンプトと以下のリファクタリングステップを読むと、生成されたリファクタリングがプロンプトに直接応答したものであることが明らかです。Claudeはコードを見たり、一般的なリファクタリングを見たりして、適用に適したものを判断することができません。人間が積極的にガイドする必要があります。これは、このアプリでの広範な経験と一致しています。開発ハーネスには明示的なリファクタリングステップが含まれています。そのリファクタリングステップは、Claudeにこのファイルを改善するように促しませんでした。より逸話的には、Claude.aiはClaude Codeよりも優れていました。私は両方のインターフェースを使用してリファクタリング計画を作成しました。Claude Codeは、最初のステップとして関数抽出を特定しました。Claude.aiはさらに進んで、クライアントクラス全体を抽出する必要があることを見ました。

また、適用も下手でした。リファクタリングの機械的な作業は、grepとsedを使用したPythonスクリプトを書いて実行されました。これらのスクリプトは、インデントによって頻繁に混乱しました。ああ、皮肉なものです。さらに、最も価値のある単一のリファクタリングが最初のパスで見逃され、フォローアップステップとして再適用する必要がありました。これが、図のステップ数が付録のリファクタリングステップと一致しない理由です。

実験全体を完了するのに約8時間かかりました。これはほとんど unattended でした。唯一の介入は、6時間40分後に完了したように見えましたが、そのステップをスキップしていたため、リダイレクトが必要になった後でした。この実験は遅いホテルのWiFiで実行されていました。それが所要時間に寄与したかどうか疑問に思いました。しかし、コードベースのより詳細な分析では、cargoの一時ビルドキャッシュが非常に大きくなっていました。テスト実行は著しく苦しんでいました。

さらなる作業と広範な影響

残念ながら、リファクタリング計画の作成と実行に必要なトークン数をカウントすることを思いついたのは、それがすでに完了した後でした。この作業を行っていた時間枠全体での集計消費量、設計と実験の実行、およびその他のさまざまなタスクを含めて確認しました。リファクタリングを実行するために必要なトークン数を正確に言うことはできません。上限は500万ですが、これにはリファクタリング計画を2回作成すること、実験を設計するための作業(代表的な変更を含む)、およびその他のさまざまなタスクが含まれます。将来の作業には、リファクタリングに消費されたトークンのより正確なカウントを含めるべきです。

これは、単一の開発者によって構築および保守されている、まだグリーンフィールドの重要なアプリケーションに対する1つの実験にすぎません。しかし、これは潜在的に興味深い第一歩であると信じています。この努力は、時間とお金の面でのリファクタリングの価値を示しています。リファクタリングのコストを測定するだけでなく。より複雑な変更、より広範なリファクタリング、継続的なリファクタリング、さらにはさまざまなリファクタリングアプローチの相対的な価値を調べるのは興味深いでしょう。

これは始まりにすぎません。

付録

注意:これらの付録には、私が使用したプロンプトと返された出力が含まれています。適用された唯一の編集は、行われた特定のコード変更を削除することでした。これらは、エージェントがどのように指示されたかを示すために編集なしで含まれています。隠されたトリックはありません。そのため、混乱を招く可能性のある言語がいくつかあります。エラーはオリジナルにあります。

代表的な変更

これは、各サブエージェントにフィードされた記録されたプロンプトであり、コードベースと付随するアーキテクチャドキュメント以外の追加のコンテキストは提供されませんでした。すべてのサブエージェントはまったく同じ情報から開始しました。

あなたは ~/dev/your-project-name のRustプロジェクトで作業しています。

既存のパターンに完全に一致するように、Firestoreレイヤーに新しい ItemWatchStore パブリック非同期トレイトを追加してください。トレイトには3つのメソッドが必要です。

  • async fn watch_item(&self, item_id: &str, user_id: &str) -> Result<()>
  • async fn unwatch_item(&self, item_id: &str, user_id: &str) -> Result<()>
  • async fn watched_items_for_user(&self, user_id: &str) -> Result<Vec<String>>

ウォッチは item_watches Firestoreコレクションに保存されます。各ドキュメントにはフィールドがあります:itemId(文字列)、userId(文字列)、createdAt(タイムスタンプ)。ウォッチレコードのRust構造体はありません — メソッドは Vec<String>(アイテムID)を返します。

FakeStore(FakeStoreInnerに Vec<(String, String)> フィールドを追加してインメモリで使用)と FirestoreStore(このファイル内の他のストア実装で使用されているのと同じHTTPパターンを使用)の両方でトレイトを実装してください。

応答の最後に正確に次のJSONブロックを出力してください(実際の値を入力してください):

{
  "files_read": [
    {"path": "src/firestore.rs", "chars": 123456},
    ...
  ],
  "response_chars": 7890
}

変更をコミットしないでください。コードを書き終えたら停止してください。

リファクタリングステップ

これは、リファクタリング計画を作成するために使用されたプロンプトです。

リファクタリングは証明可能な正しさを保持する一連のコード編集であるという厳格な定義に従い、Martin FowlerのRefactoring第2版をソースとして使用して、@src/firestore.rsを調べます。これは17K LoCのRustファイルです。ファイルがそれほど長くなるべきではありません。内部言語を使用してクエリを構築および管理している可能性はほぼありません。インターフェースをまったく変更せずに、そのファイルの行数を大幅に削減する一連のリファクタリングを生成し、説明してください。ただし、実行しないでください。

以下は、Claudeによって構築され、フォローされた計画から抽出された、適用されたリファクタリングの説明です。実際の計画には、予測されるコード変更が含まれています。各リファクタリングについて、フォローする個々のステップがリストされています。これらの各ステップは個別にテスト可能であり、個別にテストされました。これは、ほとんどの人間エンジニアが従うよりも厳格なリファクタリングです。

ここにリストされているステップは、上記の測定された変更と直接一致しません。なぜなら、Claudeは最初のパスで最も価値のある単一のリファクタリング(ストアをサブファイルに分割すること)をスキップし、その後、追加の2つのステップとしてそれを完了する必要があったからです。

Fowler ref: Extract Class (7.5); Extract Function (6.1) 各プリミティブに対して

FirestoreStoreは現在2つの責任を混同しています。

  • ドメインクエリオーケストレーション — どのクエリを実行するか、どのドキュメントを書き込むか、結果をドメインタイプにどのように解析するか
  • Firestore HTTPトランスポート — 認証ヘッダー、URL構築、FirestoreワイヤタイプのJSONエンコード/デコード、PRECONDITION_FAILEDのエラー再試行

Fowler §7.5では、クラスのデータと動作のまとまったサブセットを特定できる場合に新しいクラスを抽出するように求めています。トランスポートの責任は、client: reqwest::Client、project_id: String、MetadataAuth、およびdocuments_url() / auth_header()を所有しています。これらを新しいFirestoreClient構造体に抽出します。

推定節約量:約1,200行(FirestoreStoreの実装); FirestoreClientは正味約120行を追加します。

ステップ2 — 関数抽出:extract_doc_idとnew_link(Fowler §6.1)

Fowler ref: Extract Function (6.1)

  • extract_doc_id — 式 doc.name.rsplit('/').next()?.to_string() が、すべての20のparse_*_document関数の先頭にそのまま表示されます。これを抽出します。

  • new_link — metadata: HashMap::new() と provenance: None、および新しいUUIDを持つLink構造体の構築が62回出現します。ファクトリ関数を抽出します。

推定節約量:約500行(62 × 約10行の構造体 → 62 × 約2行の呼び出し; 20の解析関数がそれぞれ1行のボイラープレートを失います)。

Fowler ref: Extract Function (6.1)

リンククエリを実行した後、FirestoreStoreトレイト実装内の2つのサブパターンが繰り返されます。

  • パターンA — クエリ行からすべてのリンクドキュメントを収集する(約15箇所)。

  • パターンB — リンクをクエリし、正確に1つのターゲットIDを返す。欠落している場合はエラー(約8箇所):

推定節約量:約200行。

Fowler ref: Extract Function (6.1)

FakeStore実装内では、約15のメソッドがinner.links.iter()...のバリエーションを繰り返しています。

FakeStoreInnerに2つのメソッドを抽出します。15の呼び出しサイトは単一行になります。2番目の述語でさらにフィルタリングするメソッド(例:to_kindもチェックする)は、ヘルパーの結果に.into_iter().filter(...)をチェーンします。

推定節約量:約120行。

ステップ5 — インラインコードを関数呼び出しに置き換え × 4:Firestore値コンストラクタ

Fowler ref: Replace Inline Code with Function Call (8.5)

コーデックブロックの前に、4つのプライベートフリー関数(メソッドではなくファイルレベル)を追加します。すべての128以上の`json!({