cc-sddでClaude Codeの仕様駆動開発を実践する
OSSハーネスcc-sddをClaude Codeに導入し、kiro-discoveryでの仕分けからkiro-implによる自律実装まで、仕様駆動開発の手順を追います。
cc-sddは、Claude Codeを含む8種類のAIコーディングエージェント上で仕様駆動開発(Spec-Driven Development、SDD)のワークフローを動かすOSSハーネスです。npx cc-sdd@latestで導入し、/kiro-discoveryによる仕事の仕分けから、要件・設計・タスクの承認、/kiro-implによる自律実装までを1本の手順に載せます。この記事では、Claude Code向けにcc-sddを導入し、仕様から実装まで進める手順を追います。Raycast拡張のような小さなツール開発でも、Claude CodeでRaycast拡張を作る手順のように仕様を先に書き出す進め方が活きます。
cc-sddとは何か
cc-sddは、承認済みの仕様(spec)を長時間稼働する自律実装に変換するAgent Skills形式のCLIツールです。npmパッケージcc-sddとして配布され、MITライセンスで公開されています。npmの最新版は3.1.0です。要件定義・設計・タスク分解・実装という4段階のプロセスを、Claude CodeやCodexなど8種類のエージェント上で共通の17スキルとして動かします。
v3.0はAgent Skillsと長時間稼働の自律実装を軸にした作り直しで、3.1.0もこの構成を引き継いでいます。/kiro-discoveryが新しい入口になり、要望を「既存specの拡張」「spec無しの直接実装」「新規specの作成」「複数specへの分解」「混在分解」のいずれかに仕分けます。実装を担う/kiro-implは、タスクごとに独立した実装者・レビュアー・デバッガーを立ち上げる自律モードを持ちます。
IDE製品のKiroが持つ仕様駆動の手法から着想を得ており、Kiro側で作成済みの仕様ファイルはそのまま持ち込めます。スキル名がkiro-で始まるのもこのためです。
自分の環境で動くか: 対応エージェントと前提
導入の前提は、npxが動くNode.js環境と、プロジェクトのルートで起動できるClaude Codeです。対応エージェントごとのインストールフラグと成熟度は次のとおりです。
| エージェント | Skillsモードのフラグ | 成熟度 |
|---|---|---|
| Claude Code | Skillsモードのフラグ--claude-skills(既定) | 成熟度Stable |
| Codex | Skillsモードのフラグ--codex-skills | 成熟度Stable |
| Cursor IDE | Skillsモードのフラグ--cursor-skills | 成熟度Beta |
| GitHub Copilot | Skillsモードのフラグ--copilot-skills | 成熟度Beta |
| Devin Local / CLI | Skillsモードのフラグ--devin(--devin-skills) | 成熟度Beta |
| OpenCode / Gemini CLI | Skillsモードのフラグ--opencode-skills / --gemini-skills | 成熟度Beta |
| Antigravity | Skillsモードのフラグ--antigravity(--antigravity-skills) | 成熟度Beta |
| Windsurf / Cascade | Skillsモードのフラグ--windsurf-skills | 成熟度非推奨(移行用) |
Qwen Codeだけはskillsモードを持たず、レガシーの--qwenコマンドモードのみです。Windsurf向けの--windsurfと--windsurf-skillsは既存のCascade環境を移行するための残置で、新規導入にはDevin向けの--devinが用意されています。
注意したいのは、17スキルが入ったことと、その環境で自律ループが回ることは別だという点です。独立したレビュアーを立てられるかどうかは、エージェント側のサブエージェント機能と権限設定で決まります。サブエージェントが使えない環境では、実装とレビューがメインの会話の中で順に走るインライン実行になり、結果もインラインレビューとして扱われます。Claude Codeでは、スキルが内部でAgentツールを呼んでサブエージェントを立てます。
呼び出しの書式もエージェントで違います。この記事の/kiro-*はClaude Code流で、Codexでは$kiro-*、Cascadeでは@kiro-*になります。CursorとClaude Codeを併用しているチームがcc-sddを両方に入れる場合の運用は、CursorとClaude Codeの併用ワークフロー実践ガイドも参考になります。
ステップ1: cc-sddをインストールする
プロジェクトのルートでnpx cc-sdd@latestを実行すると、既定でClaude Code向けのskillsが英語ドキュメント付きでインストールされます。スキルの実体は.claude/skills/に置かれます。
cd your-project
npx cc-sdd@latest日本語ドキュメントで使いたい場合や他のエージェントを対象にする場合は、フラグを組み合わせます。
npx cc-sdd@latest --claude-skills --lang ja対応言語はen・ja・zh-TW・zh・es・pt・de・fr・ru・it・ko・ar・el・viの14言語です。導入前に変更内容を確認したい場合は--dry-run、specの格納先を.kiro/以外にしたい場合は--kiro-dir docsのように指定します。
ステップ2: /kiro-discoveryで仕事を仕分ける
インストール後、最初に実行するのはClaude Code内での/kiro-discoveryです。何を作りたいかを短い文章で渡すと、cc-sddがその要望をルーティングします。
/kiro-discovery 写真をアップロード・タグ付け・共有できるアルバム機能/kiro-discoveryは実装そのものは行わず、要望を次の5種類のいずれかに仕分けます。新規specを伴う場合はbrief.md(複数specにまたがるならroadmap.mdも)を書き出します。最後に次に打つコマンドを提示して止まります。
| 仕分け結果 | 意味 | 次のコマンド |
|---|---|---|
| 既存specの拡張 | 意味承認済み・進行中のspecの範囲内 | 次のコマンド/kiro-spec-requirements <feature> |
| spec不要 | 意味直接実装できる規模 | 次のコマンドそのまま実装 |
| 単一spec | 意味1機能として1つのspecにする | 次のコマンド/kiro-spec-init <feature>(すぐ続けるなら/kiro-spec-quick) |
| 複数specへの分解 | 意味複数specに分けるべき規模 | 次のコマンド/kiro-spec-batch(最初の1件を試すなら/kiro-spec-init) |
| 混在分解 | 意味既存拡張・新規spec・直接実装が混ざる | 次のコマンド分割をbrief.md/roadmap.mdに書き出してから、新規specの分から続行 |
brief.mdはセッションをまたいで残るため、作業を中断しても経緯を説明し直さずに再開できます。/kiro-spec-batchや/kiro-implも、brief.mdがあれば自動で読み込みます。
ステップ3: 仕様をrequirements→design→tasksへ積み上げる
単一specとして進める場合、/kiro-spec-initから順にコマンドを実行します。
/kiro-spec-init photo-albums
/kiro-spec-requirements photo-albums
/kiro-spec-design photo-albums
/kiro-spec-tasks photo-albums各コマンドの成果物は次のとおりです。
| コマンド | 主な成果物 |
|---|---|
/kiro-spec-init | 主な成果物.kiro/specs/<feature>/のワークスペース |
/kiro-spec-requirements | 主な成果物EARS形式(受け入れ基準付き)のrequirements.md |
/kiro-spec-design | 主な成果物必要に応じたresearch.mdと、Mermaid図・File Structure Planを含むdesign.md |
/kiro-spec-tasks | 主な成果物並列実行できるタスクに付く(P)マーカーと_Boundary:_/_Depends:_注釈付きのtasks.md |
design.mdのFile Structure Planは、ディレクトリ構成とファイルごとの責務をタスク分割の起点にします。tasks.mdの各タスクは担当する境界(_Boundary:_)と依存関係(_Depends:_)を明示し、後段のレビューはスタイルだけでなく境界違反も見ます。READMEによると、ここまでの仕様の生成は10分未満が目安です。
各フェーズは既定で人間の承認待ちで止まります。承認を飛ばす手段は2つあります。
/kiro-spec-design <feature> -yのように-yを付けると、直前フェーズ(この例では要件)を自動承認して進みます/kiro-spec-quick <説明> --autoは、仕様生成の4フェーズを承認なしで連続実行します
品質担保をフェーズゲートに依存させる設計なので、自動承認は統制された実験に留め、本番相当の作業では承認を挟むのが前提です。
ステップ4: /kiro-implで自律実装を回す
承認済みのtasks.mdができたら、実装は/kiro-implに引き継ぎます。引数無しで実行すると自律モードになり、タスク1件ごとに新しい実装者を立ち上げます。
/kiro-impl photo-albums自律モードでは、タスクごとに最大3つの役割が動的に立ち上がります。
タスクごとの3つの役割
Implementer(実装者)
specからタスクブリーフを組み立て、Feature Flag Protocolに沿ったTDD(RED→GREEN)で実装します。
Reviewer(レビュアー)
独立した実行コンテキストで、
git diffの確認・TODOの検索・テスト実行・境界遵守のチェックを行います。Debugger(デバッガー)
Implementerが行き詰まるか、修正を2ラウンド重ねてもReviewerが却下したときだけ起動します。クリーンな文脈で根本原因を調べ(Web検索が使える環境ではそれも使います)、修正方針を新しいImplementerに渡します。1タスクあたり最大2ラウンドです。
あるタスクで得られた知見(例: 「better-sqlite3はElectron向けにABIの再ビルドが必要」)は、tasks.mdの## Implementation Notesに記録されます。以降のImplementerのプロンプトにも注入されます。1イテレーションで処理するタスクは1件に固定され、レビューとデバッグの範囲がその1件に収まります。進捗はtasks.mdに残ります。中断した実行を再開する前には、未完了の変更と稼働中のワーカーを確認する手順になっています。記録された進捗がどのエージェントでも復旧を保証するわけではありません。
TDDでテストを先に書かせる具体的な進め方はClaude Codeでテストを書かせる実践手順にあります。Electronアプリのメイン/レンダラー構成の組み立てはClaude CodeでElectronアプリを開発する手順が扱っています。
タスク引数を渡した/kiro-impl <feature> <task-ids>は手動モードで、独立したサブエージェントを立てずメインの会話コンテキストでTDDを回します。完了前のレビューは、手動モードでも既定で必須です。役割を分けて自動レビューさせる発想は、Agent Teams並列コードレビューの実践の対立仮説型レビューとも重なります。
複数のspecを別々に進めたいときは、2つの扱いがあります。独立した機能開発やPRのライフサイクルを持つ作業は、別のチャットに切り出してそこでcc-sddを動かせます。ただし別チャットにしただけではファイル編集は隔離されないため、独立した書き手が同じリポジトリを触るなら別々のworktreeを使います。1つのspecのタスク状態とコミットは、1つのコントローラーが持つ形にします。
実装後に検証する
タスクが一通り終わったら/kiro-validate-implで機能単位の統合検証を行います。個々のタスクの正しさはReviewerが実装中に見ているので、ここではタスクをまたいだ一貫性・境界の整合・要件のカバレッジ・テストスイート全体の証跡を見ます。結果はGO・NO-GO・MANUAL_VERIFY_REQUIREDのいずれかです。
実装中にも「直った」「完了した」と報告する前の関門として、kiro-verify-completionスキルが新しい証跡の有無を点検します。返り値はVERIFIED・NOT_VERIFIED・MANUAL_VERIFY_REQUIREDの3種類です。
進捗の一覧には/kiro-spec-status <feature>を使います。spec.jsonとbrief.md、既存のrequirements.md・design.md・tasks.mdを読み、フェーズごとの状況と次の一手を要約するスキルです。許可ツールはRead・Glob・Grepだけで、ファイルは書き換えません。
既存のコードベースに入れるとき
新規機能と既存システムの拡張では、入口が違います。README記載の流れは次のとおりです。
既存システムを拡張する場合の流れ
- 1
/kiro-steering でプロジェクトの記憶を作る
アーキテクチャ・規約・ドメイン知識を
.kiro/steering/にまとめます。ドメイン固有の規則は/kiro-steering-customで足します。 - 2
/kiro-discovery か /kiro-spec-init で仕様を始める
既存specの範囲に収まるか、新規specかを仕分けます。
- 3
任意で /kiro-validate-gap を挟む
要件と既存コードのギャップを分析し、
gap-report.mdを作ります。設計後は/kiro-validate-designでも同様に既存システムとの整合を見られます。 - 4
design → tasks → impl へ進む
以降は新規機能と同じ
/kiro-spec-design・/kiro-spec-tasks・/kiro-implです。
steeringは実装側にも効きます。ImplementerとReviewerのコンテキストはsteeringの規約を引き継ぐので、アーキテクチャや規約を変えたいときの第一のつまみがsteeringです。
テンプレートとルールで挙動を変える
インストールされる{{KIRO_DIR}}/settings/には、変更できる場所が2つあります。templates/は生成される文書の構造と書式、rules/はAIの生成原則と判断基準です。PRD風の節の追加、承認チェックリストやJIRAのフィールドの追加はテンプレート側、タスクの粒度(1〜3時間を4〜8時間にするなど)や設計原則の追加はルール側で調整します。さらに踏み込むなら、インストールされた.claude/skills/配下のSKILL.mdを直接編集して、ディスパッチやレビューゲートを変える手もあります。
自由に変えてよいのは見出し名やEARS形式の書き方で、数字付きの受け入れ基準の形が保たれていれば他の書式でも動きます。維持が必要なのは、後段のスキルが構造として読み取る部分です。
| ファイル | 維持する要素 |
|---|---|
requirements.md | 維持する要素1.・2.の番号付き受け入れ基準、テンプレートとの一貫性 |
design.md | 維持する要素ファイルが存在すること、File Structure Plan(3.0で推奨) |
tasks.md | 維持する要素- [ ] N.のチェックボックス形式、_Requirements: X, Y_の参照、1・1.1・1.2の階層 |
Skillsモードとレガシー--claude-agentの違い
cc-sddには、v3.0で標準になったSkillsモードと、旧来の--claude-agentインストール対象があります。どちらも有効な選択肢で、優劣ではなく仕組みが異なります。
| 観点 | --claude-agent(レガシー) | Skillsモード |
|---|---|---|
| サブエージェント定義 | --claude-agent(レガシー).claude/agents/kiro/*.mdの静的ファイル | Skillsモードスキル内蔵のプロンプトテンプレートを動的にディスパッチ |
| 対応プラットフォーム | --claude-agent(レガシー)Claude Codeのみ | Skillsモード現行8種(非推奨のCascadeも移行用に残置) |
| 仕様の一括生成 | --claude-agent(レガシー)4フェーズをサブエージェントで連携するspec-quick | Skillsモード4つのspecスキルを順に走らせるインラインのkiro-spec-quick |
| 並列spec batch | --claude-agent(レガシー)非対応 | Skillsモード/kiro-spec-batch(クロスspecレビュー付き。並列度はホスト次第) |
| 実装 | --claude-agent(レガシー)/kiro:spec-implで手動実行 | Skillsモード/kiro-implで自律・手動の両モード |
| 失敗時のデバッグ | --claude-agent(レガシー)非対応 | Skillsモード最大2ラウンドの自動デバッグ(ネイティブサブエージェントがあるとき) |
| セッション再開 | --claude-agent(レガシー)最初からやり直し | Skillsモードタスクファイルから続行(再開時の挙動はホストごとに要確認) |
Skillsモードにはtdd-task-implementer.mdのような固定ファイルがありません。/kiro-implがホストのサブエージェント機能で実行コンテキストをその場で生成します。ワーカーに渡るのは親の会話全体ではなく、タスク固有の入力と参照元だけです。レビュアーとデバッガーのプロンプトは、kiro-reviewとkiro-debugの手順書を明示パスで読み込みます。
v2.xからの移行では、スキル数が12〜13から17に増え、--codexのプロンプトモードがブロックされた点が大きな変化です。kiro-spec-implを参照するスクリプトがあれば/kiro-implに置き換えます。
いつcc-sddが向くか、向かないか
cc-sddは、仕様を「システムの各部分の間の契約」として扱い、コードそのものを信頼できる情報源に保ちます。requirements.mdやFile Structure Plan、境界注釈が契約を定義します。design.mdの内部設計やtasks.mdの並び順、各タスク内の実装は、契約の内側で自由に決めてよい領域です。
cc-sddが効く場面・効かない場面
向く場面
- 作業が複数の中粒度specに分解できる
- 複数の人間・エージェント・作業ストリームが同じコードベースを触り、「相手の変更を壊していないか」の確認が実際に時間を食っている
- 縦切りの小さな単位でリリースして都度学びたい
- エージェントが書いたコードを、承認済みの契約まで遡って追跡する必要がある
向かない場面
- 1回のエージェントセッションで完結するソロ作業
- 書き捨て前提のプロトタイプ
- 境界を明文化するより、素早く書いたほうが早い場面
/kiro-discoveryが「spec不要、直接実装」を返すこと自体が正規の選択肢で、あらゆる変更に仕様を強制するツールではありません。人間のレビューは契約の判断(境界は適切か、責務の切り方は妥当か、依存は正直か)に集中させ、タスクの完了時には実際のgit diffを承認済みの契約と突き合わせる設計です。Claude Code向けの開発ツールを組み込んだ他社事例はClaude Code開発ツール導入事例にあります。
途中でつまずいたとき
--claudeと--claude-skillsを混同する。--claudeと--claude-agentはv3.0で非推奨になったレガシーの動作で、新機能(discovery・spec-batch・自動デバッグ)を持ちません。既定のnpx cc-sdd@latestはSkillsモードを入れるので、明示的にレガシーへ切り替えない限り迷う場面は少なくなります。
-yや--autoで承認を飛ばし続ける。自動承認が続くと、境界違反や要件の見落としが実装が進んだ後まで残ります。
デバッグで直らずタスクが止まる。2ラウンドで直らないタスクはブロック扱いになり、人間の確認に回ります。
Skillsモードなのにコロン付きのコマンドを打つ。spec-driven.mdの対応表では、Skillsモードの列でも拡張の流れが/kiro:steering・/kiro:spec-init・/kiro:validate-gapと書かれています。READMEとskill-reference.mdはkiro-steering・/kiro-steeringです。コロン付きはレガシー記法なので、Skillsモードではこの記事のとおりハイフンでつないで打ちます。
/kiro-spec-batchが矛盾を検出したのに、下流のspec側だけを直す。上流・共通のspecが壊れているときは、所有元のspecを先に直します。下流で回避すると、同じ欠陥が別の形で残ります。上流の修正後は、依存するspecの検証と実行時のスモークチェックをやり直します。
旧バージョンの手順書に従う。1.x系のコマンド(--claude-codeフラグなど)は現行と構成が違います。1.1.5が必要な場合はnpx cc-sdd@1.1.5で固定でき、2.xと1.xのレイアウトを同じ.kiroに混在させることはサポートされません。
まとめ
最初の1件は/kiro-discoveryの仕分け結果だけを見て、specを作るかどうかを決めます。「spec不要」と返ってきたら、そのまま直接実装で足ります。