project-planner

プロジェクトプランナースキル

このスキルでは、AI 支援による実装の青写真となる、包括的なプロジェクト計画書を作成するためのテンプレートとガイダンスを提供します。

クイックスタート

ユーザーが新しいプロジェクトを始めたい場合は、次の3つの主要なドキュメントを作成します。

1. 要件定義書 - 受け入れ基準を含むユーザーストーリー
2. 設計書 - 技術アーキテクチャとコンポーネント仕様
3. 実装計画 - 要件とのトレーサビリティを備えた階層的なタスク分解

明示的なアーキテクチャ計画が効果を発揮する理由

役割、責任、成果物を事前に明確に定めることで、プロジェクトの成果は大きく向上します。

事前定義のメリット

1. コンポーネントの明確化 - すべてのシステムコンポーネントを先に定義することで、スコープの拡大を防ぎ、網羅性を確保します
2. データフローの可視化 - データの流れを早い段階でマッピングすることで、統合の複雑さやパフォーマンスのボトルネックが明らかになります
3. 統合計画 - すべての接点を事前に特定することで、実装中に予期せぬ依存関係が発生するのを防ぎます
4. 明確な境界 - 対象範囲に含まれるものと含まれないものを明示することで、作業に集中し、機能の逸脱を防ぎます
5. 測定可能な成功 - 具体的な目標と制約により、客観的な進捗管理が可能になります

アーキテクトの考え方

プロジェクトアーキテクトとして計画を立てる際は、次の点を意識します。

• システム思考 - 部分に踏み込む前に、全体を捉えます
• インターフェース優先の設計 - 内部の詳細より先に、コンポーネント間の契約を定義します
• トレーサビリティ重視 - すべての要件を設計要素とタスクに対応付けます
• 制約への意識 - 意思決定の指針とするため、制限事項を事前に把握します
• 成果物重視 - 作成する成果物を正確に把握します

ドキュメント作成ワークフロー

1. プロジェクトアーキテクトの役割定義

プロジェクトを開始する際は、明確な責任を設定し、Claudeをプロジェクトアーキテクトとして明示的に定義します。

役割： システムアーキテクト兼計画スペシャリスト 責任：

• すべてのコンポーネントを含む、完全なシステムアーキテクチャを定義する
• システム要素間のデータフローをマッピングする
• すべての統合ポイントとインターフェースを特定する
• 明確なプロジェクトの境界と制約を定める
• 実装タスクまで追跡可能な要件を作成する

2. 初期プロジェクトの理解

ドキュメントを作成する前に、重要な情報とアーキテクチャ要素を収集します。

Required Project Information:
- Project name and purpose
- Target users (single-user local, multi-tenant SaaS, etc.)
- Core functionality (3-5 main features)
- Technical preferences (languages, frameworks, deployment)
- Non-functional requirements (performance, security, scalability)

Required Architectural Elements (define upfront):
- System Components: All major modules/services and their purposes
- Data Flow: How data moves through the entire system
- Integration Points: All external APIs, services, databases
- System Boundaries: What's in scope vs out of scope
- Constraints: Technical, business, and resource limitations
- Success Metrics: Clear, measurable goals for the system

3. 成果物の定義（事前に設定）

ドキュメント作成を始める前に、すべての成果物を明示的に定義します。

Standard Deliverables Package:
1. Requirements Document
   - User stories with measurable acceptance criteria
   - Complete glossary of terms
   - Traceable requirement IDs
   
2. System Design Document  
   - Component architecture diagram
   - Data flow diagrams for all major processes
   - Integration point specifications
   - API/Interface contracts
   - Performance and scaling targets
   
3. Implementation Plan
   - Hierarchical task breakdown
   - Requirement-to-task mapping
   - Dependency graph
   - Phase-based delivery schedule

Optional Deliverables (specify if needed):
- API Documentation
- Database Schema Design
- Security Threat Model
- Deployment Guide
- Testing Strategy Document

4. 要件定義書の作成

要件テンプレートを使用して、ユーザーの視点に立った仕様を作成します。

# Execute this to generate requirements structure
requirements = {
    "introduction": "System purpose and scope",
    "glossary": "Domain-specific terms",
    "requirements": [
        {
            "id": "REQ-X",
            "user_story": "As a [role], I want [feature], so that [benefit]",
            "acceptance_criteria": [
                "WHEN [condition], THE system SHALL [behavior]",
                "WHERE [context], THE system SHALL [behavior]",
                "IF [condition], THEN THE system SHALL [behavior]"
            ]
        }
    ]
}

5. 設計書の作成

明示的なアーキテクチャ要素を含む技術仕様を作成します。

# Execute this to generate comprehensive design structure
design = {
    "overview": "High-level system description",
    "architecture": {
        "diagram": "ASCII or visual representation of all components",
        "components": [
            {
                "id": "COMP-1",
                "name": "Component Name",
                "type": "Frontend/Backend/Service/Database",
                "responsibility": "Single clear purpose",
                "boundaries": "What it does and doesn't do"
            }
        ]
    },
    "data_flow": {
        "primary_flows": [
            {
                "name": "User Registration Flow",
                "steps": [
                    "1. User submits form → Frontend",
                    "2. Frontend validates → API Gateway",
                    "3. API Gateway → Auth Service",
                    "4. Auth Service → User Database",
                    "5. Response flows back"
                ],
                "data_transformations": "How data changes at each step"
            }
        ]
    },
    "integration_points": [
        {
            "name": "External Payment API",
            "type": "REST/GraphQL/WebSocket/Database",
            "purpose": "Process payments",
            "interface": "API contract definition",
            "authentication": "Method used",
            "error_handling": "Retry/fallback strategy"
        }
    ],
    "components_detail": [
        {
            "name": "Component Name",
            "responsibility": "What it does",
            "key_classes": ["Class descriptions"],
            "interfaces": "API/method signatures",
            "dependencies": "What it needs to function",
            "performance": "Targets and constraints"
        }
    ],
    "data_models": "Entity definitions with relationships",
    "system_boundaries": {
        "in_scope": ["What the system handles"],
        "out_of_scope": ["What it delegates or ignores"],
        "assumptions": ["External dependencies assumed available"]
    },
    "error_handling": "Strategies for failures",
    "testing_strategy": "Unit, integration, performance",
    "deployment": "Docker, environment, configuration"
}

6. 実装計画の作成

明確なスコープ境界を定め、プロジェクトを実行可能なタスクに分割します。

# Execute this to generate task structure with boundaries
tasks = {
    "project_boundaries": {
        "must_have": ["Core features for MVP"],
        "nice_to_have": ["Enhancement features"],
        "out_of_scope": ["Features explicitly excluded"],
        "technical_constraints": ["Framework/library limitations"]
    },
    "phases": [
        {
            "id": 1,
            "name": "Infrastructure Setup",
            "deliverables": ["What this phase produces"],
            "tasks": [
                {
                    "id": "1.1",
                    "description": "Task description",
                    "subtasks": ["Specific actions"],
                    "requirements_fulfilled": ["REQ-1.1", "REQ-2.3"],
                    "components_involved": ["COMP-1", "COMP-3"],
                    "dependencies": [],
                    "estimated_hours": 4,
                    "success_criteria": "How to verify completion"
                }
            ]
        }
    ]
}

要件定義書テンプレート

# Requirements Document

## Introduction

[System description in 2-3 sentences. Target user and deployment model.]

## Glossary

- **Term**: Definition specific to this system
- **Component**: Major system module or service
[Add all domain-specific terms]

## Requirements

### Requirement [NUMBER]

**User Story:** As a [user type], I want [capability], so that [benefit]

#### Acceptance Criteria

1. WHEN [trigger/condition], THE [component] SHALL [action/behavior]
2. WHERE [mode/context], THE [component] SHALL [action/behavior]  
3. IF [condition], THEN THE [component] SHALL [action/behavior]
4. THE [component] SHALL [capability with measurable target]

[Repeat for each requirement]

要件定義のベストプラクティス

1. 要件ごとに機能を1つにする - 各要件は単一の機能を対象とします
2. テスト可能な基準にする - すべての基準を検証可能にします
3. 必須事項にはSHALLを使う - RFC 2119のキーワードを一貫して使用します
4. パフォーマンス目標を含める - 「Xミリ秒／秒以内」
5. すべての状態を指定する - 成功、失敗、エッジケース
6. 体系的に番号を付ける - トレーサビリティのため、REQ-1、REQ-2のようにします

受け入れ基準のパターン

Behavior criteria:
- WHEN [event occurs], THE system SHALL [respond]
- THE system SHALL [provide capability]
- THE system SHALL [enforce rule/limit]

Conditional criteria:
- IF [condition], THEN THE system SHALL [action]
- WHERE [mode is active], THE system SHALL [behavior]

Performance criteria:
- THE system SHALL [complete action] within [time]
- THE system SHALL support [number] concurrent [operations]
- THE system SHALL maintain [metric] above/below [threshold]

Data criteria:
- THE system SHALL persist [data type] with [attributes]
- THE system SHALL validate [input] against [rules]
- THE system SHALL return [data] in [format]

設計書テンプレート

# Design Document

## Overview

[System architecture summary in 3-4 sentences. Key design decisions and priorities.]

## System Architecture

### Component Map

| Component ID | Name | Type | Responsibility | Interfaces With |
|-------------|------|------|----------------|-----------------|
| COMP-1 | Web Frontend | UI | User interface | COMP-2 |
| COMP-2 | API Gateway | Service | Request routing | COMP-3, COMP-4 |
| COMP-3 | Business Logic | Service | Core processing | COMP-5 |
[Complete component inventory]

### High-Level Architecture Diagram

[ASCII diagram showing all components and their relationships]

## Data Flow Specifications

### Primary Data Flows

#### 1. [Flow Name] (e.g., User Authentication)

1. [ソース] → [コンポーネント]： [データの説明]
2. [コンポーネント] → [コンポーネント]： [適用される変換]
3. [コンポーネント] → [送信先]： [最終的なデータ形式]

**Data Transformations:**
- Step 2: [How data changes]
- Step 3: [Validation/Processing applied]

[Repeat for each major data flow]

## Integration Points

### Internal Integration Points

| Source | Target | Protocol | Data Format | Purpose |
|--------|--------|----------|-------------|---------|
| Frontend | API Gateway | HTTPS/REST | JSON | API calls |
| API Gateway | Auth Service | gRPC | Protobuf | Authentication |
[All internal integrations]

### External Integration Points

#### [External System Name]

**Type:** REST API / Database / Message Queue / etc.
**Purpose:** [What this integration provides]
**Endpoint:** [URL/Connection string pattern]
**Authentication:** [Method - OAuth2, API Key, etc.]
**Rate Limits:** [Any constraints]

**Interface Contract:**
```language
// Request format
POST /api/endpoint
{
    "field": "type"
}

// Response format  
{
    "result": "type"
}

エラー処理：

• 再試行戦略： [指数バックオフ、サーキットブレーカー]
• フォールバック： [利用できない場合の動作]
• モニタリング： [問題の検出方法]

[外部統合ごとに繰り返す]

コンポーネントとインターフェース

1. [コンポーネント名]

責務： [1 文で説明]

主要クラス：

• ClassName：[目的と主なメソッド]
• ServiceName：[管理対象]

インターフェース：

class InterfaceName:
    def method_name(params) -> ReturnType
    # Core methods only

データフロー：

• [ソース] から [入力] を受け取る
• [アルゴリズム／ロジック] で処理する
• [結果] を [宛先] に出力する

パフォーマンス：

• 目標：[指標と値]
• 制約：[制限事項]

[主要なコンポーネントごとに繰り返す]

データモデル

[エンティティ名]

@dataclass
class EntityName:
    field: Type
    field: Optional[Type]
    # Core fields only

エラー処理

[エラーカテゴリ]

種類： [エラーシナリオの一覧] 処理： [戦略と復旧方法]

テスト戦略

単体テスト

• [コンポーネント]：[対象項目] をテストする
• カバレッジ目標：80%

統合テスト

• [フロー]：[エンドツーエンドのシナリオ] をテストする

パフォーマンステスト

• [操作]：[指標] を目標とする

デプロイ

Docker の設定

# Essential service definitions only

環境変数

CATEGORY_VAR=description

パフォーマンス目標

• [操作]：<[時間]
• [スループット]：>[レート]
• [リソース]：<[上限]

セキュリティに関する考慮事項

• [該当する場合は認証方式]
• [データ保護の方法]
• [アクセス制御モデル]

### Design Best Practices

1. **Component responsibilities** - Single, clear purpose per component
2. **Interface first** - Define contracts before implementation
3. **Data flow clarity** - Show how data moves through system
4. **Error categories** - Group related failures with consistent handling
5. **Performance targets** - Specific, measurable goals
6. **Deployment ready** - Include Docker and configuration

## Implementation Plan Template

```markdown
# Implementation Plan

- [x] 1. [Phase Name]
  
  - [x] 1.1 [Task name]
    - [Subtask description]
    - [Subtask description]
    - _Requirements: [REQ-X.Y, REQ-A.B]_
    
  - [ ] 1.2 [Task name]
    - [Subtask description]
    - _Requirements: [REQ-X.Y]_
    - _Dependencies: Task 1.1_

- [ ] 2. [Phase Name]

  - [ ] 2.1 [Task name]
    - [Detailed steps or subtasks]
    - _Requirements: [REQ-X.Y]_
    - _Dependencies: Phase 1_

[Continue for all phases]

タスク計画のベストプラクティス

1. 階層構造 - フェーズ > タスク > サブタスク
2. 要件の追跡 - 各タスクを要件に関連付ける
3. 依存関係の明示 - ブロッカーと前提条件を特定する
4. チェックボックス形式 - 完了には [x]、未完了には [ ] を使用する
5. アトミックなタスク - 各タスクを独立して完了できるようにする
6. 段階的な実装 - インフラストラクチャ → コア機能 → 機能 → 仕上げ

一般的な実装フェーズ

1. **Infrastructure Setup**
   - Project structure
   - Database schema
   - Docker configuration
   - Core dependencies

2. **Data Layer**
   - Models/entities
   - Database operations
   - Migrations

3. **Business Logic**
   - Core algorithms
   - Service classes
   - Validation rules

4. **API/Interface Layer**
   - REST/GraphQL endpoints
   - WebSocket handlers
   - Authentication

5. **Frontend/UI**
   - Component structure
   - State management
   - API integration
   - Responsive design

6. **Integration**
   - External services
   - Third-party APIs
   - Message queues

7. **Testing**
   - Unit tests
   - Integration tests
   - End-to-end tests

8. **DevOps**
   - CI/CD pipeline
   - Monitoring
   - Logging
   - Deployment scripts

9. **Documentation**
   - API documentation
   - User guides
   - Deployment guide
   - README

プロジェクトの種類別ドキュメントパターン

Web アプリケーション（フルスタック）

要件の重点：

• ユーザー認証と認可
• エンティティの CRUD 操作
• リアルタイム更新
• レスポンシブ UI
• API 設計

設計の重点：

• 3 層アーキテクチャ（フロントエンド、バックエンド、データベース）
• REST／GraphQL API 設計
• 状態管理戦略
• コンポーネント階層
• データベーススキーマ

タスクの重点：

1. データベースとバックエンドのセットアップ
2. API の実装
3. フロントエンドコンポーネント
4. 統合とテスト

マイクロサービスシステム

要件の重点：

• サービス境界
• サービス間通信
• データ整合性
• サービスディスカバリー
• フォールトトレランス

設計の重点：

• サービスの分割
• サービス間の API コントラクト
• メッセージキュー／イベントバス
• 分散トレーシング
• コンテナオーケストレーション

タスクの重点：

1. サービスのスキャフォールディング
2. 共有ライブラリ／コントラクト
3. 個々のサービスの実装
4. 統合レイヤー
5. オーケストレーションのセットアップ

データパイプライン／ETL

要件の重点：

• データソースと形式
• 変換ルール
• データ品質チェック
• スケジュール／トリガー
• エラー処理と再試行

設計の重点：

• パイプラインの各段階
• データフロー図
• スキーマの進化
• 監視とアラート
• ストレージ戦略

タスクの重点：

1. データソースコネクター
2. 変換ロジック
3. 検証と品質チェック
4. スケジュール設定
5. 監視の実装

CLI ツール／ライブラリ

要件の重点：

• コマンド構造
• 入出力形式
• 設定オプション
• エラーメッセージ
• パフォーマンス要件

設計の重点：

• コマンドパーサーのアーキテクチャ
• プラグインシステム（該当する場合）
• 設定管理
• 出力フォーマッター
• テスト戦略

タスクの重点：

1. コアとなるコマンド構造
2. ビジネスロジックの実装
3. 入出力ハンドラー
4. 設定システム
5. ドキュメントと例

特定の分野向けドキュメントの生成

トレーディング／金融システム

追加要件：

• リスク管理ルール
• 注文執行ロジック
• 市場データの処理
• コンプライアンス要件
• 監査証跡

追加設計：

• 高頻度データ処理
• ポジション追跡
• リスク計算
• 注文ルーティング
• フェイルオーバー戦略

リアルタイムシステム（チャット、ゲーム、IoT）

追加要件：

• レイテンシの目標
• 接続処理
• 状態同期
• オフライン対応
• プッシュ通知

追加設計：

• WebSocket/SSE アーキテクチャ
• 状態管理
• キャッシュ戦略
• メッセージキューイング
• 水平スケーリング

機械学習システム

追加要件：

• モデルトレーニングパイプライン
• 特徴量エンジニアリング
• モデルのバージョン管理
• 予測 API
• モニタリング／ドリフト検出

追加設計：

• トレーニングインフラストラクチャ
• 特徴量ストア
• モデルレジストリ
• サービングアーキテクチャ
• A/B テストフレームワーク

品質チェックリスト

ドキュメントを仕上げる前に、以下を確認してください。

要件ドキュメント

• すべての要件に明確なユーザーストーリーがある
• すべての受け入れ基準がテスト可能である
• 非機能要件（パフォーマンス、セキュリティ）が指定されている
• 用語集にすべてのドメイン用語が記載されている
• 要件が追跡できるように番号付けされている

設計ドキュメント

• アーキテクチャ図が含まれている
• すべてのコンポーネントの責任が明確である
• 統合ポイントのインターフェースが定義されている
• エラー処理戦略が文書化されている
• パフォーマンス目標が指定されている
• デプロイ設定が含まれている

実装計画

• タスクが論理的なフェーズごとにまとめられている
• タスク間の依存関係が特定されている
• 要件とタスクが対応付けられている
• タスクが個別に完了できる単位になっている
• 進捗管理にチェックボックス形式を使用している

使用例のパターン

新しいプロジェクトを開始する（アーキテクチャを明示的に重視）

User: "I want to build an order flow trading automation system"

Response: "I'll act as your Project Architect to create comprehensive planning documents. 

First, let me establish the architectural foundation:

**System Components I need to define:**
- Market data ingestion service
- Order flow analysis engine  
- Trading signal generator
- Risk management module
- Order execution service
- Monitoring dashboard

**Data Flows to map:**
- Market data → Analysis → Signals → Execution
- Position tracking → Risk calculation → Trading limits
- All events → Audit trail

**Integration Points to specify:**
- Exchange APIs (which ones?)
- Database system (time-series data needs?)
- Notification services (alerts/reporting?)

**Key Questions:**
1. Is this for personal use (single-user) or a platform (multi-user)?
2. Which specific exchanges/brokers will it connect to?
3. What are your latency requirements (milliseconds matter)?
4. What's your risk tolerance and position sizing approach?
5. Do you need backtesting capabilities?

**Deliverables I'll create:**
1. Requirements document with traceable user stories
2. System design with complete component map and data flows
3. Implementation plan with phased delivery milestones

This architectural blueprint will ensure nothing is overlooked during implementation."

新しいプロジェクトを開始する（シンプルな方法）

User: "I want to build an order flow trading automation system"

Response: "I'll help you create comprehensive planning documents for your trading system. Let me gather some key information:

1. Is this for personal use (single-user) or a multi-user platform?
2. Which markets/exchanges will it connect to?
3. What are the core trading strategies or patterns?
4. Any specific performance requirements (latency, throughput)?

Based on this, I'll generate:
- Requirements document with user stories
- System design with components and data flow
- Implementation plan with phases and tasks"

既存の要件を拡張する

User: "Add real-time monitoring dashboard to the requirements"

Response: "I'll add dashboard requirements to your document:

### Requirement 15
**User Story:** As a trader, I want a real-time dashboard, so that I can monitor system performance and trading activity

#### Acceptance Criteria
1. THE Dashboard SHALL display active positions with current P&L
2. THE Dashboard SHALL update market data within 1 second
3. THE Dashboard SHALL provide filtering by symbol, timeframe, and date range
4. WHEN a trade executes, THE Dashboard SHALL reflect it within 100ms"

よくある落とし穴

計画に関する落とし穴

1. アーキテクチャ計画を省略する - 先にコンポーネントを整理せず、要件の定義に取りかかる
2. 役割の定義が曖昧 - アーキテクトの役割を明確にしないと、焦点の定まらないドキュメントになる
3. 隠れた統合ポイント - 実装中に外部依存関係が判明する
4. 境界が未定義 - スコープが明確でないと、機能の肥大化やスケジュールの遅延につながる
5. データフロー分析が不足 - データの流れを整理しないと、問題の発見が遅れる

要件に関する落とし穴

1. 実装を過度に細かく指定する - 要件で定義すべきなのは「何を」であり、「どのように」ではない
2. 受け入れ基準が曖昧 - 指標なしに「使いやすい」や「速い」といった表現を使わない
3. エラーケースが不足 - 要件に障害シナリオを含める
4. 追跡できない要件 - すべての要件をタスクに対応付ける

設計に関する落とし穴

1. モノリシックなコンポーネント - 大きなコンポーネントを、役割を絞ったサービスに分割する
2. 循環依存 - タスクの依存関係が DAG を形成するようにする
3. データモデルが不足 - 中核となるエンティティを早い段階で定義する
4. デプロイを無視する - 最初から Docker／デプロイを含める
5. コンポーネントの境界が不明確 - 各コンポーネントの責任を明示する

出力形式

編集やバージョン管理が容易になるよう、ドキュメントを Markdown 形式で生成してください。以下を使用してください。

• 明確な階層構造の見出し（##、###、####）
• 言語ヒント付きのコードブロック
• 箇条書きと番号付きリスト
• 構造化データ用の表
• タスク追跡用のチェックボックス
• 重要な用語の強調に太字
• 技術用語のインラインコード

ドキュメントは以下の名前で保存してください。

• requirements.md - 要件ドキュメント
• design.md - 設計ドキュメント
• tasks.md - 実装計画

これらのドキュメントは、AI 支援による実装の基盤となり、開発全体を通して参照できる明確な仕様を提供します。