仕様書作成のベストプラクティス

はじめに

Vol.02で仕様書の重要性を説明しました。今回は、実際にどう書くかという実践的なベストプラクティスを紹介します。

仕様書の基本構成

# 機能名：○○機能

## 1. 概要
### 1.1 目的
この機能が必要な理由

### 1.2 対象ユーザー
誰がこの機能を使うのか

## 2. 機能要件
### 2.1 基本機能
- 機能A
- 機能B

### 2.2 制約条件
- 制約1
- 制約2

## 3. 詳細仕様
### 3.1 画面仕様
### 3.2 API仕様
### 3.3 データ仕様

## 4. エラー処理
## 5. テスト仕様

ベストプラクティス7選

1. 「なぜ」から始める

✗ 悪い例
「ログイン機能を実装する」

◯ 良い例
「ユーザーごとに学習進捗を管理するため、
ログイン機能を実装する。
これにより、学習履歴の保存と復元が可能になる」

2. 入出力を明確にする

【入力】
| 項目 | 型 | 必須 | 制約 |
|------|-----|------|------|
| email | string | ○ | メール形式 |
| password | string | ○ | 8文字以上 |

【出力】
| 項目 | 型 | 説明 |
|------|-----|------|
| user_id | integer | ユーザーID |
| token | string | 認証トークン |

3. 状態遷移を図示する

【ユーザー状態】
未登録 → 仮登録 → 本登録 → 退会

【遷移条件】
- 未登録→仮登録：メールアドレス入力
- 仮登録→本登録：メール認証完了
- 本登録→退会：退会申請

4. 境界値を明記する

【パスワード要件】
- 最小文字数：8文字（7文字はエラー）
- 最大文字数：100文字（101文字はエラー）
- 必須文字種：英字と数字を各1文字以上

5. エラーケースを網羅する

【エラー一覧】
| コード | 条件 | メッセージ |
|--------|------|-----------|
| E001 | メール未入力 | メールアドレスを入力してください |
| E002 | メール形式不正 | 正しいメールアドレスを入力してください |
| E003 | メール重複 | このメールアドレスは既に登録されています |

6. 具体例を添える

【リクエスト例】
POST /api/users
{
    "email": "test@example.com",
    "password": "password123"
}

【レスポンス例（成功）】
{
    "success": true,
    "data": {
        "user_id": 1,
        "email": "test@example.com"
    }
}

7. テスト方法を記載する

【テストケース】
□ 正常系
  - 有効なメール・パスワードで登録 → 成功

□ 異常系
  - メール未入力 → E001エラー
  - パスワード7文字 → E004エラー
  - 登録済みメール → E003エラー

チェックリスト

• □ 目的が明確に記載されているか
• □ 入出力が表形式で定義されているか
• □ 境界値が明記されているか
• □ エラーケースが網羅されているか
• □ 具体例が添えられているか
• □ テスト方法が記載されているか

まとめ

良い仕様書は、AIにも人間にも明確に意図を伝えます。これらのベストプラクティスを活用して、開発効率を向上させましょう。

---

次回：「コーディング規約の重要性」