この記事は 「レガシー」を保守したり、刷新したりするにあたり得られた知見・ノウハウ・苦労話 by Works Human Intelligence Advent Calendar 2025 15 日目の記事です。
スクリプトを移行するのは想像以上に大変
皆さんはシステムやバッチの移行案件に携わったことはありますでしょうか。私もこれまでにさまざまな移行案件には関わってきたのですが、その中で感じたことは 「スクリプト/バッチの移行案件ほど甘くみるな」 ということです。
直近の移行案件で改めてこれを感じたので、まとめてみようと思います。
スクリプトほど設計や要件が曖昧になりやすいものはない
スクリプトというのは、作成された当時、ある要件や仕様を満たすために作成されたもののはずです。そのため、安定稼働しているスクリプトというのは、それを暗に満たしているということになります。
スクリプトの開発当初は開発担当者も存在し、仕様書や思想というのもある程度組織内で明確化されていると思うので、そこまでドキュメントが整備されていなくても運用は回ると思います。
ですが、これは基本、長続きしません。
担当者の異動や離職による雑な引き継ぎであったり、エンハンスという名目での仕様外の改変などにより、あれよあれよと情報が陳腐化していきます。
よって、実際に JP1 のようなスパゲッティコード化したバッチ群における各スクリプトが、どのような思想・設計で作成されたものかが不明瞭になり、保守も大変で工数負荷となるからとリプレイス話が持ち上がり、そしてリプレイスする側が辛い思いをするというわけです。
未来の後輩に辛い思いをさせないために今の私たちがやるべきこと
そんなことを経験したからこそ、未来の後輩に辛い思いをさせないために、自分たちは同じ轍を踏ませないようにする必要があります。
つまり、誰でも今日からできる最低限のことをやりましょう、ということです。
コードは全部 Git 管理する
現在の最新のコードは絶対に Git で稼働環境とは別で見える化するべきです。GitHub Enterprise Cloud が使えるなら良し、使えないなら GitLab ないし何かしらの Git 製品を（心を強く持って）導入しましょう。
「本番環境のソース見てデバックしないとわかりません」
これが一番無駄でパワーのかかる状態です。スクリプト系はこの状態になりやすい傾向があります。
絶対に Git 管理必須です。Git でソース管理をしておけば、最悪 GitHub Copilot などの生成 AI にコードを分析させることも用意です。
仕様はコードと同じ場所に保管し、テキスト形式で残す
コードに関する仕様などは、理想で言えばちゃんとドキュメント化することです。今は Marmaid.js なども利用できるので、Excel や Word などではなく、Markdown のフラットファイルで、テキスト形式でコードと同じ場所に保存することをお勧めします。
コードと同じ場所に存在しないドキュメントは、どうせ陳腐化します。検品などで必要な時もあるでしょうが、どうせ意味のないものになるくらいなら、src ディレクトリと別に docs ディレクトリを作るなどして、Markdown で仕様を書いておいた方がマシです。
javadoc のようなモノが書けるなら、あえて細かいことは javadoc に残し、無駄な読み物を増やさないのも手だと思います。（ただこれは賛否が分かれると思いますが...）
スクリプトでもテストコードは書いた方がいい
PowerShell などのようなスクリプト言語は、ユニットテストコードが書けないと勘違いされ気味です。それは正しくありません。
PowerShell の例で言うならば、Pester というユニットテスト用のモジュールがあります。
Bash でも Bats や ShellSpec といったものがあります。絶対にこれは組み込むべきです。むしろ、テストコードを先に書く習慣をつけるべきです。
動かしてみないとわからない = ケースを網羅できていないので、後々バグが見つかった際に、調査が難航します。最初からケースを想定/網羅できるよう、スクリプトでもテストコードはちゃんと書きましょう。
CI/CD から逃げるな
「スクリプトファイル一式を hogehoge ディレクトリにコピーで配置します」
このワード、最近は本当に嫌いです。スクリプト言語こそ、CI/CD をやりましょう。IaC も含めてやれるとなお良しです。
GitHub や GitLab でソースコードを管理できているなら、CI/CD も IaC もあと一手間加えるだけです。ソースコードの最新状態を常に保証できる場を設けましょう。
実行環境のコードはレプリカで、マスターコードは Git である文化を作りましょう。
例えば、PowerShell をクラウド上で実行するにあたっても、クラウドリソースの IaC、クラウドリソースへのコード配布は CI/CD で実行するべきです。そしてこれは Terraform や各種 CLI を使用すれば絶対に実現できるはずです。
リファクタリングするならコードの品質を担保できる環境を先に整える
スクリプト言語は、他と比べると比較的入門ハードルが低く、誰でもとっつきやすい性質があると思っています。それゆえに、人のコードを見るのは正直憂鬱になりがちです。
PowerShell で言うなら、外出しされるべき汎用コードは [CmdletBinding] がある param、begin-process-end でのコーディングをされているか、などの部分も気になったらキリがありません。
テストコードがない事例を多く見かけるスクリプト言語の場合、かなり開発者の思想が出る（と思っている）ので、すぐにリファクタリングをしたくなりがちです。
ただ、安定しているスクリプト言語の場合、リファクタリングをしてしまったことによって、当初はカバーできていた内容をロストしてしまい、結局裏目に出ることもあるでしょう。
要は、これまでに述べてきたテストコードや CI/CD ができる環境を整備できていない限りは、先にコードへ手をつけると言うのは避けるべきだと私は感じでいます。
結局、やっていることはアプリ開発と一緒
スクリプト言語、（これは個人的な偏見も大きいですが）アプリケーションより軽く見られがちだと思っています。特に、IT スキルもないのにスクリプトってワードだけは知っているビジネスユーザーやマネジメント層に多いイメージ...じゃあ自分でやってみろよ、とは口が裂けても言えないですよね。
じゃあもう自分でできることをしれっとやって、周りを幸せにしてあげるしかないと思っています。縁の下の力持ちではないですが、スクリプト言語の開発でも他と同じように向き合い、後に禍根を残さない形にすることこそ、エンジニアとしての綺麗な立ち振る舞いだと思っているということで締めたいと思います。