システム開発における仕様書の最小を考える

仕様書の最小を考える

以前アジャイル開発に携わっていたとき、スケジュールに追われる中でドキュメントの更新が後回しになっていきました。

最初は「あとで直せばいい」と思っていたのですが、その“あとで”は結局来ず、
気づいたときには、「コードが正」という空気がチームに広がってしまいました。

これがなかなか厄介で、

• 新しく入ったメンバーが仕様を理解できない
• 実装者が“公式リファレンス”のような存在になってしまう
• 属人化した領域のはざまで認識齟齬が発生する

といった問題が起きます。

「じゃあドキュメントをちゃんと書こう」というのが自然な発想ですが、
ドキュメントを増やせば増やすほど、維持できず。

そこで行き着いたのが、

「最小限で、かつ壊れない仕様書とは何か？」

という問いでした。

この記事では、自分の失敗をベースに、
アジャイル開発において現実的に運用できる「仕様書の最小構成」について考えてみます。

ツッコミのコメントお待ちしております。

要件定義段階で作成する仕様書

• 画面フロー図

  • ポンチ絵を矢印でつなぎ合わせ、サービス導線を示すための資料。
  • システムの利用フローを俯瞰して確認するための資料となる。

• 画面イベント仕様書

  • Excelで作成し、1画面1ファイルとする。
  • 更新履歴を記載するためのシートを作成する。（更新履歴シートと呼称する。）
    • No（通番）
    • 変更内容
    • 要件チケット番号
    • 修正チケット番号
      • 要件 or 実装チケット番号必須（排他）
    • 修正日
    • 修正者
  • 画面のポンチ絵と、仕様を記載するシートを作成する。（画面仕様シートと呼称する。）
    • ポンチ絵に記載されているテキスト、ボタン、入力欄など、登場するすべての部品に番号を振る。
    • ポンチ絵の下に画面仕様表を作り、どの番号はどのような役割を果たす部品か、その振る舞い（仕様）はどのようなものか記載する。詳細は以下の通り。
      • 画面要素番号
        • ポンチ絵に記載されている番号を記載する
      • 役割
        • テキスト
        • エラー表示
        • 入力欄
        • ラジオボタン
        • etc...
      • 表示条件
        • ①のラジオボタンでZが選択されている場合のみ表示
        • 取得したリストが空だった場合は～を表示する
      • イベントトリガー
        • ユーザー操作（click, input）
          • Aボタン押下時
          • B入力ボックスに入力時
        • システムイベント（初期表示、API完了）
          • 初期表示時
          • API成功時
          • API失敗時
      • 実行処理
        • XX画面に遷移する。
        • hogeAPIのレスポンス.タイトルを表示する。
        • ボタン押下でYY処理(API呼び出し)を実行する。
      • 呼び出すAPI論理名
    • 重要：ここにはAPI論理名以上の内容を記載しない。
      • これはSwaggerとの2重管理を避けるため。

• ドメインモデル図

  • ビジネスが持つドメイン（機能）、ドメインが持つべきデータの組み合わせを1エンティティとし、ドメイン同士の紐づけを視覚的に表す資料。
    • 紐づけの表現では、エンティティ同士の従属関係、多重度も表現する。
    • エンジニア向けに端的に説明すると、クラス図や、抽象化したモデル図（正規化をほとんどしていない状態）と理解してほしい。
  • エンジニア、クライアントが業務構造の理解と整合性確認のために利用する。
  • 設計（DB/API）は本モデルを参考にしつつ最適化を行う。

設計段階で作成する仕様書

• Swagger(API仕様書)

  • コードから自動生成する。
    • コードから自動生成する関係上、担当者はスケルトンで構わないため素早く手を動かすこと。
  • エラーコードパターン、バリデーション仕様を明確に記載する。

• モデル図

  • DBeaver搭載機能を使用して画像を生成する。
  • ※結合試験のインプットとなるため、モデルの変更があり次第画像を更新すること

• 画面イベント仕様書

  • 要件定義段階では、条件、仕様の記載が抽象的であると想定されるため精緻化。
    • hogeAPIレスポンス.ユーザーID、画面要素番号など、読み手に左右されない具体情報となるよう記載を改める。

• シーケンス図

  • 原則作成しない。
  • ただし、以下のいずれかに該当する場合は作成すること。
    • 外部サービスとの連携がある
    • 非同期処理（キュー、バッチ、Webhook等）が含まれる
    • 状態遷移や分岐が複雑で、画面仕様書だけでは理解が困難