はじめに
Kiroに代表される仕様駆動開発（Spec-Driven Development）は、AIエージェントによる開発に「要件→設計→タスク→実装」という構造を与えるアプローチとして注目されています。
本記事では、仕様駆動開発フレームワーク「cc-sdd」で仕様を整理し、Claude Codeのカスタムスラッシュコマンドで実装からPR作成、さらにはレビューボットへの対応まで大幅に省力化する方法を紹介します。
私が実際に運用しているワークフローであり、品質を保ちつつ人間の作業量を最小限に抑えられていると感じています。
全体像
ワークフローは大きく「仕様フェーズ」と「実装フェーズ」の2段階で構成されます。
ポイントは人間の作業が仕様フェーズの承認に集中していることです。仕様を詳細につめてタスクを明確化するところに人間が注視することで、実装フェーズはコマンド1つで起動し、テスト・レビュー・修正・PR作成・レビュー対応まで走ります。
もちろん完全放置というわけではなく、最終的なPRレビューは人間が行いますし、途中で想定外のエラーが起きれば介入が必要です。しかし、正常系では仕様の承認後に人間が手を動かす場面はほとんどありません。
cc-sddとは何か
仕様駆動開発の背景
Kiroが提唱した仕様駆動開発は、AIに「とりあえずコードを書いて」ではなく、「まず要件を定義し、設計し、タスクに分解し、それに従って実装する」という構造化されたプロセスをAIエージェントに踏ませるアプローチです。
これにより「AIが的外れな実装をして大量の手戻りが発生する」という問題を軽減できます。しかし、実際のチーム開発では以下の課題がありました。
- ツールロックイン：Kiro IDEでしか使えない
- バリデーションの不足：仕様の品質チェックが弱い
- チーム標準の適用が困難：テンプレートやルールのカスタマイズ性が低い
cc-sddの位置付け
cc-sddは、gotalabが開発したKiro互換の仕様駆動開発フレームワークです。Kiroの「要件→設計→タスク→実装」というワークフローを継承しつつ、以下の特徴を持ちます。
7つのAIプラットフォームに対応：
Claude Code、Cursor、GitHub Copilot、Gemini CLI、Codex、Qwen Code、Windsurfで同じワークフローを使えます。チームメンバーがそれぞれ好みのエディタ/AIを使いつつ、仕様の形式が統一されます。
npx cc-sdd@latest --claude --lang ja # Claude Code npx cc-sdd@latest --cursor --lang ja # Cursor npx cc-sdd@latest --gemini --lang ja # Gemini CLI
実装前の必須承認フロー：
要件→設計→タスクの各段階で承認が必要です。承認しないと次のフェーズに進めないため、「AIが仕様を無視して実装を始めてしまう」問題を構造的に防ぎます。 Kiroよりもガードレールが強化されている印象が強いです。
組み込みバリデーション：
/kiro:spec-validateコマンドで、要件の曖昧さ、設計との不整合、タスクの依存関係エラーなどを自動検出できます。
cc-sddが生成するもの
セットアップ後、仕様フェーズを進めると.kiro/specs/{feature-name}/配下に以下のファイルが生成されます。
| ファイル | 内容 |
|---|---|
spec.json |
仕様のメタデータ（承認状態、言語設定など） |
requirements.md |
EARS形式の機能要件・非機能要件 |
design.md |
アーキテクチャ設計（データモデル、API、コンポーネント構成、Mermaid図） |
tasks.md |
依存関係付きの実装タスクリスト（チェックボックス形式） |
また、.kiro/steering/にはプロジェクト全体の技術スタックやアーキテクチャパターンなどの情報が保存され、仕様生成時にコンテキストとして参照されます。
仕様フェーズ：cc-sddで仕様を整える
ここでは Claude Code での利用を前提に、実際のコマンドと流れを説明します。
セットアップ
cd your-project npx cc-sdd@latest --claude --lang ja
プロジェクトルートに.kiro/ディレクトリが作成されます。
ステップ1：仕様の初期化
/kiro:spec-init 写真アルバム機能（アップロード、タグ付け、共有機能付き）
AIが機能の概要を理解し、.kiro/specs/photo-albums/配下に仕様ドキュメントのベースを作成します。
ステップ2：要件定義
/kiro:spec-requirements photo-albums
EARS形式（Easy Approach to Requirements Syntax）で詳細な要件が生成されます。ここが最初の承認ポイントです。生成された要件を確認し、不足があれば指摘して修正させ、問題なければ承認します。
ステップ3：設計
/kiro:spec-design photo-albums
承認された要件をもとに、アーキテクチャ設計が生成されます。データモデル、API設計、コンポーネント構成がMermaid図とともに明確化されます。これが2番目の承認ポイントです。
ステップ4：タスク分解
/kiro:spec-tasks photo-albums
設計に基づいて実装タスクが生成されます。各タスクは依存関係が整理されており、どの順番で実装すべきかが明確です。これが3番目の承認ポイントです。
ここまでが仕様フェーズです。各段階で人間が確認・承認することで、「AIが的外れな方向に突っ走る」ことを防ぎます。
実装フェーズ：カスタムコマンドの全貌
仕様フェーズの成果物（requirements.md、design.md、tasks.md）が揃ったら、実装フェーズに入ります。
/my:spec-impl photo-albums
このコマンドの実体は、Claude Codeのカスタムスラッシュコマンド機能で.claude/commands/配下に配置したMarkdownファイルです。中身はAIへの指示書であり、4つのフェーズを順に実行するよう記述しています。
以降、各フェーズの設計意図と、スキルに記述している指示の実際の内容を紹介します。
補足:なぜ実装フェーズを自作したのか
cc-sddには/kiro:spec-implという実装コマンドが標準で用意されています。しかし、このコマンドは「コンテキストをclearして、タスクを1つずつ指定して実行する」というスタンスで、それを人間が都度手動で行う必要があります。タスクが10個あれば10回clearして10回コマンドを打つわけで、仕様フェーズで省力化した分の手間がここで戻ってきてしまいます。
ただし、「都度clearする」という設計思想自体は理にかなっています。AIエージェントのコンテキストウィンドウは有限で、タスクを積み重ねるごとに前のタスクの情報がコンテキストを圧迫します。コンテキストが広い（クリーンな）状態でタスクを実行したほうが精度が高いというのは、実際に運用して体感しているノウハウです。
そこで着目したのがClaude Codeのサブエージェント機能です。サブエージェントはメインのコンテキストとは独立した子プロセスとして動作するため、clearの代わりに「タスクごとに別コンテキストで実行する」ことが実現できます。しかも手動でclearする必要がなく、タスクの連続実行を1コマンドで回せます。
さらにサブエージェントには専門性（エージェントタイプ）を指定できるという利点があります。TypeScriptの実装タスクにはnextjs-coder、SQLマイグレーションにはsql-coderといった具合に、タスクの内容に応じた専門エージェントを事前に定義しておき、アサインすることで汎用エージェントに比べて実装精度が向上します。
これらの知見はeverything-claude-codeのプラクティス集から着想を得て、自分のワークフローに組み合わせたものです。
PHASE 1：TDD × サブエージェントによるタスク実装
コンテキスト読み込みとタスク選択
まず、スキルは仕様フェーズの成果物とプロジェクトメモリを読み込みます。
**Read all necessary context**: - `.kiro/specs/$1/spec.json`, `requirements.md`, `design.md`, `tasks.md` - `.kiro/steering/` directory for project memory **Validate approvals**: - Verify tasks are approved in spec.json (stop if not) **Determine tasks to execute**: - If `$2` provided: Execute specified task numbers (e.g., "1.1" or "1,2,3") - Otherwise: Execute all pending tasks (unchecked `- [ ]` in tasks.md)
承認されていなければ実行を停止し、前のフェーズの完了を促します。これにより仕様なき実装が構造的に不可能になります。
特定タスクだけを指定して実行することもできます（例：/my:spec-impl photo-albums 1,2,3）。
サブエージェントへの委任
各タスクは独立したサブエージェントに委任します。先述の通り、これがclearの代替であり、クリーンなコンテキストでの実行を実現する核心です。
**Important**: 各タスクは独立したサブエージェントで実行する（コンテキスト分離のため） サブエージェントへの指示内容: - タスクの具体的な実装内容 - 関連するdesign.mdの該当セクション - 使用するファイルパス - TDD手順（下記参照）
タスクの内容に応じて最適なサブエージェントの種類を選択します。ルーティングテーブルを別途定義してあり、たとえば以下のように振り分けます。
| タスクの種類 | エージェントタイプ |
|---|---|
| TypeScript/React実装 | nextjs-coder |
| SQLマイグレーション | sql-coder |
| Terraform設定 | terraform-coder |
| JPA/Hibernateエンティティ | jpa-model-coder |
| Kotlin/Quarkus | kotlin-coder |
| 上記に該当しない | general-purpose |
TDDの強制
各サブエージェントにはTDD（テスト駆動開発）の手順を明示的に指示しています。
1. **RED - Write Failing Test**: - テストを先に書く（まだ実装がないので失敗する） - 説明的なテスト名を使用 2. **GREEN - Write Minimal Code**: - テストを通す最小限の実装 - 過剰な設計を避ける 3. **REFACTOR - Clean Up**: - コード構造の改善 - 重複の除去 - 全テストがパスすることを確認
AIにTDDを強制する理由は、テストの存在保証です。「テストも書いてね」という曖昧な指示だと省略されることがありますが、RED→GREEN→REFACTORの手順を明示すると、テストが先に書かれることが確実になります。
タスク完了とコミット
各タスク完了時に、tasks.mdの更新とコミットを行います。
1. **Mark Complete**: tasks.md の `- [ ]` を `- [x]` に更新 2. **Commit**: 日本語でコミットメッセージを作成 - `.kiro/` ディレクトリはコミット対象外とする - ステージングは対象ファイルを個別に指定する（`git add -A` は使わない）
# .kiro/ を除外してステージング git add --all -- ':!.kiro/' git commit -m "feat: [タスク番号] [タスク内容の要約]"
.kiro/配下の仕様ファイルをコミット対象外にしているのは、これらがワーキングドキュメント（作業中の管理ファイル）であり、実装コードとは管理サイクルが異なるためです。
PHASE 2：多層的な品質レビューとフィードバックループ
全タスクの実装が完了すると、4段階の品質チェックが実行されます。
検証ループ
ビルド・型チェック・リント・テスト・セキュリティスキャンを一括で実行し、結果をレポートします。
VERIFICATION REPORT ================== Build: [PASS/FAIL] Types: [PASS/FAIL] (X errors) Lint: [PASS/FAIL] (X warnings) Tests: [PASS/FAIL] (X/Y passed, Z% coverage) Security: [PASS/FAIL] (X issues) Diff: [X files changed] Overall: [READY/NOT READY] for PR
コードレビューとフィードバックループ
コードレビューエージェントが変更ファイルを全件レビューし、CRITICAL / HIGH / MEDIUM / LOW の全レベルの指摘を対応対象とします。
指摘があった場合、tasks.mdに追記されます。
## Review Fixes (Round N) - [ ] [Review] HIGH: N+1クエリの解消 (`src/db/users.ts:15`) - [ ] [Review] MEDIUM: エラーハンドリング追加 (`src/service.ts:88`)
そしてPHASE 1に戻り、追記されたタスクをサブエージェントで修正。修正後に再度PHASE 2の全チェックが走ります。このループは最大3回まで繰り返され、指摘がなくなるか上限に達したらPHASE 3に進みます。
人間が介入しなくても、AIが自分自身のコードをレビューし、問題を見つけ、修正するサイクルが回ります。
PHASE 3：PR作成
品質チェックをパスしたら、ブランチをプッシュしPRを作成します。
gh pr create --title "[Feature] $1 の実装" --body " ## Summary - [実装内容の要約] ## Tasks Completed - [x] Task 1: ... - [x] Task 2: ... ## Test Coverage - X% coverage achieved ## Review Results - Code Review: PASSED - Security: PASSED - Verification: PASSED "
PHASE 4：ボットレビュー対応
PR作成後、CodeRabbitやGitHub Copilotなどのレビューボットが指摘を残すことがあります。PHASE 4はこれにも対応します。
スキルではボットレビューのコメントを構造化データとして解析します。
エージェントが返す構造化データ: - 各コメントの severity（CRITICAL / HIGH / MEDIUM / LOW） - カテゴリ（security, performance, code-quality, bug, style, testing） - 対象ファイル・行番号 - 元のコメント本文
これらの指摘はPHASE 2のコードレビュー指摘と同じ形式でtasks.mdに追記されます。
## PR Review Fixes (Round N) - [ ] [PR-Review] CRITICAL (security): XSS脆弱性の修正 (`src/api/handler.ts:42`) > Original: "User input is not sanitized before rendering..." - [ ] [PR-Review] HIGH (performance): N+1クエリの解消 (`src/db/users.ts:15`) > Original: "This query inside a loop causes N+1 problem..."
修正後にプッシュすると再度ボットレビューが走る可能性があるため、待機→取得→修正のループを最大2ラウンド実行します。上限を超えた場合は残存する指摘をレポートに記載し、人間に引き継ぎます。
エラーハンドリング
スキルには暴走を防ぐための安全策も組み込んでいます。
即時停止する環境エラー：
ポート競合（EADDRINUSE）、権限エラー（EACCES）、ディスク容量不足（ENOSPC）などの復帰困難なエラーは即時停止し、状況を報告します。
リトライ上限：
同一エラーが5回発生した場合、実装を停止してエラーパターンと試行内容を報告し、別のアプローチを提案します。
仕様未承認の場合：
spec.jsonでタスクが承認されていなければ実行自体を拒否し、仕様フェーズの完了を促します。
この手法が効果的な理由
仕様と実装の一貫性
cc-sddで作成した仕様（requirements.md、design.md）を実装フェーズのサブエージェントが参照します。仕様から逸脱した実装が生まれにくい構造になっています。
コンテキスト分離による品質維持
各タスクを独立したサブエージェントで実装することで、AIが大量のコンテキストに埋もれて品質が劣化する問題を回避します。1つのタスクに1つのエージェントが集中し、かつタスクの種類に応じた専門エージェントがアサインされる設計です。
多層的なセーフティネット
実装→リファクタリング→カバレッジチェック→検証ループ→コードレビュー→ボットレビュー対応と、何重ものチェックを通過させます。1つのチェックをすり抜けた問題も、後段で拾われます。
まとめ
cc-sddで仕様を構造化し、カスタムスラッシュコマンドで実装の省力化を図る。このワークフローにより、人間は上流工程の品質に集中し、実装の大部分をAIに委ねることができます。
品質はTDD・コードレビュー・検証ループ・ボットレビュー対応という多層的なチェックで担保されます。完璧ではありませんが、最終的な人間レビューの負荷を大幅に軽減できる水準のコードが出てきます。
AIエージェントに「ただコードを書かせる」のではなく、仕様→実装→品質保証の構造化されたパイプラインとして活用する。これが、私が実践している仕様駆動開発の現在地です。
参考リンク: - cc-sdd GitHub Repository - Claude Code カスタムスラッシュコマンド - everything-claude-code
