この記事は、開運冬まつり2026 Day1セッションのQAエンジニアレーンで発表されたLTをブログ形式にして発信しているものです。
2026春QAエンジニアリレーブログの5本目の記事となります。
こんにちは、サイボウズでQAエンジニアをしている森長です。
グループウェア製品Garoonを担当するSpicaチームに所属しています。私たちのチームは新機能の開発はしておらず、テスト以外の観点でプロダクトの品質に貢献することをミッションとしています。 具体的には、リリースプロセス改善、ドキュメント整備、不具合改修のハンドリングなどを担当しています。
「Why を残しましょう」と言いながら、自分も忙しさに流されてサボってしまうことがあるので、自戒を込めてこの発表をしました。
「なぜそうなっているのか」、分かりますか？
コードや仕様書を見たとき、「何をしているか（What）」は書いてあるが、「なぜそうしたのか（Why）」が書いていない。 そんな経験はないでしょうか。
Garoonは長年にわたって運用されてきた製品なので、「これは仕様ですか？それとも不具合ですか？」という問い合わせを頻繁に受けます。このような問い合わせに答えるのは私のチームの仕事です。その中で「Whyが残っていたら嬉しいのにな」と思うことがよくあります。
日々おこなわれる「考古学」
問い合わせを受けて仕様書やヘルプサイトを見れば、そこに書いてあることをもとに「仕様です」と答えられることも多いです。しかし私たちが大事にしているのは、「その仕様は今見ても正しいのか」を考えることです。仕様書に書いてあるから正しい、長年こうだったから正しい、ではなく、ユーザーにとって使いやすいか、今の観点から見て改善できないかを常に考えています。
そのために、まるで考古学のように、以下のことをやっています。
- 古い仕様書をさかのぼる
- 過去のやりとりや議事録を掘り起こす
- 類似機能や他社製品と比較する
これは、問い合わせの挙動を仕様であると明記しているところがあるかどうかを探すだけの調査ではありません。未来をより良くするために、手がかりになる過去の「Why」を探します。「なぜそうなっていたのか」が分かれば、「今もその理由は有効か」「変えるとしたら何を考慮すべきか」を議論できます。
しかし時間をかけて調べても、当時の意図にたどり着けないことも珍しくありません。仕様書には「〜は不可」と書いてあっても、「なぜ不可なのか」が書かれていないケースがあるからです。
「Why」がないと判断しにくい例
架空の CMS（記事や投稿を管理するシステム）の記事管理機能を例に、「Why」がないと判断に迷うケースを考えてみましょう。
あるCMSでは、「下書き」「公開済み」の記事は、一覧画面での一括削除・記事詳細画面での個別削除のどちらもできます。ところが「予約公開待ち」の記事だけは、一括削除ができず個別削除しかできません。仕様書には「予約公開待ち：一括削除不可」とだけ書かれています。なぜ不可なのかは書かれていません。
- 誤って大量の予約投稿を消してしまわないよう、1件ずつ確認させたかったのか？
- 当時は何らかの技術的な制約があったのか？
「予約公開待ちの記事も一括削除できた方が便利なのでは？」と感じても、Why が分からない以上、「直すべきなのか」「あえて残すべきなのか」を判断する材料がありません。特に影響範囲が広い機能であれば、根拠なく「とりあえず直そう」という判断もとりにくいです。もし当時決定した仕様の理由が残っていれば、「その制約は今も有効か」を判断できたはずですし、改善に踏み切る根拠にもなりえると思います。
「Why」がないと、改善の機会を逃す
「仕様かどうか」は仕様書やヘルプサイトを見れば分かります。しかし「直していいのか」という判断や、ユーザーへの説明に必要な根拠は、その背景にある「なぜそうなっているか」がなければ答えられません。
「当時の意図」は、その場にいた人の頭の中にしかありません。コードや実際の挙動からは読み取れず、時間が経てばその人も忘れてしまいます。一見おかしな挙動でも、「あえてそうしている」理由があることは多々あります。技術的な制約、業務ルール、当時のユーザー要望など…それらが分かれば、「今も同じ制約があるのか」「状況が変わったなら直せるのではないか」という議論ができます。しかし Why が失われていると、現状を変えることへの心理的ハードルが上がってしまいます。
「Why」を残す、3つの始め方
「ちゃんとした理由書を書こう」と思うと重く感じてしまいますが、完璧なドキュメントでなくて構いません。私が実践しやすいと感じている方法を3つ紹介します。
1. リンクを貼るだけでもOK
議論したSlackのスレッド、議事録、Issueのリンクを仕様書や Pull Request の説明欄に貼るだけで十分です。「なぜか」のコンテキストが参照できる場所を示しておくだけで、未来の調査コストは大きく変わります。
2. テンプレートに「背景」欄を作る
要件定義書や設計書のテンプレートに「背景・理由」欄を設けると、書かざるを得ない仕組みになります。「フォーマットがあるから書く」という状況は、個人の意識に頼るより確実です。
「Architecture Decision Record（ADR）」というプラクティスをご存じでしょうか？設計の意思決定について、「背景」「検討した選択肢」「決定」「その結果」といった形式で短く残すものです。テンプレートの一例として参考になります。
3. 「理由なし」と書く
「特になし（なんとなくそうした）」という記録も、立派な情報です。理由がないなら、仕様を変えても問題ないか、と判断できます。
まとめ：ドキュメントは未来のチームのために
書いたドキュメントは、何年も経ってから見返されることのほうが多いと日々感じております。今日残した一行の「Why」が、数年後の自分や、チームメンバーを救うかもしれません。
また、最近業務でAIを使う機会が増えるなかで、改めて感じているのが「AIはコンテキストを持たない」ということです。セッションをまたぐと、多くのAIツールではそれまでの会話の文脈がリセットされます。「なぜこの実装になっているのか」「当時どんな議論があったのか」そういった背景をAIに伝えるには、どこかにドキュメントとして残っている必要があります。
JaSST'26 Tokyoの基調講演では「AIにとってはドキュメントが全て」という発言もあり、他の講演でもAIへコンテキストを渡すことの重要性が語られていました。AIを活用するためにも、コンテキストを渡す手段としてのドキュメントの重要性はこれからますます高まると感じています。
最後に、発表・ブログ執筆にあたって QA外部コネクトチーム（社外登壇支援などを行っているチーム）に大変お世話になりました！ありがとうございました！
2026春QAエンジニアリレーブログ、次回もぜひ読んでくださると嬉しいです！
