271 lines
7.2 KiB
Markdown
271 lines
7.2 KiB
Markdown
---
|
||
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` で確認できます
|