Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Specification Document Creation Guide

本ガイドは、各ソフトウェアコンポーネント配下の specs/ ディレクトリに作成する機能仕様書（Feature Specification: specs/[<category>/]<SPEC-ID>.md）、増分機能仕様書（Incremental Specification: specs/incremental/<SPEC-I-ID>.md）、共通仕様書（Common Specification: SPEC-C-<name>.md）、仕様総合台帳（specs/index.md）、仕様リンク台帳（specs/index.link.tsv）、および仕様採番管理台帳（specs/id-seq-no.tsv）の構成規則、記述内容、およびMarkdownテンプレートを定義するものです。

基本方針

  • 自己完結（Self-contained）原則: Incremental Spec に差分（パッチ）記述を持ち込まず、最小機能単位の完全な仕様として記述します。
  • 参照到達性（Reachability）によるライフサイクル管理: Feature Spec から参照されている Incremental Spec を現役（Live）とし、参照されないものを過去ログ（Historical）として決定論的に判定します。
  • コード変更時の Incremental Spec 必須原則: ソースコードに変更を加えるすべての作業は必ず Incremental Spec を経由するものとし、ISSUE から直接実装計画やタスク詳細を作成することを禁止します。

ディレクトリ構成と運用ルールの解決順序

各ソフトウェアコンポーネントの specs/ ディレクトリ配下の構成（サブディレクトリ分類や配置ルール）は、以下の優先順位で解決・適用されます。

  1. 予約要素: specs/index.md、specs/index.link.tsv、specs/id-seq-no.tsv、specs/AGENTS.md、および specs/incremental/ は予約されており、specs/ 直下に配置します。
  2. 機能仕様の判定: specs/ 配下のサブディレクトリを含め、<SPEC-ID>.md というファイル名を持つものが機能仕様です。
  3. 増分仕様の判定: specs/incremental/ 配下にある <SPEC-I-ID>.md のみを増分仕様とします（例: specs/archive/<SPEC-I-ID>.md のように specs/incremental/ 以外の場所にあるファイルは、増分仕様や機能仕様とはみなされず index.md 台帳には登録されません）。
  4. 共通仕様の配置と命名: specs/ 配下に配置する共通仕様のファイル名は SPEC-C-<name>.md とします。既定では specs/common/ や specs/model/ への配置を推奨とします。
  5. 構成定義 (specs/AGENTS.md): specs/AGENTS.md に ## Structure 見出しを作成し、3列テーブル（パス | 配置対象 | 命名規則）でサブディレクトリ構成や共通仕様の配置先を定義します。定義がない場合の機能仕様は specs/<SPEC-ID>.md（直下フラット配置）とします。

仕様書の種別と責務

1. Feature Specification (specs/[<category>/]<SPEC-ID>.md)

  • 役割: 各機能の仕様を網羅する責任を持ちます。specs/ 配下のサブディレクトリを含め <SPEC-ID>.md の形式とします。
  • 記述内容: 機能全体のフロー（Mermaidシーケンス図・必須）とインターフェース契約を定義し、構成する最新の Incremental Spec 群の台帳（BOM: 部品表）を保持します。

2. Incremental Specification (specs/incremental/<SPEC-I-ID>.md)

  • 役割: 実装スライスの最小単位となる自己完結した機能仕様です。specs/incremental/ 直下にのみ配置されます。
  • 記述ルール: 差分記述は禁止とし、単体で動作・検証可能な完全形として記述します。

3. Common Specification (specs/[<category>/]SPEC-C-<name>.md)

  • 役割: incremental specification から参照される共通仕様（データモデル、DTO、共通規約、エラー定義等）です。
  • ファイル名: SPEC-C-<name>.md（例: SPEC-C-auth-dto.md, SPEC-C-error-handling.md）。
  • 横断参照: 他のソフトウェアコンポーネントから参照することも可能です。
  • 配置場所: 既定では specs/common/ や specs/model/ への配置を推奨とし、specs/AGENTS.md で変更可能です。

4. Specification Resource Index (specs/index.md)

  • 役割: コンポーネント内の全仕様リソースの相互参照（Reachability）を追跡・記録する総合台帳。
  • 各表の列構成: 識別子/ファイル名 | 概要 | 参照 | 更新日
    • 概要: 対象仕様ファイルのフロントマターにある description を記述。
    • 参照: その仕様を参照している仕様の ID（リンク付き）を記述。参照元がない場合は - を記述。
    • 更新日: 対象仕様ファイルのフロントマターにある timestamp を記述。
  • 役割: 増分仕様および共通仕様の参照関係（グラフ）を管理する TSV ファイル。
  • 列構成: Path | Refs（タブ区切り）
    • Path: 各仕様の specs/ からの相対パス（例: incremental/SPEC-I-001.md, common/SPEC-C-error-handling.md）
    • Refs: その仕様を参照しているファイルの specs/ からの相対パスリスト（, で連結したもの）。
      • 増分仕様の場合: その仕様を参照している機能仕様（<SPEC-ID>.md）のリスト
      • 共通仕様の場合: その仕様を参照している増分仕様（<SPEC-I-ID>.md）のリスト
      • 外部参照（他コンポーネントからの参照）は対象外
  • 更新タイミングと整合性検証:
    • index.link.tsv は index.md の作成・更新と同時に作成・更新します。
    • 更新時に、増分仕様から外部の共通仕様へのリンク検証を行い、参照対象が存在するか確認します。

6. Specification ID Sequence Ledger (specs/id-seq-no.tsv)

  • 役割: 機能仕様書（<SPEC-ID>）および増分機能仕様書（<SPEC-I-ID>）の最大連番（次に割り当てる番号）を一元管理する TSV ファイル。仕様のアーカイブや削除が発生した場合でも、ID の重複・衝突を確実に防止します。

  • 形式: KVTsv形式（Key\tValue\tCreated\tUpdated）

  • 列構成:

    • Key: ID 種別（SPEC-ID, SPEC-I-ID）
    • Value: 次回採番する連番（SeqNo）
    • Created: 初回作成日時（ISO 8601、自動設定）
    • Updated: 最終更新日時（ISO 8601、自動設定）

  • 初期値:

    Key	Value	Created	Updated
SPEC-ID	1	2026-09-04T00:00:00+09:00	2026-09-04T00:00:00+09:00
SPEC-I-ID	1	2026-09-04T00:00:00+09:00	2026-09-04T00:00:00+09:00

  • 採番運用ルール:

    • 新しく機能仕様または増分仕様を作成する際は、本ファイルを参照して該当 ID の Value を採番し、値をインクリメント（+1）して保存します。
    • mise run aidev:kv-tsv（AIDEV-TOOL-28）を利用して値の取得（get）やインクリメント（inc）を行うことができます。

参照到達性（Reachability）と仕様変更ルール

  1. ライフサイクル判定:
    • いずれかの Feature Spec から参照されている Incremental Spec を Active（現役） と判定します。
    • すべての Feature Spec から参照されていない Incremental Spec を Historical（過去・廃止） と判定します。
  2. 仕様変更フロー:
    • 全体共通の改善・バグ修正: 既存の SPEC-I-xxx.md を完全形のまま直接更新します。
    • 特定機能都合・破壊的変更: 新規 SPEC-I-yyy.md を作成し、対象 Feature Spec の台帳リンクを差し替えます（古い SPEC-I は自動的に Historical 化）。

仕様台帳ツール・検証ツールの利用方法 (CLI Tools)

仕様書の追加・変更を行った際は、以下の mise タスクを使用して台帳（index.md, index.link.tsv）の自動同期および外部リンクの検証を実行します。

1. 仕様台帳の一括同期・一括検証

# index.md, index.link.tsv の自動同期および外部共通仕様リンク検証を一括実行
mise run aidev:spec:sync

# 差分やリンク切れがないかを一括検証
mise run aidev:spec:check

2. 個別ツールの実行

  • 仕様総合台帳 (specs/index.md) の生成・同期: 
    # 自動生成・同期
mise run aidev:spec:index:sync
# 検証（差分チェック）
mise run aidev:spec:index:check
  • 仕様リンク台帳 (specs/index.link.tsv) の生成・同期: 
    # 自動生成・同期
mise run aidev:spec:link:sync
# 検証（差分チェック）
mise run aidev:spec:link:check
  • 外部共通仕様参照のリンクチェック: 
    # 増分仕様から他コンポーネントの SPEC-C-*.md へのリンクが実在するか検証
mise run aidev:spec:check-external-links

Template

1. Feature Specification テンプレート (specs/auth/SPEC-001.md)

---
name: SPEC-001.md
title: <機能名称>
description: <機能仕様の全体概要>
status: active
timestamp: YYYY-MM-DD
ai: ai-coauthored
---

# SPEC-001: <機能名称>

## 概要

<本機能が提供する価値およびセッション管理・処理全体の概要を記述します ([DR-001](../../decision-records/DR-001.md))。>

## 機能フロー (必須)

```mermaid
sequenceDiagram
    autonumber
    Client->>API: 1. 要求送信
    API->>API: 2. 処理・検証
    API-->>Client: 3. 応答返却
```

## 機能契約・インターフェース要約

-   **公開インターフェース**: `/api/v1/...`
-   **適用規約**: `specs/common/SPEC-C-error-handling.md`

## 構成 Incremental 仕様台帳 (Active Specifications)

| 分野 / 対象 | 参照 Incremental Spec | 概要 | 適用・更新日 |
| :--- | :--- | :--- | :--- |
| **基本処理** | [SPEC-I-001](../incremental/SPEC-I-001.md) | 基本ロジック | YYYY-MM-DD |
| **拡張処理** | [SPEC-I-002](../incremental/SPEC-I-002.md) | 拡張機能 | YYYY-MM-DD |

## 関連

-   [design.md](../../design.md)
-   [DR-001](../../decision-records/DR-001.md)

2. Incremental Specification テンプレート (specs/incremental/SPEC-I-001.md)

---
name: SPEC-I-001.md
title: <最小機能仕様名称>
status: active
timestamp: YYYY-MM-DD
ai: ai-coauthored
---

# SPEC-I-001: <最小機能仕様名称>

## 概要

<本増分仕様が定義する単独完結した処理内容を記述します。>

## 参照モデル・共通仕様

-   [specs/model/SPEC-C-auth-dto.md](../model/SPEC-C-auth-dto.md)
-   [specs/common/SPEC-C-error-handling.md](../common/SPEC-C-error-handling.md)

## 入力・出力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
| :--- | :--- | :--- | :--- |
| `user_id` | string | ○ | ユーザー識別ID |

### 出力仕様

| 項目名 | 型 | 説明 |
| :--- | :--- | :--- |
| `token` | string | 発行されたトークン |

## 機能・振る舞い仕様

```mermaid
sequenceDiagram
    Client->>API: 処理要求
    API-->>Client: 200 OK
```

1.  入力パラメータの妥当性を検証する。
2.  対象のデータを取得・加工する。
3.  レスポンスオブジェクトを構築して返却する。

## エラー・例外処理

| エラーコード | 発生条件 | 処理内容 |
| :--- | :--- | :--- |
| `ERR_INVALID_PARAM` | パラメータの型不正 | 400 Bad Request を返却 |

3. 仕様総合台帳テンプレート (specs/index.md)

---
name: index.md
description: 仕様リソース総合台帳（Incremental Spec, Common Spec 参照追跡）
timestamp: YYYY-MM-DD
ai: ai-coauthored
---

# Specification Resource Index

## 1. Incremental Specifications

| Incremental ID | 概要 | 参照 | 更新日 |
| :--- | :--- | :--- | :--- |
| [`SPEC-I-001`](./incremental/SPEC-I-001.md) | 基本認証ロジック仕様 | [`SPEC-001`](./auth/SPEC-001.md) | YYYY-MM-DD |

## 2. Common Specifications

| 共通仕様ファイル | 概要 | 参照 | 更新日 |
| :--- | :--- | :--- | :--- |
| [`SPEC-C-error-handling.md`](./common/SPEC-C-error-handling.md) | 共通エラーハンドリング規則 | [`SPEC-I-001`](./incremental/SPEC-I-001.md) | YYYY-MM-DD |
| [`SPEC-C-auth-dto.md`](./model/SPEC-C-auth-dto.md) | 認証リクエスト・レスポンスDTO定義 | [`SPEC-I-001`](./incremental/SPEC-I-001.md) | YYYY-MM-DD |

4. 仕様リンク台帳例 (specs/index.link.tsv)

Path	Refs
incremental/SPEC-I-001.md	auth/SPEC-001.md
incremental/SPEC-I-002.md	auth/SPEC-001.md
common/SPEC-C-error-handling.md	incremental/SPEC-I-001.md,incremental/SPEC-I-002.md
model/SPEC-C-auth-dto.md	incremental/SPEC-I-001.md

5. 仕様採番管理台帳例 (specs/id-seq-no.tsv)

Key	Value	Created	Updated
SPEC-ID	1	2026-09-04T00:00:00+09:00	2026-09-04T00:00:00+09:00
SPEC-I-ID	1	2026-09-04T00:00:00+09:00	2026-09-04T00:00:00+09:00