はじめに

私は現在、VueからReactへのマイグレーションプロジェクトを進めています。

最初はVibe Codingでマイグレーションを進めていました。小さなコンポーネントは問題なく移行できましたが、大きめのコンポーネントになると、エッジケースで一部の機能が抜けていたり、逆に余計な機能が勝手に追加されていたりといった問題が出てきました。

考えてみると原因の一つに「既存機能の仕様が完全には把握できていない」という点がありました。コードを読めばある程度の仕様はわかりますが、移行対象のコンポーネントは多く、他の業務もある中で一つ一つ丁寧に読み込んでいられません。曖昧な仕様理解のままAIエージェントに移行させようとしてもプロンプトにうまく落とし込むことができず、期待する結果が得られないことが多かったです。

そんな中、GitHubが公開したSpecKitに興味を持ちました。SpecKitは「Spec-Driven Development（仕様駆動開発）」を支援するツールですが、仕様が曖昧な状態からどう進めるかという点で参考になる設計がされています。

実際にSpecKitとアプリケーションの実装ガイドラインをAIエージェントに渡してマイグレーションを進めてみたところ、以前より改善が見られました。SpecKitのどのようなプロンプトが改善に繋がったのか気になり、テンプレートを読んでみることにしました。本記事では、その中で気になった点を一部抜粋して紹介します。

SpecKitのワークフロー

SpecKitのワークフローは大まかに4つのフェーズで構成されています。

Specify (仕様化): ユーザーの機能説明から spec.md を生成します
Plan (計画): 技術的な仕様（言語、FW、構成）を加味して plan.md を作成します
Tasks (タスク分解): 計画をユーザーストーリー単位のタスクリスト tasks.md に分解します
Implement (実装): tasks.md に従ってコードを生成します

Phase 1: Specify

Specifyフェーズでは技術的な要素を極力含めない仕様書を作るようになっていました。技術スタックを加味するのは次のPlanフェーズで、仕様と実装を明確に分離しています。
また、作成した仕様はチェックリストで検証し、曖昧な点や抜け漏れがあれば修正するサイクルを回します。

技術に焦点を当てない

ユーザーが何を必要としているのか、そしてその理由に焦点を当てるように指示がありました。

Focus on WHAT users need and WHY.

Avoid HOW to implement (no tech stack, APIs, code structure).

不明点のマーキングと優先順位

仕様書作成の段階でわからないことは、[NEEDS CLARIFICATION] マーカーを付けて明示します。ただし、すべてをマークすると収拾がつかなくなるため、確認すべき項目には優先順位が設定され最大3つと制限されています。優先順位は スコープ > セキュリティ/プライバシー > ユーザー体験 > 技術詳細 の順です。

Limit clarifications: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:

Significantly impact feature scope or user experience

Have multiple reasonable interpretations with different implications

Prioritize clarifications by impact: scope > security/privacy > user experience > technical details

仕様書のバリデーション

仕様書作成後にチェックリストで自己レビューを行うプロセスが定義されていました。作成した仕様書を検証して修正するサイクルを回すことで、精度を上げるようになっていました。前述のマークした不明点もこのプロセスの中でユーザーに質問を提示し、解消するようになっています。

Specification Quality Validation: After writing the initial spec, validate it against quality criteria:

a. Create Spec Quality Checklist: Generate a checklist file at FEATURE_DIR/checklists/requirements.md using the checklist template structure with these validation items

b. Run Validation Check: Review the spec against each checklist item:

For each item, determine if it passes or fails

Document specific issues found (quote relevant spec sections)

c. Handle Validation Results:

If all items pass: Mark checklist complete and proceed to step 6

If items fail (excluding [NEEDS CLARIFICATION]):

List the failing items and specific issues

Update the spec to address each issue

Re-run validation until all items pass (max 3 iterations)

If still failing after 3 iterations, document remaining issues in checklist notes and warn user

If [NEEDS CLARIFICATION] markers remain:

Extract all [NEEDS CLARIFICATION: ...] markers from the spec

For each clarification needed (max 3), present options to user

Wait for user to respond with their choices

Update the spec by replacing each marker with the user's selected answer

Re-run validation after all clarifications are resolved

Phase 2: Plan

Planフェーズでは技術的な調査を行い、設計とAPIスキーマの作成をします。マイグレーションの場合、プロンプトに実装の詳細な指示を出さなくてもマイグレーション元のコンポーネントから調査して進めてくれるため、結果として実装漏れが減る恩恵が得られているのかもしれません。

Research

技術的な不明点を抽出して調査するプロセスです。
不明な項目は NEEDS CLARIFICATION として記載し、以下のように調査タスクに変換します：

Extract unknowns from Technical Context above:

For each NEEDS CLARIFICATION → research task

For each dependency → best practices task

For each integration → patterns task

調査結果は research.md に記録します。単に「何を選んだか」だけでなく、「なぜ選んだか」「他に何を検討したか」も残すフォーマットになっていて後で見返すときに便利でした。

Consolidate findings in research.md using format:

Decision: [what was chosen]

Rationale: [why chosen]

Alternatives considered: [what else evaluated]

Design & Contracts

Researchで不明点を解消した後、仕様書からエンティティを抽出してデータモデルを作成し、APIスキーマを生成するプロセスが定義されています。
マイグレーションの観点では、移行元コンポーネントとAPI間のインターフェースが contracts/ として明文化されていたので、移行時にも同じ契約を守れます。

Prerequisites: research.md complete

Extract entities from feature spec → data-model.md:

Entity name, fields, relationships

Validation rules from requirements

State transitions if applicable

Generate API contracts from functional requirements:

For each user action → endpoint

Use standard REST/GraphQL patterns

Output OpenAPI/GraphQL schema to /contracts/

Output: data-model.md, /contracts/*, quickstart.md

Phase 3: Tasks

テストを先に書く

SpecKitでは、テストを含める場合は「テストを先に書き、失敗を確認してから実装する」よう指定されています。

NOTE: Write these tests FIRST, ensure they FAIL before implementation

Within Each User Story

Tests (if included) MUST be written and FAIL before implementation

Models before services

Services before endpoints

既存Vueコンポーネントの振る舞いからテストを作成するように要求すれば、そのテストが失敗する状態からReact実装を始めます。テストがパスすれば、既存の振る舞いが再現できたことの証明になります。移行元のコンポーネントのテストがない状態だったので、この仕組みのおかげで気楽に移行が進められています。

また、手動でのテスト項目も一緒に生成されます。これをそのままPlaywrightやChrome DevToolsのMCPと組み合わせることで、ある程度の検証もできています。

Phase 4: Implement

Implementフェーズは tasks.md に従ってコードを生成する工程です。通常の実装作業となるため、本記事では省略します。

まとめ

SpecKitのプロンプトで特にマイグレーションに有用に見えたものを紹介してみました。今後もSpecKitを使い続けるかはわかりませんが、SpecKitを使わないときのプロンプトに取り入れても良いかも！と思いました。また、今回は紹介しきれなかったコマンドやプロンプトがありましたので、気になった方はぜひ読んでみてください。