現場から見えた成長の瞬間 #05｜分からなかったシステムを、図にして説明できるまで

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

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

画面にリンクを表示し、押すとPDFが開く。そこだけを見れば、それほど複雑な仕事には見えません。

でも、既存システムを変更するとなると、話は少し変わります。

PDFはどこに置かれていて、ブラウザからどの経路でアクセスするのか。URLはどの処理で作り、どこを変更すると、すでに動いている検索機能へ影響するのか。

今回、この改修を担当したエンジニアは、最初からすべてを説明できたわけではありませんでした。

対象となるシステムがどのような構成で動き、Webサーバーやアプリケーションサーバーが、それぞれ何をしているのか。

まだ、十分には見えていなかったのです。

そこで、分からないままコードや設定を触るのではなく、システムの仕組みから調べ直しました。

技術用語を確認し、ブラウザから検索結果が返るまでの流れを追って、処理を図にする。その上で、自分の改修案と判断できない点を整理し、関係者へ説明しました。

そこで得た知見をもとに、最初に考えていた案も変えています。

今回見えた成長は、知らなかった用語を覚えたことだけではありません。

分からなかったシステムを、他者へ説明し、実際の改修判断へ使える対象に変えていったことでした。

Webサーバーとアプリケーションサーバーの違いから調べた

改修を考え始めたとき、本人は対象システムの全体像を、まだ十分には説明できませんでした。

Webサーバーとアプリケーションサーバーについても、最初は物理的なサーバーそのものとして捉えていたといいます。

この理解のままでも、検索して設定例を見つけることはできます。生成AIへ聞けば、コードや設定案も出てきます。

でも、その案を自分のシステムへ入れてよいかは、判断できませんよね。

そこで、Webサーバー、アプリケーションサーバー、Webアプリケーション、API、HTTP、常駐プロセス、サービス管理といった基本的な要素から調べ直しました。

実際の環境で使われているソフトウェアについても、ブラウザからのリクエストを受けるもの、アプリケーションへ処理を渡すもの、プログラムを実行するもの、検索結果を画面へ返すものとして、それぞれの役割を確認しました。

用語を暗記するのではなく、このシステムの中で何を担っているのかを整理していったのです。

成長の出発点は、知らない用語があったことではありません。

改修方法を考える中で、自分がシステム全体の動きを説明できないと気づいたことでした。

そのまま進めず、基本へ戻った。

ここが、最初の変化だったのだと思います。

ブラウザから結果が返るまでを図にした

用語を一つずつ調べても、システム全体の動きは、まだ見えにくいものです。

知識が点のままだからです。

そこで本人は、ブラウザから検索結果が返るまでの流れを、構成図にしました。

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

文章で読むと、分かったような気持ちになりますよね。

でも、図にしようとすると、曖昧な部分で手が止まります。

この二つは、どのようにつながっているのか。ここでは、どの処理が動き、データはどこで形を変えているのか。

自分で線を引こうとすることで、理解できている部分と、まだ説明できない部分が分かれます。

本人は、アプリケーションサーバーとWebアプリケーションの関係についても、別の物理サーバー同士が通信しているようなイメージから、ソフトウェアと処理の役割として捉え直しました。

図が完成したこと自体が、成果だったわけではありません。

その図を使ってシステムの動きを説明し、自分の理解から抜けている部分を見つけられるようになったこと。

そこに変化があります。

点だった知識が、一つの処理の流れとしてつながっていきました。

図が、改修の確認項目へ変わった

構成図を作ると、次に確認すべきことも見えてきました。

PDFはどこに保存され、ブラウザはどの経路でアクセスするのか。URLはバックエンドで作るのか。画面側は、どの情報を受け取ればリンクを表示できるのか。

さらに、Webサーバーの設定を本当に変更する必要があるのか、PDFリンクを作れなかった場合に既存の検索結果をどう扱うのかも考える必要があります。

構成を理解する前は、「PDFを表示するには、どこを直せばよいか」を部分的に考えていました。

図にした後は、「この変更はどの処理へ入り、どこへ影響するのか」を考えられるようになります。

ここは、大きな違いですよね。

図は、引き継ぎのための資料ではありませんでした。

変更箇所を決めるための道具になったのです。

説明できる理解が、問いを作れる理解へ変わった。

「分かるようになった」という言葉だけでは見えにくい成長が、ここにあります。

自分の案を持って、関係者へ確認した

本人が最初に考えたのは、Webサーバーの設定を変更して、PDFを配信する方法でした。

技術的には、実現できそうな案です。

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

どの設定を変え、何を実現しようとしているのか。設定を反映するための操作をしてよいのか。アクセス権限や既存機能へ、どのような影響があり得るのか。

さらに、自分ではどこまで判断できていないのかも整理し、プロジェクト責任者、インフラ担当、前任者へ文面で確認しました。

「分からないので、教えてください」と聞くだけなら、相手も何から説明すればよいか迷います。

本人が行ったのは、答えを求めるだけの質問ではありません。

自分なりの案を作り、その前提と不明点、懸念を分けて、相手が判断できる確認事項へ変えました。

技術的な疑問を、関係者と話せる形にしたのです。

自分で考えることと、人へ聞くことは、反対ではないんですよね。

何も考えずに答えを求めるのではなく、自分の理解と仮説を持って相談する。

その方が、相手の説明も理解しやすくなります。

前任者の知見を受け、最初の案を変えた

関係者へ確認した結果、Webサーバーの設定を変更しなくても、PDFを配信できる方法があることが分かりました。

既存の公開領域と共有ストレージをつなぐ、現在の構成を利用する方法です。

今回の環境では、新しい設定を追加するよりも、既存構成を使う方が影響を抑えられると判断されました。

そこで本人は、当初考えていたWebサーバー設定の変更と、設定の再読み込みを行わない方針へ変えます。

最初の案を変えると、「考えたことが無駄になった」と感じることもありますよね。

でも、今回のケースでは違います。

自分で構成を調べ、案を作っていたからこそ、前任者から別の方法を聞いたときに、その意味を理解できました。

なぜ設定変更をしなくてよいのか。既存構成を使うことで、なぜ影響を抑えられるのか。

自分が考えた案と比較しながら、判断を更新できたのです。

正解を教わったのではありません。

新しい知見を受けて、自分の判断を変えました。

最初の案へ固執せず、より適切な方法へ切り替える。

それも、エンジニアの判断力の一つです。

構成を理解すると、触らなくてよい場所が見えてくる

次に確認したのは、PDFのURLを、検索結果のどのデータへ追加するかでした。

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

本人は、コードとデータの流れを追いました。

ファイル名やフォルダ名はどこから来て、検索結果はどの単位で作られるのか。画面表示用の情報は、どの処理で組み立てられ、バックエンドとフロントエンドは、それぞれ何を担当しているのか。

その結果、バックエンド側はPDFのURLを渡し、フロントエンド側は表示位置とリンクの作り方を担う方針へ整理しました。

ほかの検索プログラムは変更せず、バックエンド側の修正対象も限定できる見込みが立ちました。

構成理解が深まったことで、変更できる場所が増えたわけではありません。

むしろ、触らなくてよい場所を判断できるようになりました。

これは、実装できる範囲が広がることとは、少し違う成長です。

システム全体を見て、変更する場所と、変更しない場所の境界を決める。

既存システムの改修では、この判断が欠かせません。

AIの提案を、システムに合う形へ直した

実装案を考える過程では、生成AIも使いました。

本人が作成した仕様を生成AIへ渡し、修正案のたたき台を作らせます。さらに、別の生成AIにも仕様と修正案を渡し、レビューさせました。

AIを使えば、コード案は早く得られます。

でも、案が出てきたことと、そのまま採用できることは別ですよね。

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

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

リンクを作れなかったからといって、検索結果まで返らなくなるのは避けたい。

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

生成AIを使えたことが、今回の成長の中心ではありません。

本人がシステムの構成やデータの流れを理解していたからこそ、AIの案を評価できたことに意味があります。

AIから答えを受け取る側から、その答えがシステムに合っているかを判断する側へ進んでいました。

見つけた問題を、すべて直さない判断

改修後の出力を確認すると、PDFのページ番号を取得できていないことが分かりました。

リンクを開いたとき、PDFの該当ページへ直接移動できれば便利です。

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

本人は、まず原因を調べました。

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

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

つまり、少しコードを書き換えれば済む話ではありません。

元データをどう持ち、どの処理でページ番号を作るのか。既存データをどう扱うのかまで検討する必要があります。

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

成長とは、見つけた問題をすべて自分で解決できるようになることではありません。

原因と影響を調べ、今対応することと、今回対応しないことを分ける。

自分が担う責任の境界を決めることも、仕事の一部です。

説明できる理解を、テストできる理解へ

改修後は、単体テスト、結合テスト、自動テストを作成しました。

確認したのは、PDFリンクが正常に表示される場合だけではありません。

PDFではないデータや、必要な情報が欠けている場合にも正しく動くか。URL生成に失敗しても検索結果自体は返り、既存の検索結果へ影響しないかも確認しました。

構成とデータの流れを理解したからこそ、どの条件で何が起こるかを、テストケースへ変えられました。

通常の処理を説明できるだけなら、「この順番で動きます」と言えます。

異常時まで考えられるようになると、

「この情報がなければ、ここでURLを作れない」

「その場合でも、検索結果は返す」

「PDF以外にはリンクを付けない」

と、条件が崩れたときの動作も予測できます。

説明できる理解が、テストできる理解へ進んだのです。

テスト数が多いこと自体が、成長の証明ではありません。

何を守るべきかを考え、その条件を確認できる形へ落とし込んだことに意味があります。

成長は、分からないことがなくなることではない

現場では、最初からすべてを理解して仕事を始められるとは限りません。

経験のない技術を扱うこともあれば、引き継いだ既存システムに、十分な資料がないこともあります。

大切なのは、分からないことがあるかどうかではないんですよね。

自分が説明できない部分を認識し、基本から調べて、処理の流れを図にする。自分の案と不明点を整理して関係者へ説明し、得られた知見によって、最初の案を変える。

さらに、変更する場所と変更しない場所を決め、AIの案も既存システムへ照らして確認する。理解した内容を、最後はテストへ変えていく。

今回見えた成長は、Webサーバーやアプリケーションサーバーの名称を覚えたことだけではありません。

説明できなかったシステムを図にし、その図を使って質問を作り、関係者と判断し、改修範囲を決められるようになったことでした。

知らない技術を覚えた社員ではなく、未知のシステムを、自分で扱える対象へ変えていったエンジニア。

現場から見えたのは、そんな変化です。

成長とは、知らない技術がなくなることではありません。分からないことに出会ったとき、仕組みを調べ、他者へ説明できる形にし、仕事の判断へ変えられるようになることです。

分からないことを、次の判断へ変える

ディーシステムでは、最初からすべてを知っていることだけを、エンジニアの力とは考えていません。

分からないことを調べ、構成を整理し、自分の案を持って周囲へ相談する。得られた知見をもとに判断を変え、最後はテストで確かめる。

そうした仕事の積み重ねが、次に担える役割を広げていきます。

ディーシステムで働くエンジニアの仕事や、現場での成長については、採用情報でも紹介しています。

次に読む記事

同じ改修で、なぜシステム構成から確認したのか

分からなかったシステムを図にして説明できるようになった背景には、実際の改修判断があります。

対象システムの構成、処理経路、既存コード、実データを確認し、当初案より影響の小さい方法を選ぶまでの過程を紹介します。

生成AIの修正案を、人はどこまで確認したのか

この改修では、生成AIにも修正案を作らせました。

ただし、生成されたコードをそのまま採用したわけではありません。既存機能への影響やデータの扱いを人が確認し、実際のシステムで使える形へ修正した過程を紹介します。

日々の仕事は、将来の判断力へどうつながるのか

システム構成を調べ、分からない点を整理し、関係者へ確認する力は、突然身につくものではありません。

テスト、データ確認、議事録、問い合わせ対応など、最初に任されることの多い仕事が、将来の判断力や説明力へどうつながるのかを考えます。

未経験の若手は、どうやって考えて動けるようになるのか

未経験で入社した社員に、最初から一人で正しい判断を求めることはできません。

指示された作業を行う段階から、自分で調べ、状況を整理し、相談や提案ができるようになるまでに、どのような経験とフィードバックが必要なのかを紹介します。