Claude Codeで始める仕様駆動AI開発（前編）

Claude Code 開発環境 AI

こんにちは、コバヤシです。

受託開発の現場でClaude Codeを実務に導入して使っていますが、プロジェクトの規模が大きくなるにつれて仕様のブレや手戻りが増えてきました。案件ごとに技術スタックも業務要件も違う受託では、汎用的なプロンプトだけでは対応しきれません。「もっと体系的にAIと協働できないか」と考えていたところ、「実践Claude Code入門」（技術評論社）で紹介されている仕様駆動開発のアプローチがきっかけになりました。
今回は、Claude Codeのカスタムスキルを使って仕様駆動AI開発のワークフローをチームで構築・運用した話を、前後編に分けて紹介します。前編ではワークフローの構築まで、後編では実案件で回した結果をお伝えします。

gihyo.jp

仕様駆動開発とは

仕様駆動開発は、コードを書く前にドキュメントを整備し、それに基づいて実装を進める開発手法です。
従来のAI開発では「○○を作って」とプロンプトを投げて、出てきたコードを修正する流れが一般的でした。
しかしこの方法だと：

  • 仕様が曖昧なまま実装が進む
  • AIの解釈がブレる
  • 後から「これじゃなかった」となる

といった問題が起きがちです。
仕様駆動開発では、まずPRD（製品要求仕様書）や設計ドキュメントを作成し、AIはそれを参照しながら実装します。仕様が明文化されているので、AIの解釈のブレが減り、一貫性のある開発が可能になります。
Claude CodeにはPlan Modeという計画フェーズを分離する機能がありますが、これは個々のタスクに対する計画と実行の分離です。仕様駆動開発はもっと広い範囲で、PRD・設計書・用語集などをプロジェクトの資産として体系的に管理し、ワークフロー全体を駆動する仕組みです。

サンプルの基本フロー

書籍の第8章にあるサンプルコードでは、以下の流れで開発を進めます。

  1. プロジェクトセットアップ：メモを読み込み、PRD（人間が承認）→ 設計書・用語集など計6種類のドキュメントを生成
  2. ドキュメントレビュー：作成されたドキュメントの品質チェック
  3. 機能追加：ステアリング（作業計画）→ 実装 → 検証 → テスト → ドキュメント更新

スキルとしてPRD作成、アーキテクチャ設計、機能設計、用語集、リポジトリ構造、開発ガイドライン、ステアリングの7つが用意されています。TypeScriptプロジェクト向けの構成で、これだけでも「仕様を先に書いてから実装する」という基本的な流れは体験できます。

実プロジェクトで使うには

ただ、これを実プロジェクトにそのまま持ち込むと、いくつかの課題が出てきます。

  • 技術スタックの違い：サンプルはTypeScript向け。PHP/Laravelで使うには規約やパターンの追加が必要
  • チーム固有の規約：リポジトリパターン、PHPDoc必須化など、チームの開発規約をスキルに反映する必要がある
  • 運用上の課題：トークン消費、ルールの自動適用など、使ってみて初めて分かる問題
  • 人間の介在：AIに全部任せるのではなく、人間が判断する場面の設計が必要

これらのギャップを埋めて、最終的にはこんなワークフローに拡張しました。

  1. アイデア・メモ：人間が要望や課題をラフに書く
  2. PRD・設計書作成：AIがメモを読み込み、ドキュメントを構造化。人間が確認・修正
  3. ドキュメントレビュー：作成されたドキュメントの品質チェック
  4. 外部設計書作成：PRDや既存コード、メモなどから外部設計書のベースを生成。人間が手直し
  5. 実装：設計書に基づいてAIが実装。品質チェック・ドキュメント更新も含む。人間が都度確認
  6. テスト仕様書レビュー：テスト仕様書と設計書を照らし合わせ、テストケースの漏れを検出
  7. 総合テスト：全体の整合性チェック
  8. 振り返り：タスクごとの振り返りを集約し、スキルやプロジェクトルールの改善提案を生成

サンプルの3ステップから8ステップに拡張しています。以降では、このギャップをどう埋めたかを具体的に紹介します。

人間とAIのハイブリッドを目指す

サンプルはAI主導で進む設計でしたが、受託開発では案件ごとに仕様が異なり、開発途中でクライアントの要件が変わることも珍しくありません。人間がもっと介在できる形でないと現場では使えないと感じました。

簡単なメモから始められる

「完璧な仕様書を作らないと始められない」と思うと腰が重くなります。でも実際は、箇条書きのメモや「こんな感じでやりたい」程度のラフで十分です。
docs/ideas/ ディレクトリに人間が書いたメモを置く運用にしました。顧客からの要望メモ、社内MTGの議事録、Slackでの議論をまとめたものなど、形式は問いません。AIがそれを読み込んで、PRDや設計書の形に構造化してくれます。
人間は「何をやりたいか」だけ書けばいい。「どう書くか」はAIに任せる。この敷居の低さが、仕様駆動AI開発を続けられるポイントだと感じています。

都度確認の重要性

最初の頃、AIに連続実行させて最後にレビューすればいいと考えていました。しかし、ある時致命的な問題に直面しました。最終レビューの段階で、根本的な方向性が違っていることに気づいたのです。
AIは与えられた指示に従って実装を進めていましたが、前提となる情報が不足していたため、全く違う設計になっていました。気づいた時には複雑な依存関係が張り巡らされ、どこから手を付けていいか分からない状態でした。
この失敗から学んだのは：

  • 都度止めれば、指示や資料の不足に早期に気づける
  • 方向性のズレを初期段階で修正できる
  • 結果的に、最終的な手戻りが少なくなる

現在はファイル作成・編集・bashコマンド実行は必ず一度止めて内容を確認するフローにしています。Claude Codeは自動実行がデフォルトですが、意図的に都度確認する運用です。
ただ、付きっきりで見ている必要はありません。AIが作業している間は他の仕事を進めて、確認待ちの通知が来たらチェックする。都度確認といっても、他の作業と並行できるので思ったほど負担にはなりません。
確認するポイント：

  • コードの意図が合っているか
  • 想定外の変更が含まれていないか
  • 前提となる情報は揃っているか

違和感があれば即座に指示を修正する。AIは提案者であり、最終判断は人間が行います。そして最後にプルリクエストを作成して、改めて人間がレビュー。都度の確認で方向性を早期修正し、最終レビューで全体の整合性をチェックする。この二段構えで品質を担保しています。
この都度確認スタイルだと、最近話題の「並列開発」（複数エージェントの同時実行）は基本的に使えません。複数のエージェントが同時に動いても、結局人間が順番に確認することになり、並列の意味がなくなります。効率より品質を優先し、都度確認する方を選んでいます。

人間の実装をAIがレビュー

すべての実装をAIに任せるわけではありません。既存コードの微調整や、AIに指示を出すより自分で書いた方が早い修正など、人間が直接コードを書く場面は普通にあります。
そういった場合に、人間が実装したコードをAIがチェックする仕組みを用意しました。設計書やタスクリストと照らし合わせて、抜け漏れや規約違反を指摘してくれます。
「AIが書いて人間がレビュー」だけでなく「人間が書いてAIがレビュー」も可能にすることで、柔軟な分担ができるようになりました。

最終テストは人間が行う

ワークフローの出口も人間です。実装の最後にAIがテスト観点や境界値の候補、実装中に判明した注意点などをまとめて出力します。人間はそれを参考にしながらテスト仕様書を作成し、AIがそのテスト仕様書と設計書を照らし合わせて漏れをチェック。最終的なテストの実行は人間が行います。
仕様書だけでは拾えない「実装してみて初めて分かった注意点」がテストに反映されるのがポイントです。
入口のメモから、途中の都度確認、出口のテストまで、要所で人間が関与する。これがハイブリッド運用の全体像です。

チームでワークフローを共有する

ここまで紹介したスキルやコマンドは、チーム全体で共有することを前提にしています。
サンプルはTypeScript向けだったため、PHP/Laravel向けの規約スキル（PSR-12、PHPDoc、静的解析レベルなど）を追加し、tblsを使ったデータベース仕様書のMarkdown管理、コード品質チェックの自動実行なども組み込みました。これらをチーム全員が同じ基準で使えるようにする必要があります。
仕組みはシンプルで、スキル・コマンド・ルールを一つのリポジトリにまとめ、install.sh でシンボリックリンクを張るだけです。

# 各メンバーの環境で実行
chmod +x ./install.sh
./install.sh
# → ~/.claude/ 配下にシンボリックリンクが作成される

新しいスキルやコマンドを追加したら git pull するだけで全員に反映されます。Claude Codeにはプラグインとして配布する仕組みもあり、プライベートなチームマーケットプレイスも構築できます。ただ、構築当時はその方法を把握しきれていなかったため、シンプルなシンボリックリンク方式を選びました。プラグイン化は今後の課題です。

チームで共有する意味

配布の仕組みだけなら単なるツール共有ですが、仕様駆動AI開発をチームで共有することにはもっと大きな意味があります。
まず、誰が作業しても同じ品質基準で開発が進みます。スキルやRulesがチーム共通なので、「あの人が書いたコードだけPHPDocがない」「レビュー基準が人によって違う」といったブレがなくなります。
次に、PRDのタスク一覧がチームの状況を可視化してくれます。各タスクには前提タスクや依存関係が明記されているので、「今どこまで進んでいるか」「次に着手できるのは何か」がPRDを見れば分かります。誰かが途中から参加しても、タスクの状態を見れば現状を把握できる。これは属人化を防ぐ上でも重要です。
新メンバーの参加も楽になりました。install.sh を実行すればワークフローに乗れるので、「このプロジェクトではどうやって開発するの？」という質問に仕組みで答えられます。
そして、一人が改善したスキルがチーム全体に波及します。ある案件で「この規約チェックが足りない」と気づいて追加すれば、git pull で全員のワークフローが改善される。使い続けるほどチーム全体の開発基盤が強くなっていく仕組みです。

ワークフロー構築で気づいた調整ポイント

コーディング規約の適用忘れ

スキルは明示的に呼び出さないと適用されません。毎回コーディング規約スキルを呼び出すのは現実的ではありませんでした。
対策として、Claude CodeのRules機能を活用しました。

---
paths:
  - "**/*.php"
---

# PHP/Laravel 必須ルール

- PSR-12準拠
- PHPStan準拠
- PHPDocは省略禁止

paths を指定することで、PHPファイル編集時に自動適用されます。
ただし注意点があります。最初はRulesに規約を全部書いていたところ、PHPファイルを編集するたびに大量のトークンを消費する問題が発生しました。現在は詳細な規約はスキルに残し、Rulesには最小限のルールだけを記載するハイブリッド構成にしています。必ず守るべき数点だけをRulesに書き、詳細な例やパターンはスキル側に残して必要なときだけ呼び出す運用です。

トークン消費の最適化

大きなスキルファイルも同じ問題がありました。呼び出すたびにトークンを消費します。
対策として、SKILL.md（概要のみ）と guide.md（詳細手順）の2ファイル構成にしました。初回は概要だけ読み込み、詳細が必要な場合のみguide.mdを参照する構成です。

タスク管理の範囲

サンプルのPRDには「機能一覧」がありましたが、実際に使ってみると機能開発だけでは足りませんでした。環境構築やパッケージング作業も同じ仕組みで管理したくなります。
対策として「タスク一覧」に改称し、タスクIDプレフィックス規則を導入しました。

プレフィックス 種別 例
S Setup S001: Laravel環境構築
F Feature F001: ユーザー認証
P Packaging P001: Composerパッケージ化

タスクIDで作業を開始でき、依存関係の管理も明確になりました。

前編のまとめ

ここまで、仕様駆動AI開発のワークフローをチームで構築するまでの過程を紹介しました。
振り返ると、重要だったのは3つです。
1つ目は、人間とAIのハイブリッド運用。入口のメモから、途中の都度確認、逆方向のレビュー、出口のテストまで、要所で人間が関与する設計にしました。AIに丸投げするのではなく、対話しながら進めることで初めて効果が出ます。
2つ目は、チームで共有する仕組み。スキルやルールをリポジトリで管理し、シンボリックリンクで配布する。素朴な方法ですが、チーム全員が同じ基準で開発できるのは大きいです。
3つ目は、運用しながら調整すること。トークン消費の最適化やRulesとスキルの使い分けなど、実際に使ってみないと分からない課題が多くありました。
仕組みを作るだけなら、ここまでで十分かもしれません。しかし本当に大事なのは「実際に回るのか？」です。
後編では、このワークフローを実案件で全工程回した結果と、そこから見えてきた「使えば使うほど良くなる仕組み」について紹介します。