システム構成を知らずに、改修を始めてはいけない

検索結果から、PDFを直接開けるようにする。

要件だけを見ると、リンクを一つ追加する、小さな改修に思えますよね。

検索結果の横にボタンを置き、クリックするとPDFが開く。画面だけを見れば、それほど複雑な機能には見えません。

でも、実際に変更しようとすると、確認しなければならないことがいくつも出てきます。

PDFはどこから配信するのか。リンク先のURLは、どの処理で作り、検索結果のどのデータへ追加するのか。URLを作れなかった場合、検索結果まで返らなくなってよいのか。既存の検索処理には影響しないのか。

小さく見える機能追加ほど、「どこへ一行足せばよいか」だけで考えてしまいがちです。

ところが、既存システムでは、その一行がどの処理につながり、どこへ影響するのかを知らなければ、安全な変更かどうかを判断できません。

今回の改修でも、最初に考えた実装方法は、そのまま採用されませんでした。

システム構成を調べ、処理経路を図にして、既存コードと実データを追う。さらに関係者へ確認した結果、より影響の小さい方法へ方針を変えています。

既存システムの改修で大切なのは、最初に思いついた方法を早く実装することではありません。

今のシステムが、どのように動いているのか。

そこを理解することから、改修は始まります。

最初の問題は、コードではなく構成を理解していなかったこと

今回の対象は、既存の文書検索システムでした。

ブラウザから検索条件を送り、検索結果を画面へ返す。その結果から、関連するPDFを直接開けるようにしたい。

担当者は、まずPDFを配信する方法を考えました。

ただ、調査を進める中で、システム全体の構成を十分に理解できていないことに気づきます。

Webサーバーとアプリケーションサーバーは、それぞれ何をしているのか。検索処理はどこで実行され、画面へ返るデータは、どの処理で作られているのか。PDFが置かれている共有ストレージと、ブラウザから見える公開領域は、どのようにつながっているのか。

言葉としては知っていても、このシステムの中で何を担当しているのかまでは見えていませんでした。

こういう場面、ありますよね。

既存システムを引き継ぐと、コードや設定ファイルは手元にあります。画面も動いていて、依頼された変更内容も分かる。

それでも、処理全体のつながりは、すぐには見えません。

ここで大切なのは、分からないことを能力不足として隠さないことです。

分からないまま変更へ進む方が、ずっと危険です。

担当者は実装を急がず、Webサーバー、アプリケーションサーバー、Webアプリケーション、ブラウザ、検索処理が、それぞれ何を担っているのかを調べ直しました。

「どこを直せば動くか」より先に、「今はどう動いているのか」を確認したのです。

ブラウザから検索結果が返るまでを図にする

調査した内容は、構成図に整理しました。

ブラウザから送られたリクエストをWebサーバーが受け取り、アプリケーションサーバーへ渡す。Webアプリケーションが処理先を決めて検索プログラムを実行し、その結果をJSON形式のデータへ変換する。データは、アプリケーションサーバーとWebサーバーを経由して、ブラウザへ返ります。

一方、PDFは共有ストレージに置かれているため、検索結果のデータとは別の経路で配信する必要があります。

文章だけで追っていると、分かったような気持ちになります。

でも、図にすると、「この処理はどこで行われているのか」「この変更はどこへ入れるべきか」が見えやすくなるんですよね。

構成図は、引き継ぎ資料をきれいに作るためだけのものではありません。

PDF配信をどの層で扱い、URL生成をどの処理へ置くのか。Webサーバーの設定を本当に変える必要があり、その変更が既存の検索処理へどのような影響を与えるのか。

そうした判断をするための地図になります。

今回も、図にしたことで、単に画面へリンクを追加するだけではないことが見えてきました。

画面へ表示する部分だけでなく、PDFの公開方法、URLの生成、検索結果データへの追加、エラー時の挙動まで考えなければなりません。

小さく見えた改修が、システムのどの層に関係しているのか。

そこが初めて整理されました。

最初に考えたのは、Webサーバーの設定変更だった

PDFをブラウザから開けるようにするため、最初に検討したのは、Webサーバーへ新しい配信設定を追加する方法でした。

共有ストレージ上のPDFを公開できるよう、設定ファイルへ新しい記述を加える。技術的には、実現できそうな案です。

ただ、すぐには変更しませんでした。

設定ファイルのどこへ追加し、変更後にWebサーバーを再読み込みしてよいのか。公開範囲やアクセス権限へどのような影響が出るのか。既存の配信設定と競合しないのか。

そこまで含めて答えられる状態ではなかったからです。

「設定を追加すれば動きそう」と、「本番環境で安全に変更できる」は同じではありませんよね。

技術的に実現できる方法があっても、既存機能への影響を説明できなければ、そのまま変更へ進むことはできません。

担当者は、現在の構成と検討している変更案を整理した上で、確認したい設定箇所、再読み込みの影響、アクセス権限に関する懸念を文面にし、プロジェクト責任者やインフラ担当、前任者へ確認しました。

質問するときに、「どうすればよいですか」だけでは、相手も答えにくいものです。

自分で調べた構成と、考えた案と、判断できない点を分けて伝える。

そうすることで、関係者も、どこを確認すればよいか分かります。

前任者への確認で、設定変更をやめた

確認を進める中で、Webサーバーの設定を変更しなくても、PDFを公開できる方法があることが分かりました。

既存の公開領域から共有ストレージへ、シンボリックリンクを設ける方法です。

今回の環境では、すでにある構成を利用することで、新しい配信設定を追加せずにPDFへ到達できる可能性がありました。

Webサーバーの設定を変えれば、アクセス権限などへ影響することも考えられます。

そこで、当初検討していた設定ファイルの変更と設定の再読み込みは行わず、既存構成を利用する方針へ変更しました。

ここで大切なのは、「前任者に聞いたら、答えを教えてもらえた」ということではありません。

前任者の知見は、担当者が行う調査の代わりではありませんでした。

担当者自身が構成を調べ、変更案を作り、不明点とリスクを言葉にする。その上で、過去の運用判断や既存環境の知見と照らし合わせています。

最初の案をやめると、手戻りに見えることがありますよね。

せっかく考えた方法を捨てた。調査に時間がかかり、早く実装へ入れなかった。

でも、実装する前に方針を変えられたなら、それは無駄ではありません。

影響の大きい変更を行った後で戻すより、構成を調べた段階で、より小さい変更へ切り替えた方がよい。

最初の案に固執せず、既存環境に合わせて方法を変えることも、改修の仕事です。

変更を小さくするとは、コードを短くすることではない

PDFの配信方法が決まった後は、検索結果へURLを追加する処理を調べました。

検索結果の画面は、一つのデータだけで作られていたわけではありません。複数の処理が作った情報を組み合わせ、画面へ表示しています。

当初考えていたURLの追加先も、調査を進めると適切ではないことが分かりました。

そこで、検索結果がどのように作られているのかを、もう一度追います。

PDFのURLはどの処理で生成し、どのデータへ持たせるのか。フロントエンドは、どの情報を使ってリンクを表示するのか。

それぞれの責務を整理した結果、バックエンド側はURLをデータとして渡し、フロントエンド側は表示位置とリンクの作り方を担う方針にしました。

バックエンド側では、修正する対象も限定できました。

ただ、「一つのファイルだけを変更したから安全」という話ではありません。

変更範囲を小さくするとは、修正行数やファイル数を減らすことだけではないんですよね。

新しい機能のために、どこを変更し、どこには触れないのか。どの責務を変えるのかを説明でき、既存処理への波及を抑えられているか。

そこまで整理されれば、レビューする範囲が明確になり、テスト範囲も決めやすくなります。問題が起きたときにも、変更箇所を追いやすくなります。

コードが短くても、複数の機能へ影響する変更はあります。

反対に、修正箇所が複数あっても、役割と影響範囲が明確なら、確認しやすいこともあります。

見るべきなのは、変更量の少なさではなく、影響を説明できるかどうかです。

PDFリンクを作れなくても、検索結果は返したい

実装案を検討する際には、生成AIも補助として利用しました。

コード案を考えたり、処理の形を整理したりする上では役に立ちます。

ただ、生成AIは、対象システムの既存コードや実データ、運用上の優先順位をすべて理解しているわけではありません。

初期案を確認すると、PDFのURL生成に失敗した場合、検索結果全体がエラーになる可能性がありました。また、想定した場所にPDFがなければ、別のファイルを誤って参照する可能性も見つかりました。

PDFリンクは、既存の検索結果へ追加する機能です。

そのリンクを作れなかったからといって、すでに動いている検索結果まで返らなくなってよいのでしょうか。

それは違いますよね。

そこで、URLの初期状態を空にし、検索結果ごとに例外を処理するようにしました。URL生成に失敗しても検索結果自体は返し、PDFではないデータにはURLを付けません。

追加機能の失敗を、既存機能へ波及させない設計へ修正しました。

生成AIが出した案を、そのまま使わなかったからといって、生成AIが役に立たなかったわけではありません。

案を作る時間を短くし、検討の出発点を用意することはできます。

ただ、その案が既存環境でどう動くのか。データが欠けたときに何が起き、中核機能へ影響しないか。

そこを確認し、必要に応じて直すのは人の仕事です。

生成AIを使うかどうかより、出てきた案を、どの前提と照らし合わせて検証するかが問われます。

調査で見つけた問題を、すべて今回直すわけではない

改修後の出力を確認すると、PDFのページ番号が空になっていました。

検索結果からPDFを開くだけでなく、該当するページへ直接移動できれば、利用者には便利です。

では、その機能も今回追加すればよいのでしょうか。

原因を調べると、既存処理は、特定のファイル名形式からページ番号を取得する前提になっていました。

ところが、実際に使われているPDFの形式は、その前提と一致していません。元のデータにも、必要なページ番号が含まれていませんでした。

コードを少し直せば済む問題ではありません。

ページを指定するには、元データをどう持ち、どの処理で抽出するのか。既存データはどう扱うのかまで考える必要があります。

そこで、PDF内の該当ページへ直接移動する機能は、今回の改修範囲には含めないと判断しました。

調査で問題を見つけることと、今回の変更へ含めることは別です。

見つけたものをすべて直そうとすると、改修範囲は広がり続けます。

要件は何か。対応に必要なデータがあり、どこへ影響するのか。どの範囲をテストし直す必要があるのか。

そこを確認し、今回対応するものと、別の課題として扱うものを分けます。

「範囲外だから見なかった」のではありません。

原因を把握し、必要な対応を整理した上で、今回の責任範囲を決めました。

直さない判断にも、調査が必要です。

テストで見るのは、リンクが開くことだけではない

実装後には、単体テストと結合テスト、自動テストを行いました。

単体テストでは32ケース、結合テストでは11ケースを確認し、pytestでは19のテスト関数を作成しています。

これらの数字は、単純に合計して品質を示せるものではありません。

テストの数が多いから、安全だと証明できるわけでもありませんよね。

大切なのは、何を確認したかです。

PDFのURLを正常に生成できるか。PDFではないデータへ誤ってURLを付けていないか。必要な情報が欠けた場合やURL生成に失敗した場合にも、検索結果は返るのか。

さらに、複数の処理を経由して画面表示まで正しくつながり、既存の検索結果へ影響していないかも確認しました。

今回追加した機能が動くことだけでなく、追加機能が動かなかったときにも、既存機能を守れるかを見ています。

新しいリンクが表示できれば、正常系としては成功です。

でも、既存システムの改修では、それだけでは足りません。

データが想定どおりではない場合や、ファイルが見つからない場合。PDF以外の結果が返ったり、途中の処理で例外が起きたりした場合にも、既存の検索を続けられるかを見る必要があります。

追加した機能の確認と、既存機能を壊していないことの確認。

その両方が、改修後のテストになります。

改修前に必要なのは、変更方法より現状理解

既存システムへ機能を追加するとき、実装案を早く出すことが正解とは限りません。

今回も、最初に考えたのはWebサーバーの設定を変更する方法でした。

でも、そのまま実装しませんでした。

現在の構成を調べ、ブラウザから検索結果が返るまでの処理を図にする。PDFがどこにあり、どの経路で配信できるのかを確認し、既存コードとデータの生成過程を追う。

さらに、不明点とリスクを整理して、関係者や前任者へ確認した結果、既存構成を利用する、より影響の小さい方法へ方針を変えました。

実装では変更する責務を分け、修正対象を限定しています。追加機能の失敗で既存検索を止めないよう、異常時の挙動も見直しました。

実データで前提の違いを見つけたときには、すべてを今回の変更へ含めず、改修範囲を切り分けています。最後に、正常系だけでなく、異常系と既存機能への影響までテストしました。

一つひとつを見ると、実装前の準備や確認作業に見えるかもしれません。

でも、どこを変えるかは、現在の構成を知らなければ決められません。

どこを変えないかも、同じです。

既存システムの改修では、何を追加するかより先に、今どのように動いているのかを理解する必要があります。

システム構成を知ることは、実装前の準備ではありません。

どこを変え、どこを変えないかを決め、既存システムを壊さずに前へ進めるための、改修そのものです。

既存システムを理解してから、変更する

ディーシステムでは、新しい機能を早く追加することだけではなく、既存システムがどのように動いているのかを理解し、影響を確認しながら変更することを大切にしています。

分からないことを調べて構成を図にし、関係者へ確認する。最初の案より影響の小さい方法が見つかれば、実装前でも方針を変える。

そうした判断も、既存システムを支えるエンジニアの仕事です。

ディーシステムの技術支援や、エンジニアの仕事については、サービス情報・採用情報でも紹介しています。

次に読む記事

生成AIの修正案を、どのように検証したのか

生成AIは、コード案や処理のたたき台を短時間で作れます。

ただし、対象システムの構成や実データ、既存機能で守るべき条件まで理解しているわけではありません。

この改修で生成AIの案をどのように確認し、既存の検索機能へ影響させない形へ修正したのかを紹介します。

分からなかったシステムを、説明できるまでの成長

今回の担当者は、最初からシステム全体を理解していたわけではありません。

基本用語を調べ、処理の流れを図にし、自分の案と不明点を整理して関係者へ確認する。その過程で、分からなかったシステムを、改修判断に使える形で説明できるようになりました。

同じ案件を、担当者の成長という視点から紹介します。

障害調査では、最初に何を確認するのか

既存システムを安全に変更するには、構成や処理経路を理解するだけでなく、問題が起きたときに事実を切り分ける力も必要です。

ログを読み始める前に、まず現象が再現するかを確認する理由と、障害調査の進め方を紹介します。