解釈違いバグを防ぐ用語集の作り方

「それ、同じ意味で言ってます?」が仕様崩壊の入り口

要件定義のミーティングで「ユーザー」「承認」「有効」といった言葉が飛び交う。PM は「有効」を「決済が完了した状態」の意味で使い、エンジニアは「アカウントが凍結されていない状態」だと思って実装する。どちらも仕様書に書かれた言葉としては正しいのに、指している状態が違う。結果、レビューは通ったのに、リリース後に「有効なユーザーなのに機能が使えない」という報告が来る。

この種のバグは実装ミスではない。要件定義の時点で言葉の意味をすり合わせていなかったことが原因で、コードレビューでもテストでも見つからない。テストケース自体が「間違った定義」を前提に書かれているからだ。

用語集に入れるべき4項目

プロジェクト共通の用語集は辞書のように網羅的である必要はない。むしろ「解釈が割れやすい言葉」だけに絞り、次の4項目を埋める。

• 用語: 仕様書・チケット・会話で実際に使われる表記(表記ゆれも併記する)
• 定義: 1文で言い切る。条件分岐がある場合は箇条書きで分ける
• NG例: 過去に実際に誤解を生んだ言い回しやチケットの引用
• 関連画面/機能: その言葉が使われる画面・API・DBカラム名

記入例

実装後に発覚した用語ズレの実例

ある案件では、「アーカイブ」という言葉が仕様書に10回以上登場したが、定義が一度も書かれていなかった。PM は「一覧から見えなくなるだけで、データは残る」つもりで書いていたが、実装したエンジニアは「論理削除して復元不可」で作ってしまった。QA が「アーカイブしたデータを復元してほしい」というテストケースを書いた段階で初めて食い違いに気づいたが、その時点で実装は7割進んでいた。手戻りは2人日。要件定義の段階で用語集に「アーカイブ: 非表示。復元可能。物理削除ではない」の1行があれば防げたはずだ。

用語集は誰が最初に作るか

「みんなで作ろう」と言うと結局誰も手を付けない。最初の叩き台は、要件定義のミーティングでファシリテーションをしている人(多くは PM)が持ち帰って1時間で作る、と決めてしまうのが早い。ゼロから書く必要はなく、次の3つのソースから言葉を拾えば十分な量が集まる。

• 直近の仕様書・チケットに登場する名詞のうち、修飾語(有効な/承認済みの/アクティブな)が付いているもの
• 過去の問い合わせ・バグ報告で「そういう意味だったんですね」というやり取りが発生した言葉
• DB のカラム名やステータス enum の値(コードの中の言葉と仕様書の言葉は、往々にして一対一対応していない)

最初の版は5〜10語で構わない。網羅性より「解釈が割れたら必ず用語集を見に行く」という習慣を作ることの方が効く。

用語集を形骸化させない運用

作って終わりにしないための最低限のルールは3つ。

• 新しい言葉が出たら、その場で誰か1人が用語集に追記する(後回しにすると誰もやらない)
• 仕様レビューの冒頭で、その回で使う用語を用語集と突き合わせる(5分で終わる)
• 用語集は SPEC.md やチケット管理ツールと同じ場所に置き、別ドキュメントに孤立させない

Bugoon での実践

言葉のズレは要件定義だけでなく、バグ報告の場面でも起きる。「編集できない」という報告が、非エンジニアにとっての「保存ボタンが反応しない」なのか「入力欄がグレーアウトしている」なのか、言葉だけでは判別できないことが多い。Bugoon のウィジェットはスクリーンショットへのアノテーションと操作ステップの記録を残せるため、報告者の言葉の解釈に頼らず、実際に何が起きたかを画面で確認しながら GitHub Issue に連携できる。

用語集と同じで、「言葉のズレを埋める仕組み」を要件定義からバグ報告まで一貫して持っておくと、解釈違いによる手戻りは着実に減っていく。