project-planner

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

実行環境

パスの種類	説明
使用方法	このスキルはテンプレートとガイダンスを提供します。ローカルスクリプトの実行は不要です
呼び出しシナリオ	ユーザーがプロジェクト計画、要件文書、システム設計を必要とする場合に自動的に有効になります
出力形式	Markdown 文書（requirements.md、design.md、tasks.md）

パスの説明

• ローカルパスへの依存なし：このスキルは文書テンプレートを生成するもので、ローカルスクリプトの実行は伴いません
• 生成される文書：コマンドの実行時における現在のディレクトリ（process.cwd()）に保存されます
• プロジェクトのコンテキスト：現在の作業ディレクトリに基づいてプロジェクトのルートディレクトリを特定します

このスキルは、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つの要件につき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 支援による実装の基盤となり、開発全体を通して参照できる明確な仕様を提供します。