AIに「この処理を関数に分けて」と頼んだら、コードの見通しだけでもかなり変わった話

動くけど触れないコードの悪夢

月末の金曜日、時計はすでに午後9時を回っていました。蛍光灯だけが煌々と光る静かなオフィスで、目の前のディスプレイに映る300行ほどのPythonコードを前に、私は完全に固まっていました。コードは動いているのです。毎月、このスクリプトは文句も言わずにデータ集計を終わらせてくれます。しかし、今月はほんの少しだけ仕様変更がありました。「この列の集計方法を少し変えてほしいだけなんだ」上司は簡単に言いましたが、それが地獄の始まりでした。

このコードは、前任者が残したものです。変数名は `data1`, `tmp_list`, `result` といった具合で、もはや何が何だか分かりません。一つのループの中でファイルの読み込み、データの加工、計算、そして結果の出力まで、全ての処理がごちゃ混ぜに書かれています。いわゆるスパゲッティコードそのものです。一行修正すれば、どこか別の場所で予期せぬエラーが起きてしまいます。まるで時限爆弾の配線を一本ずつ手探りで確かめるような、冷や汗の出る作業でした。

動くが触れないコード、自動化を阻む壁

まず、金曜の夜、たった一行の修正のせいでスクリプトが動かなくなり、エラーメッセージと3時間格闘しました。結局原因が分からず、修正前のコードに戻して手作業で対応する羽目になりました。深夜のタクシーの中で「もうあのコードは触りたくない」と本気で思いました。

当時の対象ファイルは約300行で、非エンジニアの私には十分すぎる重さでした。

たった300行。プロのエンジニアから見れば鼻で笑われるような規模かもしれません。しかし、非エンジニアの私にとっては、それはエベレストのように高く、どこから手をつけていいか皆目見当もつかない巨大な壁でした。動いているからこそ、誰も手を出せません。改善しようものなら、正常に動いていたものまで壊しかねない恐怖があります。この「動くけど触れない」コードこそ、現場の業務自動化を静かに蝕む本当の敵だと感じています。

不安の具体化と課題の発見

次に、恐怖の正体は、漠然とした不安でした。どこを直せばどこが壊れるか分からません。この正体不明の不安こそが、私たちを行動できなくさせます。そこで私は、まずこの恐怖を具体的に言語化することから始めました。ノートを開き、何がそんなに怖いのかを一つずつ書き出していきました。

まず、変数のスコープが広すぎました。ファイルの先頭で定義された変数が、300行下の最終盤で何の前触れもなく更新されているのです。どの処理がどの変数に依存しているのか、追いかけるだけで目がかすみます。次に、処理の塊が見えないこと。どこからどこまでがデータの読み込みで、どこからが計算なのか、その境界線が全く存在しません。全てのロジックが、巨大な一つの塊として絡み合っていました。

コメントの不在も致命的でした。「なぜここでこの計算をしているのか？」その意図を説明する言葉はどこにもありません。前任者の頭の中にしかなかった設計思想は、もはや誰も知ることができません。これでは、コードはただの暗号のようでした。

課題の具体化と改善の第一歩

一方で、これらの問題点を書き出すことで、「分からない」という漠然とした不安が、「変数の依存関係が追えない」「処理の境界が不明」といった具体的な課題に変わりました。問題が具体的になれば、対策も具体的になります。闇雲にコードを修正するのではなく、まずはこの絡み合った依存関係を断ち切ることから始めました。それが、全ての改善の第一歩でした。

AI活用：既存コードの関数分割に限定

課題が明確になったところで、どうやって手をつけるか考えました。300行のコードを全て読み解き、完璧に再設計する時間もスキルもありません。そこで、最近話題のAIに助けを求めることにしました。しかし、ここでも一つ、重要な方針を立てました。それは「AIに新しいコードを書かせない」ということです。

AIに「こういう処理をするコードを書いて」と丸投げするのはリスクを伴います。なぜなら、AIはこちらの業務の細かい文脈や、データの特殊なクセまで理解しているわけではないからです。出てきたコードは一見すると美しくても、現場の泥臭い現実に即していない可能性があります。

以前、別の業務でAIにコード生成を丸投げしたことがありますが、pandas-stubsやmypyといった、自分には全く分からないライブラリを使った高度なコードが生成されてしまいました。動かすために追加の学習が必要になり、かえって時間がかかってしまった経験があります。

AIに限定指示：関数分割でリスク回避

だからこそ、AIへの指示は極めて限定的なものにしました。「このPythonコードの既存ロジックは一切変えずに、処理の塊を関数に分割してください」。これだけです。新規実装という創造的な作業ではなく、既存資産の整理整頓という、どちらかといえば機械的な作業を頼みました。AIは人間と違って、長大なコードを前にしても集中力を切らさないですし、単純な切り貼り作業でミスをすることもありません。この特性を最大限に活かす戦略をとりました。

この「関数分割だけ」というアプローチは、リスクを最小限に抑えられます。ロジックが変わらないので、分割前と後で出力結果は同じになるはずです。もし違っていれば、それは分割の仕方が間違っているだけで、原因の特定も比較的容易になります。全てをAIに任せるのではなく、人間が舵を取り、AIを優秀なアシスタントとして使う。この距離感が、非エンジニアの私たちにはちょうどいいと感じています。

なお、関連テーマとして「Pythonの基礎から学ぶ！変数とデータ型の違いを初心者向けに解説」も後で見直すと、理解がつながりやすいかもしれません。

入力・変換・出力の3層構造

AIに「関数分割だけ」を指示すると、驚くほど素直な結果が返ってきました。あの巨大な一つの塊だった300行のコードが、いくつかの関数に切り分けられたのです。しかし、ただ分けるだけではまだ不十分でした。そこで、初回は最もシンプルで強力な設計原則である「入力・変換・出力」の3層構造を意識して、手動で整理し直すことにしました。

まず「入力」を担当する関数です。これは、ExcelファイルやCSVファイルを読み込んで、プログラムが扱えるデータ構造（リストや辞書など）に変換する役割だけを担います。この関数は、ファイルパスを受け取り、データのリストを返します。余計な処理は持たせていません。

さらに、次に「変換」を担当する関数です。ここがビジネスロジックの心臓部となります。入力関数から受け取ったデータを元に、計算、加工、集計といった処理を行います。今回の仕様変更で修正が必要なのは、まさにこの部分です。他の部分と切り離されているため、安心してこの中の計算式だけをいじることができます。

保守性の第一歩、関数分離

最後に「出力」を担当する関数です。変換関数が作った最終的なデータを、Excelファイルやテキストファイルに書き出します。この関数は、データを受け取ってファイルに保存するだけで、中身の計算には触れていません。

こうして、役割を明確に分けるだけで、コードの見通しは劇的に改善されました。仕様変更があれば「変換」関数だけを見ればいいですし、入力ファイルの形式が変われば「入力」関数を修正するだけです。どこを触ればいいのかが一目瞭然になったのです。初回はこの3関数に分割するだけでも十分な効果があります。この単純な分離が、保守性の第一歩になります。複雑な設計は必要ありません。まずは混ぜずに、分けるだけ。それだけで世界は変わるのだと実感しました。

関数名と引数整理で未来投資

関数に分割しただけでも大きな進歩ですが、もう一歩だけ踏み込むと、未来の自分がもっと楽になります。それが、関数名と引数（ひきすう）の整理です。コードは書く時間より、後から読み返す時間の方が圧倒的に長いです。だからこそ、読み返すときのコストを徹底的に下げておく必要があります。

まず、関数名です。AIが自動で付けた `function1`, `process_data` といった名前を、より具体的で、処理内容が一目でわかる名前に変更しました。例えば、「売上データCSVを読み込む」処理なら `read_sales_csv` のようにします。「動詞 + 目的語」の形式を意識すると、分かりやすい名前になりやすいです。この一手間が、数ヶ月後にコードを見返したときの「これ、何やってるんだっけ…？」を防いでくれます。

データ型による約束事

次に引数と戻り値。関数同士のデータの受け渡し口です。ここが曖昧だと、結局関数の内部を全部読まないと何をしているか分からなくなってしまいます。そこで、`confirmed_facts`にもあるように、戻り値の型をコメントで明記するルールを導入しました。Pythonの型ヒントは難しく感じるかもしれませんが、コメントなら簡単です。

例として、

def read_sales_csv(file_path):
    # returns: list[dict]
    # ... 処理 ...
    return sales_data

こうして、関数の返り値が「辞書のリスト」であることをコメントで示すだけで、この関数が何をするものなのか、格段に理解しやすくなります。受け取った側も、どんなデータが来るか分かっているので、安心して処理を続けられます。データの型という「約束事」を決めておくことで、関数間の連携ミスを劇的に減らすことができました。

必要であれば「達人プログラマー 熟達に向けたあなたの旅」のような教材で、詰まった部分だけ補強するのも良い選択肢だと思います。

これらの命名ルールやコメントの追加は、地味で面倒な作業かもしれません。しかし、このひと手間こそが、将来のメンテナンス時間を何時間も節約してくれる最高の投資だと考えています。

コード分割の品質保証：出力差分チェック

コードを分割し、名前を整えました。これで万事OKかと思いきや、そうは問屋が卸しません。分割という手術を行った直後は、必ず副作用が起きるものです。変数の受け渡しがうまくいっていなかったり、分割の際にうっかりロジックの一部を消してしまったりと、この「ズレ」を確実に見つけ出し、潰していく作業が不可欠です。

大掛かりなテストツールを導入する必要はありません。やるべきことは極めてシンプルです。分割前の古いコードと、分割後の新しいコード、両方を実行して、出力される結果が完全に一致するかどうかを確認するだけです。全く同じ入力データを使えば、出力結果も一文字たりとも違わないはずです。

実際、分割後のテストで、ある数値が微妙にズレているのを発見したことがあります。原因を追っていくと、分割時にループの外に出した変数の初期化処理を、間違って消してしまっていたことが判明しました。もしこのテストを怠っていたら、翌月の集計で誤った数値を報告するところでした。背筋が凍る思いでした。

コード信頼性の最終砦、差分チェック

私たちは、過去の実データの中から典型的なパターンを3件ほど選んでテストケースとしました。そして、修正前後のコードでそれぞれ出力したExcelファイルを、差分比較ツールでチェックします。ここで差分が出なければ、分割作業は成功とみなせます。

この差分チェックという行為は、いわば自動化コードの健康診断です。目視での確認には限界があり、必ず見落としが発生します。機械的に比較することで、人間では気づけないような小数点以下のわずかな違いや、空白文字のズレなども確実に捉えることができます。この地道な確認作業こそ、コードの信頼性を担保する最後の砦になるのだと感じています。

継続的改善がレガシーコードを磨く

しかし、一度に全てを完璧にしようとすると、大抵は挫折します。あの300行のコードも、一気に理想形に書き直そうとしていたら、きっと途中で力尽きていたでしょう。我々が取った戦略は「毎月1関数ずつ良くしていく」という、非常に地味で、しかし現実的なアプローチでした。

最初の月で「入力・変換・出力」という大きな枠組みを作りました。翌月は、一番複雑だった「変換」関数を、さらに小さな2つの関数に分割しました。その次の月は、少し分かりにくかった変数名を、もっと具体的な名前に修正しました。こうして、毎月の定例作業のついでに、たった一つでいいから改善を加えるというルールを設けたのです。

この運用を始めてから、驚くべき変化が起きました。あれほど触るのが怖かったコードに対する心理的なハードルが、劇的に下がったのです。修正箇所が明確で、影響範囲も限定されているため、安心して手を入れることができます。

さらに、運用を回し始めてから、月次メンテの時間はだいたい2時間から40分まで下がりました。

非エンジニアのレガシー改善、時短と心の解放

結果として、以前は毎月2時間近くかかっていた仕様変更への対応や確認作業が、今では約40分で終わるようになりました。時間が短縮されただけでなく、「どこを直せばいいか分からない」という精神的な苦痛から解放されたことが、何より大きな成果だと感じています。

必要であれば「Udemy – みんなのAI講座 ゼロからPythonで学ぶ人工知能と機械学習」のような教材で、詰まった部分だけ補強するのも良いかもしれません。

まず、完璧なコードを一度に目指す必要はありません。まずは大きな塊を分割し、あとは時間をかけて少しずつ磨いていけばいいのです。この継続的な改善プロセスこそ、非エンジニアがレガシーコードと戦うための現実的な武器になると確信しています。

なお、関連テーマとして「ExcelVBAからPythonへ！経理担当者が乗り換えて感じたメリット・デメリット」も後で見直すと、理解がつながりやすいですよ。

関連リンクとチェックリスト

学習サービスとアンケート