はじめに
アソビューAdvent Calendar 2025の22日目（表面）です。
こんにちは。アソビューで精算業務システムを担当しているアズマです。アソビューでは、契約パートナー様の電子チケットの販売やアクティビティの予約を扱います。チケットの購入やアクティビティの予約はアソビューを通じて行われるため、パートナー様へは月に1度精算を行います。現在わたしはこの精算業務のシステムを保守開発していますが、パートナー様からの精算関連のお問い合わせや、社内からのシステムへの問い合わせも受けています。
例えば「システムからの出力結果がおかしいです」「完了画面が表示されたのに次の画面へ行くと表示されませんでした」のような表現で問い合わせをいただくことがありますし、「時々エラーが出る」など、再現性を特定するのが難しいこともあります。
今回はこれらの報告を受けて、解決するまでの手段の1つに「ただしく言語化する」が有効なのではないかと思い、本記事をまとめました。
言語化とは
言語化とは、頭の中にある曖昧な考えや理解を、他者に伝わる具体的な言葉に変換する作業です。これだけを聞くと「そんなの当たり前じゃないか」と思ってしまいそうです。しかし、実際はそう簡単ではありません。システム開発における「言語化」とは、頭の中で思い浮かんだことやシステムの仕様をそのまま説明するだけではなく、自分自身でまずシステムへの理解を深め、解決したいことを見極めて、その解決への道筋を明確にするプロセスなのだと思います。
言語化において工夫していること
ITエンジニアにとって、言語化はコードを書く能力と同じくらい重要なスキルです。技術的な知識があってもそれを適切に言葉にできなければ、チームで協力することも、クライアントの要望を正確に把握して実現することもままなりません。ここからは、私が普段の業務の中で、言語化をする際に工夫していることを述べていきます。
「あえて曖昧にしている」のか「放置されている」のかを明確にする
プロジェクトを進める中で、すべてを明確にしてから着手できることは残念ながら稀です。その中で何が曖昧でそれをそのまま進めてよいのか、それとも明確にすべきなのかを判断しないと最悪作り直しになるでしょう。 具体的に何を作るのかがイメージできていないならば「とりあえず作ってみて、使ってみてから具体的にしていきましょう」という選択もありますし、「ここを曖昧にしたまま進めると、そもそも作るべきものが違ってしまう」こともあります。 どちらを選ぶにしても、この判断を言語化してチームないしはユーザーに共有することで、後々のトラブルを防げます。
問題になっていることと解決に至るまでの手順は簡潔で正確に書いているか
システムの不具合や複雑な要件を説明する際、状況を整理して伝える能力が必要です。 発生した障害に関するお問い合わせや報告については、システムの利用状況や具体的な操作などが出揃っているとは限らないため、問題を整理して特定をしやすくするため、問い合わせを受けるメンバーには以下の内容をヒアリングしてもらうようチェック項目を設けています。
- どのシステムのどの画面を操作していたのか
- パートナー様の情報など、システム内のidがわかるなら共有してほしい
- 操作した時間はいつか
これらの内容がわかれば、
- 問題が発生しているシステムのどの箇所に問題が発生していそうか
- システム内のidから特定できるパートナーのデータに依る影響なのか
- リリースした時期との影響はあるか
が判断できます。
例えば「朝になると処理が進まずときどきエラーが出る」といった報告がありました。このままでは一体何が問題なのかを特定するにはあまりに漠然としていますから、前述のチェック項目をヒアリングしてシステムのログを調べてみると
「月末から月初にかけての夜間バッチ実行後は、翌日の朝にログインした場合、特定の権限を持つユーザーがアクセスすると500エラーが発生する」
と特定できました。これにより、特定の権限をもつユーザーが行っている処理によって、月初のバッチ処理の結果と相関してエラーを引き起こしていたことがわかりました。 複雑な状況ほど、時系列、条件、結果を整理して言語化しておけば、原因を正しく分析でき、対処にかかる時間も短くできますし、問題の一次報告も早くなります。
一次報告では以下を項目化しています。
- 問題のあったシステムやデータがあったか
- 起因となった操作は何か
- 解決するには何をするべきか
この調査結果は主語(何が)とおきた事象(問題が発生した内容と手順)、そして目的(どうなるべきか)を明確にしています。これを常に記載しておくことで、記述の過不足や読み違いを減らすことができました。
把握していること、把握できていないことを表現できたか
「分からない」と言うことは決して恥ずかしいことではなく、何が分かっていて、何が分かっていないかを正確に伝えることは、自身のタスク整理だけでなく、関わるチームへの課題整理にもなります。 例えば「データベースの接続設定は理解していますが、この環境での認証方式が把握できていません」と伝えられれば、チーム内で必要な情報がすぐに特定できて適切なサポートができます。 「分からない」と伝えるのは勇気が必要なことかもしれません。しかし全てを理解しているフリをして進めてしまい、そのまま解決方法がわからず後になって慌てることになります。知識の境界線を明確にすると、自身のタスク整理が正確にできるだけでなく、チームで仕事をする上でも非常に有効です。
言語化できれば、実現する道筋が完成する
言語化を上手にする方法の1つとして、課題や問題を構造化して整理する方法があります。この節では相手からの要求や、自分の話したいことをうまく構造化していく方法と例を紹介していきます。
迷ったらフォーマットを定める
何をどう書けばいいか分からないときは、フォーマットを決めてしまうのも一つの手段です。例えば何かの一覧データを表示する画面を作ろうとしたとき、なんとなくこんな感じの画面が作ってみたいという状態から、
- 作りたい画面のレイアウトを実装する
- データベースから必要な値を取得するクエリを実装する
- データベースから取得した値を画面へ渡す処理を実装する
- 画面の表示テストを行う
のように手順を明らかにしておくと、不足していることはないか、懸念しておくことはないか、を自分だけでなくチーム内でも確認ができるようになります。
さらには依頼側にも必要なタスクはこれだけあり、その規模の大小をより具体的に伝えることができるかもしれません。 実装の手順を言葉で説明できるということは、頭の中で設計ができあがっているとも言えます。逆にうまく説明できないタスクがあったときには、まだ理解が不十分で、潜在的な問題や課題が残っている可能性があります。
はじめから完璧な文章を書こうとするより、まず型に当てはめて書き出すことで、言語化するハードルは大きく下がるでしょう。
詳細に書いてあっても、前提がそもそも違っている場合もある
クライアントや上司から詳細なドキュメントが渡されたとしても、残念ながらそれが必ずしも実現したいことを表現しきれていないかもしれません。書かれている内容の前提条件や背景がはっきりせず、実際の状況と異なっていることもありえます。
例えば「既存のユーザーテーブルに新しいカラムを追加する」という、かなり技術的な要求がありました。しかし詳しく話を聞いてシステムで参照しているデータベースを調べてみると、実は別の関連テーブルを参照するだけで実現できることがわかり、新しいカラムを追加したいというよりは、別テーブルにあるユーザー関連情報を画面上に表示することでした。 このように要求された内容を文字通りに受け取るのではなく、その背景にある「実現したいこと」を理解すること、探求することが大切で、そのためにはシステムへの理解が欠かせません。
読み返すことを習慣づける
書いた直後は完璧に思えても、時間を置いて読み返すと、分かりにくい表現や論理の飛躍に気づくことがあります。 わたしが読み返すことを決めていることとしては、メールを送信する前、ドキュメントやソースコードをコミットした後、チケットを起票した後です。書いているときは完成することばかりに目が行きがちでしたが、いざ書いてみてから読み返すと案外間違いがあるもので、見直すことで、改めて見える不要な修正や文言が見つかることがたびたびあります。
なおこれは、先々の自分が読み返したときにもかなり有効です。「あの時、どんな判断があってこの変更をしたのか」が整理して的確に書かれていることは、ふと忘れていたその時の経緯や背景を思い出させるきっかけにもなるでしょう。
まとめ
言語化はエンジニアにとってコードと同じくらい成果物につながると思っています。相手の意図を汲み取って実現したいものを表現するには、複雑な状況を整理し、正確に伝えること、実現する内容を簡潔にすること、そのためにはできあがった成果物を読み返すことを忘れずに行うことが肝要です。 完璧な言語化は難しいかもしれません。しかし「伝わる言葉」を意識し続けることで、仕事が整理され、自分だけではなく、関係する人たちも仕事がしやすくなっていくのではないかと思います。
最後に
アソビュー株式会社では新しいメンバーを随時募集しております。ご興味がある方はお気軽にカジュアル面談へご応募ください。
