AI Coding Agent時代の中核スキル：優れたSoftware Specの書き方

Vibe CodingからSpec-Driven Developmentへ——コードが源泉でなくなれば、意図こそが源泉になる。

はじめに：AIへ渡す「要件文書」が、これまで以上に重要な理由

2025〜2026年、AI coding agentは質的な変化を遂げました。Claude Code、Codex CLI、Cursor、Kiroは、もはや次の一行を予測するだけの自動補完ツールではありません。リポジトリ全体を理解し、複数ファイルを変更し、テストを実行し、自律的に反復できる 自律型エージェント（autonomous agent） へ進化しました。GoogleのAddy Osmaniは、広く読まれた自身のワークフロー解説で、この新しい形を「AI-augmented software engineering」と定義しています。これはAIによって 強化された ソフトウェアエンジニアリングであり、AIによって自動化されたソフトウェアエンジニアリングではありません。

この区別は極めて重要です。開発者の役割は、「コードを書く人」から「AIにコードを書かせる指揮者」へ変わりつつあります。その指揮の中心となる媒体が、Software Spec（ソフトウェア仕様書） です。

GitHubは2025年9月にSpec Kitツールキットをオープンソース化し、Spec-Driven Development（SDD、仕様駆動開発） という方法論を正式に提示しました。AWSはSDDワークフローを内蔵したKiro IDEを公開しました。Martin Fowlerの技術ブログでも、SDDの定義、ツール、限界について体系的な検討が始まっています。明確な業界コンセンサスが形成されつつあります。AI agentの時代には、specificationがcodeに代わって「信頼できる唯一の情報源（source of truth）」になりつつある という認識です。

この記事では2025〜2026年の最新の業界実践を基に、Software Specとは何か、なぜ重要か、どう書けばよいかを体系的に説明し、そのまま使えるベストプラクティスのテンプレートを紹介します。

1. Software Specの定義

AI coding agentの文脈では、Software Specは従来のソフトウェアエンジニアリングよりも具体的な意味を持ちます。Martin FowlerのWebサイトに掲載されたSDDの連載は、次のように正確に定義しています。

Specとは、ソフトウェアの機能を自然言語で記述し、AI coding agentの作業指針となる、構造化された振る舞い指向の成果物（artifact）です。

より直感的に言えば、SpecはあなたとAIの間の「契約」です。 何を求め、何を求めず、どのような制約があるかを正確に記述することで、最小限のやり取りで、頭の中のイメージに最も近いコードをAIに出力させます。

バックエンドエンジニアの経験があるなら、次のように考えられます。プロダクトマネージャーから曖昧なPRDを渡されると、何度も確認し、手戻りが発生します。AI coding agentは「非常に優秀な新人エンジニア」です。実行力が高く、作業は非常に速い一方で、明言しなかった部分を意図どおりに補ってはくれません。Specの質が高いほど、AIの出力は頭の中にある完成像へ近づきます。

Spec ≠ Prompt

ここで、よくある混同を解消しておく必要があります。Specは一度限りのpromptではありません。Promptは一つのメッセージであり、送信後は会話履歴の中へ埋もれます。Specはリポジトリに固定され、セッションをまたいで存在し、プロジェクトの進化に合わせて更新される 永続的かつバージョン管理された文書 です。

Addy Osmaniが勧めるように、specをプロジェクト内のSPEC.mdとして保存し、自分とAIのどちらもいつでも参照できるようにします。会話履歴が長くなったときやagentを再起動するとき、このspecファイルがAIの「忘却」を防ぐ錨になります。

2. AI Agent時代にSpecの重要性が増した理由

1. AIには暗黙のコンテキストがない

同僚と協働するとき、相手はチームの技術スタック、コーディングスタイル、ビジネス背景を知っています。AIは、教えない限り何も知りません。あなたにとって「当然」に見える前提も、AIには明示すべき制約です。

2. AIの「創造性」は両刃の剣

specに空白があっても、AIは必ずしも立ち止まって質問せず、自分で埋めます。そして、その埋め方はしばしば意図とは異なります。「ユーザー認証モジュールを書いて」と頼むと、必要なのはAPI key認証だけなのに、JWT + OAuth2 + ソーシャルログインを含む一式を作るかもしれません。過剰設計がAIのデフォルトです。

3. 「指示の呪い」（Curse of Instructions）

研究によれば、promptに多すぎる指示を入れると、各指示に対するモデルの遵守率は大きく低下します。これは「指示の呪い」と呼ばれます。すべての要件、制約、スタイル規則を一つのメッセージへ詰め込むことはできません。情報を管理するには、構造化され、階層化された specが必要です。

4. SpecはAIの出力を受け入れるための物差し

明確なspecがなければ、AIの書いたコードが良いかどうかを判断する基準すらありません。Specはchecklistを提供し、感覚ではなく体系的に検収できるようにします。

5. Specは複数Agentの協働を可能にする

sub-agentや並列agentを使う場合、それぞれが担当範囲と境界を知る必要があります。その境界を定義するのがSpecです。specがなければ、複数のagentが互いの作業領域へ踏み込み、競合するコードを生成します。

3. Specを構成する六つの主要領域

GitHubのAIチームは2,500件を超えるagents.mdを分析し、明確なパターンを見いだしました。最も効果的なspecは、六つの主要領域を網羅しています。 この知見は、あらゆるAI coding agent向けのspecに当てはまります。

1. コマンド（Commands）

実行可能なコマンドをspecの前半に置きます。ツール名だけではなく、フラグと引数を含む完全なコマンド を記載してください。Agentはこれらを頻繁に参照します。

- ビルド: `npm run build`（TypeScriptをコンパイルし、dist/へ出力）
- テスト: `npm test`（Jestを実行。コミット前に必ず成功させる）
- コード検査: `npm run lint --fix`（ESLintエラーを自動修正）

2. テスト（Testing）

テストの実行方法、使用するフレームワーク、テストファイルの配置場所、カバレッジ要件を示します。

3. プロジェクト構成（Project Structure）

ソースコード、テスト、文書の配置場所を明示します。

- `src/` — アプリケーションのソースコード
- `tests/` — 単体テストと統合テスト
- `docs/` — プロジェクト文書

4. コードスタイル（Code Style）

実際のコード例一つは、説明文三段落より効果的です。 命名規則、フォーマット規則、期待する良いコードの例を示します。

5. Gitワークフロー（Git Workflow）

ブランチ命名、コミットメッセージ形式、PR要件を示します。明確に伝えれば、Agentはすべて遵守できます。

6. 境界（Boundaries）

Agentが絶対に触れてはいけないもの、つまり秘密情報のファイル、vendorディレクトリ、本番環境の設定、特定のフォルダなどを示します。GitHubの調査では、「秘密情報をコミットしない」が最も一般的で、最も効果的な制約の一つでした。

三段階の仕組みで境界を表します。

- ✅ 常に実行: コミット前にテストを実行し、命名規則に従う
- ⚠️ 先に確認: データベースschemaの変更、新しい依存関係の追加
- 🚫 絶対禁止: 秘密情報のコミット、node_modules/の変更、CI設定の変更

4. Specのワークフロー：四段階のゲートモデル

GitHubのSpec Kitは、実践で検証された四段階のワークフローを提案しています。その中心となる考え方は、各段階に人によるチェックポイントを設け、現在の段階が検証されるまで次へ進まないこと です。

第1段階：Specify（意図を定義する）

何を構築し、なぜ構築するのかについて、概要を示します。ここで扱うのは技術スタックやアーキテクチャではなく、ユーザージャーニー、体験、成功基準 です。誰が機能を使うのか、どの問題を解決するのか、ユーザーがどう操作するのかを記述します。

AI agentに概要を詳細な仕様へ展開させます。このspecが、自分とAIが共同で作る最初の成果物になります。

実践上の提案： Claude CodeのPlan Mode（Shift+Tab）を使い、読み取り専用モードでagentにリポジトリを分析させ、詳細な計画を作らせます。計画に問題がないことを確認するまで、コードは一切書かせません。

第2段階：Plan（技術設計）

ここで技術レベルへ進みます。望ましい技術スタック、アーキテクチャ、制約を提示し、agentに包括的な技術案を生成させます。チームに標準の技術選定がある場合は、ここで説明します。コンプライアンス要件やレガシーシステムとの統合要件も、この段階で明示します。

第3段階：Tasks（タスク分解）

Agentはspecとplanを、個別に完了しテストできる具体的な作業単位へ分解します。「認証システムを構築する」ではなく、「メール形式を検証するユーザー登録エンドポイントを作る」とします。各タスクは、独立して実装・検証できるほど小さくする必要があります。これは本質的に、TDDの考え方をAI agentのワークフローへ対応づけたものです。

第4段階：Implement（実行）

Agentはタスクを一つずつ、あるいは並列に実行します。何千行もの巨大なdiffをreviewする必要はなく、特定の問題を解決する小さな変更を確認できます。Agentは、何を構築するかをspecから、どう構築するかをplanから、現在何をするかをtaskから理解しています。

このゲート型ワークフローは「砂上の楼閣のようなコード」という問題を解決します。 一見動くように見えても、少し押しただけで崩れる脆弱なAI出力を防ぎます。

5. 業界最前線から得られたベストプラクティス

実践1：まずAIに草案を書かせ、自分で洗練する

ゼロから完璧なspecを書こうとしてはいけません。より効果的なのは、AIへ明確な上位目標を与えて詳細なspec草案を生成させ、その後に自分でreviewして修正する方法です。詳細を展開するAIの強みを活用しながら、方向性の主導権は自分で保てます。

具体的には、新しいプロジェクトを始めるとき、agentへ次のように伝えます。

「あなたはAIソフトウェアエンジニアです。[プロジェクトX]について、目標、機能一覧、制約、段階的な計画を含む詳細な仕様書の草案を作ってください。」

出力を確認し、ずれやhallucinationを修正して、SPEC.mdとして保存します。

実践2：構造化が最重要

Markdownの見出しやXMLタグを使い、specの各部分を分けます。AIモデルは自由形式の散文より、構造化された文章をはるかに効率よく処理します。Anthropicのエンジニアリングチームも、promptを<background>、<instructions>、<constraints>、<output_format>などのブロックへ整理することを推奨しています。

重要な原則は、「簡潔」が必ずしも「短い」を意味しない ということです。重要な詳細は省略せず、適切な場所に配置してください。

実践3：「何をするか」より「何をしないか」を書くことが重要

多くの人が最も見落としやすい部分ですが、AI agentを制御するうえで非常に効果的です。AIが追加した不要なものを手直しするコストは、AIが漏らした必要事項を追加で頼むコストよりはるかに大きいからです。

優れた「しないこと」リストの例：

このバージョンではあいまい検索をサポートしない
V1なのでキャッシュ層を追加しない
既存のmemory_store.pyを変更せず、新しいファイルだけを追加する
現在のrequirements.txtにない依存関係を導入しない

実践4：コード例一つは説明文三段落に勝る

AIに特定のコードスタイルやアーキテクチャパターンへ従わせたい場合は、参考となるファイルを直接示す ほうが、文章で説明するより効率的です。例：

## コードスタイルの参考
src/handlers/digest.pyの構造パターンに従う。

実践5：モジュール化——分割して対処する

すべてを一つの巨大なpromptへ詰め込んではいけません。specをコンポーネントやモジュール単位に分け、その時点のタスクに必要な部分だけをAIへ渡します。指示が増えるほど各指示の遵守率が低下する「指示の呪い」の効果は、研究でも確認されています。

上級テクニック：Extended TOC（拡張目次）を作成します。 specの各章について要点だけを残した短い要約をagentに生成させます。この要約を「メンタルマップ」としてpromptへ常駐させ、詳細は必要に応じて渡します。

実践6：Specは一度限りの成果物ではなく、生きた文書

AIが実装中に設計上の判断をした場合や、機能を削除すると決めた場合は、specを更新します。specをGitへコミットしてバージョン管理してください。specはAIのためだけではありません。開発者自身がプロジェクト全体を把握し続ける助けにもなります。

実践7：技術スタックの具体的なバージョンを明記する

「Reactプロジェクト」ではなく、「React 18 with TypeScript, Vite, and Tailwind CSS」と書きます。バージョン番号と主要な依存関係を含めてください。曖昧なspecは曖昧なコードを生みます。

実践8：受け入れ基準はテスト可能にする

最も優れた受け入れ基準は、そのままテストケースへ変換できます。

## 受け入れ基準
1. 引数なしで/recallを送信 → 使用方法を返す
2. /recall <存在するキーワード>を送信 → タイムスタンプと要約を含む1〜3件の結果を返す
3. /recall <存在しないキーワード>を送信 → 分かりやすい「結果なし」メッセージを返す

AIにテストコードも同時に生成させれば、さらに効果的です。自動検証の循環ができます。

6. 最適なSoftware Specテンプレート

GitHub Spec Kitの四段階モデル、Addy OsmaniのPRD+SRS混合手法、Kiroの三文書構成、2,500件を超えるagents.mdの分析結果を組み合わせると、Claude Code、Codex CLI、Cursorなどの主要なAI coding agentで使える実践テンプレートは次のようになります。

# [機能名/プロジェクト名] — Software Spec

## 1. 目標と背景（Why & What）
### 目標
一文で要約：[この機能/プロジェクトが解決する問題]

### 背景
- ユーザー：[対象ユーザー像]
- ユーザーの課題：[この機能がない場合にユーザーが直面する問題]
- 成功基準：[完成後に「成功」をどう定義するか]

### 範囲
- これは[新規プロジェクト / 既存プロジェクトの新機能 / バグ修正]
- 現在のバージョン：V[x]。[中核価値]に集中し、完璧さは追求しない

---

## 2. 技術的制約（Constraints）
### 技術スタック
- 言語：[例：Python 3.11]
- フレームワーク：[例：python-telegram-bot 21.x]
- データベース：[例：Supabase経由のPostgreSQL 15]
- 主要な依存関係：[例：mem0ai SDK 0.1.x]

### 実行環境
- [例：GCP Cloud Run上のDocker container]
- [例：ローカル開発環境はmacOS + Python venv]

### 既存アーキテクチャの制約
- 新しいファイルの配置先：[例：src/handlers/]
- 既存パターン：[例：src/handlers/digest.pyの構造に従う]
- エントリーポイントへの登録：[例：src/main.pyで新しいhandlerを登録]

### 既知の技術的な注意点
- [例：Mem0のsearch APIは一度に最大10件を返し、ページネーションをサポートしない]
- [例：python-telegram-bot v21のAPIには破壊的変更があるため、v20の書き方を使わない]

---

## 3. コマンド一覧（Commands）
```bash
# ビルド
npm run build        # または python -m build

# テスト
pytest -v            # すべて成功してからコミットする

# コード検査
ruff check --fix .   # フォーマットの問題を自動修正

# ローカル実行
python -m src.main   # 開発サーバーを起動
```

---

## 4. インターフェースとデータ契約（Interface Contract）
### 入力
[入力の形状、提供元、形式を正確に記述]

### 処理ロジック
[中核処理の疑似コードまたはフローの説明]

### 出力
[出力の形状と形式を、例を含めて正確に記述]

### 例外
- [条件A]の場合 → [動作A]
- [条件B]の場合 → [動作B]

---

## 5. 境界（Boundaries）
### ✅ 常に実行
- コミット前にテストを実行する
- 既存のコードスタイルに従う
- 新しいファイルには対応するテストファイルを用意する

### ⚠️ 先に確認
- データベースschemaの変更
- 新しいサードパーティ依存関係の追加
- 公開APIインターフェースの変更

### 🚫 絶対禁止
- 秘密情報やtokenをコミットしない
- node_modules/やvendor/を変更しない
- CI/CD設定ファイルを変更しない
- ⚠️で確認しない限り、現在の依存関係一覧にないものを導入しない

### 機能の境界（このバージョンでは対応しない）
- [例：キャッシュ層を追加しない]
- [例：ページネーションをサポートしない]
- [例：国際化を実装しない]

---

## 6. コードスタイルの参考（Style Reference）
[実際のコード断片をスタイルの参考として示す。説明文三段落より効果的]

```python
# 参考: src/handlers/digest.py
async def handle_digest(update: Update, context: CallbackContext):
    """/digestコマンドを処理し、今日の要約を返す。"""
    user_id = update.effective_user.id

    try:
        digest = await digest_service.get_daily(user_id)
        await update.message.reply_text(
            format_digest(digest),
            parse_mode="Markdown"
        )
    except ServiceError as e:
        logger.error(f"Digest failed for {user_id}: {e}")
        await update.message.reply_text("要約を取得できませんでした。しばらくしてからもう一度お試しください。")
```

---

## 7. 受け入れ基準（Acceptance Criteria）
[GIVEN-WHEN-THEN、または直接テスト可能な場面を記述]

1. **正常系：** [入力X] → [期待する出力Y]
2. **境界事例：** [空または異常な入力] → [期待するエラー処理]
3. **統合検証：** [既存モジュールとの連携が正常か]
4. **構造への準拠：** [新しいコードが指定したアーキテクチャパターンに従っているか]

---

## 8. 参考資料（References）
- [関連するAPIドキュメントの抜粋]
- [既存コード例のファイルパス]
- [設計判断の背景]

7. テンプレートを使った実践例

上のテンプレートを使い、実際のプロジェクト向けにspecを書いてみます。例はTelegram botの記憶検索機能です。

# /recallコマンド — Software Spec

## 1. 目標と背景
### 目標
hey!stalker Telegram botに/recallコマンドを実装し、ユーザーが意味記憶から情報を能動的に検索できるようにする。

### 背景
- ユーザー：hey!stalkerの個人ユーザー
- ユーザーの課題：現在はbotから情報が届くのを受動的に待つことしかできず、過去の記憶を自分で検索できない
- 成功基準：ユーザーがキーワードを入力してから3秒以内に、関連する記憶の上位3件を返す

### 範囲
- 既存プロジェクトに追加するV1の新機能
- 高度な意味理解ではなく、基本検索に集中する

---

## 2. 技術的制約
### 技術スタック
- Python 3.11, python-telegram-bot 21.x
- mem0ai SDK経由のMem0、Supabase経由のPostgreSQL

### 既存アーキテクチャの制約
- 新しいhandlerをsrc/handlers/recall.pyに配置
- src/main.pyで登録
- src/handlers/digest.pyの構造パターンに従う
- Mem0 clientはsrc/clients/mem0.pyですでに初期化済み

### 既知の技術的な注意点
- Mem0 search APIは一度に最大10件を返し、limit引数が利用できる
- python-telegram-bot v21はasync handlerを使用する

---

## 3. コマンド一覧
```bash
pytest -v tests/
python -m src.main
```

---

## 4. インターフェースとデータ契約
### 入力
ユーザーがTelegramで`/recall <query_string>`を送信する

### 処理ロジック
```
1. query_string（/recallの後ろにあるテキスト）を解析する
2. mem0_client.search(query=query_string, user_id=user_id, limit=3)を呼び出す
3. 返された結果を整形する
```

### 出力形式
```
📌 記憶1（2025-06-15）
機械学習に関する議論：Transformerのattention機構の本質について触れた...

📌 記憶2（2025-06-10）
読書メモ：論文「Attention Is All You Need」の主要な貢献...
```

### 例外
- 引数なしの/recall → 「使い方：/recall <キーワード>、例：/recall 機械学習」
- 検索結果なし → 「関連する記憶が見つかりません。別のキーワードを試しますか？」
- Mem0 APIの異常 → 「記憶検索は一時的に利用できません。しばらくしてからもう一度お試しください。」

---

## 5. 境界
### 🚫 機能の境界（このバージョンでは対応しない）
- キャッシュを追加しない
- ページネーションを追加しない
- あいまいなスペル訂正を行わない
- main.pyへのルート登録を除き、既存ファイルを変更しない
- 新しい依存関係を導入しない

---

## 6. コードスタイルの参考
技術的制約で指定したsrc/handlers/digest.pyを参照する

---

## 7. 受け入れ基準
1. 引数なしの/recall → 使用方法を返す
2. /recall 機械学習（関連する記憶が存在すると仮定）→ タイムスタンプと要約を含む1〜3件の結果を返す
3. /recall xyzabc123（存在しないキーワード）→ 分かりやすい「結果なし」メッセージを返す
4. 新しいhandlerの構造がdigest.pyと一致する
5. tests/test_recall.pyに上記三つの場面のテストを含める

8. よくある落とし穴と対処法

落とし穴1：Specが長すぎると逆効果になる

AIの注意は均等に分布しません。冒頭と末尾は、中間部分より注目されやすい傾向があります。1ページを超えるspecは、複数のタスクへ分け、それぞれに簡潔なspecを用意することを検討してください。

対処法： 長いspecにはExtended TOC（拡張目次の要約）を作ります。各章を1〜2文の要点へ圧縮し、agentの「メンタルマップ」としてcontextへ常駐させ、詳細は必要に応じて渡します。

落とし穴2：実装方法をSpecへ書き込む

Specが記述すべきなのはWhatとWhyであり、Howではありません。AIへ目標と制約を伝え、実装方法は選ばせます。それこそがAI agentを使う意味です。

例外： AIが高い確率で誤った実装方法を選ぶと分かっている場合は、Howを明示しなければなりません。判断基準は、経験豊富なエンジニアが初めてプロジェクトを引き継いだとき、その箇所で間違える可能性があるかどうかです。間違えるならAIも間違えるため、specへ記載します。

落とし穴3：一度に大きすぎるタスクを渡す

specが優れていても、「ユーザーシステム全体を実装する」のように範囲が大きすぎると、AIの出力品質は大きく低下します。小さなタスクへ分解し、各タスクにspecを用意し、依存関係の順序に従って実行します。

落とし穴4：Specを書いた後に放置する

Specは生きた文書でなければなりません。AIが実装中に予想していなかった設計判断をした場合や、要件を変更した場合は、specを更新する必要があります。そうしなければspecとコードが乖離し、「信頼できる唯一の情報源」としての意味を失います。

落とし穴5：SDDツールが過剰設計を招く場合がある

Martin Fowlerの技術ブログに掲載された評価では、現実的な問題が指摘されています。KiroやSpec Kitのようなツールは、単純なbug fixにも複数のuser storyや十数件のacceptance criteriaを含む、大量のMarkdownファイルを生成する場合があります。小さなタスクに対しては、「鶏を割くのに牛刀を用いる」ようなものです。

対処法： タスクの規模に応じてspecの詳細度を調整します。単純なbug fixなら数行の説明で足りるかもしれません。複雑な新機能であれば、完全な四段階のフローが必要です。Specの形式は目的に奉仕するものであり、形式そのものが目的ではありません。

9. SDDエコシステムの現状（2026年4月）

現在、Spec-Driven Developmentのツールエコシステムは急速に形づくられています。

GitHub Spec Kit は、現時点で最も成熟したオープンソースのSDDフレームワークです。CLIツールとテンプレートを提供し、Claude Code、Codex、Cursor、Copilotなど主要なagentに対応しています。Specify → Plan → Tasks → Implementという四段階のゲート型ワークフローで開発を構造化します。特定agentに依存しないため、どのagentでも利用できます。

AWS Kiro は、VS Code/Code OSSを基盤としてSDDワークフローを内蔵したIDEです。requirements.md → design.md → tasks.mdという三文書構成はより直感的で、プロジェクト単位の永続設定として「steering files」も利用できます。Kiroはagent hooksにも対応し、ファイル変更やコミットを契機としてagentのタスクを自動実行できます。

OpenSpec は、より軽量な代替手段を掲げ、厳格な段階ゲートではなく柔軟な反復を重視しています。そのため、既存コードベースを持つbrownfieldの場面に適しています。

オープン標準である AGENTS.md は、60,000件を超えるオープンソースプロジェクトに採用されています。SDDフレームワークではなく、agentにプロジェクトの規約を理解させるための共通形式であり、「AIが読むREADME」と考えられます。

注意点： SDDという用語には、現時点でも統一された定義がなく、ツールごとに実装が大きく異なります。specを先に書き、コードを後で書くという中核原則は広く支持されていますが、specの構造、詳細度、長期的な保守戦略は、まだ業界で模索されている段階です。

10. 優れたSpecを書くことがキャリアにもたらす価値

AIアプリケーションエンジニアへの転向を進めているなら、specを書く能力には三つの価値があります。

第一に、portfolioプロジェクトの品質を直接高めます。 良いspecがあればAI agentをより効率的に使って高品質なコードを生成でき、作品集のプロジェクトをより早くdemo-readyな状態へ到達させられます。

第二に、これはprompt engineeringをエンジニアリングとして実践することです。 面接でprompt engineeringの経験を問われたとき、「構造化した要件定義、技術的制約の明示、境界の制御、テスト可能な受け入れ基準を含むspec-driven developmentによってAI agentを指揮しています」と答えるほうが、「temperatureを調整できます」と答えるよりはるかに説得力があります。

第三に、AI時代のエンジニアにとって中核的な能力の一つです。 AI coding agentを日常のワークフローへ取り込むチームは増え続けています。「AIに効果的にコードを書かせられるか」は、「自分で良いコードを書けるか」と同じくらい重要な能力になりつつあります。

参考資料

Addy Osmani, “How to write a good spec for AI agents,” January 2026
GitHub Blog, “Spec-driven development with AI: Get started with a new open source toolkit,” September 2025
GitHub Blog, “How to write a great agents.md: Lessons from over 2,500 repositories,” November 2025
Martin Fowler (Birgitta Böckeler), “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl,” 2025
Kiro Documentation, “Specs,” 2026
Zencoder Docs, “A Practical Guide to Spec-Driven Development,” 2025

AI Coding Agent時代の中核スキル：優れたSoftware Specの書き方#

はじめに：AIへ渡す「要件文書」が、これまで以上に重要な理由#

1. Software Specの定義#

Spec ≠ Prompt#

2. AI Agent時代にSpecの重要性が増した理由#

1. AIには暗黙のコンテキストがない#

2. AIの「創造性」は両刃の剣#

3. 「指示の呪い」（Curse of Instructions）#

4. SpecはAIの出力を受け入れるための物差し#

5. Specは複数Agentの協働を可能にする#

3. Specを構成する六つの主要領域#

1. コマンド（Commands）#

2. テスト（Testing）#

3. プロジェクト構成（Project Structure）#

4. コードスタイル（Code Style）#

5. Gitワークフロー（Git Workflow）#

6. 境界（Boundaries）#

4. Specのワークフロー：四段階のゲートモデル#

第1段階：Specify（意図を定義する）#

第2段階：Plan（技術設計）#

第3段階：Tasks（タスク分解）#

第4段階：Implement（実行）#

5. 業界最前線から得られたベストプラクティス#

実践1：まずAIに草案を書かせ、自分で洗練する#

実践2：構造化が最重要#

実践3：「何をするか」より「何をしないか」を書くことが重要#

実践4：コード例一つは説明文三段落に勝る#

実践5：モジュール化——分割して対処する#

実践6：Specは一度限りの成果物ではなく、生きた文書#

実践7：技術スタックの具体的なバージョンを明記する#

実践8：受け入れ基準はテスト可能にする#

6. 最適なSoftware Specテンプレート#

7. テンプレートを使った実践例#

8. よくある落とし穴と対処法#

落とし穴1：Specが長すぎると逆効果になる#

落とし穴2：実装方法をSpecへ書き込む#

落とし穴3：一度に大きすぎるタスクを渡す#

落とし穴4：Specを書いた後に放置する#

落とし穴5：SDDツールが過剰設計を招く場合がある#

9. SDDエコシステムの現状（2026年4月）#

10. 優れたSpecを書くことがキャリアにもたらす価値#

参考資料#