みなさんこんにちは！アクセルラボでプラットフォーム開発・AI推進を担当している山本です。
今回は、社内の新規 IoT プロジェクトの PoC 開発で Claude Code（Anthropic の AI コーディングエージェント）と cc-sdd（仕様駆動開発フレームワーク）を組み合わせて使った実践レポートをお届けします。
結論から言うと、AI にコードを書かせる量が増えるほど「ガードレール」の設計が重要になるということを痛感しました。
前編では「仕様策定〜実装」まで、後編では「ガードレールの構築」と開発全体の所感をお届けします。
作ったもの
IoT カメラと AI 画像解析を組み合わせた PoC システムです。カメラのイベント検知をトリガーに、自動でスナップショットを撮影し、AI が画像解析を行い、結果をダッシュボードにリアルタイム表示します。
→ スナップショット撮影 → AI画像解析
→ S3 → ダッシュボード
技術スタックはこんな感じです。
| レイヤー | 技術 |
|---|---|
| Backend | Hono + AWS Lambda (ARM64) |
| AI | Gemini Flash (JSON mode) |
| Infrastructure | AWS CDK |
| Frontend | React + Vite + Tailwind CSS v4 |
| パッケージ管理 | Bun (monorepo) |
| Lint / Format | oxlint + oxfmt (Rust製、高速) |
| テスト | Vitest |
| Git hooks | Lefthook |
| CI | GitHub Actions (3ジョブ並列) |
開発フロー全体像
このプロジェクトでは、3つのフェーズに分けて AI を活用しました。
↓
Phase 2: Claude Code でコードを書く（AIが実装する）
↓
Phase 3: Lefthook + CI で品質を担保する（AIの出力を検証する）
AI に自由に書かせる前に仕様で制約し、書いた後は自動検証で品質を担保する。 このサンドイッチ構造が今回のキモです。
前編では Phase 1・2 について解説します。
Phase 1: cc-sdd で「何を作るか」を固める
cc-sdd とは
cc-sdd は、AI コーディングエージェント向けの仕様駆動開発（Spec-Driven Development）フレームワークです。npx cc-sdd@latest でプロジェクトに導入すると、スラッシュコマンド群が使えるようになります。
ワークフローはシンプルで、以下の4ステップです。
/kiro:spec-requirements → 要件定義書を生成 /kiro:spec-design → 設計書を生成（Mermaid図付き） /kiro:spec-tasks → 実装タスクに分解 /kiro:spec-impl → タスクに基づいて実装
なぜ仕様を先に書くのか
Claude Code は優秀ですが、「何を作るか」が曖昧だと、AI は勝手に判断して実装を進めます。結果、意図しないアーキテクチャや不要な機能が混入することがあります。
cc-sdd を使うと、AI に渡す前に仕様を構造化できるのがポイントです。
実際に生成された要件定義書はこんな形式になります（内容は抽象化しています）。
### Requirement 1: イベント受信 **Objective:** As a システム, I want 外部APIからのイベントを受信・パースしたい, so that イベントをトリガーとして解析パイプラインを起動できる #### Acceptance Criteria 1. When 外部APIが検知イベントをPOSTした場合, the Lambda shall ペイロードを正しくパースし、正規化された型に変換する 2. When ペイロードのフォーマットが不正な場合, the Lambda shall HTTP 400レスポンスを返し、エラー内容をログに記録する #### Edge Cases - 外部API側からの重複イベント送信（at-least-once delivery）
EARS 形式（When/Shall 構文）で書かれた受入基準と、エッジケースまで定義されています。これが複数の要件分、自動生成されます。
タスク分解が秀逸
さらに spec-tasks で実装タスクに分解すると、依存関係を考慮した Wave 構造になります。
## Wave P0: 基盤（先行完了必須） - [x] 1. モノレポ初期化 + 共通型定義 - [x] 2. 外部APIクライアント実装 - [x] 3. CI/CD + DXツール導入 ## Wave P1: コア機能（並列可能） - [x] 4. AI解析クライアント テスト追加 (P) - [x] 5. イベントハンドラー テスト追加 (P) - [x] 6. ストレージ テスト追加 (P) ## Wave P2〜P4: API → フロントエンド → インフラ
P0 → P1 → P2 の順で進める必要がありますが、P1 内のタスクは並列実行可能、という構造です。Claude Code にタスクを渡す際、この Wave 構造があるおかげで「今何を実装すべきか」が明確になります。
Phase 2: Claude Code で実装
cc-sdd で仕様とタスクが揃ったら、Claude Code に実装を任せます。
Claude Code はターミナル上で動く AI コーディングエージェントで、「Wave P0 のタスク1を実装して」のように自然言語で指示するとコードを書いてくれます。cc-sdd の仕様書がプロジェクト内にあるので、Claude Code はそれを参照しながら要件に沿った実装を行います。
ここで重要だったのが CLAUDE.md の活用です。
CLAUDE.md — AI への永続的な指示書
プロジェクトルートに CLAUDE.md を置くと、Claude Code が毎回の会話でそれを読み込みます。ここにコーディングルール、アーキテクチャ、技術スタックを書いておくことで、会話が変わっても一貫した実装が得られます。
実際に書いた内容の一部です。
## コーディングルール - `strict: true`、`any`使用禁止 - ESM（`"type": "module"`）、import拡張子は `.js` - RPC型推論のため AppType をエクスポートし、フロントとの型共有 ## Git - mainへの直接プッシュ禁止。featureブランチ→PR→レビュー→マージ - コミットメッセージ: Conventional Commits
cc-sdd の仕様書 + CLAUDE.md のルールで、AI の実装範囲と品質基準を「挟み込む」構造ができます。
CLAUDE.md は育てるもの
CLAUDE.md は最初から完璧に書く必要はありません。開発を進めながら「AI がこういうミスをした」「こういうルールを守ってほしい」と気づくたびに追記していきます。
実際、プロジェクト開始時はシンプルだった CLAUDE.md が、最終的にはアーキテクチャ図・インフラ構成・ドメイン設計まで含む充実したドキュメントに育ちました。AI のための指示書が、結果的に人間にとっても最良のプロジェクトドキュメントになるのは嬉しい副産物でした。
後編では、AI が書いたコードの品質をどう担保するか — Lefthook・GitHub Actions・Devin Review によるガードレール構築について解説します。
本ブログを読んでいただきありがとうございます。 もし内容にご興味を持っていただけましたら、以下よりお気軽にお問い合わせ・ご応募ください。
アクセルラボでは採用を強化しています。 私たちの技術やビジョンに共感し、スマートホームの未来を共に創っていきたい方のご応募をお待ちしています。 👉お問い合わせ - アクセルラボ採用情報
