コンテンツにスキップ

01.基本規定

本規定は、プロジェクト内のドキュメント作成における基本的なルールを定めます。

Note

本規定は、ドキュメント全体の体系を定めるものです。 ナビゲーションやレビューに関する詳細は、以下の各規定を参照してください。 02.サイト構築規定 03.レビュー規定

1. 基本方針

  • 明確性: ドキュメントは、対象読者が容易に理解できるよう、明確かつ簡潔な言葉で記述します。
  • 一貫性: 用語、書式、構造などにおいて、プロジェクト全体で一貫性を保ちます。
  • 保守性: 将来的な変更や更新が容易に行えるよう、構造化されたドキュメントを作成します。
  • 自己完結性: 可能な限り、このドキュメントサイト内で情報が完結することを目指します。

2. ファイルとフォルダ

2.1. ドキュメントの分割戦略

ドキュメントは、その内容のまとまりや粒度に応じて、以下のいずれかの方法で適切に分割・構成します。

パターンA: フォルダによる分割（基本形）

関連する複数のドキュメントで一つの概念を説明する場合は、専用のフォルダを作成して管理します。これは、論理的なグループ分けを行う際の基本的な方法です。

  • 例: 認証機能に関する仕様書群

    Docs/
└── 01_要求仕様/
    └── 01_認証機能/       <-- 認証機能フォルダ
        ├── 01_ログイン処理.md
        └── 02_パスワードポリシー.md

パターンB: ファイル名プレフィックスによる分割（大規模ファイル向け）

単一の仕様書が肥大化し、一つのファイルでの管理が困難になった場合に、このパターンを適用します。同一フォルダ内で、ファイル名のプレフィックスによって階層構造を表現します。

  • インデックスファイル:
    • 分割された章全体を取りまとめる概要ページには、プレフィックスの末尾に _00_ を付けます。（例: XX_00_概要.md）
    • このファイルには、各詳細ページへのリンクを記述します。
  • 詳細ファイル:
    • 概要から分割された詳細ページには、XX_01_、XX_02_ のように連番を振ります。

  • 再帰的な分割:

    • この分割ルールは、さらに深い階層にも適用可能です。

  • 例: 02_アーキテクチャ設計仕様書が大規模になった場合

    Docs/
└── 02_設計仕様/
    ├── 02_00_アーキテクチャ設計概要.md   <-- インデックスファイル
    ├── 02_01_レイヤー構造.md
    ├── 02_02_コンポーネント設計.md
    │
    ├── 02_02_00_コンポーネント設計概要.md <-- さらにコンポーネント設計を分割
    ├── 02_02_01_認証コンポーネント.md
    └── 02_02_02_データアクセスコンポーネント.md

2.2. 命名規則

  • ファイル形式: Markdown形式 (.md) を使用します。
  • エンコーディング: UTF-8 (BOMなし) を使用します。
  • 命名規則:
    • ファイル名およびフォルダ名は、半角英数字、ハイフン (-)、アンダースコア (_) を基本とします。スペースは使用しません。
    • 主要なドキュメントやカテゴリフォルダには、01_のような2桁の数字プレフィックスを付け、順序を明確にします。
    • 内容の理解を助けるため、ファイル名に日本語を含めることもできます。（例: 01_認証機能.md）
    • 各カテゴリフォルダの案内ページとなるファイル名は README.md に統一します。

2.3. ファイル名と機能IDの関係

  • ファイル名は、人間がその内容を理解しやすいように命名します。（例: 01_認証機能.md）
  • 機能ID (FUNC-XXX-X.Xなど) は、原則としてファイル名には含めません。
  • 機能IDは、ファイル内の見出しや本文で定義・参照します。

3. 機能IDによるトレーサビリティ

プロジェクト全体の成果物の追跡可能性を確保するため、機能IDを定義し、その利用ルールを定めます。

3.1. 命名規則

  • 要求仕様書で定義される各要件には、プロジェクト内で一意のIDを付与します。
  • フォーマット: [種別]-[カテゴリ]-[メジャー番号]-[マイナー番号]
    • 種別: 以下の分類から適切なものを選択します。
      • 機能要件系: FUNC(機能要件), API(API仕様), UI(UI/UX要件), BIZ(ビジネスロジック)
      • 非機能要件系: PERF(パフォーマンス), SEC(セキュリティ), COMPAT(互換性), SCALE(スケーラビリティ)
      • 技術・アーキテクチャ系: ARCH(アーキテクチャ), DATA(データ設計), INFRA(インフラ), DEPLOY(デプロイメント)
      • 品質・テスト系: TEST(テスト要件), QUAL(品質要件), VALID(バリデーション)
      • 運用・保守系: OPS(運用要件), MAINT(保守要件), MON(監視要件)
      • 設計・実装制約: CONST(設計・実装上の制約)
      • その他: OTHER(その他、上記に該当しない要件や補足)
    • カテゴリ: 機能を示す3〜4文字の略称 (例: AUTH, USER, POST)。
    • メジャー番号: 機能の大きな塊を表す番号 (例: 1, 2, 3...)。
    • マイナー番号: メジャー番号に属する詳細な要求を表す番号 (例: 0, 1, 2...)。0 は親となる概要要求に使うことを推奨します。
  • 具体例:
    • FUNC-AUTH-1-0: 認証機能全体の要求
    • FUNC-AUTH-1-1: パスワードポリシーに関する要求
    • API-USER-2-1: ユーザー管理API仕様
    • UI-LOGIN-1-0: ログイン画面の要件
    • SEC-PASS-1-1: パスワードセキュリティ要件
    • PERF-RESP-1-0: レスポンス時間要件
    • ARCH-LAYER-1-0: レイヤーアーキテクチャ設計
    • DATA-USER-1-0: ユーザーデータモデル設計
    • TEST-AUTH-1-1: 認証機能のテスト要件

3.2. ドキュメント内での利用

  • 定義: 要求仕様書でIDを定義する箇所には、見出しに { #FUNC-AUTH-1-0 } のようにIDを付与します。（推奨）
    • 例: ### 1.1. パスワードポリシー { #FUNC-AUTH-1-1 }
  • 参照: 他のMarkdownドキュメントからIDを参照する場合は、必ずアンカーへのリンクを作成します。
    • 例: この設計は、[FUNC-AUTH-1-1](../../01_システム仕様/01_機能要件/01_認証機能.md#FUNC-AUTH-1-1)を実現する。

注意

見出しにIDを付与する { #... } 形式を利用するには、mkdocs.yml の markdown_extensions に attr_list が設定されている必要があります。

Note

ソースコードや自動テストコード内での機能IDの記述ルールについては、それぞれ 04.コーディング規定 および 05.リリース規定 を参照してください。

4. Markdownの記述スタイル

4.1. 基本構造とH1見出し

各ドキュメントファイルは、一貫性と機械的な処理のしやすさを考慮し、以下の基本構造に従います。

# [章番号] [タイトル]

このドキュメントの本文...
  • H1見出し (必須):
    • 全てのドキュメントは、ファイルの先頭に、必ず#から始まるH1見出しを1つだけ含める必要があります。
  • 章番号とタイトル:
    • H1見出しには、ファイル名のプレフィックスと連動した章番号を必ず含めます。
    • これにより、ファイルツリーの構造とドキュメント内の見出し体系が一致し、全体像の把握が容易になります。

章番号の命名規則

  • 章番号は、Docs/直下のカテゴリフォルダ（例: 03_開発ルール/）の内部から開始される形で、以下のルールに従って生成します。
    1. 起点: Docs/直下のカテゴリフォルダの、一つ下の階層からパスの解析を開始します。
    2. プレフィックスの抽出: パスに含まれる各サブフォルダとファイル名から、数字のプレフィックスを全て抽出します。
    3. 先頭ゼロの除去: 抽出した各数字から、先頭のゼロを除去します。（例: 02 -> 2）
    4. 結合: 整形した数字を、階層順にドット (.) で結合します。
    5. インデックスファイルの扱い: ファイル名のプレフィックスが _00_ で終わるインデックスファイルの場合、その .0 は章番号から省略します。

具体例

例1: カテゴリ内の第一階層のファイル

Docs/03_開発ルール/は無視され、05_から番号が始まります。

  • ファイルパス: Docs/03_開発ルール/05_ブランチ規定.md
  • 導出過程:
    1. 起点は03_開発ルール/の内部。
    2. 05_を抽出し、5に変換。
  • H1見出し: # 5. ブランチ規定
例2: 深い階層のファイル

Docs/03_開発ルール/は無視され、01_から番号が始まります。

  • ファイルパス: Docs/03_開発ルール/01_フォルダ構成/01_ルートディレクトリ.md
  • 導出過程:
    1. 起点は03_開発ルール/の内部。
    2. 01_と01_を抽出し、それぞれ1に変換して結合。
  • H1見出し: # 1.1. ルートディレクトリ
例3: インデックスファイル (_00_)

Docs/02_設計仕様/は無視され、02_00_から番号が始まります。

  • ファイルパス: Docs/02_設計仕様/02_00_アーキテクチャ設計概要.md
  • 導出過程:
    1. 起点は02_設計仕様/の内部。
    2. 02_00_を抽出。02は2に。_00_のルールにより末尾の.0は省略。
  • H1見出し: # 2. アーキテクチャ設計概要

4.2. リンクスタイル

ドキュメント間のリンクテキストの書式は、可読性と構造の分かりやすさのため、以下のように統一します。

  • ファイル名を直接指す場合:
    • [05.ブランチ規定](../02_プロジェクト規定/05_ブランチ規定.md) のように、[番号.タイトル]形式で記述します。ドットの後のスペースは入れません。
    • タイトル部分には、リンク先ドキュメントのH1見出しからプレフィックスを除いたものを記述します。
  • パスを含む場合:
    • [02.プロジェクト規定/05.ブランチ規定](../../02_プロジェクト規定/05_ブランチ規定.md) のように、実際のパス構造を/で区切って表現します。これにより、リンクの階層が一目で分かります。
    • または、05.ブランチ規定 のように、ファイル名を直接指す場合と同様に[番号.タイトル]形式で記述します。
  • 機能IDを参照する場合:
    • この設計は[FUNC-AUTH-1-1: 認証フローのセキュリティ要件](../../01_要求仕様/01_機能要件/01_認証機能.md#FUNC-AUTH-1-1)を実現する。 のように、機能IDと機能名の組み合わせで記述します。

4.3. スタイルガイド

コーディング規定への移管

Markdownの具体的な記述スタイル（見出し、コードブロック、注釈など）に関する詳細なルールは、 Markdown規約.md に集約されています。 ドキュメントを記述する際は、そちらを参照してください。