spec-driven-development

新しいプロジェクトや機能を始めるのに、まだ仕様が無いときに使います。要件があいまい、変更が複数のファイルやモジュールにまたがる、設計の判断をしようとしている、実装に 30 分以上かかりそう、という場面も「使うとき」に入っています。

本文の言い方では、仕様書は利用者とエージェントの間の「唯一の正」で、何を作るか・なぜか・どうなれば終わりかを決めるものです。仕様の無いコードは当て推量だ、と書いています。

4 段を、段ごとに人が見る

1. 仕様前提を出し、6 つの領域を覆う仕様書を書く。保存したら止まる
2. 計画部品と依存、作る順、危険と対策、並行できるもの、確かめの区切り
3. 作業の分解1 回で終わる大きさの作業に割り、受け入れの条件と確かめ方を付ける
4. 実装作業を 1 つずつ、試験を先に書く進め方で

どの段も、人が見て認めるまで次に進みません。仕様の前には、1 つの要件に独立した機能が束になっているときだけ働く「範囲の確認」（0 段目）があります。

0 段目: 大きな要件は機能の地図に割る

ほとんどの依頼は機能が 1 つなので、0 段目は飛ばします。次の兆しがあるときだけ、仕様を書く前に「機能の地図」を出させます。

• 要件が、別々の利用者やデータを持つ機能を名指ししている（認証・課金・通知・集計など）
• 受け入れの条件が、別々に出荷して確かめられる塊に分かれる
• 1 つの機能を外しても、ほかの機能の要件を書き直さずに済む

地図はモジュールの表と作る順だけの小さなものです。モジュールの ID は小文字とハイフンで、一度決めたら途中で変えない。依存は一方向で循環させない。モジュール間の約束は提供する側の仕様書に書く、と決められています。

地図も人が見て認めてから、モジュールごとに 4 段を依存の順に回します。仕様書はモジュールの ID で SPEC-identity.md のように名付け、地図をその索引にします。

1 段目: 前提を先に出させる

仕様の中身を書く前に、置いている前提を一覧で出させます。本文の例は「Web のアプリである」「認証はセッションの cookie」「データベースは PostgreSQL」などで、最後に「今のうちに直してほしい、直さなければこれで進む」と添えます。

あいまいな要件を黙って埋めるな、と本文は書いています。仕様書の目的は、コードを書く前に食い違いを表に出すことで、前提はいちばん危ない食い違いだからです。

仕様書が覆う 6 つの領域

• 目的何を作り、なぜか。誰が使い、何をもって成功か
• コマンド道具の名前ではなく、フラグ付きの実行できるコマンド
• プロジェクトの構成本体・試験・文書の置き場所
• コードの書き方説明の段落より、実際のコード片 1 つ
• 試験の方針道具・置き場所・網羅の期待・どの段の試験で何を見るか
• 境界常にやる・先に聞く・決してやらない、の 3 段

雛形はこれに技術の構成・成功の条件・未解決の問いを足した 9 つの節です。OpenSpec などの仕様の仕組みをすでに使っているなら、SPEC.md を重ねて作らず、その仕組みの書式と置き場所に従え、とも書かれています。

指示を「成功の条件」に言い換える

「ダッシュボードを速くして」のような要件は、確かめられる条件に言い換えさせます。本文の例は、4G 回線で LCP が 2.5 秒未満、初回のデータの読み込みが 500 ミリ秒未満、読み込み中にレイアウトがずれない（CLS が 0.1 未満）の 3 つです。

本文が名指しで外しているのは、1 行の修正、誤字の修正、要件があいまいでなく自己完結している変更です。

話しながら決めたいとき

このスキルは仕様書を書くところから始まり、聞き取りは要件が具体的になるまでの確認にとどまります。まだ何を作るか自体を探っている段階なら、brainstorming のように対話で考えを広げる側が合います。

会話の内容を仕様書にまとめるだけなら

すでに話し終わったことを文書に畳みたいだけなら、to-spec が聞き取りをせずに統合します。こちらは 4 段の関門と承認の止まりを伴うので、まとめるだけの用途には重くなります。

計画の書き方をほかの仕組みでそろえているとき

計画と作業の分解は、同じリポジトリの planning-and-task-breakdown が正だと本文は書いています。obra の writing-plans など別の計画の仕組みをすでに使っているなら、どちらの書式を正とするかを先に決めてください。

SKILL.md には、外部への通信やシェルの実行の記述はありません。ファイルは書きます。仕様書（1 件なら SPEC.md、モジュールごとなら SPEC-<ID>.md）、計画の tasks/plan.md、作業の一覧（既定で tasks/todo.md）で、tasks/ が無ければ作ります。

同梱ファイルは 0 件で、SKILL.md は 13,096 バイトです（2026-10-22 時点）。

同じリポジトリのスキルを名指しで呼ぶ

計画と作業の分解は planning-and-task-breakdown、実装は incremental-implementation と test-driven-development、読み込む範囲の調整は context-engineering、モジュール間の約束の設計は api-and-interface-design を名指しします。このスキルを 1 件だけ入れると、名指しされた先が手元に無いことになります。そのときは本文にある簡単な手順で進むことになります。

作業の大きさに上限がある

分解した作業は、1 回の集中で終わる大きさで、変えるファイルがおよそ 5 つまで、と決められています。並べる順は重要度ではなく依存の順です。

仕様書は生きた文書

決めたことが変わったら、先に仕様書を直してから実装する。範囲が変わったら仕様書に反映する。仕様書はコードと一緒にコミットし、プルリクエストからは該当する節を参照する。古くなった仕様書でも無いよりはよい、というのが本文の立場です。

ライセンス

リポジトリのライセンスは MIT です。

小さな作業でも仕様書が要りますか

1 行の修正や誤字の修正は対象外です。それより大きいものについて本文は、単純な作業に長い仕様書は要らないが受け入れの条件は要る、2 行の仕様書でよい、と書いています。

なぜ仕様書を書いたところで止まるのですか

仕様書の価値は、コードの前に食い違いをはっきりさせることにあるからです。本文の危険の兆しには「仕様書を書いて、同じ回に計画やコードを始める」が入っていて、確かめの一覧にも「仕様書を保存した回で止まり、承認は次の回に来た」があります。

Claude Code の `/spec` とは何が違いますか

公開元は、Claude Code のプラグインとして入れたときの命令 /spec を用意していて、中身はこのスキルを呼んで SPEC.md をプロジェクトの直下に保存する指示です（2026-10-22 確認）。npx skills add でこのスキルだけを入れた場合、命令は付かず、スキルが単体で動きます。

対応しているエージェントはどれですか

公開元の README が、Claude Code（推奨と明記）と Codex のそれぞれに入れ方を案内しています（2026-10-22 確認）。README はほかに Cursor・Gemini CLI・GitHub Copilot などへの入れ方も載せていますが、当サイトが表示しているのは Claude Code と Codex の 2 つです。