「ビジネスアナリストが仕様を書き、エンジニアが実装する」をAI時代に再設計する ── Spec Kitをオフショア開発にカスタマイズした話（設計編）

本記事では、github/spec-kit（以下、Spec Kit）をオフショア × AI駆動開発のプロジェクトに導入するにあたって、標準のSpec Kitに対してどんな設計判断を重ねてきたかを書き残します。本格運用はこれから始まります。だからこそ、判断のプロセスと、設計時点で見えている懸念を、後から検証可能な形で残しておきたいと考えました。

オフショア × AI駆動開発で感じている摩擦

ある一覧APIの仕様書には、「並び順に従って表示する」とだけ書いてあります。実装したエンジニアは、既存の同様のAPIに合わせて、並び順の値が null のものをリストの末尾に並べて返しました。ビジネスアナリストが画面を確認すると、「null のものは出さない想定だった」と言います ── 運用上は表示する必要がありません。仕様書を見直すと、null の扱いについては書かれていません。書かれていないことを、それぞれが「自然な解釈」で埋めていたのです。エンジニアは既存実装との整合で、ビジネスアナリストは運用目線で。

書かれていないことの判断は、AIに任せても人間に任せても、結局どこかで分岐します。仕様の解像度がチーム共通の前提として揃っていない以上、AI駆動開発で増えた速度はそのまま摩擦に転化してしまいます。

オフショア協業の現場で、この摩擦は珍しいものではありません。私たちのチームは日本とベトナムの両方にビジネスアナリスト（以下BA。要件を理解し仕様策定を担当する）がいて、両者とも日本語の仕様書を読み書きできる体制です。それでも「書かれていないことは判断が分岐する」という一点だけは、仕組みでしか解けません。

私が担当しているプロジェクトでもAI駆動開発を取り入れることになりました。弊社では技術選定はプロジェクト単位で行っており、本プロジェクトの特性に合わせて、こうした摩擦への仕掛けとして選びつつあるのが Spec Kit です。仕様書を原本としてgit管理し、コードを書かせる前にAIと一緒に spec の曖昧さを潰しに行く ── そのアプローチが、私たちのチームにどう機能するかを試すフェーズにあります。

Spec Kitは、仕様 → 技術設計 → タスク → 実装の各段階を、/speckit.specify、/speckit.plan、/speckit.tasks、/speckit.implement といったコマンドで進めるフレームワークです。各段階の成果物（spec.md、plan.md、tasks.md、実装コード）はMarkdownとしてリポジトリに残るため、コードと同じレビュー基盤に乗せられます。

ロール設計：BAとエンジニアの分業をAIの文脈で組み直す

Spec Kitを紹介する記事の多くは、個人開発者が spec → plan → tasks → implement を一人で回す前提で書かれています。私たちのフローは違います。BAが /speckit.specify と /speckit.clarify を回し、エンジニアが /speckit.plan 以降を担う ── 仕様策定と実装をフェーズで分業する形です。

元々この分業は、オフショア体制では既にありました。日本とベトナム両方にいるBAが仕様書を書き、エンジニアが実装する。Spec Kitが提供する段階分割（spec / plan / tasks / implement）は、この既存の境界線にほぼ重なります。私たちのSpec Kit導入は「新しい分業を作る」のではなく、既にある分業を、AIが介在する文脈で組み直す作業でした。

具体的には、BAは /speckit.specify で仕様の原本（spec.md）を作成します。このコマンドはカスタマイズしてあり、AIが作成過程で検出した曖昧さをBAに一問一答で確認する設計にしてあります ── 標準のSpec KitだとAIが「推奨値」で勝手に決めてしまうところを、判断はBAに残す方に倒しました。

書き上がった spec.md にまだ曖昧さが残っている場合は、/speckit.clarify で体系的なスキャンをかけます。完成済みの仕様書を業務スコープ・エッジケース・用語の一貫性などの観点から見直し、/speckit.specify で取りこぼした曖昧さを補完するコマンドです。冒頭の null の事例で言えば、これは「エッジケース」の観点で /speckit.clarify が拾い上げる類のものです。

Backendエンジニアは spec.md を起点に /speckit.plan で技術設計（plan.md と openapi.yaml）を起こし、/speckit.tasks でタスクに分解、/speckit.analyze で整合性を確認した上で /speckit.implement を回します。FrontendエンジニアはSpec Kitのコマンドを使いません ── 完成した spec.md と openapi.yaml を参照して実装する立場です。レビューを経た openapi.yaml が信頼できる原本として手元に届くため、FEは仕様の解釈ブレなく実装に入れる、というのがFE側の恩恵です。

もう一つの設計判断として、BAがGitHubでドラフトPRを開く運用を選びました。仕様書をコードと同じリポジトリでgit管理し、コードと同じプロセス（PR・レビュー・Approveラベル）で承認します。BAにとっては仕様書を書く媒体がドキュメントツールからMarkdownとgitに変わります。これを選んだのは、これがなければ「仕様書をgit管理する」という根幹思想が運用レベルで成立しないからです。具体的なゲート運用は後の章で扱います。

ツール選定：Spec Kit + Copilot の理由

ツール選定では2つの判断を重ねました。spec駆動の枠組みとしてSpec Kitを、AIアシスタントとしてGitHub Copilotを。それぞれに別の選択肢があり、個人的な好みより組織的な事情を優先した判断が含まれています。

Spec Kitを採用した理由は、生成物がすべてMarkdownでgit管理可能で、コードと同じレビュー基盤に乗ることです。spec / plan / tasks / implement の段階分けが前章で書いた分業境界と素直に重なるのも、選定の決め手になりました。特定のAIツールに依存しない構造であるのも重要なポイントで、Copilotで運用しても、Claude Codeに切り替えても、Spec Kitの仕組みはそのまま乗せ換えられます。

Copilotを選んだのは、ベトナム側のメンバーが現時点でCopilotを使っている、という事情が大きな理由です。個人的にはClaude Codeを日々使っていますが、チーム標準としてはベトナム側に合わせました。

カスタマイズ方針：標準のSpec Kitから何を変えたか

標準のSpec Kitに対して、本プロジェクトに合わせた変更を加えました。各フェーズのプロンプト、shellスクリプト、運用ガイドまで、ひと通り手を入れています。本記事では、このうちプロンプト側のカスタマイズを中心に扱います。設計思想として一貫しているのは次の2点です。

原則① 仕様と実装の整合性をコマンド側に埋め込む

/speckit.plan には、標準のSpec Kitにはない Spec-Code Consistency Check という GATE を差し込みました。spec.md の内容を既存コードベースと6つの次元で照合し、矛盾が見つかれば その時点で plan の作成を止め、BAに差し戻す 仕組みです。

次元	何をチェックするか
データモデル	spec内のデータ項目が既存テーブルにあるか
API重複	同目的の既存エンドポイントがないか
ビジネスルール	spec前提が既存ロジックと矛盾しないか
認証・権限	認証想定が既存方式と合うか
命名規則	spec用語が既存コード命名と揃うか
APIパターン	spec内に実装詳細が漏れていないか

注目したいのは最後の「APIパターン」次元です。これだけは spec → コード の方向ではなく、plan時にspecを逆検査します。本来、specにはWhatだけを書き、Howはplanで決めるのが原則ですが、実際には既存システムを参考にしながら要件を整理するうちに、spec.md に実装詳細が混入することがあります。「データはPostgreSQLのJSONB型で保存する」のような書き方が混じっていたら、それを検出して「planで決めるべき内容」として差し戻す ── 仕様にHowが漏れ込むのを、planの段階で構造的に弾く仕組みになっています。

原則② AIに過剰な権限を渡さない

AIは「親切に動こうとして、頼まれていないところまで触る」傾向があります。これを構造的に封じる仕掛けを、各エージェントに散らしました。

• /speckit.plan のAIは、specs/{ticket-id}/ ディレクトリの外に書き込めません。.github/ や src/、docs/ への変更は明示的に禁止しています
• /speckit.clarify のAIは、BAに対して技術的なHowを質問できません。「どのDBを使うか」「APIをどう設計するか」は禁止リストに入っており、許可されているのは業務ルール、ユーザー操作、アクセス制御などWhatに属する事項のみです
• /speckit.implement のAIは、生成した実装コードに FR-001 や T001 のようなSpec Kit由来のIDを残してはいけません。コードはSpec Kitの文脈を知らない第三者が読んでも自然であるべき、という設計です

これらは「AIの暴走を事後に止める」というより、AIの役割と動ける範囲を、最初から明示しておくという方向の設計です。

---

この2つの原則はそれぞれ、AIに「何を検証させるか」「何をさせないか」に対応しています。標準のSpec Kitは便利な土台ですが、本プロジェクトの運用に収めるには、この2軸は明示的に手を入れる必要がありました。

なお、これらのカスタマイズ作業そのものも、AIに依頼して進めました。各エージェントの定義ファイル（Markdown）を書き換える作業は、プロジェクト固有の事情を渡せばAIが大筋を組み立ててくれます。Spec Kitをプロジェクトに合わせて調整するハードルは、思ったより高くありませんでした。

想定している運用フローと、現時点で見えている懸念

設計はここまでです。実際の運用フローは、BAが開いた一つのドラフトPRが3段階のゲートを通って閉じる形を想定しています。

ゲート1は仕様承認です。BAが /speckit.specify で生成した spec.md をドラフトPRとして開き、他BAやTL（テックリード、技術判断を担う役割）のレビューを経て spec approved ラベルが付くまでです。あるスプリント内でこのラベルが付かなかった仕様は、次のスプリントの実装対象にしません ── 設計上の制約として明文化しています。ゲート2は技術設計承認 ── 同じPRにエンジニアが plan.md と openapi.yaml を追加コミットし、TLレビューを通します。ゲート3は実装承認 ── 実装コードを載せたPRがマージされます。

一つのドラフトPRが spec → plan → 実装と通り抜けることで、git履歴には「仕様 → 設計 → 実装」が時系列で残ります。「実装後に仕様書を更新し忘れる」という問題は、すべてを同じPRに含めるルールにすることで根本から消しています。

ただし本格運用はこれから始まります。この段階で「うまくいくはず」と書くのは設計編としても誠実ではありません。現時点で見えている懸念を、仮説として4つだけ挙げておきます。

• BAがAI対話とドラフトPR運用に慣れるまでの学習コスト
• 既存コードがレガシー寄りだと、Spec-Code Consistency Check がノイズだらけになるリスク
• 実装PRに spec 修正を含めるルールが、レビュー負荷を上げる可能性
• あるスプリント内で spec approved が付かない場合、次のスプリントの実装が空白になる進捗リスク

最後にもう一つ、設計編としての誠実さとして書き残しておきます。仕組みだけでは運用の漏れを防ぎきれない、という観測は既に出ています。BA向けプロンプトには「DBカラム名等の技術用語を spec.md に混入させない」という明示の禁則を入れていますが、実際に書かれた仕様の一部にはその漏れが起きています。これは「ガードレールを強化する」だけでは解けない、レビュー文化との両輪が要る話だと考えています。

結び：導入後の振り返りについて

導入後の振り返り ── BAが実際にspecを書いてみての感触、エンジニア側で起きた引き継ぎの齟齬、Copilotが想定通り効いた／効かなかったケース、カスタマイズの調整履歴 ── は、運用しながら試行錯誤を重ねて磨いていくものです。その過程を、機会があればまた書き残してみたいと思います。

参考リンク

• GitHub Spec Kit ── 本記事で扱った spec 駆動開発フレームワーク
• GitHub Copilot ── AIコーディングアシスタント

---

本記事内の画像は ChatGPT で生成したものを使用しています。