はじめに
こんにちは、AI Lab の しょーた です！
AI エージェントを使った開発には様々な手法がありますが、今回は Claude Code のスキル・サブエージェントを活用した開発フローについて紹介します。
TL;DR
- Claude Code のスキルとサブエージェントを組み合わせ、「設計からコーディング」までを自動化するワークフローを構築
- 設計フェーズでは、調査・仕様作成・詳細設計の3工程をサブエージェントに分担
- コーディングフェーズでは、TDD 実装・テスト・コード品質を基準を満たすまで最大10回ブラッシュアップ
- Claude のコンテキスト上限問題を緩和するため、品質レビューは Codex CLI に担当
本記事では、このワークフローに行き着いた背景と、実際に稼働しているエージェント群の具体的なプロンプト構造を紹介します。Claude Codeを現場で使い倒したい方の参考になれば幸いです！
開発ワークフローでやること
今回紹介する開発ワークフローでは、Claude Code の「スキル」と「サブエージェント」を組み合わせて、「設計からコーディング」までを実行します。
ワークフローでは大きく設計とコーディングの2つに分けたスキルで構成されています。
設計スキル
- 調査 → 要件定義 → 詳細設計の3ステップを別々の3つのサブエージェントに分担させる
- 各ステップで成果物となる「仕様書（SPEC.md）」と「詳細設計書」を出力する
コーディングスキル
- コーディング用のサブエージェントを使って、TDD（テスト駆動開発）でコードを実装する
- テストコードの品質をレビューするサブエージェントと、コードの品質をレビューするサブエージェントを使って、コードの品質をチェックする
- 品質基準に満たない場合は、コーディング用のサブエージェントを再度呼び出して修正させて一定回数ループさせる
なぜこのワークフローにしたのか
このワークフローで2つのスキルと6つのサブエージェントを用意しているのは、Claude Code を使い込む中で遭遇した課題への対処がベースになっています。大きく「コンテキストの節約」と「自動化」の2つです。
1. コンテキストの節約
調査・設計・実装を1つの会話で進めるとコンテキストが膨らんで精度が落ちてしまいます。そこで工程ごとにサブエージェントを分けて、それぞれが必要な情報だけを持った独立したコンテキストで動作するようにしています。また、最初は全てを Claude に任せていたのですが、すぐに Current Session の上限に到達してリセットされるまで何もできない状況になってしまいました。そこで品質チェックのレビュー部分は Codex CLI に担当させることで Current Session の消費を節約しています。
2. コーディングと品質チェックの自動化
コーディングと品質チェックを別々に手動で実行すると、品質チェックでNGが出るたびにユーザーが介入して修正を依頼し直す必要があり、ボトルネックになってしまいます。そこで TDD 実装 → テスト品質チェック → コード品質チェックの一連の流れをスキルとして定義し、品質チェックでNGが出たら自動で TDD 実装に戻って修正するようにしています。また、 永遠にループしてトークンを消費することを防ぐために最大10回までループし、それまでに解決できなかった場合はユーザーへ報告するようにしています。
次のセクションから、この課題を踏まえて構成した各スキルとサブエージェントの詳細について紹介します。
機能開発の流れ
Claude Code を使った開発フロー図を以下に記載します。
このフローでは「設計書の作成」を行う plan-workflow スキルと「コーディング」を行う python-tdd-flow-with-codex スキルを使って機能開発を行なっています。
plan-workflow スキルでは以下のサブエージェントを呼び出して設計書の作成を行なっています。
pre-plan-researcher: 事前調査requirements-designer: 仕様書作成detailed-designer: 詳細設計書作成
python-tdd-flow-with-codex では以下のサブエージェントを呼び出してコーディングを実施しています。
python-tdd-coder: TDD 実装python-test-quality-checker: テスト品質チェックpython-quality-checker: コード品質チェック
それぞれのスキルは以下のキャプチャのように簡単に呼び出して使うようにしています。
次に各スキルで行なっている機能の詳細について紹介します。
設計書の作成: plan-workflow スキル
このスキルでは3つのサブエージェントと1つのメインエージェント処理を使って設計書の作成を行なっています。
事前調査: pre-plan-researcher サブエージェント
仕様書の作成を行う前に、事前調査を行う pre-plan-researcher サブエージェントを使って要件の整理や洗い出しを行います。調査用のサブエージェントで事前調査を行うことで、仕様書作成で行う調査作業をスキップして、調査作業によるコンテキスト消費を抑える目的があります。
具体的には以下の調査を指示しています。
- コードベース分析
- 仕様確認
- 技術調査
- 影響範囲の特定
- 実装時のリスク・注意点の抽出
上記の調査を行ったのちに、最終的にサブエージェントでは調査結果をレポート形式で以下のように返すようにしています。このレポートは次の requirements-designer サブエージェントへのインプットとなります。
## 事前調査レポート ### 1. タスク概要 - 実装/修正の目的 - 期待される動作 ### 2. 関連ファイル - 変更対象ファイル - 依存ファイル - テストファイル ### 3. コードベース分析結果 - 既存の実装パターン - 参考にすべきコード - 再利用可能なコンポーネント ### 4. 影響範囲 - 影響を受けるモジュール/機能 - テストへの影響 - 設定変更の必要性 ### 5. 技術的考慮事項 - 使用するAPI/ライブラリ - パフォーマンスの考慮 - セキュリティの考慮 ### 6. リスク・注意点 - 潜在的な問題点 - 注意が必要な箇所 - 推奨される対策 ### 7. 不明点・確認事項 - 仕様上の不明点 - 追加で確認が必要な事項
仕様書の作成: requirements-designer サブエージェント
仕様書の作成では requirements-designer サブエージェントを使って、後続の詳細設計書のインプットとなる仕様書の作成を行います。
具体的には以下のことを行なっています。
pre-plan-researcherサブエージェントが出力した調査結果の確認- 要件の整理
- 完了条件の定義
- 仕様書の作成
要件の整理では整理中に出てきた疑問点・矛盾点を洗い出すように指示し、明示的に Claude Code が標準提供する AskUserQuestionTool を使ってユーザーへ質問して疑問点・矛盾点の解消を行なった後に仕様書を作成するようにしています。
AskUserQuestionTool は「なぜそのような実装をするのか？」や「ここの実装はどうするか」などをユーザーに回答させることで、ユーザー側の考慮もれをキャッチして仕様書をブラッシュアップさせることが可能なツールです。そのため、仕様書の作成だけでなく、詳細設計書の作成でも AskUserQuestionTool を使うようにしています。
その要件の擦り合わせを行った後に、Claude から仕様書が提案されるので自分が実装したい内容や要件とあっているか確認して SPEC.md として仕様書を出力させます。
詳細設計書ファイル名一覧決定（メインエージェント）
仕様書を出力した後に詳細設計書作成を行うのですが、その前に作成した仕様書を元に詳細設計書のファイル一覧を以下のキャプチャのようにメインエージェントに決めさせます。
これは詳細設計書作成でクラス・モジュールごとに detailed-designer サブエージェントを複数起動して詳細設計書を作成させる必要があるためです。「1クラス/モジュール = 1詳細設計書」の粒度で設計対象を分解し、各サブエージェントにどの詳細設計書を作成するか明示的に指示します。
はじめはこのメインエージェントの処理は特に定義しておらず、いきなり detailed-designer サブエージェントを並列起動して詳細設計書を作成するように指示していたのですが、同じクラス・モジュールの詳細設計書を作ってしまうケースが発生したため、メインエージェントでまず作成する詳細設計書名を全て洗い出して、各サブエージェントへどの詳細設計書を作成するか指示するようにしました。
詳細設計書の作成: detailed-designer サブエージェント
詳細設計書の作成では detailed-designer サブエージェントを複数起動して仕様書を元に並列で詳細設計書の作成を行います。各サブエージェントは1つのクラスまたはモジュールのみを担当し、複数のクラスを1つの設計書にまとめません。
具体的には以下のことを行なっています。
- 仕様書の確認
- 既存コードの分析
- 詳細設計書の作成
この詳細設計書の作成でも明示的に AskUserQuestionTool を使って疑問点を洗い出してから詳細設計書を作成するように指示しています。
以上で、 plan-workflow で用いるスキルとサブエージェントの説明は終わりです。最後に以下に plan-workflow の成果物を記載します。
plan-workflow の成果物
| ステップ | 成果物 | パス |
| Step 1 | 調査レポート | 会話内に出力 |
| Step 2 | 機能仕様書 | docs/{タスク名}/SPEC.md |
| Step 2.5 | 設計対象リスト | 会話内に出力 |
| Step 3 | 詳細設計書 | docs/{タスク名}/designs/01-xxx.md, 02-yyy.md, … |
コーディング: python-tdd-flow-with-codex スキル
このスキルでは3つのサブエージェントを連携させて、品質基準を満たすまで自動的にサイクルを繰り返すワークフローを実行します。以下のフロー図のように、テスト品質チェックとコード品質チェックでNGが出た場合は TDD 実装に戻って修正を行います。最大10回までループしてそれまでに解決できなかったらユーザーへ報告するようにスキルへ記述しています。
TDD 実装: python-tdd-coder サブエージェント
設計書作成で作成した詳細設計書を元に、TDD での実装を python-tdd-coder サブエージェントを使って行います。
python-tdd-coder サブエージェントでは Red-Green-Refactor のサイクルを厳守してコードを実装します。
- Red フェーズ: テストを作成し、実行して失敗することを確認
- Green フェーズ: テストが通る最小限の実装を書く
- Refactor フェーズ: 必要に応じてコードを改善し、テストが通ることを確認
テスト品質チェック: python-test-quality-checker-with-codex サブエージェント
TDD 実装が完了したら、python-test-quality-checker-with-codex サブエージェントを使ってテストコードの品質をチェックします。このサブエージェントは Codex CLI を使用してテストコードのレビューを実行します。
Codex CLI でレビューしている理由としては、サブエージェントをループして利用する都合、Claude 単体で利用するとすぐに Current Session の上限に到達してしまうからです。
最初は Claude 単体で全てやってきましたがすぐに Current Session が 100% に到達してリセットされるまで何もできない状況になってしまったので、レビューについては Codex が担当するようにこのサブエージェントの md ファイルに以下のように記述しています。
### 2. codex exec コマンドの実行 対象のテストファイルを指定して、Codexにレビューを依頼します： codex exec -s read-only "You are an expert in Python test code quality review, focusing on verifying whether test code adheres to best practices. Review the following Python test file for test code quality: File: /absolute/path/to/test_file.py ## Key Responsibilities ...
このサブエージェントで指摘されたら、指摘内容を整理して python-tdd-coder サブエージェントにレビュー結果を渡して再度修正を依頼します。 問題なければ次のコード品質チェックを実行します。
コード品質チェック: python-quality-checker-with-codex サブエージェント
テスト品質チェックがOKになったら、python-quality-checker-with-codex サブエージェントを使って実装コードの品質をチェックします。このサブエージェントも Codex CLI を使用してコードレビューを実行します。
ここでも以下のような形でサブエージェントの md 内に Codex CLI のコマンドを記述して、それを使ってレビューをするように指示しています。
### 2. codex exec コマンドの実行 対象ファイルを指定して、Codexにレビューを依頼します： codex exec -s read-only "You are an expert Python Code Quality Analyst, well-versed in software engineering principles and Python best practices. You have extensive experience in code reviews, refactoring legacy systems, and mentoring developers on how to write clean, maintainable code.Review the following Python file for code quality: File: /absolute/path/to/target_file.py ...
重大度に応じて Critical / Major / Minor / Suggestion の4段階で分類して、Critical または Major が1件以上ある場合は、指摘された問題点を python-tdd-coder サブエージェントに渡して修正を依頼します。
完了報告
全ての品質チェックがOKになった場合、以下のような完了レポートを出力します。
# TDD フロー完了レポート ## 実装結果 - 作成/更新したテストファイル: [ファイルリスト] - 作成/更新した実装ファイル: [ファイルリスト] - 実行したTDDサイクル数: [回数]
冒頭に示したフローをもう一度提示しますが、以上のようなスキルとサブエージェントを構成することで以下のフローを実現しています。
最後に
今回は私が行なっている Claude Code のスキル・サブエージェントを活用した開発フローについて紹介しました。 Claude Code や他の AI エージェントを用いた開発方法については人によって様々なやり方があり、自分にあった育て方をしているかと思います。私が紹介した方法も自分ではまだベストだとは思っていないので、これからも日々改善しながら育てていこうと思います。
