どうもこんにちは。
今回は、Claude Codeを使って開発をしていて、せっかく作ったサブエージェントとかSkills使ってくれないなぁ... っていうのを解決するためにワークフローを定義しようと思い、実際に形になっていい感じにワークフローが回るようになったので、記事にします。
はじめに
Claude Code, Codex, Kiro, Antigravityなどを使用していて、以下のような悩みを抱えている方は多いのではないでしょうか。
- エージェントのコンテキストを圧迫してしまい、エージェントの精度が低下してしまう
- いちいちエージェントに頼みたいことを細かく書いてリクエストを送信するのがめんどくさい
また、上記の悩みを解決するために、こんな方法を試した方もいると思います。
- サブエージェントを作ってみる
- Skillsを作ってみる
でも、こんな風に上手くいかないことがありませんでしたか？
- エージェントがサブエージェントやSkillsを呼び出してくれない
今回は、このような悩みを解決するための記事となっております。
なぜサブエージェントを作成した？
コーディングエージェントツールを使用して、1つのエージェントに大規模なタスクを与えるとコンテキストが圧迫されます。
コンテキストが圧迫されると、エージェントは、「ユーザからリクエストされた記憶」「エージェントが実装した記憶」「ユーザから追加リクエストされた記憶」を圧縮します。最初のうちは「圧縮された〜」くらいにしか感じないと思いますが、エージェントとのやりとりの回数が多くなるにつれ、今までの記憶が断片的になっていきます。
こうなってしまうと、ユーザがエージェントに求めていることが正確にできなくなり、開発の精度が低下するという現象が発生します。
人間と一緒っすね。
なので、サブエージェントを作ることで、タスクを分散し、「コンテキストに入る情報は同じような内容にしよう」「コンテキストの圧迫を遅らせよう」となっているわけでございます。
なぜSkillsを作成した？
前々から、MCPという概念がエージェントにツールを与える便利な手段として確立されていましたが、MCPのデメリットは エージェント起動時に接続されているMCPサーバにアクセスし、すべてのツールの情報をコンテキストに入れることです。
これによって、以下のような問題が発生します。
- エージェントの起動が遅い
- エージェントにやって欲しくないことまで実行されてしまう
- 最初にすべてのツールがコンテキストに入ることで、最初からコンテキストが圧迫される
この問題を解決するためにSkillsという概念が誕生しました。
でもさぁ...
作ったサブエージェントとSkills、想定通りに呼び出されていますか？
自分の場合はちょっと厳しかったです...
Skillsを呼び出して欲しい場面で、ファイル新規作成しやがったり、Bashスクリプト作成しやがったり、Pythonスクリプト作成しやがったり。
サブエージェントを呼び出して欲しい画面で、「自分でできるから大丈夫です」みたいな頑固になってきやがったり。
なら決まった形でタスクの実行をさせていくのが良いよねという発想に至るわけです。ということで「ワークフローを定義しよう！」となるわけです。
ワークフローを定義することでどんな恩恵を得られる？
上記の問題が解決するのはもちろんですが、以下のようなメリットがあります。
エージェントにやるべき作業の全容を理解してもらいやすくなる
ワークフローとは、一連の作業の流れを定義したものです。（それはそう。）
人間も初めてやる作業に決まったフローがあればスムーズに作業ができますよね？それと同じことをエージェントにもしてあげます。
例えば、エージェントに「このIssueに記載されている内容を開発して」と伝えるのと、「このIssueに記載されている内容を設計理解→実装→コード解析→自動テスト→コミットの順で開発して」と伝えるのでは、理解度が変わります。
ただ、毎回これをエージェントにリクエストするのはめんどくさいよねということで、最初にワークフローを定義しておいて、それを参照させて実行させるというような感じです。
人間の想定通りにコンテキストの分散ができるようになる
エージェントが1体で抱え込んでいたコンテキスト・記憶を分散させることで精度が向上するようになります。また、ワークフローの中でサブエージェントに「君の作業はこれだけね。これだけやれば良いからね。わかったね。」というように役割を正確に伝えることにも繋がります。
メリットが分かったところでワークフローを作っていく
以下のようにMarkdown形式で書き起こしていきます。
# 開発ワークフロー
## 実行手順
1. 設計を理解してまとめる
2. まとめられた設計を読んで実装する
3. コード解析してコード規約チェックする
4. 自動テストを実行する
5. `git commmit`コマンドでコミットする
これだと、どのエージェントが何をするのかがわからないので、以下のように追加します。
# 開発フロー
## 実行手順
1. `PlanerAgent`が設計を理解してまとめる
2. `CodingAgent`がまとめられた設計を読んで実装する
3. `AnalysisAgent`がコード解析してコード規約チェックする
4. `AutoTestAgent`が自動テストを実行する
5. `Agent`が`git commmit`コマンドでコミットする
これでサブエージェントの役割ができますが、どのSkillを使えば良いのかわかりませんよね。以下のように追加します。
※ 実装にはSkillを使用しないようにしています。
# 開発フロー
## 実行手順
1. `PlanerAgent`が`/understand-plan`スキルを使って設計を理解してまとめる
2. `CodingAgent`がまとめられた設計を読んで実装する
3. `AnalysisAgent`が`/run-analysis-tool`スキルを使ってコード解析してコード規約チェックする
4. `AutoTestAgent`が`/run-auto-test-tool`スキルを使って自動テストを実行する
5. `Agent`が`git commmit`コマンドでコミットする
これでサブエージェントの役割とSkillsを使う場面が明確になりましたが、こういう場面に直面します。
- ステップ3で実装されたコードがコード規約に違反した場合のフローはどうすれば良いの？
- ステップ4で実行された自動テストがすべてPASSしなかった場合のフローはどうすれば良いの？
じゃあ条件分岐を考えなきゃ...
もう無理です。ギブアップってなりますよね。どんどんややこしくなってくる。
ならフローチャート的な形でワークフローを組みませんか？
CC Workflow Studioを使ってワークフローを定義する
エージェントのワークフローをフローチャート的な形で作ることのできるVSCode拡張機能です。
CC Workflow Studioでできること
- ワークフローをビジュアルエディタで設計・編集できる
- Claude Codeの
.claude/commandsディレクトリに、ワークフローが定義されたMarkdownファイルが自動で生成される - VS Codeの拡張機能として使用することができる
- マウス操作でノードを配置し、繋げてワークフローを作成できる
8種類のノードを使用してワークフローを作成する
エージェント対応ノード（SubAgent, Skills, MCPなど）
| ノード | 説明 |
|---|---|
| Prompt | エージェント, サブエージェントに対するプロンプトを設定 |
| Sub-Agent | 特定のタスクを任せるサブエージェントを定義 |
| Sub-Agent Flow | 特定のタスクを任せるサブエージェントを定義し、 サブエージェントが使用するSkillsやMCPツールを定義 |
| Skill | Skillsの実行を定義 |
| MCP Tool | MCPサーバを経由したツールの実行を定義 |
フロー内でSub-Agentを配置すると、保存するときに自動でSubAgentが作成されます。
MCP Toolを配置する時、エージェントに使用させたいツールのみを使えるように指定することができます。
フロー内条件分岐用ノード
| ノード | 説明 |
|---|---|
| If/Else | 二択分岐 |
| Switch | 複数選択肢の多分岐処理 |
ツール実行の成功or失敗であればIf/Elseを使って条件分岐を定義、それ以上の結果パターンがあればSwitchを使う。
その他ノード
| ノード | 説明 |
|---|---|
| Ask User Question | ワークフロー途中でユーザーに選択を求める |
途中でユーザの確認を求めたいときに使用します。大規模ワークフローに使うことが多いかも。
CC Workflow Studioのイメージ図
使い方
簡単な説明だけ記載します。
- ノードを配置し、それぞれのノードに設定を行う（ノード名, プロンプトなど）
- ノード同士を線で繋げる
- 「保存」ボタンをクリックする →
.vscode/workflowsディレクトリにJSONファイルが生成されます - 「変換」ボタンをクリックする →
.claude/commandsディレクトリにMarkdownファイルが生成されます
注意点
ワークフローを作成する中で、SubAgentは自動で作成されます。
しかし、Skillsについては自動で作成されません。そのため、ワークフローに使いたいSkillがないときは、claude /pluginコマンドを実行して、/skill-creatorというSkillをインストールし、Skillを作成してからノードで配置を行なってください。
.claude/commandsディレクトリにファイルが作られるということは？
.claude/commandsディレクトリにファイルが作られるということは、Claude Codeで実行することができるカスタムスラッシュコマンドが実行できるということです。
つまり、作成したワークフローはカスタムスラッシュコマンドによって実行できる ということです。
実行例
例えば、CC Workflow Studioでsample-developというワークフローを作成したとします。すると、.claude/commandsディレクトリにsample-develop.mdというファイルが作成されているはずです。
中身を参照すると、Mermaid形式でフローが定義されています。
このワークフローを実行したい時は、以下のように実行します。
$ claude
▐▛███▜▌ Claude Code v2.1.34
▝▜█████▛▘ global.anthropic.claude-sonnet-4-5-20250929-v1:0 · API Usage Billing
▘▘ ▝▝ ~/code/sample-app
/model to try Opus 4.6. Note: you may need to request access from your cloud provider
────────────────────────────────────────────────────────────────────────────────────────
❯ /sample-develop
────────────────────────────────────────────────────────────────────────────────────────
プロンプトノードで変数を定義しておくと、以下のようにスラッシュコマンドの後に引数を指定して実行できます
$ claude
▐▛███▜▌ Claude Code v2.1.34
▝▜█████▛▘ global.anthropic.claude-sonnet-4-5-20250929-v1:0 · API Usage Billing
▘▘ ▝▝ ~/code/sample-app
/model to try Opus 4.6. Note: you may need to request access from your cloud provider
────────────────────────────────────────────────────────────────────────────────────────
❯ /sample-develop SAMPLE-001
────────────────────────────────────────────────────────────────────────────────────────
また、以下のように、スラッシュコマンドの後にワークフローで指定していない処理をするようにリクエストすることもできます。
$ claude
▐▛███▜▌ Claude Code v2.1.34
▝▜█████▛▘ global.anthropic.claude-sonnet-4-5-20250929-v1:0 · API Usage Billing
▘▘ ▝▝ ~/code/sample-app
/model to try Opus 4.6. Note: you may need to request access from your cloud provider
────────────────────────────────────────────────────────────────────────────────────────
❯ /sample-develop 一番最初にこのブランチで行われている実装分を`git diff`コマンドで取得し、現状のソースコードの状態を理解してください。
────────────────────────────────────────────────────────────────────────────────────────
まとめ
ワークフローの作成はめんどくさいけど、CC Workflow Studioを使用すれば簡単にワークフローの作成ができます！
2/13（金）のQiitaBashでは、これを使って作成したワークフローでどんな開発ワークフローを作って運用してるのかをお話しする予定です。
以上