---
description: 機能仕様ドキュメントを作成する
argument-hint: [追加の指示（オプション）]
---

# 機能仕様ドキュメントの作成

前のステップで整理した要件に基づいて、詳細な機能仕様書を作成します。

## 追加の指示
$ARGUMENTS

## 前提条件の確認

ドキュメント作成を開始する前に、以下を確認してください：

### 1. タスクファイルの存在確認

```javascript
const fs = require('fs');
const tasksFile = '.tasks.json';

if (!fs.existsSync(tasksFile)) {
  console.log('❌ タスクファイルが見つかりません');
  console.log('\n先に要件整理を実行してください:');
  console.log('  /new-feature [機能の説明]');
  process.exit(1);
}
```

### 2. 前のステップ（要件整理）の完了確認

```javascript
const data = JSON.parse(fs.readFileSync(tasksFile, 'utf-8'));

// タスクID 1 (要件整理) が完了しているか確認
const requirementTask = data.tasks.find(t => t.id === 1);

if (!requirementTask || requirementTask.status !== 'completed') {
  console.log('❌ 要件整理が完了していません');
  console.log('\n先に要件整理を完了してください:');
  console.log('  /new-feature [機能の説明]');
  process.exit(1);
}
```

### 3. 重複実行の防止

```javascript
// タスクID 2 (ドキュメント作成) の状態を確認
const docTask = data.tasks.find(t => t.id === 2);

if (docTask && docTask.status === 'completed') {
  console.log('⚠️  ドキュメントは既に作成されています');
  console.log('\nドキュメントを確認:');
  console.log('  docs/ ディレクトリを参照');
  console.log('\n再作成する場合は、既存のドキュメントを削除してから実行してください。');
  console.log('次のステップに進む場合:');
  console.log('  /resume');
  process.exit(0);
}
```

## ドキュメント作成の指針

前提条件を満たしていることを確認したら、`doc-writer` エージェントを使って、階層的なドキュメント構造を作成してください。

### ドキュメント構造

**重要**: ドキュメントは単一ファイルではなく、`docs/` ディレクトリ配下に適切な階層構造として作成します。

```
docs/
├── README.md                    # ドキュメント全体のインデックス
├── 00-overview/                 # 全体設計
├── 01-requirements/            # 要件定義
├── 02-design/                  # 基本設計
├── 03-detailed-design/         # 詳細設計（機能ごと）
├── 04-api/                     # API設計
├── 05-interface/               # インターフェース設計
├── 06-test/                    # テスト設計
└── 07-implementation/          # 実装ガイド
```

### 作成する内容

#### 1. 概要
```markdown
# [機能名]

## 目的
[この機能が解決する課題]

## 期待される効果
- [効果1]
- [効果2]
```

#### 2. 機能要件
```markdown
## 機能要件

### ユーザーストーリー
- As a [ユーザー], I want to [やりたいこと], so that [理由]

### 機能詳細
#### [機能1]
- 説明: [...]
- 入力: [...]
- 出力: [...]
- 振る舞い: [...]

#### [機能2]
...
```

#### 3. 技術仕様
```markdown
## 技術仕様

### アーキテクチャ
[システム構成図や説明]

### データモデル
[必要なデータ構造]

### API仕様
[エンドポイント、リクエスト/レスポンス形式]

### インターフェース
[関数シグネチャ、クラス定義など]
```

#### 4. 非機能要件
```markdown
## 非機能要件

- **パフォーマンス**: [レスポンスタイム、スループット]
- **セキュリティ**: [認証、認可、データ保護]
- **スケーラビリティ**: [負荷対応]
- **互換性**: [ブラウザ、OS、バージョン]
```

#### 5. UI/UX（該当する場合）
```markdown
## UI/UX

### 画面遷移
[遷移図やフロー]

### インタラクション
[ユーザー操作とシステム応答]

### エラーハンドリング
[エラーメッセージ、リカバリー方法]
```

#### 6. テスト戦略
```markdown
## テスト戦略

### テスト観点
- [正常系のテストケース]
- [異常系のテストケース]
- [境界値テスト]
- [エッジケース]

### パフォーマンステスト
[必要な場合]
```

#### 7. 実装の考慮事項
```markdown
## 実装の考慮事項

### 既存コードへの影響
[変更が必要な箇所、依存関係]

### マイグレーション
[必要な場合の移行計画]

### ロールバック
[問題発生時の対応]
```

## ドキュメント保存先とリンク

### ディレクトリ作成

プロジェクトルートに `docs/` ディレクトリを作成し、必要なサブディレクトリを作成します。

機能の規模に応じて、以下のように調整してください：

**小規模機能**: 最小限のディレクトリ（requirements, detailed-design）
**中規模機能**: 主要なディレクトリ（overview, requirements, design, api/interface）
**大規模機能**: 完全なディレクトリ構造

### 相互リンクの設定

各ドキュメント間で適切にリンクを設定してください：

```markdown
# 例: 01-requirements/functional.md
詳細な設計については [詳細設計](../03-detailed-design/[feature-name]/README.md) を参照してください。

# 例: 04-api/[endpoint].md
データモデルの詳細は [データモデル](../02-design/data-model.md) を参照してください。
```

### インデックスファイル (docs/README.md)

ルートの README.md にすべてのドキュメントへのリンクを含めてください：

```markdown
# [機能名] - ドキュメント

## 📚 ドキュメント構成

### [全体設計](./00-overview/README.md)
- [アーキテクチャ](./00-overview/architecture.md)

### [要件定義](./01-requirements/README.md)
- [機能要件](./01-requirements/functional.md)
- [非機能要件](./01-requirements/non-functional.md)

[...]
```

## タスク状態の更新

ドキュメント作成を開始する前に、タスク状態を更新してください：

```javascript
// .tasks.json の該当タスクを更新
{
  "id": 2,
  "type": "workflow",
  "name": "ドキュメント作成",
  "status": "in_progress",  // pending → in_progress
  "command": "/create-docs",
  "startedAt": "[現在時刻]"
}
```

ドキュメント作成が完了したら：

```javascript
{
  "id": 2,
  "status": "completed",  // in_progress → completed
  "completedAt": "[現在時刻]"
}
```

## 次のステップ

ドキュメントを作成したら、ユーザーに以下を確認してください：

```
ドキュメントを確認してください。
承認いただければ、次のステップ（テスト作成）を自動的に開始します。

承認しますか？ (yes/no)
```

**ユーザーが承認した場合**: SlashCommandツールを使って `/create-tests` を実行してください。

**注意**:
- `post-docs-check` フックが自動的に実行され、ドキュメントの完全性をチェックします
- タスク進捗は `/list-tasks` で確認できます