こちらは GAOGAO Advent Calendar 2023 の 17 日目の記事として公開されています。
前回は同僚の Masanao さんによる「ChatGPT を活用した英語学習法」でした。
チームメンバーにベトナム、マレーシアの方がいるため私も英語学習は日々しておりますが、ChatGPT で英会話ができるようになって文字通り「いつでもどこでも」英会話が可能になりましたね。

前置き

私はバックエンド開発に軸足を置いていますが、今年は PjM として仕様書を書くことがとても多い 1 年間になりました。
完成とは程遠いとは思いますが、どんな点に気をつけて書いているかなどご参考になりましたら幸いです。
また、冒頭ですが日々拙い仕様書にレビューをいただいたチームのメンバーに感謝を申し上げます。

誰向けの記事か

仕様書をまだ書いたことがない人
機能開発でゴールが明確になっていないことによって問題が起きた人

結論

ベストな仕様書が何かは勉強中ですが、重要だと思うポイントは以下です。

想定されるエラーが起きた場合の挙動も全て書く
用語を統一する（意外と難しい）
- 「タスク」なのか「TODO」なのかなどを統一
仕様と詳細な技術設計は分ける
- 仕様書が肥大化するのを避けるため

なぜ仕様書を書くか

その機能開発に取り掛かる前に全員で何を作るのか共通認識を持つため
その機能開発のゴールを明確にするため
将来の自分や、新しいメンバーへのドキュメントとして使うため

特に開発チーム内で認識の齟齬をなくすために書いています。

書く内容

下記の項目に分けて記入をしています。
文末に仕様書の例を記載しました。そちらもご参考にいただければと思います。

目的
概要
詳細
技術設計
タスク

1.目的

その機能開発がなぜ必要なのかを記入します
多くの場合、「誰」が「何」をするための機能かを説明します
ユーザにどの様な価値を与えるか、という観点になります

目的の明記は非常に重要です。目的が理解されていないと、仕様が正確に解釈されず、それらしきものができあがっても、目的が果たせない、あるいは果たすには適していない機能になる可能性があります。また、将来的に改変されていく中で本来の目的を果たせないものに変わってしまったりチグハグな用途の機能になってしまう可能性もあり、バグの原因にもなります。

2.概要

その機能でできることを大まかに列挙します

3.詳細

画面ごとに何ができるのかを記入します
- Figma など UI が分かるものの画像を添付し、その下に何ができるのかを記入します
自分で決めきれないことについては後々に確認を行うため分かりやすく記入します
- 私は次のように書くことが多いです
  - 確認
    - パターン ① ...
    - パターン ② ...

4.技術設計

どの API を使うのかを記入します
実装方針が目で見て分かるようなシーケンス図を追記します
- あくまでエンジニア向けではなく仕様の理解を助けるためなので実装と完全に一致していなくてはならないわけではないとしています

5.タスク

その機能開発がどんなタスクに分割するかを記入します
- 私は Jira で管理していたので Jira チケットタイトルと URL を貼りました

アンチパターン

仕様と詳細な技術設計が一緒になっている

仕様と技術設計が一つの場所にまとまると肥大化し読みにくい
仕様 → PdM やデザイナー、エンジニア用
技術設計 → エンジニア用

仕様と詳細技術設計を同じ文書にまとめていましたが、肥大化し見にくいため分割しようとチームメンバーにご意見をいただき分割をしました。

ドキュメントを読むにも労力がかかるので、文書の目的や対象者に応じて分けて、読む必要がないものは読まなくて済むようにします。

記入後に誰にも見てもらわない

仕様書の目的の「認識の齟齬をなくす」ことが達成できない
誤植や仕様の漏れを発見できない

記入後にはレビュー、チームメンバーで確認する場を必ず設けましょう。

書いた後

レビューをもらいます
- 自分一人で書いていると自分には分かるが、メンバーには伝わらない箇所が生まれます
- エラーケース等全てのパターンを列挙できていない場合があります
チーム全員での読み合わせも行いましょう
- 私のチームでは PdM, PjM, エンジニア, デザイナーで読み合わせとディスカッションを行い不足部分などの検討を行いました
- ディスカッションの叩き台としても機能し有用です
- ※ 注意として、この MTG はかなり緊張します笑
仕様書は常に最新にします
- 仕様変更はない方が望ましいですが、変更はプロジェクトにつきものです。都度更新を行います
- 他のメンバーにも追記していただいていい旨を伝え、チーム全体でメンテナンスをしていくことで最新の状態が保てます

仕様書の例

ここでは例として TODOアプリを作ると仮定します
Figma Community の LOW CODE TODO LIST APP AESTHETIC を例とします
Epic ごとに仕様書を書いています。今回の例では下記のように分割します（一例です）
- 一覧ページでタスクを閲覧できる
- 一覧ページでタスクを削除できる
- 一覧ページでタスクを完了できる
- 新規追加ページでタスクを追加できる
- 編集ページでタスクを更新できる
- 完了ページで完了済みのタスクを閲覧できる
今回はこの中で一覧ページでタスクを閲覧できるを例に 1 つずつ見ていきます

目的

ユーザーがタスク新たに追加し管理できるようにするため

概要

タスク追加ページの作成する
フォームに「タイトル」「詳細」を入力して保存できる
保存完了後に一覧ページに遷移できる

詳細

タスク追加ページ

Title に文字を入力できる
- 必須である
  - 入力がない場合には「Title は必須です」という赤いバリデーションメッセージを表示する
- 3 文字以上 20 文字以下である
  - 足りない、もしくは超過する場合...略
Detail に文字を入力できる
- 任意である
- 最大 30 文字である
  - ...略
[追加]ボタンを押し、保存が成功するとタスク一覧ページに遷移する
- 確認
  - ① エラーが発生した場合には「エラーが発生しました」スナックバーを表示する
  - ② エラーが発生した場合にはエラーページへ遷移させる
...略

技術設計

Mutation.addNewTodo

タスク

BE: タスクを新規追加する Mutation.addNewTask を作成する
- Jira の URL
FE: タスク一覧ページを作成する
- Jira の URL
FE: タスク一覧ページで [ADD] ボタンクリックでタスクを保存できる
- Jira の URL

認識齟齬を防ぐための仕様書

前置き