speckit-baseline

Spec Kit ベースラインスキル

使用する場面

• 既存コードやレガシーコードの仕様が必要な場合。
• リファクタリングの前に機能を文書化したい場合。
• 要件が文書化されていないコードベースを引き継いだ場合。

入力

• 分析対象のコードを示すパス、ファイル一覧、または glob パターン。
• .specify/ のスクリプトとテンプレートを含むリポジトリのコンテキスト。

対象が見つからない場合や曖昧な場合は、続行する前に要点を絞った質問をしてください。

目標

既存コードの技術に依存しない仕様を生成し、標準の Spec Kit テンプレートを使って機能ブランチと仕様ファイルを作成します。

ワークフロー

1. 対象入力を解析する：分析対象のファイル、ディレクトリ、パターンを特定します。

   • ファイルパス、glob パターン、ディレクトリパスを受け付けます。
   • 空の場合：停止して、具体的な対象を尋ねます。

2. ソースファイルを検出して読み込む：

   • glob をファイル一覧に展開します。
   • 分析のためにファイルの内容を読み込みます。
   • 主な言語とフレームワークを特定します。
   • 主要なファイル間の関係と依存関係をマッピングします。

3. コード構造を分析する：

   • エントリーポイントと公開インターフェースを特定します。
   • 関数／メソッドのシグネチャと動作を抽出します。
   • データモデルとエンティティを特定します。
   • API エンドポイントとルートを検出します。
   • ユーザー向け機能を特定します。

4. 分析したコードから短い名前（2～4語）を生成します：

   • 動作を表す語と名詞を組み合わせた形式を使います（例："user-auth"、"payment-processing"）。
   • 発見した主要な機能に基づいて名前を付けます。
   • 意味のある技術用語はそのまま保持します。

5. 機能ブランチと仕様ファイルを作成する：

   • この短い名前に対応する既存の機能番号（ブランチ／仕様）の最大値を確認します。
   • 算出した番号と短い名前を指定して、.specify/scripts/bash/create-new-feature.sh --json を実行します。
   • スクリプトの JSON 出力から BRANCH_NAME、FEATURE_DIR、SPEC_FILE のパスを読み取ります。
   • "I'm Groot" のように引数にシングルクォートが含まれる場合は、エスケープ構文を使います。例：'I'''m Groot'（可能であればダブルクォートの "I'm Groot" も使用できます）。

6. .specify/templates/spec-template.md から仕様テンプレートを読み込みます。

7. テンプレートの構成を使って仕様書を作成します：

   • ユーザーストーリー：ユーザー向けのコードパスと操作から推測します。
   • 受け入れシナリオ：検証ロジック、エラー処理、テストから導き出します。
   • 機能要件：ビジネスルールと制約を抽出します。
   • 主要なエンティティ：データモデルとスキーマから特定します。
   • 成功基準：メトリクス、ログ、またはパフォーマンス関連のコードから推測します。
   • 前提事項：分析中に行った推測を記録します。

8. 実装の詳細を抽象化する：

   • 技術的なパターンをユーザー中心の要件に変換します。
   • フレームワーク固有の用語を取り除きます。
   • 実装方法ではなく、コードが何をするかに焦点を当てます。

9. FEATURE_DIR/checklists/requirements.md に仕様の品質チェックリストを作成します。

10. 次の内容を含めて完了を報告します：

    • ブランチ名と仕様ファイルのパス。
    • 分析したファイルの概要。
    • 発見した主要な機能。
    • 確認やレビューが必要な箇所。

出力

• specs/<feature>/spec.md
• specs/<feature>/checklists/requirements.md

主なルール

• HOW から WHAT と WHY を抽出することに重点を置きます。
• 生成する仕様では実装の詳細を抽象化します。
• コード分析中に行った前提を記録します。
• コードの動作が不明確な箇所にはフラグを立てます。
• 見つかったビジネスルールと制約を保持します。
• 曖昧なコード部分には [NEEDS CLARIFICATION] を使用します（最大3件）。
• 生成した仕様は、その機能に詳しい人が検証する必要があります。

例

コードパターン → 仕様要件：

• if (user.role === 'admin') → 「システムは、管理者ユーザーに操作を制限しなければなりません」
• password.length >= 8 → 「パスワードは8文字以上でなければなりません」
• cache.set(key, value, 3600) → 「システムは、パフォーマンスを向上させるために結果をキャッシュしなければなりません」
• try { ... } catch (e) { notify(e) } → 「システムは、エラーが発生したときにユーザーに通知しなければなりません」

コードパターン → ユーザーストーリー：

• OAuth を使用するログインエンドポイント → 「ユーザーとして、ソーシャルアカウントを使ってサインインできます」
• ショッピングカートのロジック → 「顧客として、後で購入するために商品をカートに追加できます」
• レポート生成 → 「アナリストとして、システムのアクティビティに関するレポートを生成できます」

次のステップ

spec.md の生成後：

• speckit-clarify を使って、ドメインの専門家と明確化します。
• speckit-plan を使って、モダナイズ／リファクタリングを計画します。
• 生成された仕様を実際の要件と比較し、ギャップを特定します。