SESで設計書とコードがずれていたら｜確認済み・推定・未確認に分けて客先へ聞く文面

設計書には「入力必須」と書いてあるのに、コードを読むと空欄でも通る。保守案件で一度はぶつかる場面ですが、正しいのはどちらなのかを、自分で決めるわけにはいきません。

私はSESで5年ほど、4社の現場を経験しました。3社目の保守改善の約1年半では、この種のずれに何度も当たり、聞き方を間違えて手戻りにしたこともあります。今回は、ずれを見つけてから客先に質問し、設計書を直すところまでの進め方を、実体験を交えてお伝えします。

目次

1. SESで設計書とコードがずれていたときは、まずコードで確かめる
2. 設計書が古くなるのは、珍しいことではない
3. 質問の前にやる2つの確認
4. 確認済み・推定・未確認に分けて、メモにする
5. 推定を確認済みと書いて、書き直した失敗
6. メモはこの形で十分
7. 客先の窓口に聞く質問文の例文
8. 実際に送った文面の例
9. 返事は約半日で届き、実装が正だった
10. 設計書を直すのは誰の仕事か｜準委任の範囲と、直してよい範囲の確認
11. 契約の範囲は、依頼の範囲で決まる
12. 私の現場では、改修の範囲だけ直すことになっていた
13. 直す前に確認する項目
14. まとめ

SESで設計書とコードがずれていたときは、まずコードで確かめる

結論質問より先に、コードで「確認済み」の範囲を作ります。何を見て、どこまで分かったかを持たずに聞くと、窓口の担当者に調査を丸投げすることになるからです。

ここでは、設計書が古くなる理由を短く押さえたうえで、質問の前にコードで確かめる手順を見ていきます。入場直後の全体把握は別の記事に書いたので、ここではずれを見つけた後の確認だけを扱います。

関連記事SES 新しい現場についていけない最初の1か月｜入場後の立ち上がり方を週ごとに整理SESで新しい現場についていけないと焦る最初の1か月を、週ごとの動き方で整理します。権限待ちの過ごし方、仕様書が古い現場での把握…

設計書が古くなるのは、珍しいことではない

NTTデータは2013年のニュースリリースで、保守運用で改修が重なると設計書への反映漏れが起き、ソースと設計書が食い違う「不備」や、そもそも書かれていない「不足」の状態になると説明しています。長期間運用されたシステムほど顕著だとも書かれています（出典: NTTデータ 設計書リカバリーのニュースリリース）。

私の3社目も、まさにそうした現場でした。金融系のWebサイトを長く保守していて、フレームワークは古い作りのObjectWorksです。設計書とコードにずれがあること自体は、前提として受け入れるしかありません。

問題は、ずれを見つけた後に何をするかです。

質問の前にやる2つの確認

私が先にやるのは、次の2つです。どちらも、1時間かからない範囲に収めます。

1. 画面の文言でコードを検索する画面に出ているラベルやエラーメッセージで全文検索し、該当の処理に当たりをつけます。設計書の項目名ではなく、実際の画面の文言から入るのがコツです。
2. 1つの操作を入力から保存まで追う入力チェック、サーバー側の処理、DBへの保存の順に、実際の動きを読みます。設計書のどの行と食い違うかを、行単位で言える状態にします。

ここまでで分かるのは、「今のコードがどう動くか」だけです。なぜそう動くのか、設計書が間違いなのか実装が間違いなのかは、コードからは分かりません。

この区別が、次の章の分類につながります。

確認済み・推定・未確認に分けて、メモにする

結論調べて分かったことを、事実と推測と空白に分けて書きます。質問する側が何を知っていて何を知らないかを、相手に一目で伝えるためです。

コードを読んだ後は、頭の中の理解をそのまま質問にしないで、いったんメモにします。分け方は3つで、私の中では次のように決めていました。

推定を確認済みと書いて、書き直した失敗

入場して数か月のころ、私は推定を確認済みの欄に書いてしまったことがあります。調査結果表に「この項目は仕様として必須ではない」と書いてレビューに出したところ、レビュアーから聞かれました。

その指摘のとおりでした。コードの動きは確認済みですが、「仕様である」は推定です。表を書き直し、窓口への確認も1往復増えました。

見たことと、そう思ったことを、同じ欄に混ぜない。この癖をつけてから、レビューで同じ指摘を受けたことはありません。

メモはこの形で十分

実際に私が使っていたメモは、次の4行です。長い文章にはせず、項目ごとに短く書きます。

この4行がそろっていれば、質問文はほぼ書けたも同然です。

客先の窓口に聞く質問文の例文

結論質問文は、ずれの内容・確認済み・推定・聞きたいことの順で、5〜6行に収めます。窓口の担当者は、前提を読むだけで判断できる状態が一番返事が早いからです。

3社目では、利用部門への質問は連絡窓口のリーダーを経由する決まりでした。直接聞ける相手がいない現場は多いので、窓口の相手が忙しくても読める形を心がけました。質問をする相手づくりそのものは、別の記事で扱っています。

関連記事客先常駐で質問できない｜相談相手の作り方と聞き方の工夫客先常駐で質問できない・相談相手がいないと感じたら、質問をどこに置くかを決めると動きやすくなります。在宅中心の現場で隣席に声をか…

実際に送った文面の例

マイページの契約内容変更まわりの改修で、先ほどの「入力必須」のずれを見つけたときの質問文を、固有の名称を伏せて再現します。

ポイントは、最後の「影響」の一行です。この質問に答えないと何が止まるのかが書いてあると、後回しにされにくくなります。

返事は約半日で届き、実装が正だった

この質問の返事は、窓口のリーダーから約半日後に来ました。実装のほうが正で、過去に利用部門の要望で緩めた経緯があり、設計書の更新が漏れていた、という内容です。

もし確認済みと推定を分けずに「設計書が間違っていると思います」とだけ送っていたら、窓口の側で調べ直す手間が増えていたはずです。半日で済んだのは、聞く前に自分で確かめた範囲を示せたからだと私は見ています。

窓口経由の往復に半日かかる点は、保守のリリースが重くなる話の中でも触れています。

関連記事SESの保守改修でリリースが重い理由｜影響範囲調査は半日〜1日かかった現場SESの保守改修でリリースが重くなる理由を、保守改善約1年半の実体験で整理します。影響範囲調査のやり方、証跡とドキュメントの多さ…

設計書を直すのは誰の仕事か｜準委任の範囲と、直してよい範囲の確認

結論設計書を直してよいかは、技術の話ではなく、作業の範囲の話です。契約と作業指示で決まるので、自分で判断せず、窓口か自社の営業に確認します。

ずれの正体が分かると、次に「この設計書、直していいのか」という問題が出てきます。ここでは、私の現場での線の引き方と、確認する相手を整理します。

契約の範囲は、依頼の範囲で決まる

SESの多くは準委任契約で、客先から指示された作業を行うことが仕事の中心です。準委任と請負の違いは、別の記事にまとめています。

関連記事SESの準委任契約とは｜請負・派遣との違いと指揮命令・偽装請負の境目SESの準委任契約とは何か。請負・労働者派遣との違い、指揮命令と偽装請負の境目、履行割合型と成果完成型の違いを、契約書を見られな…

設計書の更新が、今回の作業に含まれているのか。それとも、頼まれてもいない設計書を勝手に直すことになるのか。ここは契約書や作業指示の書き方次第で、現場ごとに違います。契約書の中身は私の手元にはなかったので、窓口のリーダーに確認しました。

私の現場では、改修の範囲だけ直すことになっていた

3社目では、窓口のリーダーに聞いたうえで、次のように整理されました。

保守のリリースが重い話の記事にも書きましたが、小規模な改修でも設計書の更新に3時間ほどかかっていました。範囲外まで直し始めると、この時間がふくらみます。

範囲外のずれを勝手に直さないのは、手間の問題だけではありません。どの設計書が最新かを客先が管理しているのに、一部だけ私が書き換えると、版の整合が崩れるからです。

直す前に確認する項目

別の現場に移ったときも、同じ順で確認しておくと、後で揉めません。

答えが曖昧なら、窓口のリーダーか、自社の営業に聞くのが早いです。窓口に確認しにくい内容でも、自社の営業経由なら聞ける場合があります。

まとめ

設計書とコードのずれは、長く運用されているシステムでは起こるものです。見つけたときの動き方を型にしておくと、慌てずに済みます。

私が一番伝えたいのは、質問の質は、聞く前にどこまで自分で確かめたかで決まるということです。確認済みの範囲を示せば、窓口の担当者も判断しやすく、返事も早くなります。

次にずれを見つけたら、まず「確認済み・推定・未確認」の3行だけでも書いてみてください。それだけで、質問文の半分はできています。