sakamotchi/generate-project-docs

プロジェクトドキュメント生成スキル

概要

このスキルは、大規模で長期的なプロジェクト向けのドキュメント群を docs/projects/{プロジェクト名}/ 配下に自動生成します。

通常の開発作業ドキュメント（generate-working-docs）との違い：

• スコープ: 複数フェーズにわたる大規模機能追加
• 期間: 数週間〜数ヶ月の長期プロジェクト
• 管理: フェーズ分割と段階的実装が必要
• ドキュメント: より詳細なWBS、技術設計、実装計画を含む
• 設計書の分割: 各フェーズごとに詳細設計書を作成

使用シーン

以下のような大規模プロジェクトに使用します：

• 新しいクエリタイプの追加（SELECT句拡張、CTE対応など）
• アーキテクチャの大幅な変更（ストア再設計、API刷新など）
• 複数の機能にまたがる横断的な改善（パフォーマンス最適化プロジェクトなど）
• 長期的なリファクタリングプロジェクト

使い分けの目安：

• タスク数が10個以上 → プロジェクトドキュメント
• 複数のコンポーネント/モジュールを横断 → プロジェクトドキュメント
• 3フェーズ以上に分割が必要 → プロジェクトドキュメント
• 単一機能の追加・バグ修正 → 開発作業ドキュメント（generate-working-docs）

生成ファイル

docs/projects/{プロジェクト名}/
├── project-plan.md          # プロジェクト計画書
├── requirements.md          # 要件定義書
├── design.md               # 全体アーキテクチャ概要（簡潔版）
├── wbs.md                  # WBS（作業分解構造）
├── implementation-plan.md  # 実装計画書
└── phases/                 # フェーズごとの詳細
    ├── phase1/
    │   ├── design.md       # Phase 1の詳細設計
    │   ├── tasklist.md     # フェーズ1のタスクリスト
    │   └── testing.md      # フェーズ1のテスト手順
    ├── phase2/
    │   ├── design.md       # Phase 2の詳細設計
    │   ├── tasklist.md
    │   └── testing.md
    └── phase3/
        ├── design.md       # Phase 3の詳細設計
        ├── tasklist.md
        └── testing.md

各ファイルの役割

| ファイル | 内容 | |---------|------| | project-plan.md | プロジェクト概要、目的、スコープ、制約、成功基準 | | requirements.md | 機能要件、非機能要件、ユースケース、成功基準、除外事項 | | design.md（ルート） | 全体アーキテクチャ概要のみ（データモデルの概要、システム構成、データフロー） | | wbs.md | フェーズ分割、タスク一覧、依存関係、工数見積もり | | implementation-plan.md | 実装順序、マイルストーン、リスク管理、品質保証計画 | | phases/phaseN/design.md | 各フェーズの詳細設計（型定義、コンポーネント設計、UI/UX設計） | | phases/phaseN/tasklist.md | 各フェーズの詳細タスクリスト | | phases/phaseN/testing.md | 各フェーズのテスト手順書 |

実行手順

このスキルが呼び出されたら、以下の手順で実行してください：

1. プロジェクト名の確認

ユーザーにプロジェクト名を確認します。プロジェクト名は英語のケバブケース（例：select-clause-extension, cte-support, performance-optimization）を推奨します。

2. プロジェクト要約の収集

以下の情報をユーザーから収集します（すでにコンテキストにある場合はスキップ可）：

• プロジェクトの目的
• 実現したい主要機能
• 想定される技術的課題
• フェーズ数（デフォルト3フェーズ）

3. ディレクトリ作成

プロジェクト名を使ってディレクトリを作成します：

mkdir -p docs/projects/{プロジェクト名}/phases/{phase1,phase2,phase3}

注意: フェーズ数は柔軟に調整可能です（2〜5フェーズ程度）。

4. ドキュメント生成

以下のドキュメントを順次生成します：

4.1 プロジェクト計画書（project-plan.md）

以下の構成で作成：

• プロジェクト概要
• 目的とゴール
• スコープ（対象・対象外）
• 前提条件と制約
• ステークホルダー
• 成功基準
• リスクと課題

4.2 要件定義書（requirements.md）

以下の構成で作成：

• 概要と背景
• 実現したいこと（ユースケース）
• 機能要件（FR-1, FR-2, ...）
• 非機能要件（NFR-1, NFR-2, ...）
• 制約事項
• 成功基準
• 除外事項
• 参考資料

4.3 技術設計書（design.md）- ルート

ルートのdesign.mdは全体アーキテクチャ概要のみを記載（簡潔に）：

• システム全体のアーキテクチャ図
• 主要なデータモデルの概要（詳細は各フェーズで定義）
• フロントエンド・バックエンド間のデータフロー
• 技術スタックの選定理由
• 全体的な設計方針

詳細設計は各フェーズのdesign.mdに記載します。

4.4 WBS（wbs.md）

以下の構成で作成：

• フェーズ分割の方針
• 各フェーズの概要と目標
• タスク一覧（階層構造）
• タスク間の依存関係
• 工数見積もり（オプション）
• クリティカルパス

4.5 実装計画書（implementation-plan.md）

以下の構成で作成：

• 実装の優先順位と順序
• マイルストーン
• 段階的リリース計画
• リスク管理計画
• 品質保証計画
• ドキュメント更新計画
• 後方互換性の保証方法

4.6 各フェーズの詳細設計書、タスクリスト、テスト手順（既存スキルを活用）

各フェーズディレクトリ（phases/phaseN/）のドキュメント生成には、既存のサブスキルを再利用します。

重要: 以下のスキルを各フェーズごとに順次実行してください：

Phase 1の場合:

1. generate-design スキルを呼び出し

   • 引数: docs/projects/{プロジェクト名}/phases/phase1 {プロジェクト名}-phase1
   • 生成内容: 型定義の詳細（TypeScript + Rust）、バックエンドSQL生成ロジック、データベース方言マッピング、バリデーションロジック

2. generate-tasklist スキルを呼び出し

   • 引数: docs/projects/{プロジェクト名}/phases/phase1 {プロジェクト名}-phase1
   • 生成内容: フェーズの詳細タスクリスト（WBSから抽出）

3. generate-testing スキルを呼び出し

   • 引数: docs/projects/{プロジェクト名}/phases/phase1 {プロジェクト名}-phase1
   • 生成内容: テスト手順書（単体テスト、統合テスト、E2Eテスト）

Phase 2、Phase 3も同様に実行します。

各フェーズの設計内容の違い:

• Phase 1: 型定義の詳細、バックエンドSQL生成ロジック、データベース方言マッピング、バリデーションロジック
• Phase 2: UIコンポーネント設計（例: FunctionBuilder）、状態管理（Piniaストア）、ユーザーインタラクション設計、プレビュー機能の実装
• Phase 3: 高度な機能の設計（例: SubqueryBuilder）、相関サブクエリ対応、パフォーマンス最適化、エッジケース対応

注意: 既存スキルは docs/working/ 向けに設計されていますが、docs/projects/ 配下でも同様に動作します。

5. 既存ドキュメントの参照

生成時に以下のドキュメントを参照して整合性を保ちます：

• CLAUDE.md - プロジェクトの技術スタック
• docs/01_product_requirements.md - プロダクト要求
• docs/02_functional_design.md - 機能設計
• docs/03_architecture_specifications.md - 技術仕様
• docs/features/query-builder.md - 既存機能仕様

6. 完了報告

生成したディレクトリとファイル一覧をユーザーに報告し、各ドキュメントの役割を簡潔に説明します。

重要な注意事項

Nuxt UI v4 記法

このプロジェクトは Nuxt UI v4 を使用しています。設計書のコード例では必ず v4 の記法を使用してください：

• ✅ UFormField + items
• ❌ UFormGroup + options（v3）

詳細は generate-working-docs スキルの技術仕様を参照してください。

フェーズ分割の原則

1. Phase 1: 基盤となる型定義とバックエンド実装
2. Phase 2: UIコンポーネントと基本機能
3. Phase 3: 高度な機能と最適化

各フェーズは独立してテスト可能で、段階的にリリースできる単位にします。

ドキュメントの粒度と分割方針

プロジェクトレベル（ルート）のドキュメント:

• 全体像と方針に焦点を当てる
• design.md（ルート）は全体アーキテクチャ概要のみ（5〜10セクション程度）
• 詳細な型定義やコンポーネント設計は含めない

フェーズレベルのドキュメント:

• phases/phaseN/design.md: そのフェーズで実装する具体的な設計詳細
• phases/phaseN/tasklist.md: 具体的なタスクリスト
• phases/phaseN/testing.md: テスト手順書

設計書分割の基準:

• ルートのdesign.mdが20セクション以上になる場合は分割必須
• 各フェーズのdesign.mdは10〜15セクション程度が目安
• フェーズごとに独立して読める構成にする

使用例

詳細は examples.md を参照してください。

関連スキル

サブスキル（このスキルから呼び出される）

このスキルは以下のサブスキルを再利用します：

• generate-design - 各フェーズの詳細設計書生成（Phase 1〜3で使用）
• generate-tasklist - 各フェーズのタスクリスト生成（Phase 1〜3で使用）
• generate-testing - 各フェーズのテスト手順書生成（Phase 1〜3で使用）

関連スキル

• generate-working-docs - 小規模な開発作業用ドキュメント生成（こちらも上記サブスキルを使用）
• generate-requirements - 要件定義書生成（単独使用可能）

関連ドキュメント

• CLAUDE.md - プロジェクト全体の技術スタックとガイドライン
• docs/ - 永続化ドキュメント群
• docs/projects/ - プロジェクトドキュメント格納ディレクトリ
• docs/working/ - 開発作業ドキュメント格納ディレクトリ