翻訳ドキュメントについて

最近、仕様駆動開発がトレンドになっています。しかし、そもそも仕様駆動開発がどのような概念であるかを体系的に説明した日本語の書籍は現時点で見当たりませんでした。そこで、spec-kitに付属している仕様駆動開発の概念を説明した2025年12月19日時点でのspec-driven.mdを非公式に翻訳しました。本非公式翻訳が、仕様駆動開発を促進する一助になりましたら幸いです。
以下、翻訳ドキュメントのURLです。

HTML版
https://souldist.sakura.ne.jp/translation/spec-kit/spec-driven.ja.html
Markdown版(ブラウザで直接閲覧すると文字化けするかもしれません)
https://souldist.sakura.ne.jp/translation/spec-kit/spec-driven.ja.md

原文はこちらです
https://github.com/github/spec-kit/blob/main/spec-driven.md

解説

以下、上記spec-kit.mdの中身を解説します。
筆者はまだspec-kitを実際には動かしたことが無いことを断っておきます。

spec-kitとは

仕様駆動開発を実現するためのシステムの一つにspec-kitがあります。Kiroが有名ですが、こちらはIDEです。spec-kitはCLIで、CI/CDに組み込むなど自動化するのに向いています。CLIなので特定のエディタに依存しません。仕様駆動開発を実現するための最小のツール群が組み込まれています。

力の逆転

仕様が主かコードが主かについて述べられています。従来の開発ではコードが正で仕様がコードに従属しています。コードが変化していくと仕様がコードに追いつくことはありませんした。つまり、コードが主です。そして、仕様と実装の間に生じるギャップがソフトウェア開発を苦しめてきました。仕様駆動開発ではこの関係を逆転させます。AIが仕様を理解し、仕様に基づいて実装できるようになったため、仕様から実装計画を生み出すことで、自動的に仕様と実装のギャップを埋めることができます。仕様が主です。

また、仕様駆動開発のプロセスの概要についても触れられています。

0 -> 1, (1', ..), 2, 3, Nのように進む

との記載がありますが、こちらはドキュメント内の数字の意味が記載されていなかったため、AIに推察させたところ、原文の文脈から導かれたのは以下の見解でした:

- 0：仕様がまだ存在しない状態（ゼロからの出発）
  - 新規アプリや新規機能を作る前の「空白状態」
  - まだ仕様（spec）がない
- 1：最初の仕様を作る
  - 仕様を書く
  - 仕様が「真実の源（source of truth）」になる
- 1'：仕様の改訂・派生（複数回発生しうる）
  - 新機能追加や改善のために仕様を更新する
- 1' が複数あるのは、仕様が何度も改訂されることを示す
  - (1', …) は「1 の派生・繰り返し」を表す
- 2：実装計画（implementation plan）を作る
  - 仕様に基づいて実装方針を作成
  - ここで初めてコード生成の準備が整う
- 3：コード生成・実装
  - 実際にコードを書く、または自動生成する
  - 仕様と実装計画に従ってコードが作られる
- N：その後の継続的な反復
  - デバッグ（仕様や計画の修正）
  - リファクタリング
  - 新機能追加
  - 仕様の再訪問
  - 実装計画の再生成
  - コードの再生成
→つまり N は「継続的な反復サイクル」 を象徴しています。

SDDワークフローの実践

従来の開発では要件定義や設計というものが個々のフェーズとして分断されていましたが、仕様駆動開発(SDD)では連続的な活動で、各フェーズの成果物に変更があった場合、影響があるところにフラグが立てられ更新されます。
一つ前の章で

つまり Nは「継続的な反復サイクル」を象徴しています

と述べましたが、まさにその通りで、ワークフローを反復することで、システムを継続的に進化させて行きます。

なぜSDDが今重要なのか

3つのトレンドが、仕様駆動開発を可能にするだけでなく必要にしたと述べられています:

AIが仕様から実装への機械的な翻訳を自動化できるようになったため最初からの作り直しが容易になった
モダンなシステムは多数のサービス、フレームワークおよび依存関係が統合されているが、手動ではメンテナンスするのが困難になっていく
世の中の変化のペースが加速し、要件は急速に変化するため、方向転換は予期されるものとして扱う必要がある

従来仕様変更は障害として扱われていましたが、SDDではそれを通常のワークフローに変換します。要件を変更すると、影響を受ける実装計画は自動的に更新されます。

中心となる原則

以下の6つの原則が挙げられています

共通語としての仕様: 仕様は最初の中間生成物になる。コードは特定の言語とフレームワークで表現される。ソフトウェアを保守することは仕様を進化させることを意味する
実行可能な仕様: 仕様は動くシステムを生成するのに十分正確で、完全で、曖昧性のないものでなくてはならない。これは意図と実装の間のギャップを取り除く
継続的な改善: 無矛盾性の検証は1度限りのゲートでなく、継続して実施される。AIは継続するプロセスとして仕様の曖昧さ、矛盾、ギャップを分析する
調査駆動のコンテキスト: 調査エージェントは仕様策定プロセス全体を通じて重要なコンテキストを収集しながら、技術的な検討候補、性能面への影響、および組織的な制約を調査する
双方向のフィードバック: 本番環境の実態は仕様の進化を方向づける。メトリクス、インシデント、そして運用から得られた知見は仕様の改善に向けたインプットとなる
探索のための分岐: 性能、保守性、ユーザー・エクスペリエンス、コストといった異なる最適化目標を探索するために、同じ仕様から複数の実装アプローチを生成する

実装アプローチ

SDDを実践するためのアプローチの概要について述べられています。
色々なツールが必要ですが、重要なの考え方として、仕様を真実の源として扱い、コードは仕様を満たす生成物として扱うということです。

コマンドによるSDDの合理化

SDDの方法論は仕様→計画→タスク化という一連のワークフローを自動化する3つの強力なコマンドにより大幅に強化されると述べられています。

/speckit.specifyコマンド
→ユーザーによる機能の説明から仕様を生成します
/speckit.planコマンド
→実装計画を作成します
/speckit.tasksコマンド
→実行可能なタスクリストを生成します

従来のアプローチでは手動でのドキュメント化の作業が伴うため、12時間かかるところを、
コマンドを使ったアプローチでは15分で可能と述べられています。

また、時間を節約するだけではなく整合性や完全性も担保できます。
さらに、テンプレートという仕組みがあるため、LLMの振る舞いに制約をかけ、より良い成果を導くことが可能です。もう少し具体的には以下の内容です：

抽象化レベルを維持するようにします(仕様と実装技術を分離する)
不確実な箇所は[NEEDS CLARIFICATION]というマーカーの使用を義務付けます
仕様に対して「単体テスト」として振る舞うチェックリストを含んでいます
ゲートというチェックポイントを使って原則(ルール)に従う事を徹底させます
読みやすい情報の構造を徹底させます
テストファースト開発を徹底させます
「あるといい」だけの機能を追加することを阻止します

上記の制約が作用することで、以下のような特性を備えるようになります

完全
曖昧でない
テスト可能
保守可能
実装可能

基本原則の基盤: アーキテクチャの規律の徹底

SDDの中心を成すものとして、「基本原則」があります。原文ではconstitutionなので直訳すると「憲法」なのですが、いわゆる一般的な憲法とは違いますし、仰々しいので、悩んだ末に「基本原則」と訳しました。基本原則は仕様がどのようにコードへと変換されるかを規定しています。基本原則は(memory/constitution.md)に記載されています。
基本原則は以下の6つの条項から成っています。

条項I: ライブラリファーストの原則
条項II: CLIインターフェース機能
条項III: テストファーストの原則
条項VII・VIII: シンプルさと非抽象化
条項IX: 結合ファーストなテスト

原文では9つの条項と記載されていましたが、本ドキュメントに登場するのは上記の6つのみで、IV、V、VIが存在しません。ドキュメントの変更履歴を見てみましたが、過去にはこれらの条項が存在して、削除されたという訳ではありませんでした。将来的に空いているナンバーのところに条項が追加されるのかもしれません。

また、ひとつ前の章で登場した実装計画のテンプレートを通じることで基本原則を徹底させることができます。テンプレートはチェックリスト形式になっていて、チェック観点の集合であるゲートで構成されています。LLMはチェック観点をすべて満たし、ゲートを通過するか、通過できなかった場合は、なぜなのか、正当な理由を文書化しないと先に進むことができません。

基本原則は通常不変なので、以下4つを得ることができます:

時を跨いだ一貫性
LLMを跨いだ一貫性
アーキテクチャの整合性
品質保証

例外はあって、以下がある場合は基本原則を修正することが可能です

変更の論理的根拠が記載された明確なドキュメント
プロジェクトのメンテナによるレビューと承認
後方互換性の検証

ここで注意が必要なのは「中心となる原則」で述べた、「原則(principle)」と「基本原則(constitution)」は別ということです。SDDのよりコアなルールである「原則(principle)」は全く変更することができません。「基本原則(constitution)」は「原則(principle)」をどう運用するかのルールなので、通常は変更できないものの、条件を満たせば変更可能です。

そして、基本原則は以下の哲学を形作ります:

不透明性よりも可観測性: 全てはCLIインターフェースで検査可能でなければならない
技巧よりもシンプルさ: 最初はシンプルに、必要と証明された時だけ複雑さを加える
隔離よりも結合: 人工環境ではなく実環境でテストする
モノリスよりもモジュール方式: 全ての機能は明確な境界を持つライブラリとする

変貌

仕様駆動開発によって、開発者を置き換えたり、創造性を自動化するという訳ではなく、人間の能力を増幅させます。反復を続ける中で、仕様とコードが進化していきます。

ソフトウェア開発はユーザーの意図と実装の間で整合性を保守するためのよりよいツールを必要としており、SDDはコードを生成する実行可能な仕様によってこの整合性を達成するための方法論を提供します。

さいごに

仕様駆動開発一般というよりはspec-kit寄りではあったものの、プロセスの流れも含めて仕様駆動開発の概念について知ることができました。筆者の中で、色々とアイデアはあるけど、時間が無くてできていないものがあるので、こういったアイデアも仕様駆動開発で実現できるようになれば良いかなと思います。