AIコーディングエージェントに「ログイン機能を作って」と頼んで、出てきたコードを眺めて「そうじゃないんだよな…」と何度もやり直した経験はありませんか。本記事では、仕様を先に定義してから実装に進む Spec-Driven Development（仕様駆動開発） を NPM パッケージ 1 つで実現する cc-sdd を、これから触る方向けに解説します。
読み終えたら、あなたのプロジェクトで npx cc-sdd@latest を実行して、最初の仕様を書き始められる状態を目指します。
1. なぜ「仕様から書く」必要があるのか
AI に一発で大きな機能を書かせようとすると、だいたいこんなふうに詰まります。
- 頼んだ本人も要件をふわっとしか言語化できていないので、生成結果がブレる
- 何度もやり直すうちにコンテキストが溢れ、AI が文脈を見失う
- 「なぜこの設計にしたのか」が会話ログにしか残らず、後から誰も追えない
人間同士のソフトウェア開発でも、いきなりコードを書かずに「要件 → 設計 → タスク分解 → 実装」という段階を踏むのは、まさにこれらの問題を避けるためでした。AI と協働する場合も同じです。事前に仕様を構造化しておけば、AI は迷わず実装に集中でき、人間は各段階でレビューできるようになります。
cc-sdd は、この段階的なプロセスをスラッシュコマンドのセットとして提供してくれる仕組みです。
2. cc-sdd とは何か
cc-sdd は、AI コーディングエージェント上で Spec-Driven Development を実現する NPM パッケージです。要件・設計・タスクをすべて Markdown ファイルとしてリポジトリに残しながら、AI と協働で開発を進められます。
設計思想は Kiro IDE の Spec-Driven Development に着想を得ており、Kiro spec との互換性があるため、Kiro 由来のベストプラクティスをそのまま活用できます。
大きな特徴は 2 つあります。
多様なエージェントに対応: Claude Code をはじめ、Cursor、Gemini CLI、Codex CLI、GitHub Copilot、Qwen Code、OpenCode、Windsurf の 8 種類のエージェントに対応しています（Claude Code と OpenCode は Commands／Subagents の 2 形態を選択可能）。インストール時のフラグ（--claude、--cursor など）で切り替えるだけです。
13 言語で仕様を生成: --lang ja のように指定することで、生成される要件・設計ドキュメントを日本語で出力できます。英語・日本語・中国語（繁体・簡体）・スペイン語・ドイツ語・フランス語・韓国語ほか、合計 13 言語に対応します。
3. 5 分で始めるセットアップ
プロジェクトのルートディレクトリで、次のコマンドを 1 本実行するだけで準備は完了します。
cd your-project
npx cc-sdd@latest --claude --lang ja
これで以下がセットアップされます。
.claude/commands/にスラッシュコマンドを配置.kiro/settings/にテンプレートとルールファイルを展開
実行後、.kiro/ はこんな構造になります。
.kiro/
├── settings/ # npx cc-sdd で生成（テンプレート・ルール）
│ ├── templates/
│ │ ├── specs/ # requirements.md / design.md / tasks.md のひな型
│ │ └── steering/ # product.md / tech.md / structure.md のひな型
│ └── rules/ # AIの生成ルール（EARS形式、設計原則など）
├── steering/ # /kiro:steering で生成（プロジェクトコンテキスト）
└── specs/ # /kiro:spec-init で生成（機能ごとの仕様）
steering/ と specs/ は各コマンド実行時に自動で作られるので、インストール直後は settings/ だけが存在する状態です。
最初に覚えておくと便利なオプション
| オプション | 説明 |
|---|---|
--lang ja | 生成ドキュメントの言語を指定（13 言語対応） |
--dry-run | 何も書き換えず、適用される変更をプレビューできる |
--backup | 既存ファイルのバックアップを残してから上書きする |
初めて触るときは --dry-run でどこに何が作られるかを確認してから、本番実行するのがおすすめです。
4. ワークフローを体験する
セットアップが終わったら、あとはスラッシュコマンドを順番に叩いていくだけです。最小のフローは次の 6 ステップです。
| ステップ | コマンド | 何が起きるか |
|---|---|---|
| 0（任意） | /kiro:steering | コードベースを分析し、プロジェクトコンテキストを生成 |
| 1 | /kiro:spec-init "プロジェクト説明" | 仕様ディレクトリを初期化 |
| 2 | /kiro:spec-requirements {feature} | 要件定義（EARS 形式）を生成 |
| 3 | /kiro:spec-design {feature} | 技術調査ログ + 設計ドキュメントを生成 |
| 4 | /kiro:spec-tasks {feature} | 実装タスクをチェックリストで生成 |
| 5 | /kiro:spec-impl {feature} | タスクに従って実装を実行 |
たとえば「フォトアルバムの CRUD API」を作る場合は、次のように進めます。
/kiro:steering
/kiro:spec-init "フォトアルバムのCRUD API"
/kiro:spec-requirements photo-albums
/kiro:spec-design photo-albums
/kiro:spec-tasks photo-albums
/kiro:spec-impl photo-albums
各ステップでは生成された内容を確認し、「この要件で進めていいか」をレビューしてから次に進むのが基本です。
y フラグは最初のうちは使わない
/kiro:spec-design {feature} -y のように -y を付けると、前フェーズを自動承認してそのまま次に進めます。便利ですが、初めてのうちは各フェーズで必ずレビューしてから手動で次に進むことを強くおすすめします。要件の段階で間違っていると、設計・タスクまでまとめてズレてしまうからです。
5. 各フェーズで何が起きているのか
コマンドの順番だけ覚えても、途中で「今なにを決めるべきか」がわからなくなりがちです。ここでは各フェーズの目的と成果物を押さえておきましょう。
Phase 0: Steering ― プロジェクトの「前提」を共有する
/kiro:steering は、コードベースを AI に読み込ませ、以下 3 つのファイルを自動生成します。
product.md: プロダクトの目的、対象ユーザー、コアバリューtech.md: 技術スタック、バージョン管理戦略、コーディング規約structure.md: ディレクトリ構成パターン、命名規則
Steering はすべてのコマンドから参照される「プロジェクトメモリ」として働きます。ここを充実させておくと、後続の要件・設計の品質が目に見えて上がります。プロジェクトに変化があったときは /kiro:steering を再実行すると、差分を検出して同期を提案してくれます。
空のディレクトリでは実行できません。既存のソースコードがあるプロジェクトルートで実行してください。
Phase 1: 仕様策定 ― 要件から設計、タスクへ
Phase 1 は 3 つのステップに分かれています。
要件定義（/kiro:spec-requirements） では、「何を作るか（WHAT）」を EARS 形式（Easy Approach to Requirements Syntax、構造化された自然言語で要件を記述する形式）で定義します。「When〜, the system shall〜」のようなパターンに沿って書くことで、曖昧さを減らします。成果物は requirements.md です。
技術設計（/kiro:spec-design） では、「どう作るか（HOW）」を決めます。AI が既存コードを調査して research.md に調査ログを残したうえで、design.md に技術設計をまとめます。
タスク分解（/kiro:spec-tasks） では、実装手順をチェックリスト化した tasks.md を生成します。各タスクには P0（逐次実行が必須）/ P1（並列実行が可能） のラベルが付与され、並行開発の境界が明示されます。
Phase 2: 実装 ― タスク単位で進める
/kiro:spec-impl は、生成された tasks.md を見ながら実装を進めます。
/kiro:spec-impl {feature} 1.1 # 特定のタスクだけ実行
/kiro:spec-impl {feature} 1.1,1.2 # 複数タスクを連続で実行
/kiro:spec-impl {feature} # 未完了タスクをすべて実行
大きな機能の場合は、タスクを 1〜2 個ずつ実行し、タスク間で /clear や /compact を入れてコンテキストを整理すると、AI の精度が保ちやすくなります。
6. Spec は living documents ― 実装後の管理
cc-sdd を使い始めて最初につまずくのが、「一度作った Spec は、そのまま凍結しておくもの？」という疑問です。答えは NO で、Spec は開発を通じて継続的に更新される living documents として扱います。Kiro IDE の公式ベストプラクティスでも「Specs remain living documents throughout development」と明記されています。
修正は上流から下流へ
仕様を修正するときは、変更が下流にどう波及するかを意識します。
| 修正したい内容 | 操作方法 | 後続フェーズへの影響 |
|---|---|---|
| 要件の追加・変更 | requirements.md を直接編集、または /kiro:spec-requirements を再実行 | design.md、tasks.md の再生成が必要 |
| 設計の変更 | /kiro:spec-design を再実行 | tasks.md の再生成が必要 |
| タスクの追加・変更 | /kiro:spec-tasks を再実行 | 影響なし（実装前の最終段階） |
実装を進めている途中で大きな要件変更が発生した場合は、いったん実装を中断して requirements.md → design.md → tasks.md の順で更新し、/kiro:validate-impl で完了済みタスクとの整合性を確認してから再開する、という進め方が安全です。
Spec をリポジトリに残す
実装が完了した Spec は、削除せずにリポジトリにコミットして残すことが推奨されています。
- 設計意図の記録: ADR（Architecture Decision Records）のように「なぜこの設計にしたか」を後から参照できる
- チーム共有: 機能の背景や要件を、コードから読み取れない文脈ごと共有できる
- 改修時の参照: 将来その機能に手を入れる人が、元の要件と設計を確認できる
- PR レビューのコンテキスト: レビュアーに「何をなぜ作ったか」を伝えられる
実装完了時は spec.json の status を "completed" に手動更新しておくと、進行中の Spec と完了済みの Spec を区別できます。
7. 向いているケース・向かないケース、そして次の一歩
ここまで読んで「よし全部 cc-sdd で始めよう」と思うのはちょっと待ってください。cc-sdd が向かないケースもあります。
| ケース | 理由 |
|---|---|
| 小規模な修正（タイポ、1 ファイルの軽微な変更） | 仕様策定のオーバーヘッドが大きすぎる |
| 一問一答で完結するタスク（「このエラーの原因は？」など） | 調査や質問は通常の会話で済ませた方が軽い |
| 探索的な作業 | ゴールが不明確で試行錯誤する段階には向かない |
逆に言えば、「1 つの PR に相当する規模の機能を作る」タイミングが cc-sdd の得意領域です。1 spec = 1 PR の粒度を意識すると、Spec とコード変更の対応関係も保ちやすくなります。
よくあるつまずきと対処
- Steering が薄くて生成品質が上がらない →
/kiro:steeringを再実行し、.kiro/steering/の内容を手でも加筆する - コンテキストウィンドウが溢れる →
/kiro:spec-impl {feature} 1.1のようにタスク単位で実行し、タスク間で/clearする - 空のディレクトリで
/kiro:steeringが失敗する → Steering はソースコードを分析する仕組みなので、必ず既存コードのあるプロジェクトルートで実行する
次の一歩
まずは既存プロジェクトで、こんな流れを試してみてください。
npx cc-sdd@latest --claude --lang ja --dry-runで何が追加されるか確認する- 問題なければ
-dry-runを外して本実行 - 小さな機能を 1 つ選び、
/kiro:steering→/kiro:spec-init→/kiro:spec-requirementsまで進めて、要件ファイルを眺めてみる
この「1 周」を体験するだけで、AI と協働する感覚が大きく変わります。
参考リンク
公式ドキュメント
- cc-sdd GitHub リポジトリ
- cc-sdd NPM パッケージ
- コマンドリファレンス（日本語）
- Spec-Driven Development ガイド（日本語）
- カスタマイズガイド（日本語）
記事・スライド
- Kiroの仕様書駆動開発プロセスをClaude Codeで徹底的に再現した – Zenn記事
- Claude Codeは仕様駆動の夢を見ない – Speaker Deck