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を導入し、実際に手を動かして仕様から実装まで進める手順を追います。
cc-sddとは何か
cc-sddは、承認済みの仕様(spec)を長時間稼働する自律実装に変換するAgent Skills形式のCLIツールです。npmパッケージcc-sddとして配布され、MITライセンスで公開されています。要件定義・設計・タスク分解・実装という4段階のプロセスを、Claude CodeやCodexなど8種類のエージェント上で共通の17スキルセットとして動かす点が特徴です。
現行のv3.0は、Agent Skillsと長時間稼働の自律実装を軸にした作り直しです。/kiro-discoveryが新しい入口になり、要望を「既存specの拡張」「spec無しの直接実装」「新規specの作成」「複数specへの分解」「混在分解」のいずれかに仕分けます。実装フェーズを担う/kiro-implは、タスクごとに独立した実装者・レビュアー・デバッガーを立ち上げる自律モードを持ち、後述する境界(boundary)ベースの仕様設計と組み合わせて動きます。IDE製品のKiroが持つ仕様駆動の手法から着想を得ており、Kiro側で作成済みの仕様ファイルもそのまま持ち込めます。
前提条件
cc-sddのインストール自体はNode.jsのnpxが動く環境であれば完了します。Claude Codeでskillsモードを使う場合、事前に用意しておくものは次の2つです。
- Claude Codeがプロジェクトのルートで実行できる状態になっていること(認証済みであること)
npxが使えるNode.js環境(cc-sdd自体はTypeScript製のCLIで、インストール時にビルド済みのJSが展開されます)
対応エージェントは8種類あり、同じ17スキルの構成がどの環境でも展開されますが、プラットフォームごとの実績には差があります。
| エージェント | Skillsモードのフラグ | 安定度 |
|---|---|---|
| Claude Code | Skillsモードのフラグ--claude-skills(既定) | 安定度Stable |
| Codex | Skillsモードのフラグ--codex-skills | 安定度Stable |
| Cursor IDE | Skillsモードのフラグ--cursor-skills | 安定度Beta |
| GitHub Copilot | Skillsモードのフラグ--copilot-skills | 安定度Beta |
| Windsurf IDE | Skillsモードのフラグ--windsurf-skills | 安定度Beta |
| OpenCode / Gemini CLI | Skillsモードのフラグ--opencode-skills / --gemini-skills | 安定度Beta |
| Antigravity | Skillsモードのフラグ--antigravity | 安定度Beta(実験的) |
Qwen Codeだけはskillsモードを持たず、レガシーの--qwenコマンドモードのみに対応します。CursorとClaude Codeを併用しているチームがcc-sddを両方に入れる場合の運用は、CursorとClaude Codeの併用ワークフロー実践ガイドも参考になります。
ステップ1: cc-sddをインストールする
プロジェクトのルートでnpx cc-sdd@latestを実行すると、既定でClaude Code向けの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の13言語です。導入前に変更内容を確認したい場合は--dry-run、specの格納先を.kiro/以外にしたい場合は--kiro-dir docsのように指定します。インストールされる{{KIRO_DIR}}/settings/templates/と{{KIRO_DIR}}/settings/rules/はチームの運用に合わせて編集できるテンプレートで、以降に生成されるrequirements.md・design.md・tasks.mdの構造やレビュー基準に反映されます。
ステップ2: /kiro-discoveryで仕事を仕分ける
インストール後、最初に実行するのはClaude Code内での/kiro-discoveryです。何を作りたいかを短い文章で渡すと、cc-sddがその要望をルーティングします。
/kiro-discovery 写真をアップロード・タグ付け・共有できるアルバム機能/kiro-discoveryは実装そのものは行わず、要望を次の5種類のいずれかに仕分けてbrief.md(複数specにまたがる場合はroadmap.mdも)を書き出し、次に打つべきコマンドを提示して止まります。
| 仕分け結果 | 意味 | 次のコマンド |
|---|---|---|
| 既存specの拡張 | 意味承認済み・進行中のspecの範囲内 | 次のコマンド/kiro-spec-requirements <feature> |
| spec不要 | 意味直接実装できる規模 | 次のコマンドそのまま実装 |
| 単一spec | 意味1機能として1つのspecにする | 次のコマンド/kiro-spec-init <feature> |
| 複数specへの分解 | 意味複数specに分けるべき規模 | 次のコマンド/kiro-spec-batch |
| 混在分解 | 意味既存拡張・新規spec・直接実装が混ざる | 次のコマンドbrief.md/roadmap.mdの分割を確認して続行 |
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 | 主な成果物P0・P1などの並列実行ラベルと_Boundary:_/_Depends:_注釈付きのtasks.md |
design.mdのFile Structure Planは、ディレクトリ構成とファイルごとの責務をタスク分割の起点にする仕組みです。tasks.mdの各タスクは自分が担当する境界(_Boundary:_)と依存関係(_Depends:_)を明示し、後段のレビューはスタイルの指摘だけでなく境界違反も検出対象にします。
各フェーズは既定で人間の承認待ちで止まります。-yやCLIの--autoフラグで承認をスキップできますが、この仕組みは品質担保をフェーズゲートに依存させているため、スキップは実験的な用途に留め、本番相当の作業では承認を挟む運用が前提になっています。
ステップ4: /kiro-implで自律実装を回す
承認済みのtasks.mdができたら、実装は/kiro-implに引き継ぎます。引数無しで実行すると自律モードになり、タスク1件ごとに新しい実装者を立ち上げます。
/kiro-impl photo-albums/kiro-implの自律モードは、タスクごとに最大3つの役割を動的に立ち上げます。
- Implementer: specからタスクブリーフを組み立て、Feature Flag Protocolに沿ったTDD(RED→GREEN)で実装する
- Reviewer: 独立した実行コンテキストで
git diffの確認・TODOの検索・テスト実行・境界遵守のチェックを行う - Debugger: Implementerが行き詰まるか、Reviewerが2回連続で却下したときだけ起動し、クリーンな文脈でWeb検索を使って根本原因を調べ、修正方針を新しいImplementerに引き継ぐ(1タスクあたり最大2ラウンド)
あるタスクで得られた知見(例: 「better-sqlite3はElectron向けにABIの再ビルドが必要」)は、tasks.mdの## Implementation Notesに記録され、以降のタスクのImplementerへのプロンプトに自動で注入されます。1イテレーションで処理するタスクは1件に固定されており、これが長時間の自律実行でも文脈を汚さず、中断後に/kiro-implを再実行しても安全に再開できる理由になっています。TDDでテストを先に書かせる具体的な進め方はClaude Codeでテストを書かせる実践手順にまとめています。
タスク引数を渡した/kiro-impl <feature> <task-ids>は手動モードになり、独立したサブエージェントを立てずメインの会話コンテキストでTDDを回します。役割を分けて自動レビューさせる発想自体は、Agent Teams並列コードレビューの実践で扱っている対立仮説型のレビューとも重なる部分があります。
実装後に検証する
タスクが一通り終わったら/kiro-validate-implで機能単位の統合検証を行います。個々のタスクの正しさはReviewerサブエージェントが実装中に見ているため、ここではタスクをまたいだ一貫性・境界の整合・要件のカバレッジ・テストスイート全体の証跡を確認します。結果はGO・NO-GO・MANUAL_VERIFY_REQUIREDのいずれかで返ります。
進捗そのものを一覧したいときはレガシーコマンドの/kiro:spec-status <feature>が使えます。フェーズごとの承認状況と未完了タスクをCLI上に要約します。
Skillsモードとレガシー--claude-agentの違い
cc-sddには、v3.0で標準になったSkillsモードと、旧来の--claude-agentインストール対象という2つの経路があります。どちらも有効な選択肢で、優劣ではなく仕組みが異なります。
| 観点 | --claude-agent(レガシー) | Skillsモード |
|---|---|---|
| サブエージェント定義 | --claude-agent(レガシー).claude/agents/kiro/*.mdの静的ファイル | Skillsモードスキル内蔵のプロンプトテンプレートを動的にディスパッチ |
| 対応プラットフォーム | --claude-agent(レガシー)Claude Codeのみ | Skillsモード8プラットフォーム |
| 並列spec batch | --claude-agent(レガシー)非対応 | Skillsモード/kiro-spec-batch(クロスspecレビュー付き) |
| 実装 | --claude-agent(レガシー)/kiro:spec-implで手動実行 | Skillsモード/kiro-implで自律・手動の両モード |
| 失敗時のデバッグ | --claude-agent(レガシー)非対応 | Skillsモード最大2ラウンドの自動デバッグ(Web検索付き) |
| セッション再開 | --claude-agent(レガシー)最初からやり直し | Skillsモード中断後も安全に再実行可能 |
Skillsモードでは.claude/agents/配下に固定ファイルを置く代わりに、/kiro-impl自身がプラットフォームごとのネイティブなサブエージェント機能(Claude CodeであればTask tool)を通じて実行コンテキストをその場で生成します。これが同じ/kiro-implスキルをClaude Code・Codex・Cursorなど8プラットフォームで共通に動かせる理由です。
いつcc-sddが向くか、向かないか
cc-sddは、仕様(specification)を「システムの各部分の間の契約」として扱い、コードそのものを信頼できる情報源に保つという立場を取ります。requirements.mdやFile Structure Plan、境界注釈が契約(仕様)を定義し、design.mdの内部設計やtasks.mdの並び順、各タスク内の実装は契約の内側で自由に決めてよい領域(設計)として区別されています。
公式ドキュメントは、向くケースと向かないケースを次のように整理しています。
- 向くケース: 作業が複数の中粒度specに分解できる/複数の人間・エージェント・作業ストリームが同じコードベースを同時に触れていて「相手の変更を壊していないか」の確認コストが実際にかさんでいる/縦切りの小さな単位でリリースして都度学びたい/エージェントが書いたコードを承認済みの契約まで遡って追跡する必要がある
- 向かないケース: 1回のエージェントセッションで完結するソロ作業/書き捨て前提のプロトタイプ/境界を明文化するより素早く書いたほうが早い場面
/kiro-discoveryが「spec不要、直接実装」という結果を返すこと自体が正当な選択肢として設計されている点も、cc-sddがあらゆる変更に仕様を強制するツールではないことを示しています。Claude Code向けに開発ツールを組み込んだ他社事例はClaude Code開発ツール導入事例でも紹介しています。
よくあるつまずき
--claudeと--claude-skillsを混同する。--claudeと--claude-agentはv3.0で非推奨になったレガシーの動作で、動くには動きますが新機能(discovery・spec-batch・自動デバッグ)を持ちません。既定のnpx cc-sdd@latestはSkillsモードを入れるので、明示的にレガシーへ切り替えない限り迷う場面は少ないはずです。
-y/--autoで承認を飛ばし続けると、フェーズゲートの意味が薄れる。requirements・design・tasksの各段階は人間のレビューを前提に設計されており、自動承認は実験用途を想定した機能です。多用すると、境界違反や要件の見落としが実装が進んだ後まで気づかれなくなります。
デバッグが2ラウンドで止まる。Reviewerの却下が2回続き、Debuggerの修正方針でも解決しない場合、/kiro-implはそこで止まって人間の判断を求めます。これは無限ループを避けるための上限で、バグと言うより設計です。
/kiro-spec-batchが矛盾を検出したのに、下流のspec側だけを直してしまう。上流・共通のspecが原因で失敗している場合は、まず所有元のspecを直すのが前提です。下流のspecをその場しのぎで書き換えると、同じ矛盾が別の形で再発します。
Codespaces/npxが使えない制限された環境でインストールが止まる。cc-sdd自体はnpm経由の配布のため、npxが使えないネットワーク制限環境では事前にnpm install -g cc-sddなどレジストリへのアクセス経路を確保しておく必要があります。
まとめ
cc-sddは、npx cc-sdd@latestの1コマンドでClaude Codeに仕様駆動開発のワークフローを追加するOSSハーネスです。/kiro-discoveryで仕事を仕分け、/kiro-spec-initから/kiro-spec-tasksまでで契約としての仕様を積み上げ、/kiro-implが実装者・レビュアー・デバッガーの役割分担で自律的にタスクを消化します。仕様を書く手間が発生するのは事実ですが、複数のエージェントや人間が同じコードベースを並行して触るときの「相手の変更を壊していないか」という確認コストを、契約の形で先に減らしておく設計です。ソロで完結する小さな変更まで無理に仕様化する必要はなく、/kiro-discovery自身がその判断を仕分けの一部として行います。
よくある質問
Kiro IDEで作った仕様ファイルはそのまま使えますか
使えます。cc-sddはKiro IDEの仕様駆動の手法から着想を得ており、Kiro側で作成済みの仕様ファイルはそのまま持ち込んで使える設計になっています。
レガシーの/kiro:*コマンドモードは今から使うべきですか
--claudeや--claude-agentなどのレガシーモードはv3.0で非推奨になっており、Discoveryや自律実装、自動デバッグといった新機能を持ちません。新規に導入するなら既定のSkillsモードを使う理由のほうが大きく、レガシーモードは既存導入からの移行期にのみ関係します。
対応言語は日本語だけですか
日本語を含め13言語(en・ja・zh-TW・zh・es・pt・de・fr・ru・it・ko・ar・el)のドキュメントに対応しています。--lang jaのようにインストール時のフラグで指定します。