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の型ヒントは難しく感じるかもしれないが、コメントなら簡単です。

次に、“`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へ！経理担当者が乗り換えて感じたメリット・デメリット」も後で見直すと。理解がつながりやすい。

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

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