Specification Document Creation Guide

本ガイドは、各ソフトウェアコンポーネント配下の specs/ ディレクトリに作成する機能仕様書（SPEC-XXX.md）の記述内容とMarkdownテンプレートを定義するものです。

ディレクトリ構成と仕様書の分類

各ソフトウェアコンポーネントの specs/ ディレクトリ配下は、用途に応じて以下のように分類・配置します。

• 画面・機能仕様 (specs/SPEC-XXX.md または specs/screens/): 画面UIや一般機能の入出力・振る舞い仕様。
• 増分機能仕様 / feature specification (specs/<SPEC-ID>/<SPEC-F-ID(-1)>.md): feature ごとに実装する際の増分機能仕様書（例: specs/SPEC-001/SPEC-F-001-1.md）。
• API機能仕様 (specs/api/): REST/RPC等のAPIエンドポイント仕様。
• 共通サービス仕様 (specs/services/): コンポーネント内共通ビジネスロジック・DTO仕様。
• 共通定義 (specs/_common/): 共通エラーコード定義や共通ヘッダースキーマ等。

feature specification (増分機能仕様書) の運用規則

• 概要: feature ごとに開発を進める際、ベースとなる機能仕様書（SPEC-XXX.md）に対して増分となる仕様を定義する仕様書です。
• 配置場所: 対象の機能仕様書（<SPEC-ID>）が存在する場所に <SPEC-ID>/ ディレクトリを作成し、その配下に <SPEC-F-ID(-1)>.md（例: specs/SPEC-001/SPEC-F-001-1.md）として配置します。
• ID命名規則: <SPEC-F-ID(-1)> 形式（例: SPEC-F-001-1 は SPEC-001 の F-1 に対する仕様）。
• feature ID との区別: SPEC-F-001-1 の末尾 1（F-1）は対象 SPEC に対する増分番号であり、ユースケース配下の機能単位である全体 feature の <F-ID> とは別物です。
• 内容: 基本フォーマット・セクション構成は通常の仕様書（SPEC-XXX.md）と同じで、内容はベース仕様に対する増分（差分・拡張機能）を記述します。

API仕様書 (specs/api/) の運用規則

• 命名規則: フォルダ名およびファイル名は基本 kebab-case としますが、本番環境のAPIエンドポイント名・ルーティング名と一致させるための例外（大文字小文字、キャメルケース等）を認めます。
• ファイル集約方針（パターンB）: 同一リソースや同一URLパスに関連する複数のHTTPメソッド（GET, POST, PUT, DELETE 等）およびパスパラメータ（/{id} 等）の操作は、 1つのファイルに集約 して記述します（例: specs/api/users.md, specs/api/auth/login.md）。

---

Section & Property Guidelines

1. フロントマター

• 標準項目（name, description, timestamp, ai）を設定します（※ 機能仕様書自体のフロントマターには実装ステータスを持たせず、実装進捗は各コンポーネントの台帳 backlog/spec.md で一括管理します）。

2. 概要 (Overview)

• 本仕様書が定義する機能や処理の概要を記述します。

3. 入出力仕様 (Inputs & Outputs)

• 入力データパラメータ、リクエストフォーマット、出力レスポンスデータ構造を明記します。

4. 機能・振る舞い仕様 (Behavior & Logic)

• 正常系の処理フロー、ビジネスロジック、計算アルゴリズム等を記述します。フローや構成図は Mermaid 図（mermaid）を使用してください。

5. エラー・例外処理仕様 (Error Handling)

• 発生し得る例外ケース、エラーコード、エラー発生時の振る舞いを明記します。

6. 関連意思決定記録 (DR) とのインライン相互リンク

• 本機能仕様の決定根拠となる意思決定記録（DR-XXX.md）が存在する場合、 該当する振る舞い・仕様ロジック記述の直後に ([DR-001](../../decision-records/DR-001.md)) 形式でインライン記述 し、「関連」セクションにも相互リンクを記載します。

---

Template

1. 一般機能仕様書テンプレート (SPEC-001.md)

以下は機能仕様書（SPEC-XXX.md）を作成する際の標準Markdownテンプレートです。

---
name: SPEC-001.md
description: <機能仕様の1行概要>
timestamp: YYYY-MM-DD
ai: ai-coauthored
---

# SPEC-001: <機能名称>

## 概要

<本機能仕様が対象とする処理や機能の概要を記述します ([DR-001](../../decision-records/DR-001.md))。>

## 入力・出力仕様

### 入力パラメータ

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

### 出力仕様

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

## 機能・振る舞い仕様

```mermaid
sequenceDiagram
    Client->>API: リクエスト送信
    API-->>Client: 200 OK (Response)
```

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

## エラー・例外処理

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

## 関連 (References)

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

---

2. API機能仕様書テンプレート (specs/api/users.md)

以下はAPI機能仕様書（specs/api/*.md）を作成する際の標準Markdownテンプレートです。

---
name: users.md
description: ユーザー管理APIエンドポイント仕様群（一覧取得・新規作成・詳細取得・更新・削除）
timestamp: YYYY-MM-DD
ai: ai-coauthored
---

# API: /api/v1/users

## 概要

ユーザー情報のCRUD操作を提供するREST API群の仕様を定義します ([DR-001](../../decision-records/DR-001.md))。

---

## エンドポイント一覧

| Method | Path | 概要 | 認証 |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/users` | ユーザー一覧取得 | 必須 (Bearer) |
| `POST` | `/api/v1/users` | ユーザー新規登録 | 必須 (Admin) |
| `GET` | `/api/v1/users/{id}` | ユーザー詳細取得 | 必須 (Bearer) |
| `PUT` | `/api/v1/users/{id}` | ユーザー情報更新 | 必須 (Bearer/Admin) |
| `DELETE` | `/api/v1/users/{id}` | ユーザー論理削除 | 必須 (Admin) |

---

## メソッド詳細仕様

### GET /api/v1/users

ユーザーの一覧を検索・取得します。

#### クエリパラメータ

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| :--- | :--- | :--- | :--- | :--- |
| `limit` | integer | - | `20` | 取得件数 (最大: 100) |
| `offset` | integer | - | `0` | 取得開始位置 |

#### レスポンス (200 OK)

```json
{
  "users": [
    {
      "id": "usr_01",
      "name": "山田 太郎",
      "email": "yamada@example.com"
    }
  ],
  "total": 1
}
```

---

### POST /api/v1/users

ユーザーを新規登録します。

#### リクエストボディ

```json
{
  "name": "鈴木 一郎",
  "email": "suzuki@example.com",
  "password": "SecurePassword123!"
}
```

#### レスポンス (201 Created)

```json
{
  "id": "usr_02",
  "name": "鈴木 一郎",
  "email": "suzuki@example.com",
  "created_at": "2026-08-16T12:00:00Z"
}
```

---

### GET /api/v1/users/{id}

指定されたIDのユーザー詳細情報を取得します。

#### パスパラメータ

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

#### レスポンス (200 OK)

```json
{
  "id": "usr_01",
  "name": "山田 太郎",
  "email": "yamada@example.com",
  "role": "member"
}
```

---

## エラー仕様

| ステータスコード | エラーコード | 発生条件 | 処理内容 |
| :--- | :--- | :--- | :--- |
| 400 Bad Request | `ERR_VALIDATION_FAILED` | リクエストボディの型・制約不正 | エラー詳細メッセージを返却 |
| 401 Unauthorized | `ERR_UNAUTHORIZED` | 認証トークンが無効または期限切れ | 認証エラーを返却 |
| 404 Not Found | `ERR_USER_NOT_FOUND` | 指定IDのユーザーが存在しない | 該当リソースなしエラーを返却 |

## 関連 (References)

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