4
11

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

cc-sddによる仕様駆動開発の記録

4
Posted at

TL;DR

  • cc-sddを使って、React Native + Expoの音声操作スコアボードアプリを仕様策定から実装完了まで開発した
  • 仕様→要件→設計→タスク→TDD実装の全フェーズをスラッシュコマンドで進め、最終的に29サブタスク・370テストで完了した
  • 開発中に3回の仕様変更があったが、いずれもcc-sddのフローに乗せてトレーサブルに対応できた
  • 生成された全成果物をGitHubリンク付きで記録する
  • マルチエージェント実装対応は現状なく、速度面で劣る
    • 対話的に実行するよりもバックグラウンドタスク的に実行するのに向いている
  • 要件定義~設計~Task分解の過程は即効性あり、その後の実装は別の枠組みで進行する方が高速

この記事について

個人開発を実施するにあたって、仕様駆動開発ツールを試してみた記録と改善を期待するポイントの記録。
本業での採用計画が立ち上がっている事情もあり、cc-sddを導入した。
候補としては他にGitHub spec-kitがある。
それと比較し、採用に至った根拠としては以下。

  • EARS形式の構造化要件
  • TDD統合
  • 日本語対応(そもそも日本産)
# インストール(Claude Code + 日本語テンプレート)
npx cc-sdd@latest --claude --lang ja

以下、実際の開発で各フェーズを通して何が起きたかを記録する。

cc-sddのワークフロー

cc-sddは5フェーズで進行する。各フェーズに承認ゲートがあり、前のフェーズが承認されないと次に進めない。

仕様策定フェーズ(Phase 1〜4)

Phase 1: 初期化

/kiro:spec-init 音声操作対応のスポーツスコアボードアプリ。
バレーボール練習時の得点板代わりに使用。
音声コマンドとタッチ操作の両方でスコアを管理。

ディレクトリとメタデータ(spec.json)が生成される。この時点では要件や設計は生成されない。

Phase 2: 要件定義

/kiro:spec-requirements voice-scoreboard

プロジェクトの説明文から、EARS形式(When〜, the system shall〜)の要件が自動生成された。
結果は9つの要件群・38の受入基準(requirements.md)。

EARS形式の例:

When ユーザーがチームの+1ボタンをタップした,
the Voice Scoreboard shall 該当チームの得点を1点加算する

生成後にフィードバックを返して対話的に修正した。
例えば「音声コマンドでリセットする場合は確認ダイアログなしで即実行にしたい」と伝えると要件に反映される。

Phase 3: 技術設計

/kiro:spec-design voice-scoreboard -y

承認された要件から、design.md(アーキテクチャ図・技術スタック表・状態マシン設計・コンポーネント契約)とresearch.md(調査ログ)が生成された。

手動で追加したもの: cc-sddはコードの設計は生成するが、見た目のデザイン仕様は生成しない。
Figma Makeで作成済みのデザインモックをもとに、design.mdへ ## Visual Design セクションを手動追加した(カラーパレット、レイアウト仕様、エフェクト定義)。

ビジュアル仕様がdesign.mdにないまま実装フェーズに入ると、AIがデザインモックと異なる見た目で実装する可能性がある。
UIが重要なプロジェクトでは、この手動補完が重要だった。

Phase 4: タスク分解

/kiro:spec-tasks voice-scoreboard -y

設計から8メジャータスク・20サブタスクが生成された(tasks.md)。

各タスクの末尾に対応する要件IDが記載されており、トレーサビリティが保たれている。

- [ ] 3.1 左右チームのスコア表示パネル
  - ...
  - _Requirements: 1.1, 1.2, 2.1, 2.2_

データ依存がなく並列実行可能なタスクには (P) マーカーが付与される。
ただし、実装時のファイル競合(共通のindex.tsへのエクスポート追加等)まではカバーしていないため、並列実行する場合は事前調査が必要。

design.md更新後のタスク再生成:
ビジュアルデザイン仕様をdesign.mdに追加した後、/kiro:spec-tasks を再実行した。
UIタスクにデザイン仕様の詳細(グロー効果、カラーパレット9色、ゴールド枠線等)が自動反映された。

補完: 手動検証マイルストーンの定義

cc-sddのtasks.mdはAIが実行するコーディング作業のみを管理しており、人間が実機やエミュレータで動作確認するタイミングは定義されない。
これはバグではなくcc-sddの設計思想で、cc-sddのタスク生成ルール(.kiro/settings/rules/tasks-generation.md)には以下の明示的な除外規定がある。

Include ONLY: Coding tasks / Testing tasks / Technical setup tasks
Exclude: Deployment tasks / Documentation tasks / User testing / Marketing

つまり、人間による手動検証はcc-sddのタスク管理のスコープ外として意図的に切り離されている。
仕様に沿ってコードを完成させることに集中し、手動検証は別の仕組みで管理すべきという思想になっている。

これを補完するため、/kiro:steering-custom で検証マイルストーンを定義した(verification-milestones.md)。
steeringファイルは .kiro/steering/ に配置され、AIのコンテキストに自動で読み込まれる。
これにより、タスク完了時にAIが「エミュレータで動作確認をお願いします」と促してくれるようになった。

当初4段階で定義したマイルストーンは、実装の進行に伴い6段階に拡大した(詳細は実装フェーズの節で記載)。

実装フェーズ(Phase 5)

spec-implの実行

cc-sddの spec-impl はタスク番号を指定して、TDDサイクル(Red→Green→Refactor)で実装するコマンドである。

/kiro:spec-impl voice-scoreboard 2.1

spec-impl はタスク番号に対応する requirements.md / design.md / tasks.md を読み込み、テストを先に書いてから実装コードを書くサイクルを実行する。

但し、今回の事例では /kiro:spec-impl を直接実行していない。
後述する課題(実行記録の不在・進捗の不可視)を補完するため、独自のdev-cycleスキルを作成し、そこから spec-impl を間接的に呼び出す形で全タスクを実装した。

タスクログ

各タスクの実装後に docs/02_TaskLog/ にタスクログを作成した(全27件)。

セクション 内容
実装予測(Plan) 実装前に立てた方針(ファイル構成、パターン、リスク)
実装結果 作成/変更ファイル、テスト結果、テストケース一覧
予測との比較 予測と実際の乖離分析
意思決定ログ 採用/不採用の選択肢と理由
学び 再利用可能な知見

「予測→実際→乖離」のフォーマットでAIの実装精度を定量的に把握できる。
予実乖離は殆ど無かったこともあり、予測結果は活用できなかったことから不要だった。

検証マイルストーンの実際

steeringで定義した検証マイルストーンは、当初の4段階から最終的に6段階に拡大した。

マイルストーン タスク 検証内容
M1 3.0 Android Development Build 起動確認
M2 3.4 タッチ操作スコアボードのエミュレータ検証
M3 4.3 設定永続化のエミュレータ検証
M4 5.4 音声サービスのエミュレータ検証
M5 7.4 音声UI統合のエミュレータ検証
M6 8.4 Android実機による最終検証(Release Ready)

M1〜M5はエミュレータ、M6は実機(Pixel 7a)で検証した。音声認識はエミュレータでの検証が困難だったため、エミュレータで検証可能な範囲を段階的に確認し、M6で実機フォローアップする戦略を取った。

成果物サマリー

コマンド 生成ファイル 概要
spec-init spec.json メタデータ
spec-requirements requirements.md 9要件・38受入基準
spec-design design.md アーキテクチャ・コンポーネント設計
spec-design research.md ディスカバリー調査ログ
spec-tasks tasks.md 8メジャー・29サブタスク(当初20 + 開発中追加9)
spec-impl docs/02_TaskLog/ 27件のタスクログ(予測/実績/意思決定/学び)
steering-custom verification-milestones.md 手動検証マイルストーン
手動追加 design.md 内 ## Visual Design ビジュアルデザイン仕様

振り返り

良かった点

  • 要件の構造化が速い: 自然言語の説明からEARS形式の要件が数分で生成された。手書きだと数時間かかる作業だった
  • 設計の一貫性: requirements→design→tasksの一方向フローにより、設計と実装のトレーサビリティが保たれた
  • 承認ゲートの安心感: 各フェーズで人間がレビューできるため、AIの暴走を防げた
  • TDDの強制力: spec-impl がRed→Green→Refactorサイクルを自動実行するため、テストを書き忘れることがなかった。最終的に370テストが積み上がり、仕様変更時のリグレッション検知に役立った
  • 仕様変更のトレーサビリティ: 仕様書を更新してから spec-impl を再実行する流れにより、「なぜこの変更が必要になったか」がrequirements.md / design.md / tasks.mdの差分として残った

cc-sddがカバーしなかったもの

  • ビジュアルデザイン仕様:
    コードの設計に特化しており、UIの見た目に関する仕様は生成されなかった。design.mdへの手動追記で補完した

  • 手動検証タイミング:
    tasks.mdはAI向けのタスク管理であり、人間が実機で動作確認するタイミングは含まれなかった。steering機能で補完した

  • 否定的な境界定義(「××ではない」の記述):
    design.mdには「○○する」という肯定的な仕様のみが生成され、「××しない」「××ではない」という否定的な境界定義が含まれなかった。
    AIが仕様を読んだときの誤解・拡大解釈を防ぐために、肯定と否定の両面から仕様を定義することが推奨されている。
    例えばdesign.mdでは、以下のような否定的な記述が本来あるべきだったと考えている。

    • 「LISTENING状態ではウェイクワードを無視する」(状態マシンの境界)
    • 「GameRulesはセットカウントを管理しない。1セットの勝敗判定のみを担当する」(責務の境界)
    • 「ScoreStoreのスコアは負の値にならない」(データの不変条件)

    これらは結果的に実装とテストでは正しく対処されたが、設計ドキュメント上には明示されていなかった。
    今回のプロジェクトでは要件が比較的シンプルだったため問題は顕在化しなかったが、規模が大きくなるほど「書いてないから自分で判断する」というAIの拡大解釈リスクは高まると考えている。

spec-implの残った課題

最も頻繁に実行するコマンドである spec-impl に、3つの不満が残った。いずれもv2.1.1(2026年2月時点の最終リリース)で未解決であり、Issue #112として並列実行の要望がOpenになっている。

  • Agent Teams / マルチエージェント非対応:
    spec-tasks が (P) マーカーで並列可能なタスクを自動標識するにもかかわらず、spec-impl はこれを無視して全て順序実行する。
    TDDサイクル(Red→Green→Refactor)は1タスクあたりの実行時間が長いため、並列化できないことの影響が大きかった。
  • 進捗の可視化がない:
    spec-impl はClaude CodeのTask機能(TaskCreate / TaskUpdate)を使わないため、実行中にどこまで進んだかが分からない。
    TDDの各ステップ(テスト作成→実装→リファクタ→全テスト実行)が長時間走るため、進捗が見えないストレスがあった。
    この点も踏まえると、やはり対話的に進めるよりもバッチ的な実行とするべき。
  • 実行記録を生成しない:
    spec-impl はTDDサイクルを実行して tasks.md のチェックボックスを更新するが、何を作り、どんな判断をし、何を学んだかの記録は残さない。
    ロングランするTDD自動実行という特性上、タスクごとの振り返りができないと改善サイクルが成立しにくい

今回はこの3つの課題を補完するため、dev-cycleスキルを作成した。
dev-cycleは spec-impl をラップし、以下の3ステップを強制する。

  1. Plan モード: 実装前に予測レポートを作成し、ユーザーの承認を得る
  2. /kiro:spec-impl 呼び出し: TDD実装はspec-implに委任(dev-cycle自身はコードを書かない)
  3. 実行記録の作成: テンプレートに従い、実装結果・予測との比較・意思決定ログ・学びをタスクログとして出力

このアプローチが高精度に機能した理由がある。
spec-impl はSubAgentを呼ばずシングルセッションで完結するため、TDDサイクル中の全コンテキスト(何のファイルを作り、どのテストが失敗し、どう修正したか)がセッション内に残る。
dev-cycleスキルはその同一セッション上で実行記録を作成するので、コンテキストの欠落なく正確な記録が書けた。
もし spec-impl がSubAgentに処理を委任する設計だった場合、SubAgentのコンテキストは親セッションに返らないため、この手法は成立しなかっただろう。

参考資料

4
11
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
4
11

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?