機能仕様書スキル
全体像とデータの流れが理解しやすい機能仕様書を作成する。既存コードからのリバース生成と、ユーザーの構想からの新規作成の両方に対応する。
使用タイミング
- •新機能の構想を仕様書として整理・言語化したい場合
- •仕様書なしで実装されたコードをドキュメント化したい場合
- •既存機能の全体像・データフローを可視化・共有したい場合
- •リファクタリング前に現状の振る舞いを記録したい場合
ワークフロー
ステップ1: ヒアリング
ユーザーに以下を質問して方針を確定する:
- •情報源: コードから生成するか、ユーザーの構想から作成するか、またはその両方か？
- •対象: どの機能・ディレクトリ・テーマか？
- •粒度: 単一機能 / 機能グループ / プロジェクト全体のどれか？
- •出力先: どこに保存するか？（デフォルト:
.doc/specs/） - •関心事: 特に整理したいポイントはあるか？（データフロー、状態遷移、依存関係等）
ステップ2: 判定
code
情報源は？ ├── コードから生成 → ステップ3a ├── ユーザーの構想から作成 → ステップ3b └── 両方（既存コード + 追加構想）→ ステップ3a → ステップ3b
ステップ3a: コードベース分析
対象コードを読み取り、全体像の理解に必要な情報を抽出する:
構造分析:
- •モジュール構成と各モジュールの責務
- •エントリーポイントと処理の起点
- •レイヤー構造（ルーティング→ロジック→データアクセス等）
データフロー分析:
- •入力データの受け取りから最終出力までの流れ
- •データの変換ポイント
- •外部システムとのデータ連携（DB、外部API等）
依存関係分析:
- •モジュール間の依存関係
- •外部ライブラリ・サービスへの依存
- •共有リソース（定数、型定義、ユーティリティ等）
テストからの補完:
テストファイル（*.spec.ts）が存在する場合、テストケースから補完する:
- •主要なユースケース（テストの describe/it から抽出）
- •境界条件・エッジケース
- •期待される振る舞い
ステップ3b: ユーザー構想の整理
ユーザーの説明をヒアリングし、仕様として構造化する:
- •目的・背景: なぜこの機能が必要か？
- •ユーザーストーリー: 誰が、何をしたいか？
- •処理フロー: どのような流れで動くか？
- •データ: どんなデータを扱い、どう変化するか？
- •制約・前提: 技術的制約やビジネスルールはあるか？
不明点は質問して明確化し、[NEEDS CLARIFICATION: 質問] マーカーで未解決事項を記録する。
ステップ4: 仕様書生成
templates.md のテンプレートに基づき仕様書を生成する。
code
粒度は？ ├── 単一機能 → 単機能テンプレート ├── 機能グループ → グループテンプレート └── プロジェクト全体 → 全体概要テンプレート
- •図解が有効な箇所にはMermaid記法のダイアグラムを使用する
- •コードから生成した部分で読み取れない設計意図は
[NEEDS VERIFICATION: 質問]で明示する - •ユーザー構想から作成した部分で未確定の事項は
[NEEDS CLARIFICATION: 質問]で明示する
ステップ5: ユーザー確認
- •仕様書のドラフトをユーザーに提示する
- •フィードバックを反映し、承認後に出力先へ保存する
ベストプラクティス
- •全体像を優先 — 細かいI/F定義より、システムの構造とデータの流れを重視する
- •図で伝える — データフロー・依存関係はMermaidダイアグラムで視覚化する
- •コード分析時はコードが真実 — 推測ではなく、実際のコードの振る舞いを記述する
- •構想整理時は対話で深掘り — ユーザーの曖昧なアイデアを質問で具体化する
- •不明点は明示 — マーカーで未解決事項を可視化し、曖昧なまま進めない