lulliecat

Software Design & Development

Menu
Search
›
SERIES
ToDoで学ぶ仕様書作成第 1 回

ドキュメント体系の全体像を俯瞰する

大河るり(Taiga Luri)大河るり(Taiga Luri)
記事の先頭へ

    今回から始まるのが「ToDoで学ぶ仕様書作成」シリーズです。ToDoアプリという身近な題材を使って、実際に仕様書を作成していきます。全部で十数回のシリーズになる予定ですが、最後まで見ていただければ、きっと皆さんの開発に役立つスキルが身につくはずです。

    さて、配信ネタを作るためのToDoアプリを設計していますが、存外複雑ですね。Claudeにドキュメント書かせているのですが、なかなか膨大な量のドキュメントになりました。具体的には、機能仕様書が3000行を超えています。もう少しコンパクトになるかな、と思ったのですが、想定外でした。

    エラーまで網羅させているので、それはそうな部分はあるのですが、それにしても少し詳細すぎるかな、という気もしています。もう少し省略できるか、悩ましいです。

    プロジェクト憲章やユーザーストーリー、要求仕様、アーキテクチャ設計、データ設計、あたりまではまぁ納得のサイズではあったのですが、その後が膨大になりますね。API仕様とUI仕様、機能仕様、あたりです。テスト仕様書まで含めると、さらに増えるかもしれません。スクラムとかやる前提だと、このやり方は無理があるかなぁ。

    ドキュメントは、今のところClaudeに初期版を書かせて、ぼくが適宜修正する、という方向で書いています。結構優秀なので、ある程度は満足がいくのですが、やはり細かいところはこちらの伝え方が悪いせいか、なかなか思い通りとはいきません。

    今回ははじめて、契約プログラミングちっくに、事前条件と事後条件、不変条件を各機能に書かせてみたのですが、それらの条件が網羅されているかがわからないところも悩みどころです。ちゃんと契約プログラミングの本を読むべきでしょうか。完全にエアプなので現状はよろしくないです。

    さて、今回の一連の動画を制作するにあたり、ソフトウェア開発プロジェクト　上流工程ドキュメントガイドを作成しました。今後はこれをベースに動画を作成していきます。書くべき項目について、簡単な説明は記載してあります。先取りしてドキュメントを作成していきたい場合は、これをご覧になってください。項目自体は以下に列挙してあります。

    1. プロジェクト憲章

      1. プロジェクト名
      2. プロジェクト実行の背景
      3. プロジェクトの目的
      4. 提供価値
      5. プロジェクトスコープ
        1. スコープ内の項目
        2. スコープ外の項目(重要!)
      6. 成功基準
      7. スケジュール概要
      8. メンバー
      9. 利害関係者(ステークホルダー)
      10. 予算
      11. リスク
      12. 前提条件と制約条件
      13. 承認者

    2. 体制図

      1. 組織構造図
      2. 役割と責任
      3. 外部組織との関係

    3. ユーザーストーリー

      1. 更新履歴
      2. ユーザーペルソナ
      3. ユーザージャーニー
      4. ユーザーストーリー
      5. 受け入れ基準(Acceptance Criteria)

    4. 要求仕様書

      1. 更新履歴
      2. 機能要件
      3. 非機能要件
      4. インターフェース要件
        1. 外部インターフェース(API等)
        2. ユーザーインターフェース(UI)
      5. データモデル
      6. 制約条件
      7. 品質要件
      8. トレーサビリティマトリクス

    5. 設計仕様書群

      1. アーキテクチャ設計書
        1. 更新履歴
        2. システム概要図
        3. アーキテクチャパターン
        4. アーキテクチャ決定記録(ADR)
        5. 設計指針
        6. 技術スタック
        7. 非同期・並行処理設計
      2. データ設計書
        1. 更新履歴
        2. 概念データモデル
        3. 論理データモデル
        4. 物理データモデル(データベース設計)
        5. アプリケーションデータ型仕様
        6. データ制約とバリデーション
        7. データマイグレーション
      3. API仕様書
        1. 更新履歴
        2. API概要
        3. エンドポイント定義
        4. 内部API仕様(関数/メソッド)
      4. UI仕様書
        1. 更新履歴
        2. UI全体方針
        3. 画面遷移図
        4. 画面仕様
        5. 共通UI コンポーネント
      5. 機能詳細仕様書
        1. 更新履歴
        2. 機能一覧
        3. 状態遷移図
        4. シーケンス図
        5. 機能詳細仕様
        6. ビジネスロジック
        7. データフロー図(DFD)