敏捷設計ドキュメント生成

核心原則

1. MVP導向、過度な設計を避ける

• 敏捷開発は迅速なイテレーションを目標とするため、すべての境界条件を考慮する必要はありません
• コア機能に焦点を当て、主要でない機能は後続のイテレーションで対応できます
• 「完全性」のために不要な機能を追加しないでください

2. 既存の技術スタックに基づく

• プロジェクト設定ファイル（pyproject.toml、package.jsonなど）を最初に読み込み、技術スタックを理解する必要があります
• 既存のコンポーネントを再利用し、車輪の再発明を避けます
• 設計案は現在の技術スタックと互換性がある必要があります

3. 設計意図を明確に説明する

• 今回の設計で解決する問題または提供する機能を明確にします
• mermaid シーケンス図を使用してインタラクションフローを示します
• 各機能ポイントに対して、実装アイデアと重要なメソッドを示します
• 複雑なロジックは mermaid を使用してフローを実装します
• サンプルコードを提供して、重要な実装を説明します

4. 洗練されたドキュメント、技術者向け

• 読者は開発者とビジネスを理解しているプロダクト担当者です
• 長々とした背景説明や無駄話を避けます
• 既存のコンポーネントを理解してから、重複した設計を避けます

ワークフロー

第一段階：事前分析

設計ドキュメントを生成する前に、次の分析を完了する必要があります。

1.1 プロジェクトの背景を理解する

ユーザーに質問するか、プロジェクトを分析します：
- プロジェクトの背景は？ 現在どのようなシステムで、どのような機能/モジュールを作成しますか？

1.2 技術スタックを識別する

必ず読み込む必要がある設定ファイル：
- Python プロジェクト：pyproject.toml, requirements.txt, setup.py
- Node.js プロジェクト：package.json, yarn.lock, pnpm-lock.yaml
- Java プロジェクト：pom.xml, build.gradle
- Go プロジェクト：go.mod, go.sum
- その他：プロジェクトの種類に応じて識別

分析内容：
- 主要なフレームワークとライブラリ
- データベースとストレージ
- メッセージキューとミドルウェア
- デプロイと運用ツール

1.3 既存のコンポーネントを理解する

次の方法で既存のコンポーネントを理解します：
1. ユーザーに質問する：再利用できる既存のコンポーネントはありますか？
2. プロジェクト構造を読み取る：src/、lib/、components/ などのディレクトリを分析します
3. ドキュメントを確認する：README.md、docs/ など

再利用可能なコンポーネントを記録します：
- 基本サービス クラス
- ユーティリティ関数
- ミドルウェア
- データモデル

第二段階：設計ドキュメントの生成

次の構造に従って設計ドキュメントを生成します。

2.1 設計目標（1〜2段落）

明確に説明します：
- 今回の設計で解決する問題
- 提供する機能

2.2 機能リスト（簡潔なリスト）

今回の設計の機能ポイントを簡潔にリストします：
- 機能1：一言で説明
- 機能2：一言で説明
- 機能3：一言で説明

詳細な説明は展開せず、簡潔さを保ちます

2.3 インタラクションフロー（Mermaid シーケンス図）

主要な機能ごとにシーケンス図を作成します：
```mermaid
sequenceDiagram
    participant User
    participant API
    participant Service
    participant DB

    User->>API: リクエスト
    API->>Service: 呼び出し
    Service->>DB: クエリ
    DB-->>Service: 戻り値
    Service-->>API: 結果
    API-->>User: レスポンス

シーケンス図の目的：

• コンポーネント間のインタラクションの順序を示す
• システム境界を明確にする
• 外部依存関係を識別する

2.4 実装案（コア部分）

各機能ポイントについて、次の構造で説明します。

機能ポイント名

実装アイデア（2〜3文）

• 採用する技術的な解決策を説明します
• なぜこの解決策を選択したのか
• 既存のコンポーネントとの統合方法

重要なメソッド（コード例）

# 例：ユーザー認証
def authenticate_user(token: str) -> User:
    """ユーザーtokenを検証し、ユーザー情報を返します"""
    # 1. token形式を検証する
    # 2. キャッシュまたはデータベースからクエリする
    # 3. ユーザー情報を返す
    pass

技術的な課題（もしあれば）

• 課題を説明します
• 解決策を説明します
• 参考リンクまたは例を提供します

2.5 データモデル（必要な場合）

新規または変更されたデータモデルのみをリストします：
- User: {id, name, email}
- Order: {id, userId, amount, status}

簡潔なテーブルまたはJSON形式を使用します

2.6 インターフェース定義（必要な場合）

新規または変更されたAPIのみをリストします：
POST /api/users
- リクエスト：{name, email}
- レスポンス：{id, name, email, createdAt}

簡潔さを保ち、すべてのフィールドを展開しないでください

第三段階：品質チェック

ドキュメントを生成した後、次のチェックを行います。

3.1 洗練度チェック

• [ ] 長々とした背景説明はありますか？
• [ ] 重複した内容はありますか？
• [ ] 理解に影響を与えずに削除できる章はありますか？

3.2 重点強調チェック

• [ ] 設計目標は明確ですか？
• [ ] 機能リストは簡潔ですか？
• [ ] シーケンス図はコアインタラクションを示していますか？
• [ ] 実装案は重要なメソッドを提供していますか？

3.3 技術的な正確性チェック

• [ ] 技術スタックはプロジェクトと一致していますか？
• [ ] 既存のコンポーネントを再利用しましたか？
• [ ] コード例は正しいですか？

3.4 MVP導向チェック

• [ ] 不要な機能が含まれていますか？
• [ ] 一部の設計を簡略化できますか？
• [ ] 後続のイテレーションで対応できる内容はありますか？

常见问题处理

Q1: ユーザーが十分な情報を提供していない

優先順位：
1. プロジェクトファイル（pyproject.toml、package.jsonなど）を読み取る
2. プロジェクト構造を分析する
3. ユーザーに具体的な質問をする
4. 一般的なパターンに基づいて合理的な仮定をする（ドキュメントで説明する）

Q2: 特定の機能が必要かどうか不明

原則：
- コア機能の場合は、必ず含める
- 補助機能の場合は、後続のイテレーションで対応できる
- 不明な場合は、ユーザーに質問する
- ドキュメントで「オプション」または「後続のイテレーション」と明記する

Q3: 技術スタックに慣れていない

処理方法：
1. プロジェクト設定ファイルを読み取って技術スタックを理解する
2. 関連するドキュメントとベストプラクティスを検索する
3. プロジェクトの既存のコードの実装方法を参考にする
4. ドキュメントで技術選定の理由を説明する

参考資料

• 設計ドキュメントテンプレート - 標準設計ドキュメントテンプレート