Zenn
😁

Claude Codeで構築するAIエージェント駆動開発 - 設計から実装、テストまでの実践ガイド

に公開
LLM
Claude Code
tech

Claude Codeで構築するAIエージェント駆動開発 - 設計から実装、テストまでの実践ガイド

前提条件

  • 現状最強のOpus4を定額で使えるため、Claude Code MAXプランでの運用を前提とする

Claude Codeの実行モード

  • インタラクティブモード: claudeコマンドで対話的に実行（設計書作成、レビュー対応など）
  • バックグラウンドモード: claude -p --output-format jsonで非対話的に実行（長時間の実装作業など）
  • セッション再開: -r <session_id>で過去のセッションを継続

基本的な開発フロー

開発の大まかな流れ：

  1. コンテキストの作成
  2. それを使って、実装用・レビュー用エージェントを動かす

この流れをベースに、まず実装設計書や計画を具体的に書くことから始める。

1. 実装設計書の作成

1-1. 設計書作成プロセス

  1. 要件を伝えて設計書を作成（Opus4推奨、インタラクティブモード）
  2. 新しくClaude Codeを立ち上げレビューし、レビュー結果をファイルに残す（新規セッション）
  3. 人間によるレビュー
  4. 1とのチャットを再開
  5. レビュー結果ファイルを参照させ、レビュー指摘対応をさせる
  6. 漏れがあった理由を分析させる
    • ドメイン的指摘 → CLAUDE.mdに記載
    • 機能的指摘 → 該当機能の仕様書に追記
  7. 振り返りを実施し、成功要因をコンテキストとして保存
  8. 設計書から実装計画書を作成
  9. 実装計画書からプロンプトファイルを作成

2. 実装フェーズ

2-1. 実装の実行

  • cat promptfile | claude -p --output-format jsonでバックグラウンド実行
  • 明確な実装計画書の場合はSonnet4でも可
  • 出力されるsession_idは後で使用するため保存

2-2. レビュープロセス

  1. 実装計画書からレビュー用プロンプトを作成（Opus推奨、プロンプトが重要）
  2. **新規セッション（インタラクティブモード）**でレビューを実施
  3. レビュー結果をファイルに出力
  4. レビュー指摘の修正：
    • 実装時のセッションを-r <session_id>で再開
    • レビュー指摘の修正と再レビューを繰り返す

3. フィードバックループの構築（オプション）

エージェントにフィードバックループを与えることで、作業完了の精度を高めることができる。

3-1. ユニットテスト

  • 仕様書を基にユニットテスト作成用エージェントを立ち上げる（新規セッション）
  • 仕様書から必要なテストケースを洗い出し、テストコードを生成
  • 実装前にテストを実行し、すべて失敗する状態を確認
  • 実装時にこのテスト環境を参照させることで、実装完了の精度が劇的に向上

4. 結合テスト

4-1. ブラウザテストの自動化

  • MCPサーバーを導入し、ブラウザをAIが操作可能に設定
  • 設計書からエージェントのためのテスト計画書を作成（インタラクティブモード）
  • テスト実行はバックグラウンドモードを推奨（長時間実行のため）
  • テスト計画書がコードレベルで具体的であるほど、ブラウザテストの成功率が向上
  • トークン消費量が多いため、Sonnet4の使用を推奨
  • 複雑なテストは計画書作成より手動実施の方が効率的
  • E2E環境がある場合は、テスト後に作成してもらう方が効率的

Tips & Best Practices

  1. コンテキストファイルの活用

    • 設計書に含められない内容は別途コンテキストファイルを用意
    • 計画書作成時に参照させることで、毎回同じ指摘を回避

  2. AI用アカウントの作成

    • 開発アプリケーションにAIエージェント専用アカウントを作成するとAIと並行してテストが可能

  3. 自動化について

  4. セッション管理のコツ

    • 重要な作業は必ずsession_idを記録
    • 長時間作業はバックグラウンドモード、対話的作業はインタラクティブモード
    • セッションの使い分けで効率的な開発が可能

  5. 注意事項

    • Claude Code特有のパーミッション問題でユニットテストが実行できない場合がある
    • 適切な権限設定の確認が必要

Discussion