Work Documentation

Appearance

Document Design Guide ​

本ガイドは、プロジェクト全体および各ソフトウェアコンポーネントにおける設計ドキュメントの分類（必須・任意）、記述順序、および標準記述仕様を定義するものです。

1. 設計ドキュメントの分類と優先順序 ​

設計ドキュメントは、以下の通り 必須ドキュメント (Required) を前方、 任意ドキュメント (Optional) を後方に配置して構成・整理します。

txt
設計ドキュメント
├── 必須 (Required)
│   ├── concept.md (コンセプト・概要)
│   ├── architecture.md (基本設計・システム構成)
│   ├── usecases/ (ユースケース・feature定義)
│   ├── specs/ (機能仕様書)
│   └── design.md (詳細設計書)
└── 任意 (Optional)
    ├── requirements.md (要件定義書)
    ├── security.md (セキュリティ定義・ポリシー)
    ├── schema.md (DB設計方針・全体ER図)
    ├── models/ (物理モデル定義)
    └── specs/services/ (共通サービス・DTO仕様)

2. 必須設計ドキュメント (Required) ​

2.1 concept.md (コンセプト) ​

プロジェクト全体（<root>/docs/concept.md）および個別のソフトウェアコンポーネント（<root>/docs/[<group>/]<component>/concept.md）において、「何を作るのか（What）」と「なぜ作るのか（Why）」を明確化する最上位の必須ドキュメントです。（※ 詳細は concept-guide.md を参照）

  • 概要: What（何を作るのか）、機能全体像、主要コンポーネントを記述します。

  • 目的: Why（なぜ作るのか）、開発背景、解決すべき課題、ビジネス/技術的価値を明記します。

2.2 architecture.md (基本設計・システム構成) ​

システム全体の基本設計、ディレクトリ構造、システム構成、ソフトウェアコンポーネントの役割と技術スタック、依存関係およびデータフローを定義する必須ドキュメントです。（※ 詳細は architecture-guide.md を参照）

  1. ディレクトリ構造: プロジェクト配置構造や主要ディレクトリの役割。
  2. システムアーキテクチャ: 全体概要および構成図（Mermaid等）。
  3. ソフトウェアコンポーネント構成: 各コンポーネント（アプリ、ライブラリ、ツール等）の役割と技術スタック。
  4. 依存・データフロー: コンポーネント間の依存関係・通信プロトコル・データフロー。
  5. 関連: 関連設計書へのリンク・参照。

2.3 usecases/ (ユースケース・feature定義) ​

複数コンポーネントにまたがる機能群やシナリオを束ね、ユーザー価値・目的および最小機能単位（feature）を定義・追跡する必須ディレクトリです。（※ 詳細は usecase-guide.md を参照）

  • 配置場所: <root>/docs/usecases/USECASE-XXX.md

  • 構成要素: 概要、実現条件（AND/OR/XOR 論理式等）、feature 詳細（F-<no>: <feature-name>、関連仕様書 <AppID>:<SpecID>、完了条件、種類、シーケンス図）。

  • 台帳管理: 総合台帳（docs/usecases/index.md）および feature 実装ステータス台帳（docs/backlog/usecase.md）と連携して管理。

2.4 specs/ (機能仕様書) ​

各ソフトウェアコンポーネント配下に機能仕様書・入出力仕様書を格納する必須ディレクトリです。（※ 詳細は specification-guide.md を参照）

  • 配置場所: <root>/docs/[<group>/]<component>/specs/ 配下

  • ステータス管理: 機能仕様書自体のフロントマターには進捗ステータスを持たせず、各コンポーネントの台帳 backlog/spec.md で一括管理。

  • グループ構成と分類: 画面仕様（specs/SPEC-XXX.md または specs/screens/）、API仕様（specs/api/）、共通サービス仕様（specs/services/）、共通定義（specs/_common/）に分類して配置。

2.5 design.md (詳細設計書) ​

コンポーネント構造、モジュール設計、内部処理ロジック等を定義する詳細設計書です。（※ 詳細は design-guide.md を参照）

  • 必須構成: 「設計方針」「ビルド・成果物」「レイヤー構造（L1/L2表）」「関係図（L1+L2 Mermaid図）」「機能仕様書一覧」「関連」。

  • 仕様書マッピング: specs/ 配下の すべての機能仕様書（SPEC-XXX.md）を L1/L2 分類して一覧表に掲載することを必須 とします。

3. 任意設計ドキュメント (Optional) ​

プロジェクトの規模や技術要求に応じて作成・追加する任意ドキュメントと構成項目です。

3.1 requirements.md (要件定義書) ​

各ソフトウェアコンポーネントにおける機能要件・画面要件を整理・明確化するドキュメントです。

  • 構成項目:
    • 機能一覧: システムが提供する機能の洗い出し（機能ID、機能名、機能概要）。
    • 画面一覧: アプリケーションの画面構成一覧（画面ID、画面名、役割・画面遷移概要）。

3.2 security.md (セキュリティ定義・ポリシー) ​

プロジェクト全体のセキュリティ方針、リスク対策、およびセキュリティ設計ガイドラインをまとめたドキュメントです。

  • 構成項目:
    • セキュリティポリシー: プロジェクト全体のセキュリティ基本方針。
    • 認証・認可: 認証方式、ユーザー権限・アクセス制御方針。
    • データの保護: 通信・保管時の暗号化方式、個人情報・機密情報の取り扱い定義。
    • 脆弱性対策: 入力値検証、各種攻撃（XSS, CSRF, SQLi等）への対策。
    • シークレット管理: APIキー、環境変数、パスワード等の安全な管理・運用の仕組み。

3.3 schema.md (データベース設計方針) ​

データベース全体の設計方針、ネーミングルール、マイグレーション方針、および全体ER図をまとめたドキュメントです。

  • 構成項目:
    • データベース概要: データベースの種類、バージョン、ホスティング環境方針。
    • ネーミングルール: テーブル、カラム、インデックス、外部キーの命名規則。
    • 全体ER図: Mermaidを用いたエンティティ間の全体リレーション表現。
    • マイグレーション方針: テーブル変更管理ルール、マスタデータ投入方法。

3.4 models/ (物理モデル定義) ​

schema.md の設計方針に基づき、テーブルごとに個別に分割して作成する物理テーブル定義書群（docs/models/<table-name>.md）です。

  • 構成項目:
    • モデル概要: テーブル物理名、論理名、役割・責務。
    • カラム定義: 物理名、論理名、データ型、制約（PK/FK/Null）、デフォルト値、説明。
    • インデックス定義: プライマリキー、ユニークキー、外部キーインデックスなどの設計情報。
    • アソシエーション（関連）: 他テーブルとのリレーションシップ（1対1、1対多、多対多）。

3.5 specs/services/ (共通サービス・DTO仕様) ​

複数画面や機能から横断的に呼び出される共通のビジネスロジック（Shared Services）と通信用データ構造（DTO）を定義する仕様書群（docs/specs/services/<service-name>.md）です。

  • 構成項目:
    • サービス概要: サービスの役割、公開インターフェースとしての責務。
    • インターフェース定義: メソッドシグネチャ、引数、戻り値、例外処理、処理フロー。
    • DTO定義: レイヤー間でやり取りするDTOの各フィールド（物理名、論理名、データ型、バリデーションルール）。