plan-docs

name	plan-docs
description	要件定義書・仕様書・実装計画書を自動生成するスキル。 要件には REQ-{SCOPE}-{SEQ} 形式のIDを付与し、実装計画は要件IDに基づいて作成。 docs/requirements/、docs/specifications/、docs/implementation/ に複数ファイルとして出力する。 トリガー: "plan-docs", "/plan-docs" 使用場面: プロジェクトの要件定義・仕様策定・実装計画の作成が必要な時。新規プロジェクト開始時や機能追加の計画時。

plan-docs

プロジェクトの要件定義書・仕様書・実装計画書を体系的に生成するスキル。

引数

• (自然言語) — プロジェクトや機能の説明（任意）
• --step-by-step — requirements → specifications → implementation を段階的に生成し、各フェーズ後にユーザーレビューを挟む
• --lang=en|ja — 出力言語を明示指定（デフォルト: 会話言語に追従）
• --output=path — 出力先ディレクトリを変更（デフォルト: docs/）
• --deep — コードベースの深層解析を行う（デフォルト: 構造解析のみ）

出力構成

{output}/
├── requirements/
│   ├── overview.md          # 要件一覧・スコープ・用語集
│   ├── REQ-{SCOPE}.md       # スコープ別要件定義
│   └── ...
├── specifications/
│   ├── architecture.md      # アーキテクチャ（必須）
│   └── ...                  # API, データモデル, UI等（プロジェクトに応じて動的決定）
└── implementation/
    ├── plan.md              # 実装計画概要 + トレーサビリティマトリクス
    └── tasks/
        ├── TASK-001.md      # 実装タスク
        └── ...

実行手順

ステップ 0: 準備

1. 引数のパース: --step-by-step, --lang, --output, --deep を解析。未指定はデフォルト値を使用。
2. 出力言語の決定: 以下の優先順位で決定する。
   • --lang で明示指定されていればそれを使用
   • 既存の {output}/ 配下にドキュメントがあればその言語に追従
   • 上記いずれもなければ、ユーザーの会話言語に追従
3. 既存ドキュメントの確認: {output}/requirements/ が既に存在するか確認。存在する場合は既存の REQ-ID を読み取り、続番で差分更新する。

ステップ 1: プロジェクト解析

構造解析（デフォルト）

以下を解析してプロジェクトのコンテキストを把握する:

• ディレクトリ構成（find . -type f | head -100 等）
• 設定ファイル（package.json, Cargo.toml, pyproject.toml, go.mod 等）
• README.md
• 既存のドキュメント

深層解析（--deep 指定時）

上記に加えて:

• 主要ソースコードの読み込み（エントリポイント、ルーティング、モデル定義等）
• テストファイルの確認
• CI/CD設定の確認

解析結果とユーザー入力を統合し、要件の素案を内部的に整理する。

ステップ 2: SCOPE の自動判定

プロジェクトの性質から適切な SCOPE カテゴリを自動判定する。

判定基準:

• 機能ドメインごとに分類（例: AUTH, DATA, UI, API, INFRA, SEARCH, PAYMENT 等）
• 1つのSCOPEに含まれる要件が多すぎる場合（目安: 10件超）は分割を検討
• SCOPEは英大文字、2〜6文字程度の略称

ステップ 3: requirements/ の生成

以下のテンプレートに従って生成する。テンプレートは templates/ 配下を参照。

1. overview.md を生成（テンプレート: templates/req-overview.md）

   • プロジェクト概要
   • スコープ（対象範囲・対象外）
   • 全要件の一覧表（ID, タイトル, 優先度, ステータス）
   • 用語集

2. REQ-{SCOPE}.md をスコープごとに生成（テンプレート: templates/req-scope.md）

   • 各要件エントリに: ID, タイトル, 説明, 優先度(Must/Should/Could), ステータス(Draft), 受入条件(チェックリスト), 依存要件

--step-by-step の場合: ここでユーザーにレビューを求める。AskUserQuestion で「要件定義の内容を確認してください。修正点があれば指摘を。問題なければ次の仕様書生成に進みます。」と確認する。

ステップ 4: specifications/ の生成

architecture.md は必須生成。その他はプロジェクトの性質に応じて動的に決定する。

動的決定の基準:

• API エンドポイントがある → api.md を生成
• データベースやストレージを使う → data-model.md を生成
• UIがある → ui-spec.md を生成
• 外部連携がある → integrations.md を生成
• セキュリティ要件が重要 → security.md を生成

各仕様書はプロジェクトの技術スタックに合わせた内容にする。テンプレートの厳密な形式は定めないが、以下を含むこと:

• 概要
• 詳細設計
• 制約・前提条件
• 関連する REQ-ID への参照

--step-by-step の場合: ここでユーザーにレビューを求める。

ステップ 5: implementation/ の生成

1. tasks/TASK-{SEQ}.md を生成（テンプレート: templates/impl-task.md）

   • 要件から実装タスクを導出
   • 各タスクに: ID, タイトル, 関連REQ-ID, 実装概要, 対象ファイル/コンポーネント, 規模見積(S/M/L), 依存タスク, 実装ステップ

2. plan.md を生成（テンプレート: templates/impl-plan.md）

   • 実装計画概要
   • 実装順序（依存関係を考慮）
   • トレーサビリティマトリクス（REQ-ID ↔ TASK-ID の対応表）
   • マイルストーン（あれば）

ステップ 6: CLAUDE.md ルール追記の確認

全ドキュメント生成完了後、AskUserQuestion でユーザーに確認する:

「CLAUDE.md に『作業完了時にドキュメント更新が必要か確認する』ルールを追記しますか？これにより、今後の作業完了時に生成したドキュメントとの整合性チェックが促されます。」

選択肢:

• 追記する — CLAUDE.md に以下のルールを追記する:

## ドキュメント整合性
- 作業完了時、docs/ 配下の要件定義書・仕様書・実装計画書に影響する変更がないか確認し、必要なら更新するかユーザーに確認すること

• 追記しない — 何もしない

追記する場合:

1. プロジェクトルートの CLAUDE.md が存在するか確認
2. 存在しない場合は作成するか確認
3. 存在する場合は末尾に上記ルールを追記
4. 追記内容はプロジェクトの出力パスに合わせて調整（--output で変更している場合）

ステップ 7: 完了報告

生成結果のサマリを報告する:

• 生成したファイル一覧
• 要件数（SCOPE別）
• タスク数
• CLAUDE.md 更新の有無

既存ドキュメントへの差分更新

{output}/requirements/ が既に存在する場合の振る舞い:

1. 既存の全 REQ-{SCOPE}.md を読み取り、使用済みの REQ-ID を把握
2. 新規要件は既存の最大SEQの続番を振る
3. 既存要件は保持し、内容を上書きしない
4. 新規SCOPEが必要な場合は新しい REQ-{SCOPE}.md を作成
5. overview.md の一覧表は既存+新規を統合して再生成
6. implementation/ も同様に既存TASKを保持し、新規タスクを追加

ルール

• 要件IDは REQ-{SCOPE}-{SEQ} 形式を厳守（例: REQ-AUTH-001）
• SEQ は SCOPE 内で 001 から連番
• SCOPE は英大文字の略称（AI自動判定）
• 優先度は MoSCoW 法: Must / Should / Could / Won't
• ステータスは Draft で初期生成
• TASK-ID は TASK-{SEQ} 形式で 001 から連番
• 既存ドキュメントがある場合は破壊しない（差分更新）
• テンプレートの形式に従うが、プロジェクトに不要な項目は省略してよい