kryota-dev/planning

実行計画の作成

概要

このドキュメントは、.claude/plansディレクトリに配置する実行計画ファイルの作成ガイドです。明確で実行可能な計画を作成するための指針を提供します。

ファイル名の規則

• 配置場所: .claude/plans ディレクトリに作成する
• 命名規則: YYYYMMDDHHMMSS_taskName.md 形式を使用する
  • date コマンドで現在時刻を取得してファイル名にすること
  • taskNameは英語で簡潔に記述（例：user-auth-implementation）

ファイル名生成例

# 現在時刻を取得してファイル名を生成
TIMESTAMP=$(date +"%Y%m%d%H%M%S")
TASK_NAME="your-task-name"
FILENAME="${TIMESTAMP}_${TASK_NAME}.md"
echo "ファイル名: ${FILENAME}"

実行計画の構造

必須セクション

実行計画には以下のセクションを必ず含めてください：

1. タイトルと概要

# [機能名] 実装計画

## 概要

[実装内容の簡潔な説明]

- なぜこの変更が必要か
- 解決する問題
- 期待される効果

2. ファイル変更計画

## ファイル変更計画

- 新規: `[ファイルパス]` - [目的]
- 更新: `[ファイルパス]` - [変更内容]
- 移動: `[移動元パス]` → `[移動先パス]` - [理由]
- 削除: `[ファイルパス]` - [理由]

3. 主要実装ステップ

## 主要実装ステップ

1. - [ ] [ステップ1の説明]
   - [詳細な作業内容]
   - [注意点や考慮事項]

2. - [ ] [ステップ2の説明]
   - [詳細な作業内容]
   - [依存関係]

3. - [ ] [ステップ3の説明]
   - [詳細な作業内容]
   - [検証方法]

4. 技術的考慮事項

## 技術的考慮事項

### [カテゴリ1]

- [重要な技術的ポイント]
- [設計上の決定事項]

### [カテゴリ2]

- [パフォーマンスへの影響]
- [セキュリティ考慮事項]

### 潜在的な課題

- [予想される問題]
- [対策案]

5. 見積時間

## 見積時間

総見積時間: [X時間]

- [作業項目1]: [X時間]
- [作業項目2]: [X時間]
- [作業項目3]: [X時間]
- テスト・デバッグ: [X時間]

オプションセクション

必要に応じて以下のセクションを追加してください：

注意点・改善提案

## 注意点・改善提案

### 実装時の注意点

- [重要な注意事項]
- [避けるべき実装パターン]

### 将来的な拡張性

- [将来の機能拡張の可能性]
- [アーキテクチャ上の考慮事項]

参考資料

## 参考資料

- [関連するPR]: [URL]
- [設計ドキュメント]: [URL]
- [技術仕様]: [URL]

Claude 4ベストプラクティスの適用

1. 明示的で具体的な指示

良い例：

- [ ] ユーザー認証APIエンドポイントの実装
  - POST /api/auth/login エンドポイントを作成
  - Zodスキーマによるリクエストバリデーション
  - JWTトークンの生成と返却
  - エラーハンドリング（401, 422, 500）の実装

避けるべき例：

- [ ] 認証機能の実装

2. コンテキストの提供

実装の背景や理由を明確に記述してください：

## 概要

ユーザーがログイン状態を維持できるよう、JWTベースの認証システムを実装する。
現在はセッションベースの認証を使用しているが、SPA（Single Page Application）
の特性上、トークンベースの認証がより適している。これにより、API呼び出し時の
認証状態の管理が簡素化され、フロントエンドとバックエンドの責任分離が明確になる。

3. 詳細な例と具体的な実装内容

抽象的な説明ではなく、具体的な実装内容を記述してください：

### API仕様

- **エンドポイント**: `POST /api/auth/login`
- **リクエスト形式**:
  ```json
  {
    "email": "[email protected]",
    "password": "securePassword123"
  }
  ```

- **レスポンス形式**:
  ```json
  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "user_123",
      "email": "[email protected]",
      "name": "John Doe"
    }
  }

### 4. 段階的な実装アプローチ

複雑な機能は段階的に実装できるよう分割してください：

```markdown
## 段階的実装計画

### フェーズ1: 基本認証機能

- [ ] ログインAPIの実装
- [ ] JWTトークン生成
- [ ] 基本的なエラーハンドリング

### フェーズ2: セキュリティ強化

- [ ] パスワードハッシュ化
- [ ] レート制限の実装
- [ ] トークンの有効期限管理

### フェーズ3: ユーザビリティ向上

- [ ] リフレッシュトークン機能
- [ ] ログアウト機能
- [ ] パスワードリセット機能
```

計画詳細化のための質問フレームワーク

実行計画を立てる際に、ユーザーからの要求が曖昧または不完全な場合は、以下の観点から質問を行い、計画をより詳細化してください。効果的な質問により、実装の成功率を大幅に向上させることができます。

質問すべきタイミング

以下の状況では、必ず詳細化のための質問を行ってください：

• ユーザーの要求が抽象的または曖昧な場合
• 複数の実装アプローチが考えられる場合
• 既存システムへの影響が不明確な場合
• 技術的制約や要件が明確でない場合
• ユーザビリティやUXの観点が不足している場合

質問の観点とフレームワーク

1. 機能要件の明確化

目的: 実装すべき機能の具体的な仕様を明確にする

質問例:

### 機能要件について

- この機能の主要なユースケースは何ですか？
- ユーザーはどのような操作フローを期待していますか？
- 必須機能と任意機能の優先順位はどうなっていますか？
- 既存の類似機能との違いや関連性はありますか？
- エラーケースや例外的な状況での動作はどうあるべきですか？

2. 技術的制約と要件

目的: 技術的な実装方針と制約を明確にする

質問例:

### 技術的要件について

- パフォーマンス要件（応答時間、スループットなど）はありますか？
- セキュリティ要件や認証・認可の考慮事項はありますか？
- 既存のAPIやデータベーススキーマとの互換性は必要ですか？
- 使用すべき特定の技術スタックやライブラリはありますか？
- スケーラビリティや将来の拡張性についての考慮事項はありますか？

3. ユーザーエクスペリエンス（UX）

目的: ユーザビリティとユーザーエクスペリエンスの要件を明確にする

質問例:

### UX要件について

- ターゲットユーザーの技術レベルや使用環境はどうですか？
- レスポンシブデザインやモバイル対応は必要ですか？
- アクセシビリティ要件（WCAG準拠など）はありますか？
- ユーザーフィードバック（成功・エラーメッセージ）の表示方法は？
- 既存のUIパターンとの一貫性は重要ですか？

4. データとビジネスロジック

目的: データ構造とビジネスルールを明確にする

質問例:

### データ・ビジネスロジックについて

- 扱うデータの種類、形式、サイズはどの程度ですか？
- データの永続化や保存期間についての要件はありますか？
- バリデーションルールや制約条件は何ですか？
- 他のシステムとのデータ連携は必要ですか？
- データの移行や既存データとの整合性は考慮すべきですか？

5. 運用と保守

目的: 運用面での要件と保守性を明確にする

質問例:

### 運用・保守について

- ログ出力や監視の要件はありますか？
- エラー処理や障害時の復旧方法はどうすべきですか？
- 設定変更や機能の有効/無効化は必要ですか？
- テスト戦略（単体テスト、統合テスト、E2Eテスト）はどうしますか？
- ドキュメント化すべき内容や範囲はありますか？

6. スケジュールとリソース

目的: プロジェクトの制約と優先順位を明確にする

質問例:

### スケジュール・リソースについて

- 実装完了の希望時期やマイルストーンはありますか？
- 段階的リリース（MVP、フェーズ分け）は可能ですか？
- 他の開発タスクとの依存関係や優先順位はどうですか？
- レビューやテストに必要な時間は確保されていますか？
- 外部リソースや承認プロセスは必要ですか？

効果的な質問のガイドライン

質問の作成原則

1. 具体的で明確: 曖昧な質問ではなく、具体的な回答を求める
2. 選択肢の提示: 可能な場合は選択肢を提示して回答しやすくする
3. 優先順位の明確化: 重要度の高い質問から順番に行う
4. 段階的な深掘り: 基本的な質問から詳細な質問へと段階的に進める

質問の例（良い例と悪い例）

良い例:

ユーザー認証機能について、以下の点を確認させてください：

1. 認証方式について：
   - JWTトークンベース認証
   - セッションベース認証
   - OAuth（Google、GitHub等）
     どちらを希望されますか？

2. パスワード要件について：
   - 最小文字数（8文字、12文字など）
   - 複雑性要件（大文字、小文字、数字、記号の組み合わせ）
     具体的な要件はありますか？

3. セキュリティ機能について：
   - 二要素認証（2FA）は必要ですか？
   - ログイン試行回数制限は必要ですか？
   - パスワードリセット機能は必要ですか？

悪い例:

認証機能について、どのような仕様にしますか？
セキュリティは重要ですか？

質問結果の活用

質問によって得られた情報は、以下のように実行計画に反映してください：

1. 要件の明文化

## 詳細化された要件

### 機能要件

- [質問結果に基づく具体的な機能要件]

### 技術要件

- [質問結果に基づく技術的制約と要件]

### UX要件

- [質問結果に基づくユーザーエクスペリエンス要件]

2. 実装方針の決定

## 実装方針

### アーキテクチャ決定

- [質問結果に基づく技術選択の理由]

### 段階的実装計画

- [質問結果に基づく優先順位と段階分け]

3. リスクと対策の明確化

## リスクと対策

### 特定されたリスク

- [質問によって明らかになった潜在的リスク]

### 対策案

- [各リスクに対する具体的な対策]

質問テンプレート

新しい実装計画を立てる際に使用できる質問テンプレート：

## 計画詳細化のための質問

### 基本要件

1. この機能の主要な目的と期待される効果は何ですか？
2. 主要なユーザーとそのユースケースを教えてください
3. 必須機能と任意機能の優先順位はどうなっていますか？

### 技術要件

1. パフォーマンス要件（応答時間、同時ユーザー数など）はありますか？
2. セキュリティ要件や認証・認可の考慮事項はありますか？
3. 既存システムとの互換性や連携要件はありますか？

### UX要件

1. ターゲットユーザーの技術レベルはどの程度ですか？
2. モバイル対応やレスポンシブデザインは必要ですか？
3. アクセシビリティ要件はありますか？

### 運用要件

1. ログ出力や監視の要件はありますか？
2. エラー処理や障害時の対応方法はどうすべきですか？
3. 設定変更や機能の有効/無効化は必要ですか？

### スケジュール

1. 実装完了の希望時期はありますか？
2. 段階的リリースは可能ですか？
3. 他のタスクとの依存関係はありますか？

品質チェックリスト

実行計画作成時に以下の項目を確認してください：

内容の完全性

• [ ] 概要が明確で理解しやすい
• [ ] 変更対象のファイルがすべて列挙されている
• [ ] 実装ステップが具体的で実行可能
• [ ] 技術的考慮事項が十分に検討されている
• [ ] 見積時間が現実的

技術的正確性

• [ ] ファイルパスが正確
• [ ] 技術仕様が既存のアーキテクチャと整合している
• [ ] 依存関係が適切に識別されている
• [ ] エラーハンドリングが考慮されている

実行可能性

• [ ] ステップが論理的な順序で配置されている
• [ ] 各ステップの完了条件が明確
• [ ] 必要なリソースや権限が特定されている
• [ ] テスト方法が定義されている

テンプレート

新しい実行計画を作成する際は、以下のテンプレートを使用してください：

# [機能名] 実装計画

## 計画詳細化のための質問（必要に応じて実施）

### 基本要件

1. この機能の主要な目的と期待される効果は何ですか？
2. 主要なユーザーとそのユースケースを教えてください
3. 必須機能と任意機能の優先順位はどうなっていますか？

### 技術要件

1. パフォーマンス要件（応答時間、同時ユーザー数など）はありますか？
2. セキュリティ要件や認証・認可の考慮事項はありますか？
3. 既存システムとの互換性や連携要件はありますか？

### UX要件

1. ターゲットユーザーの技術レベルはどの程度ですか？
2. モバイル対応やレスポンシブデザインは必要ですか？
3. アクセシビリティ要件はありますか？

### 運用要件

1. ログ出力や監視の要件はありますか？
2. エラー処理や障害時の対応方法はどうすべきですか？
3. 設定変更や機能の有効/無効化は必要ですか？

### スケジュール

1. 実装完了の希望時期はありますか？
2. 段階的リリースは可能ですか？
3. 他のタスクとの依存関係はありますか？

実行計画の更新

実装中に計画の変更が必要になった場合：

1. 進捗の記録: 完了したステップにチェックマークを付ける
2. 変更の記録: 計画からの変更点を記録する
3. 学習の記録: 実装中に得られた知見を記録する

進捗記録の例

## 主要実装ステップ

1. - [x] ユーザー認証APIの実装 ✅ 完了 (2024-01-15)
2. - [x] フロントエンド認証フォームの実装 ✅ 完了 (2024-01-16)
3. - [ ] 認証状態管理の実装 🚧 進行中
4. - [ ] テストの実装

## 実装中の変更点

- **2024-01-16**: パスワードバリデーションのルールを変更（最小8文字 → 最小12文字）
- **2024-01-16**: エラーメッセージの表示方法をトーストからインラインに変更

まとめ

効果的な実行計画は：

1. 明確で具体的: 曖昧さを排除し、実行可能な指示を提供
2. 包括的: すべての必要な作業とファイル変更を網羅
3. 構造化: 論理的な順序で整理された実装ステップ
4. 現実的: 実現可能な見積時間と技術的制約の考慮
5. 保守可能: 将来の変更や拡張を考慮した設計
6. 詳細化された: 適切な質問により要件が明確化されている

質問フレームワークの活用により期待される効果

• 実装の成功率向上: 曖昧な要件による手戻りの削減
• 品質の向上: 技術的制約やUX要件の事前考慮
• 効率的な開発: 明確な優先順位と段階的実装計画
• リスクの軽減: 潜在的な問題の早期発見と対策
• ステークホルダーとの合意形成: 共通理解に基づく開発進行

これらの原則と質問フレームワークに従って実行計画を作成することで、効率的で品質の高い実装が可能になります。