【ITニュース解説】Hash the Output Tree Before You Extract One Helper

既存のソフトウェアプロジェクト、特に長く使われている「ブラウンフィールドスクリプト」は、システムエンジニアを目指す皆さんにとって、最初は理解が難しいかもしれない。これらのスクリプトは、データの読み込み（I/O）、計算処理、結果の出力などが一つの場所に混ざり合っていることがよくある。このような状況で、例えば「スコアリング」という計算ロジックだけを改善しようとしても、どこを触れば良いのか、変更が他の部分にどのような影響を与えるのかがわかりにくい。もし、これらの処理を一度にすべて書き直そうとすると、何がどこで壊れたのか、どの変更が予期せぬ挙動を引き起こしたのかを特定するのが非常に困難になる。

そこで提案されるのが、「出力ツリーをハッシュ化してオラクルにする」という方法だ。これは、複雑なコードを安全に改善するための段階的なアプローチである。「オラクル」とは、正しい動作の基準となるもののことで、この場合はスクリプトが生成する「出力ファイル」そのものを指す。

この方法の核心は、まず現状のスクリプトがどのような出力（ファイル）を生成するのかを正確に把握し、その出力が未来永劫変わらないように「凍結」することにある。具体的には、次の三つの事実だけを厳密に記録する。一つ目は、スクリプトが正常に終了したかを示す「終了コード」。二つ目は、スクリプトが生成する「すべてのファイルの相対パス」。そして三つ目は、それらのファイル一つ一つの内容を特定する「SHA-256ハッシュ値」だ。タイムスタンプやプロセスID、現在の作業ディレクトリなど、実行環境によって変わりうる情報は記録しない。これらが記録されたものを「ゴールデンツリー」と呼ぶ。

ゴールデンツリーを作成するには、まず「フィクスチャ」と呼ばれる小さなテスト用の入力データを用意する。例えば、CSVファイルをいくつか用意し、それらをスクリプトの入力とする。そして、スクリプトが結果を書き出すための空の出力ディレクトリも用意する。これらのフィクスチャは、一度作成したら安易に変更せず、バージョン管理システムで管理する。

次に、このフィクスチャを使ってスクリプトを実行し、出力ディレクトリに生成されたファイル群のハッシュ値を計算する。全てのファイルのSHA-256ハッシュ値と相対パスをまとめた「マニフェスト」を作成し、これをゴールデンツリーとして保存する。この作業は複数回実行し、常に同じマニフェストが生成されることを確認する。もし異なる結果が出た場合、それはスクリプトが非決定的な挙動をしていることを意味し、問題の修正が必要になる。

ゴールデンツリーが確立されたら、いよいよ実際の改善作業に進む。しかし、ここでも重要なのは「一度に一つの変更」をすることだ。例えば、在庫管理スクリプトの例では、複数のCSVファイルを読み込み、商品の数量と価格、フラグからスコアを計算し、最終的にJSONファイルとして出力するという処理が示されている。このスクリプトでは、スコアリングの計算ロジックがデータの読み書きと密接に結びついており、改善のターゲットとなる部分だ。

変更は、このスコアリングロジックを元の場所から切り出し、独立した「ヘルパー関数」として定義することから始める。このとき、関数の引数の順番を変えたり、結果の丸め方を変えたり、出力JSONのキーの名前を変えたり、余計なログを追加したりするなど、スコアリングロジックの抽出以外の変更は一切行わない。ただ、その計算部分だけを切り出すことに集中する。

ヘルパー関数の抽出が終わったら、再びゴールデンツリーと比較するテストを実行する。このテストは、スクリプトを実行し、その出力ディレクトリのハッシュ値を計算し、最初に記録したゴールデンツリーのマニフェストと比較する。もし計算されたハッシュ値がゴールデンツリーと完全に一致すれば、その変更はスクリプトの外部的な動作に影響を与えなかった、つまり安全な変更であったと判断できる。もしハッシュ値が一致しなければ、それは抽出作業の過程で予期せぬ動作変更が発生したことを意味するため、その変更は元に戻すべきだ。

このプロセスのメリットは、変更の責任範囲を非常に狭くできることにある。もしテストが失敗した場合、その原因は直前に行った一つの小さな変更にほぼ限定されるため、原因特定と修正が格段に容易になる。全面的な書き換えのように、何十、何百もの変更が一度に行われると、どこで問題が起きたのか全く分からなくなる事態を避けられる。

どのような変更がテストを失敗させるか、という判断基準も明確だ。スクリプトの終了コードが変わったり、出力ファイルが増えたり減ったり、既存のファイルのハッシュ値が変わったりした場合は、直ちに変更を中止し、問題の検査と修正を行う。一方で、コード内部の名前が変わっても、出力ツリーのハッシュ値が変わらない場合は、外部の振る舞いが変わっていないため、その変更は安全であると判断できる。

AIツールを活用して、このようなヘルパー関数の抽出を提案させることも可能だが、AIが出力するコードをそのまま受け入れるのではなく、必ずゴールデンツリーによる検証を経るべきだ。AIに「スコアリングを改善する」ように依頼すると、意図しない挙動変更を伴うコードが生成される可能性があるため、「スコアリングロジックを分離する」といった、純粋なリファクタリングの依頼に留めるのが望ましい。

ただし、この方法は万能ではないという限界も理解しておく必要がある。オラクルは、フィクスチャでカバーできる範囲のテストしか行えない。フィクスチャに含まれていない特殊なデータ（例えば、予期せぬエンコーディングや、これまで見たことのないフラグ値など）が本番環境で現れた場合、このテストではその問題を検出できない。また、この方法はあくまで出力バイト列の一致を保証するものであり、パフォーマンスの改善や、OSの異なるユーザー権限に関する問題、法規制や安全基準への準拠などは検証できない。浮動小数点数の計算精度による問題も、round()関数などで明示的に丸めることで対処し、不意な不一致を防ぐ必要がある。

この方法が適さないケースもある。例えば、スクリプトがファイルを出力しない場合、出力ファイルに常に変化するライブタイムスタンプが含まれる場合、本番に近いテストデータを用意できない場合、機密情報を含むデータをフィクスチャとして使えない場合（個人情報は必ず匿名化してから使う）、そしてそもそも自動テストを実行する環境がないチームなどだ。自動テストランナーがない場合、「スクリーンショットで動作確認した」というだけでは信頼できるオラクルにはならない。

最終的に、このプロセスは「フィクスチャと出力ツリーのハッシュ値から始め、純粋なヘルパー関数を一つ抽出し、同じオラクルで再ハッシュし、そのパッチを出荷する。次の改善は次の安全な実行後に持ち越す」という循環的な流れで構成される。この規律を守ることで、複雑なシステムの改善を、予測可能かつ安全に進めることが可能になる。