曖昧な要望を、検証できる結果に書き換える

「フレームワークを変えてほしい」「もう少し見た目をよくしてほしい」は、仕事を始めるきっかけにはなります。ただし、そのまま納品の条件にはできません。方向性は示していますが、読者が最終的に何を見るのか、どこで確認するのか、今回の対象に含まれないものは何かが明らかではないからです。

要件は、最初から完成した仕様書のようである必要はありません。大量の実装を始める前に、曖昧な一文を、観察し、議論し、受け入れを判断できる結果へ書き換えることのほうが重要です。よい要件とは、専門用語を増やすことではなく、違う人が同じ結果を見て、正しくできたかを判断できるようにすることです。

「何を望むか」と「どう判断するか」を分けます

納品の条件として使える要件には、少なくとも次の四つの答えが必要です。

1. 結果は何ですか？ ユーザーは何を見るのか、どの操作を完了できるのかを示します。
2. どこで確認しますか？ 公開URL、初期HTML、ブラウザーでの操作、ビルド後のファイルのどれで確認するのかを示します。
3. 今回は何を含めませんか？ 関係がありそうに見えても、今回の要望から追加して解釈してはいけない機能、効果、成果を示します。
4. 誰が最後に判断しますか？ ツールで確認できる部分と、人が決める必要のある部分を分けます。

たとえば、「サイトをもっとよくする」は、まず次のように書き換えられます。

元の要望	検証できる結果	明確な対象外事項・限界
フレームワークを変えてほしい	公開URLを直接開いた時点で主要な内容が表示されます。ナビゲーションには実際のリンクを使い、ブラウザーでの動作が必要な部分だけを局所的なスクリプトで処理します	旧フレームワークのApp全体の外枠をそのまま移すことは求めません。また、これだけでパフォーマンスやSEOの改善を主張することはできません
もう少し見た目をよくしてほしい	モバイルでは見出し、説明、操作の順序が明確です。固定の高さで内容が切れず、コントロールはキーボードでも操作できます	色の雰囲気や全体が期待に合うかは、見た目の確認が必要です。すべての端末を確認済みだとは主張しません

表の「結果」と「限界」は、どちらも同じくらい重要です。制限がなければ、実装する側はもっともらしい機能を要望に付け足しがちです。確認する場所がなければ、受け入れの判断は「だいたいよさそう」という感覚に戻ってしまいます。

「フレームワークを変える」だけでは受け入れ基準になりません

このプロジェクトはもともとVueを使っていましたが、その後、Astro本来の構成へ移行しました。要望が「フレームワークを変える」だけなら、まったく違う方法でも完了と見なされかねません。Astroで旧Appを包む方法、Vueコンポーネントをページ単位で移す方法、Astroのルーティングとコンテンツデータを使ってページを組み直す方法などです。

確認すべきなのはフレームワークの名前ではなく、サイトの振る舞いです。今回の要望は、直接確認できるいくつかの結果に書き換えました。

• 公開URLを直接開くと、初期HTMLに見出しと主要な内容が含まれています。ブラウザー上の空のマウント先に依存しません。
• ナビゲーションには実際のリンクを使い、読者がほかのページへ直接移動できます。
• 既存のコンテンツ、画像、言語別URLは残します。旧コンポーネントの形そのものを、維持しなければならない理由にはしません。
• 単純なページ構造は、まずAstro、HTML、CSSで実現します。ブラウザーの状態が必要なインタラクションだけに、局所的なTypeScriptを追加します。

これらの条件は、「VueからAstroに変えてほしい」よりも実際の納品内容に近いものです。選択や妥協点も議論できるようになります。旧App全体を残す案が出たときには、コンポーネントがすでにあるから採用するのではなく、上の結果に役立つかを問い直せます。

受け入れの確認では、ページのHTML、下層ページのURL、リンク、JavaScriptを無効にしたときの主要な内容を直接調べられます。これらの確認で証明できるのは、現在出力されているページが条件を満たしていることです。サイトが速くなった、検索順位が上がった、すべての見た目の細部が完成した、とまで証明できるわけではありません。

「見た目をよくする」を、まずUIの振る舞いに絞ります

「きれいにしてほしい」は無意味な要望ではありません。ただ、もう一段具体的に分ける必要があります。参考画像を一枚渡して「これに合わせて」とだけ伝えると、実装する側は画像内の文章、日付、ボタン、さらには存在しない機能まで仕様と捉えるかもしれません。それらが、もともと望んでいた結果とは限りません。

まず、読者が確認できる条件に書き換えます。

• モバイルでは、見出しと説明の後に主要な操作が表示されます。CSSのorderで、読む順序と異なる見た目の順序を作りません。
• 記事本文は読みやすい幅に保ちます。コードや横に広い表はそれぞれのコンテナー内だけでスクロールし、ページ全体にはみ出させません。
• カバー画像やおすすめ記事がない場合は、実際の件数に合わせて表示します。見本のカードを複製してレイアウトを埋めません。
• 操作できるコントロールには、目に見えるフォーカス状態があります。JavaScriptを無効にしても主要な文章を読めます。

これらは、DOM、CSS、キーボード操作、表示幅を変えた確認で検証できます。一方、「全体の雰囲気が合っているか」「情報の階層が心地よいか」は、決定権のある人が見て判断する必要があります。開発仕様にある320、390、768、1024、1440 CSS pxと200% zoomは、確認範囲として使えます。ただし、「すべての端末で問題がない」ことの証明にはなりません。

見た目の要望を振る舞いに書き換えるのは、デザインを無機質なテスト項目に変えるためではありません。実装に影響する部分を先に明確にするためです。残る主観的な判断はそのまま残し、ビルドの結果で代わりに判断できるふりをしないことが大切です。

どの要件にも「何をしないか」を添えます

曖昧な要件が膨らみやすい場面は二つあります。実装する側が機能を付け足すときと、受け入れの際に、当初言っていなかった成果まで条件に加えるときです。そのため、要件カードには対象外事項も書くとよいでしょう。

このサイトなら、たとえば次のようになります。

• 「元のサイトを残す」は、古いファイルを一つ残らず維持することではありません。まず、どのコンテンツや振る舞いに実際の公開された入口があるかを確認します。
• 「チェックに通る」は、見た目、パフォーマンス、SEO、トラフィック、事業上の成果がすでに実証されたという意味ではありません。
• 「相談を始められる」は、決まったサービス、機能の範囲、公開日を約束したという意味ではありません。

対象外事項は、消極的に仕事を減らすためのものではありません。次の判断に境界を設けるものです。要件を広げる必要が出たら、条件を明示的に追加できます。もっともらしい推測が、そのたびに知らないうちに製品仕様になるのを防げます。

繰り返し使える要件カード

どこから始めるか分からなければ、次の形式で整理してみてください。すべての詳細が決まるまで待つ必要はありません。

解決したい問題：
ユーザーが最終的に見るもの、または完了できること：
結果を確認できる場所：
今回、明確に含めないもの：
ツールで確認する部分：
人が最後に判断する必要のある部分：

「要件がまだ整理できていなくても、まずは問題を持ってきてよい」という考えは変わりません。このカードは、相手に仕様書の完成を求めるものではなく、少しずつ書き足せる形を議論に与えるものです。結果を先に書いてから、あるコードを残すかを決めます。限界を先に書いてから、機能を増やす価値があるかを決めます。

誤解を減らすのは、要件を専門的に見せることではありません。次に関わる人が、何を変えるのか、どこで結果を見るのか、現時点で何を断言できないのかを分かるようにすることです。