「仕様駆動開発って何？」と思っている方でも読める記事です。
後半は思想強めです。
仕様駆動開発が生まれる背景
Vibe Codingの限界とリスク
コーティングAIエージェントの普及で、設計なしに感覚でプロンプトを投げるVibe Codingが登場した。プロトタイプ作成には早いが、エンタープライズ開発では致命的である。
チャットが長引くとAIが全体像を見失い、コンテキスト・ドリフトが起き、デグレが多発する。また、AIはデザインパターンやセキュリティを無視した動くだけのコードを書きがちで、技術的負債が自動生成されてしまう。自然言語だけでは再現性がなく品質が安定しないのも課題だ
仕様書は最強のプロンプト
仕様駆動開発はAIのコンテキスト・アンカーとして機能する。
ユーザー登録機能を作ってではなくこのユーザー登録機能の仕様に従ってと指示するSchema-Driven Promptingなら、AIの探索空間を狭めて決定論的なコード生成ができる。
仕様書は人間とAIの共通言語だ。先に定義された仕様書を参照すれば、その場の自然言語指示よりトークン効率が圧倒的に高く、コンテキスト制限内でも複雑なシステムを扱えるようになる。
仕様駆動開発のやり方
仕様駆動開発用のツールは数多く存在する、
Kiro、GitHub Spec Kit、cc-sdd、Agent Skills製のものなど、選択肢豊富
ツールごとに用語が異なるが、共通するプロセスが存在する。
| ステップ | GitHub Spec Kit | Kiro | cc-sdd |
|---|---|---|---|
| プロジェクト方針の定義 | Constitution（憲法） | - | Steering（プロジェクト定義） |
| 用件定義 | Specify（仕様化） | Requirements | Specs（機能ごとの仕様ファイル） |
| 設計・実装計画 | Plan（計画） | Design | Design（settings にテンプレートあり） |
| タスク分解 | Implement（実装） | Task List | tasks.md |
共通する流れ
① プロジェクト方針の定義
プロジェクト全体の指針を定義する。使用する言語、フレームワーク、コーディング規約、絶対にやってはいけないことなどだ。
これはコーティングエージェントにとってシステムプロンプトとして機能する。
② 用件定義
開発者は何を作りたいかを自然言語で入力する。コーティングエージェントはそれを解析し、詳細な仕様書を生成する。開発者はこの生成された仕様書をレビューし、意図とずれている部分を修正する。
③ 設計・実装計画
確定した仕様に基づき、コーティングエージェントが技術的な実装計画を作成する。
ファイル構造、変更すべき関数、API定義などだ。コードを書く前に、この計画のレビューが行われる。
④ タスク分解・実装
計画が承認されると、コーティングエージェントはそれをタスク単位に分解し、コードを生成する。この時点では、プロジェクト方針、技術スタック、コーディング規約、要件定義、設計、そして現在やるべきタスクと対応する要件をすべて把握した状態で実装に入る。
この流れを経て、コーティングエージェントはログイン機能を作ってという一言ではなく、完全なコンテキストを持って作業に進められる。
cc-sddの使い方
cc-sddを選定した主な基準は以下の通りです。
- IDEに依存しない：特定の開発環境に縛られず利用可能であること
- Claude Codeとの親和性：Claude Codeから利用しやすい構成であること
- 社内実績：KAG内の別チームですでに採用実績があり、知見が活用できること
cc-sddのクイックスタート
プロジェクトのルートディレクトリで以下のコマンドを実行し、cc-sdd に必要な環境を初期化する。
npx cc-sdd@latest --claude --lang ja
CLAUDE.md がすでに存在する場合、コマンド実行時にその処理方法を尋ねられる。
基本的には Overwrite（上書き）を選択する。
すでに CLAUDE.md を独自にカスタマイズして運用している場合は、Append（追記）や Skip（何もしない）を選ぶことも可能だ。
Planned changes:
• Commands (.claude/commands/kiro/) — new (11 file(s))
• Project Memory document (CLAUDE.md) — updates detected (1 existing) (1 file(s))
• Settings templates and rules (.kiro/settings/) — new (25 file(s))
Project Memory document (CLAUDE.md) already exists. How should we apply updates? (recommended: Overwrite)
1. Overwrite CLAUDE.md
Replace the document with the latest template (previous content will be backed up if enabled).
2. Append updates to CLAUDE.md
Keep your existing notes and add new template sections after them.
3. Keep current CLAUDE.md
Do not change the Project Memory document.
Select option [1-3] (Enter for 1): 1
✅ Setup completed: written=37, skipped=0
== Recommended models ==
• Claude Opus 4.5 or newer
== Next steps ==
1. Launch Claude Code and run `/kiro:spec-init <what-to-build>` to create a new specification.
2. Tip: Steering holds persistent project knowledge—patterns, standards, and org-wide policies. Kick off `/kiro:steering` (essential for existing projects) and `/kiro:steering-custom <what-to-create-custom-steering-document>`. Maintain Regularly
3. Tip: Update `{{KIRO_DIR}}/settings/templates/` like `requirements.md`, `design.md`, and `tasks.md` so the generated steering and specs follow your team's and project's development process.
CLAUDE.md は Claude Code 起動時に読み込まれる説明書のような役割を果たすが、
cc-sddで上書きを行うと、その役割は cc-sddのSteeringへと移管される。
初期化完了後、下記のフォルダが追加される。
your-project/
├── .kiro/
│ └── settings/ # テンプレート
└── .claude/commands/ # cc-sdd用のClaude Codeコマンド
プロジェクト方針・定義を作成
Claude Code 単体で使用する場合、CLAUDE.md がその役割を担う。
cc-sdd を使う場合は、Steering にその役割が移管される。
Claude Code を起動し、以下のコマンドを実行する。
/kiro:steering
実行が完了すると、以下のディレクトリが追加される。
your-project/
├── .kiro/
│ ├── settings/
│ └── steering/ # プロジェクト方針
│ ├── product.md # プロダクト概要
│ ├── structure.md # プロジェクト構造
│ └── tech.md # 技術スタック
└── .claude/commands/
steeringフォルダの中身を確認し、もし不足があれば内容を追記・修正する、
ここまでで下準備は完了だ。
要件定義
作りたいものを入力する。
ここで注意すべきは、いきなり大きなタスクを投げるのではなく、
人間の開発者にアサインするときと同様に、中規模くらいのタスクを依頼することだ。
/kiro:spec-init ocrの図表読み取りと既存のデータ比較機能を実装する(作りたいもの)
実行すると、下記のようなフォルダが生成される、.kiro/specs/{英語のタスク名}、機能実装のワークスペースのようなものである。
そのワークスペースの配下に、requirements.mdが追加され、用件定義書として、最低限のものが書かれてる状態である。
# Requirements Document
## Introduction
ocrの図表読み取りと既存のデータ比較機能を実装する
## Requirements
次に、要件を詳細化するために以下のコマンドを実行する。
/kiro:spec-requirements ocr-diff-compare
実行が完了すると、requirements.md の内容が以下のように細分化される。
# Requirements Document
## Introduction
本仕様は、ooでんきサービスのチェックシート画像をアップロードし、AI（Mastra エージェント）による画像認識で構造化データを抽出した上で、既存のモックデータと比較して差分を検出・表示する機能を定義する。
フロントエンド（React）が画像アップロード UI を担当し、バックエンド（Mastra）が画像認識・構造化出力・差分比較を担当する。Mastra の構造化出力（Structured Output）機能を活用し、画像から抽出したデータをモックデータと同一スキーマで出力することで、正確なフィールド単位の差分比較を実現する。
### 比較対象モックデータ構造
比較対象となる既存データは以下の構造を持つ auでんきサービスのチェックシート情報である:
- `document_info`: ドキュメントメタ情報（タイトル、サービス名、対象エリア、バージョン等）
- `urls`: 関連URL（利用規約等）
- `checklist_items`: チェックリスト項目（ID、カテゴリ、質問、選択肢、注意事項、要件等）
- `contact_info`: 連絡先情報
- `legal_consent`: 法的同意事項
## Requirements
...(その他内容)
内容を確認し、不足があれば Claude Code に追加を依頼できる。
もしくは手動で修正した上で /kiro:spec-requirements ocr-diff-compare を再実行する。
設計・実装計画
このステップでは、どう作るかが設計される重要なステップだ。
下記のコマンドを実行するとdesign.mdとresearch.mdが作られる。
/kiro:spec-design ocr-diff-compare
.kiro/specs/ocr-diff-compare/design.mdが生成されます。
# Design Document: OCR Diff Compare
## Overview
**Purpose**: ooでんきサービスのチェックシート画像を AI エージェントのビジョン能力で直接読み取り、既存モックデータとの差分を検出・表示する機能を提供する。
**Users**: 店舗スタッフが、チェックシート画像をチャットにアップロードし、対話的に差分を確認するワークフローで利用する。
**Impact**: 既存のチャットインターフェースに画像アップロード機能を有効化し、OCR Diff Compare エージェントと差分比較ツールを追加する。旧設計の OCR 抽出ツール（`ocrExtractTool`）は削除し、エージェントのビジョン能力による直接解析方式に移行する。
### Goals
...(その他)
.kiro/specs/ocr-diff-compare/research.md に調査結果と設計判断を記録済み
# Research & Design Decisions
---
**Purpose**: OCR Diff Compare 機能の技術設計に向けた調査結果と設計判断の記録
---
## Summary
- **Feature**: `ocr-diff-compare`
- **Discovery Scope**: Extension（既存の Mastra + React チャットアプリケーションへの機能拡張）
- **Key Findings**:
個人的なやり方として、このステップで Agent Skills の利用を挟んでいる。
Claude Code だけではベストプラクティスがわからないこともあるため、MCP でドキュメントを検索させたり、各ライブラリの公式が提供する Agent Skills を使わせた方が精度は高い。
プロジェクトによって使う Skills は異なるが、今回の例は Mastra + React のプロジェクトのため、
- vercel-react-best-practices
- web-design-guidelines
- mastra
三つの Skills を事前にインストールしている。
インストール方法も簡単で、以下のコマンドを実行し、必要な Skills を選んでインストールするだけだ。
npx skills add vercel-labs/agent-skills
npx skills add mastra-ai/skills
インストール済みであれば、以下のように Skills を使って research.md を更新できる。
.kiro/specs/ocr-diff-compare/research.mdのmastraに関連する内容、mastraのスキル使って、正しいかどうか確認して
⏺ まず、research.mdの内容を確認します。
⏺ Read 1 file (ctrl+o to expand)
⏺ research.mdの内容を確認しました。Mastra関連の記述を検証するため、Mastraスキルと埋め込みドキュメントを確認します。
⏺ Skill(mastra-embeded-docs-look-up)
インフラにAWSを使っていれば、AWSのナレッジMCPも使えるようにしておくと良い
{
"mcpServers": {
"aws-knowledge-mcp-server": {
"command": "uvx",
"args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"]
}
}
}
タスク分解
実装計画完了したら、下記のコマンドを実行して、タスク分解に入る。
/kiro:spec-tasks ocr-diff-compar
分解完了したら、ワークスペースにtasks.mdファイルが作られて。
TODO LISTのようなタスクが生成される、チェックボックスはタスク実行後に自動更新される。
# Implementation Plan
- [ ] 1. チェックシートの Zod スキーマとモックデータを定義する
- [ ] 1.1 (P) チェックシートドキュメントの Zod スキーマを作成する
タスク内容問題なければ、下記のコマンドで実装に入れる
/kiro:spec-impl ocr-diff-compar
一部のタスクを実行するだけの場合、下記のようにタスク指定もできる
/kiro:spec-impl ocr-diff-compar [task-ids]
仕様駆動開発でナレッジの欠損を防ぐ方法
仕様駆動開発を続けていると、開発者の役割がレビュワーへとシフトし、実装ナレッジが開発者側に蓄積されにくくなるという問題が生じる。
しかし、これは避けられない変化だと考えている
工業革命で機械が労働者の作業を代替したのと同じ構造であり、あえて逆らう必要はない。
大事なのは、ナレッジを人間に戻すことではなく、コーディングエージェントがナレッジにアクセスしやすく、作業しやすい環境を整えることだ。
やるべきことは、個人的には以下の二つだと考えている。
- ドキュメントをコーディングエージェントにとって理解しやすい形に整えること
- ドキュメント更新の役割もコーディングエージェントに移管すること
これからの内容はあくまで個人的な考えであるため、参考にするかはご自由にどうぞ
コードマップの作成
コーディングエージェントがプロジェクトの全体像——何をやっていて、どんな機能があるのか——を把握するためのドキュメント構造だ。
すでにドキュメントが整理されていれば、既存の構造を活用して問題ない。
コードマップの切り方は2種類あります。
docs/CODEMAPS/
├── INDEX.md # 概要
├── frontend.md # フロントエンドの構成
├── backend.md # バックエンドおよびAPIの構成
├── database.md # データベース設計（スキーマ）
├── integrations.md # 外部サービス連携
└── workers.md # バックグラウンドジョブ（非同期処理）
docs/CODEMAPS/
├── INDEX.md # 概要
├── power-point-creation.md # パワポー作成機能構成
└── review.md # レビュー機能構成
どちらが良いかはケースバイケースだが、特定機能の開発に集中させたい場合は、機能ごとの分割が有用だ。コンテキストを絞れる反面、分割の粒度に不備があるとコンテキスト不足になるリスクもある。
コードマップのフォーマットも自由だが、最終更新日は必須とする。
# [Area] Codemap
**Last Updated:** YYYY-MM-DD
**Entry Points:** list of main files
## Architecture
[ASCII diagram of component relationships]
## Key Modules
| Module | Purpose | Exports | Dependencies |
|--------|---------|---------|--------------|
| ... | ... | ... | ... |
## Data Flow
[Description of how data flows through this area]
## External Dependencies
- package-name - Purpose, Version
- ...
## Related Areas
Links to other codemaps that interact with this area
コードマップとSteering（プロジェクト定義）は何が違うのか、と疑問に思うかもしれない。
コードマップはより粒度が細かい実装寄りの情報であり、Steeringはプロジェクト全体の制約やルールを定義するものだ。
動的にドキュメントを参照する
Claude CodeのRulesは、CLAUDE.mdの肥大化を防ぎ、プロジェクトやファイル単位でAIの挙動を精密に制御するための動的読み込み機能である。.claude/rules/配下に定義することで有効化できる。
Rulesを使えば、作業に必要なドキュメントだけコーディングエージェントに渡せることができる。
使い方は簡単で、下記のようにルールファイルを作成する。
paths:には、どのファイル操作時にこのルールを適用するかというスコープを定義する。
このサンプルルールでは、コーディングエージェントがinfrastructureフォルダ配下のTerraformファイルを操作する際に、自動的にルールが読み込まれる設定になっている。
---
paths: infrastructure/**/*.{tf}
---
docs/test.mdを確認してください。
そして、ルール内で参照先として指定したドキュメントには、下記のような内容を記載しておく。
今Terraformで構築してるけど、いつかはAWS CDKに置き換えますよ
この状態で、infrastructure関連のタスクをやらせると、.claude/rules/iac-rule.mdが自動的に読まれた。
❯ infrastructure/envs/deva/outputs.tfを読んでください
⏺ Read 1 file (ctrl+o to expand)
⎿ Loaded .claude/rules/iac-rule.md
次に、CDKに置き換える計画はありますか？と聞いてみる。
cdkに置き換える予定あるか？
∴ Thinking…
The user is asking if there are any plans to replace Terraform with CDK (AWS CDK). This is a question about project plans/decisions, not a
coding task. I should check if there's any documentation or discussion about this in the project.
Let me check docs/test.md as mentioned in the system reminder rule, and also look for any CDK-related references in the project.
03:13 PM claude-opus-4-6
⏺ プロジェクト内にCDK移行に関する情報があるか確認します。
⏺ Read(docs/test.md)
⎿ Read 1 line
このように、作業コンテキストに応じたナレッジを動的にコーディングエージェントへ渡すことができた。
なぜルールファイルに直接ナレッジを書かないのか？
Rulesはあくまでナレッジへのリンクとして機能させ、実際のナレッジは別ドキュメントに記載する。
ナレッジは作業を進めるたびに更新されるが、リンクであるRules自体は変更する必要がない。この分離により、ナレッジの鮮度を保ちつつ、ルール定義のメンテナンスコストを最小限に抑えられる。
ナレッジの自動更新フロー
必要なナレッジの自動読み込みができた、ここからは、変更された内容をナレッジに反映することの自動化について紹介する。
ドキュメント整理専用のサブエージェントおよびコマンドを用意する。
サブエージェント:
- .claude/agents/doc-updater.md
---
name: doc-updater
description: Documentation and codemap specialist. Use PROACTIVELY for updating codemaps and documentation. Runs /update-codemaps updates READMEs and guides.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: haiku
---
# Documentation & Codemap Specialist
あなたは、コードマップとドキュメントをコードベースに合わせて最新の状態に保つことに重点を置くドキュメンテーションスペシャリストです。あなたの使命は、コードの実際の状態を反映した、正確で最新のドキュメントを維持することです。
コマンド:
- update-codemaps.md
# Update Codemaps
コードベースの構造を分析し、アーキテクチャのドキュメントを更新します。
1.git statusで変更範囲を確定する
2.参照されたドキュメントに変更すべき内容があるとそれを変更する。
3.各コードマップにフレッシュネスタイムスタンプを追加する
4.レポートを .reports/codemap-diff.txt に保存します。
動的でドキュメントを読んだことで、修正範囲も絞りやすい。
❯ 読んだドキュメントを教えてください
⏺ この会話で読んだドキュメントは以下の2つです：
1. infrastructure/envs/deva/main.tf - deva環境のTerraformメイン設定ファイル
2. docs/test.md - CDK移行に関するメモ（「いつかはAWS CDKに置き換える」という記載）
そして、ナレッジの修正タスクをサブエージェントに依頼する。
サンプルとして、以下のようなAIエージェントが実際に使用しているモデルを定義したドキュメントを想定する。
このドキュメントは、mastra/agents/review-agent.tsが読み込まれる際、Rulesによって参照されるよう設定するものとする。
#### エージェントシステム設定
```typescript
// Review Agent設定
reviewAgent: {
model: "jp.anthropic.claude-sonnet-4-5-20250929-v1:0",
region: "ap-northeast-1",
capabilities: [
"document_analysis",
"strategic_review",
"presentation_optimization"
],
context_window: "200k_tokens",
temperature: 0.3
}
そしてmastra/agents/review-agent.tsを修正して、使用するモデルを変更する。
},
+ model: bedrock("anthropic.claude-haiku-4-5-20251001-v1:0"),
});
この状態で、ドキュメント変更サブエージェントを呼び出す。
❯ ドキュメント変更サブエージェント呼び出して、読んだドキュメントも教えて
⏺ 私が読んだドキュメントは以下の2つです：
1. docs/agent.md — エージェントシステム設定のドキュメント（モデル: jp.anthropic.claude-sonnet-4-5-20250929-v1:0 と記載）
2. xx/mastra/agents/review-agent.ts — 実際の実装コード（モデル: anthropic.claude-haiku-4-5-20251001-v1:0 を使用）
doc-updaterサブエージェントを呼び出します。
⏺ doc-updater(Update docs/agent.md to match code)
⎿ Read(xx/mastra/agents/review-agent.ts)
Write(docs/agent.md)
+3 more tool uses (ctrl+o to expand)
ctrl+b to run in background
これで、ナレッジの同期も簡単にできるようになった。
コラボレーション・ユニットの話
ここからは思想強めな怪文書になる!
Aatish Nayakさんの記事と個人の考え方をまとめたものになる。
ここまで読んだ方は、コーダーはもういらないのでは？ と思うかもしれない。
実際、コーディングエージェントをうまく使いこなせば、かつての開発チームに匹敵する開発力を、個人が比較的少ないコストで手にできる時代になった。
特にClaude Code Agent Teamsの登場により、もう人間で構成される開発チームは不要だと感じる人もいるだろう。たしかにその通りだ。どうやって作るかからなぜこれを作るのかへ、開発者の役割の転換はすでに始まっている。
しかし、AIエージェントは個人の生産性向上には有効である一方、組織での活用にはまだ課題が残る。
なぜなのか？ 今の企業における仕事とは、コラボレーション、交渉、エスカレーション、そして時間をかけた判断の共有といった、人と人との間で生まれるプロセスによって成り立っているからだ。
このプロセスの中に、どれほど有能な個人もしくはAIが一人いたとしても、成果を大きく変えることはできない。
この制約から脱却するには、エージェントが人間の役割と一対一で対応するものではないと理解する必要がある。エージェントは再生可能な知能のリソースとして捉えるべきだ。
コーディングエージェントが良い例だ。
成熟したコーディングエージェントは一人の開発者を置き換えるものではなく、開発チームそのものの本質を引き出す存在である。
役割ではなく「コラボレーション・ユニット」を中心に組織を再構成する
こうした未来の協力構造を構築するには、まず、人間の制約、専門性、階層などから解放されたとき、組織のあるべき姿を想像しなければならない。
各部門が何のために存在しているのか、その中心となる共有されたオブジェクトを定義し、それを人間の役割に代わる組織の重心に据える。
プロダクト開発部 → 核は「ロードマップ」
再編前: プロダクトマネージャーはリソース調整やスケジュール管理に追われていた。
再編後は: AIが参加し、未解決のトレードオフを追跡したり、リソースの再配分を推奨したりする。人間の仕事は、コンテキストの再確認ではなく、方向性の設定と顧客課題の理解へとシフトする。
この能力を解き放つには、モデル能力の向上、環境整備、そして組織の権限委譲の融合が必要になる。
コーディングエージェントですでに見られ始めているように、Claude Codeはエージェントの軍団を管理するインターフェースになりつづある。
これから、大手のモデルベンダーからは、ユーザーやタスクをまたいでモデルが状態を保持する共有チームコンテキストをリリースするだろう。
AIを無尽蔵の労働力としてユニット——見解、物語、前提、ロードマップ——の維持管理に充て、人間はそのユニットの方向性を判断し、責任を負う側になる、それがこの再編の本質だ。
悪く言えば、雇用を生まない産業革命がもう始まっている。自分のキャリアをどうするか、本気で考えるべき時期だ
参考資料