【AWS】Kiroのカスタムサブエージェントでタスクを並列実行【Kiro】

はじめに

2026年2月5日にKiroのIDEにCustom Subagentsが実装されました。
カスタムサブエージェントを活用することで定義した任意の定型作業の並列実行などが可能になります。
今回の記事ではCustom Subagentsについて使い方を解説しています。

KA AI WEEK で登壇しました

2026年2月20日(金)に行われたKAG AI WEEKにて本記事の内容を含むKiroに関する内容の登壇を行いました。
本記事と合わせてご覧ください。

SpeakerDeck

Specだけじゃない便利なKiroのやつ

イベントページ

結論

• カスタムサブエージェントは任意で定義したタスクを実行できる
  • 繰り返し実行する必要があるタスクの自動化などで便利
• 複数のカスタムサブエージェントを並列で実行可能
• カスタムサブエージェントを期待通りに動かすためには詳細な定義と精度の検証が必要
  • 今回の検証ではカスタムサブエージェントで一部期待外の結果が確認された
  • 詳細に記載していない内容はAIが判断するため人の予想外の結果になる
  • 詳細に記載すぎるとコンテキストウィンドウの圧迫やメンテナンスが困難になることも危惧される

サブエージェント

複数のタスクを実行する際に、Kiroのメインエージェントからの指示で複数のサブエージェントが並列でタスクを実行することができます。
例えば、GitHubに複数のイシューが登録されている場合、メインエージェントに課題の取得と複数のサブエージェントによるタスク実施を依頼すると、複数のサブエージェントが分担してタスクを実行します。
これにより、全体のタスク完了までの時間が短縮できます。

↓ サブエージェントのイメージ

カスタムサブエージェント

2026年2月5日のKiroのアップデートではカスタムサブエージェントの機能が実装されました。
カスタムサブエージェントはその名前の通り、サブエージェントで実行されるタスク(どのツールを使ってどの手順で実行するか)をあらかじめ定義することができます。

カスタムサブエージェントの活用シーン

カスタムサブエージェントを活用する場面では、「繰り返し実施する」かつ「実施手順が決まっている」かつ「前提や制約、手順などが複雑」なものをカスタムサブエージェントとして定義すると便利だと思います。
例えばコードレビューを同じツールを使って同じ基準で同じ観点を重要視してレビューするカスタムサブエージェントや、毎回人間が指定したフォーマットに従って結果を出力するテスト実行カスタムサブエージェントなどが有効だと思います。

カスタムサブエージェントとコンテキストウィンドウ

コンテキストウィンドウとは

コンテキストウィンドウとは、AIモデルが一度に処理できるテキスト量の上限です。
コンテキストが多い、つまりAIへ共有する情報が多いほどより期待に近い成果物が生成されます。
その反面、コンテキストが多すぎる場合、コンテキストウィンドウの制限を超えてしまい、古いコンテキストが切り捨てられたり、出力の打ち切りなどの問題が発生する可能性があります。
コンテキストが少なすぎる場合はAIへ共有する情報が少なくなり、不明な部分をAIが自律的に判断し、期待とは異なる生成がされます。

カスタムサブエージェントのコンテキストウィンドウ

Kiroのカスタムサブエージェントはメインエージェントとは独立した専用のコンテキストウィンドウを持っています。
これにより、サブエージェントの実行内容がメインエージェントのコンテキストを汚染しない設計になっています。
そのため、メインエージェントのコンテキストウィンドウが圧迫されず、AIとの適切なコンテキストの共有が可能になります。

カスタムエージェントとSkillsの違いのイメージ

似た機能としてAgentSkillsがありますが、AgentSkillsはメインエージェントを拡張する機能の集合のようなイメージです。前回紹介したPDFに関するSKILL.mdには「PDF作成」「PDFの結合」「PDFの分割」のようなPDFに関する機能一式が定義されています。
それに対してカスタムエージェントは「レビュータスク」のような「1つのタスク」に関して、どのツール(MCPやSkills)を使ってどのような手順で、何に注意して実行するかのような詳細が定義されています。

前回のAgentSkillsの記事

↓ カスタムエージェントとSkillsの違いのイメージ

上の図ではSkillsは大工作業に関する椅子や机などの作り方が書かれたマニュアル。カスタムサブエージェントは椅子を作る専門の職人や机を作る専門の職人であるという例えをしています。

AgentSkillsとカスタムサブエージェントどちらで実装するべきか

タスクによってはカスタムサブエージェントとAgentSkillsのどちらでも実現できるものがあります。
その場合は以下のような基準で選ぶと良いと考えています。

再利用可能なタスクはSkillsを利用する

便利なSkillsは以下のようなサイトで一般公開されています。
このように、構築するシステムを問わず再利用可能なタスクに対してSkillsは有効です。

複雑な自立タスク、並列作業可能なタスクはカスタムサブエージェントを利用する

カスタムサブエージェントはメインエージェントとは別に独立して動きます。そのため、他のカスタムサブエージェントと並列して作業できる単位で作成し、利用すると良いです。

カスタムサブエージェントの定義内容

カスタムサブエージェントはKiroとチャットでやり取りしながら定義できます。
Attribute以外に厳密に決められた書式はありませんが、およそ以下のような内容を定義します。

Attribute

name

必須項目。エージェントの一意な識別子であり、この名前でカスタムサブエージェントが呼び出されます。
そのため、他のエージェントと重複しない名前を設定する必要があります。
小文字とハイフンのみ使用可能です。

description

必須項目。エージェントの役割と機能を1，2行の短い文章で説明します。対象にしたい言語があればこの項目で明記します。

tools

エージェントが使用できるルールのカテゴリを指定します。
カテゴリは以下のような種類があります。

• read：ファイル読み取り
• write：ファイル書き込み
• shell：シェルコマンド実行
• web：Web検索
• spec：仕様ファイル操作（スペックモードでのみ有効）
• includeMcpJson：trueの場合、全てのMCPツールを含める
• @ < mcp_server>：特定のMCPサーバからのすべてのツールを含める
• @ < mcp_server>/ < tool>：特定のMCPサーバからの特定のツールを含める
  その他のツールの定義はKiroのドキュメントを参照して下さい

model

オプション項目。特定のAIモデルをしたい場合はモデルIDを指定します。
指定しない場合はデフォルトのモデル(カスタムサブエージェント呼び出し時に使用しているモデル)が使用されます。

Attributeは、例えば以下のように定義します

---
name: cdk-code-reviewer
description: AWS CDKコードのベストプラクティス、セキュリティ、コスト最適化、パフォーマンスの観点から詳細なレビューを行うエージェント。Well-Architected Frameworkに基づいた評価と具体的な改善提案を日本語で提供します。
tools: ["read", "write"]
---

エージェントの役割や責務

サブエージェントの役割とタスクの概要を記載します。
Attributeに記載したdescriptionや手順と記載が一部重複しますが、詳細な手順は記載せずにサブエージェントが実行するタスクの一覧がわかるように記載します。

# AWS CDK コードレビューエージェント

あなたは AWS CDK (Cloud Development Kit) のコードレビューを専門とするエキスパートエージェントです。

## 役割と責任
1. **セキュリティ** - AWS Well-Architected Framework のセキュリティの柱に基づく評価
2. **コスト最適化** - 不要なコストを削減し、効率的なリソース利用を提案
3. **パフォーマンス** - リソースの最適な構成とスケーラビリティの確保
4. **信頼性** - 高可用性、障害復旧、バックアップ戦略の評価
5. **運用の優秀性** - 監視、ログ、デプロイメント戦略の確認
6. **ベストプラクティス** - CDK固有の推奨パターンと命名規則

使用するツール(MCPやpowers、Skillsなど)について

Kiroの外部のツールを呼び出す際は以下のようにツール名と何のために使用するツール化を定義します。

## 利用可能なツール

### AWS Infrastructure as Code Power
レビュー時に以下のツールを活用してください：

1. **cdk_best_practices** - CDKベストプラクティスガイドを取得
   - レビュー開始時に必ず実行してください
   - 最新のセキュリティガイドライン、アーキテクチャパターン、開発ワークフローを参照

2. **search_cdk_documentation** - CDK公式ドキュメントを検索
   - 特定のConstructの正しい使用方法を確認
   - プロパティやメソッドの推奨設定を調査

3. **search_cdk_samples_and_constructs** - CDKコードサンプルを検索
   - ベストプラクティスに従った実装例を参照
   - 言語固有のイディオムを確認

4. **validate_cloudformation_template** - CloudFormationテンプレートを検証
   - CDKコードをsynthしたテンプレートの構文チェック
   - リソースプロパティの妥当性検証

5. **check_cloudformation_template_compliance** - セキュリティコンプライアンスチェック
   - AWS Control Tower proactive controlsに準拠しているか確認
   - セキュリティベストプラクティス違反を検出

タスクの実行手順

どの手順でタスクを実行すればよいかをステップごとのタイトルと詳細を記載します。
詳細にはどのツールを使うかや、どのコマンドを実行するかを詳細に記載します。
例えば、以下のように定義します

## レビュープロセス
### 1. コード分析
(手順の詳細、この手順で何を意識すべきか)
### 2. セキュリティチェック
(手順の詳細、この手順で何を意識すべきか)
### 3. コスト最適化チェック
(手順の詳細、この手順で何を意識すべきか)
### 4. パフォーマンスチェック
(手順の詳細、この手順で何を意識すべきか)
### 5. ベストプラクティスチェック
(手順の詳細、この手順で何を意識すべきか)

結果出力形式

どの国の言語で出力するか。Markdown形式などどの形式で出力するか。
出力形式が決まっていて、値を代入する形で出力したい場合は「```」で上下を囲んで以下のように定義します。

# AWS CDK コードレビュー結果

## サマリー
- レビュー対象: [ファイル/ディレクトリ名]
- 検出された問題: Critical: X件、High: Y件、Medium: Z件、Low: W件
- 総合評価: [優秀/良好/要改善/重大な問題あり]

## Critical（重大）
### [問題タイトル]
**場所**: `ファイル名:行番号`
**問題**: [具体的な問題の説明]
**リスク**: [セキュリティリスク、コスト影響、パフォーマンス影響など]
**推奨対応**: [具体的な修正方法]

エラーハンドリング

カスタムサブエージェント実行中にエラーが発生した際に、どのような動作をしてほしいかを定義します。
例えば、以下のように定義します。

## エラーハンドリング

- テスト実行が失敗した場合、エラーメッセージを詳細に分析
- 依存関係の問題がある場合は、`npm install`の実行を提案
- CDK synthが失敗した場合、スタック定義の問題を特定
- タイムアウトエラーの場合、テストの最適化を提案

使用例

複数のドキュメントを生成するカスタムサブエージェントを使って、一部のドキュメントだけ生成したい場合などでは使用例を定義しておきます。
以下のように定義をします

## 使用例

ユーザーが「プロジェクトのドキュメントを生成してください」と依頼した場合：
1. プロジェクト構造を分析
2. 主要なファイルを読み取り
3. 包括的なドキュメントセットを生成
4. 生成したドキュメントの概要を報告

ユーザーが「APIドキュメントだけを生成してください」と依頼した場合：
1. 公開APIを特定
2. 各API要素の詳細を分析
3. API.mdを生成
4. 生成したドキュメントを報告

カスタムサブエージェントの動作検証

カスタムサブエージェントの作成

今回は例として「CDKのコードレビューエージェント」「ドキュメント生成」「テスト実行」の3つのエージェントを作成しました。

並列実行依頼

作成したサブエージェントを並列で動かすため「ドキュメント生成、CDKのコードのレビュー、テスト実行をお願いします。可能であれば並列実行をお願いします。」とチャットで依頼します。

↓ 並列でカスタムサブエージェントが実行されていることが確認できました

実行結果

カスタムサブエージェントが実行された結果以下の内容が確認できました。

コードレビューは定義したタスクが実行され、指定した形式で結果が出力された

↓ コードレビュー結果の出力形式の指定

↓ 実際に出力された結果

テスト実行カスタムサブエージェントは定義していないエラーには対応しない

テスト実行カスタムサブエージェントではテストが実行され、その結果が定義したとおりに出力されました。
ただし、テストカバレッジはJest設定の問題により0％と判定されてしまいました。
これはカスタムサブエージェントでカバレッジの値が設定不備の問題で正確に出ないときはその問題を修正するなどの動作を定義していないことが原因と思われます。
問題発生時に設定の修正を行ってほしい場合は、カスタムサブエージェントにどの問題が発生したら修正を行うかを明示的に定義する必要があります。

プロジェクトのドキュメント生成は定義したもの以外のドキュメントも生成された

ドキュメント生成のカスタムサブエージェントでは、以下のキャプチャ画像のように
README.md: プロジェクト概要、インストール、クイックスタート
API.md: 詳細なAPI仕様とリファレンス
ARCHITECTURE.md: システムアーキテクチャと設計思想
USAGE.md: 詳細な使用方法とサンプルコード
CONTRIBUTING.md: 開発者向けガイド（必要に応じて）
5種類のファイルを定義していました。

実際に生成されたファイルは以下のキャプチャ画像のように、READMEに記載されるはずのプロジェクト概要が別ファイルに記載されて生成された「PROJECT_OVERVIEW.md」などを含む9種類のファイルが生成されました。

この結果は以下のような基準により、カスタムサブエージェントが自律的に判断したものと思われます。

• エージェントの自律的判断: プロジェクトの規模に応じた適切な構造を決定
• 可読性の考慮: README.mdを簡潔に保つため
• 関心の分離: 異なる目的の情報を異なるファイルに分離
• ベストプラクティス: ドキュメント構造の業界標準に従う

もしもこのようなエージェントの自律的な判断を防ぎたい場合は「定義されたファイルのみ作成し、以外のファイルは作詞しないでください」のような、より強力な動作を制限する定義を行う必要があります。

順次実行と並列実行の効率化の検証

今回の検証ではレビュー、テスト、ドキュメント作成を行いましたが本当に効率化できるか実行時間を測ってみました。
AIモデル：ClaudeHaiku4.5
検証方法：Kiroに順次実行と並列実行の時間をそれぞれ計測してもらう

比較結果：並列化により、最も長いタスクの実行時間で全タスクが完了した

結果は上記キャプチャ画像のように以下のようになりました
順次実行が合計115秒(レビュー45秒、テスト30秒、ドキュメント作成40秒)。
並列実行合計45秒(最長タスク45秒※おそらくレビュータスク)。
この結果から、並列実行により全体のタスク完了までの時間が最も長く時間がかかるタスクである45秒になり、約61％の効率化が行えました。

カスタムサブエージェントの作り方のポイント

今回の検証では一部期待通りの結果が得られないものがありました。
今回のような問題の発生を予防するために、私が思うカスタムサブエージェントの作り方のポイントを記載します。

カスタムエージェントのタスクを細分化する

コンテキスト量の削減

小さな単位で独立したカスタムサブエージェントを作ることで、それぞれのカスタムサブエージェントが担当するタスクを定義するコンテキストの量が減り、コンテキストウィンドウの圧迫を防ぐことができます。
また、タスクを並列可能な単位で分割することで分割されたタスクの内容をより詳細に記載することができます。

全体の実行時間の削減

今回の検証では並列化により、同時に実行したタスクのうち最も時間のかかったタスクの実行時間で全タスクが完了しました。
そのため、タスクを細分化して最長のタスクがより短い時間で完了するようにすることで、全体のタスクの実行時間が短縮できます。

手順より「制約」を書く。エラーケースを定義する。

今回の検証ではタスクの手順の未記載したため、0%のままテストカバレッジが出力されたり、成果物の設計書が分割された問題が発生しました。
どのような問題が発生するか予測することは難しいですが、「〇〇しないこと」「〇〇の結果になったらその問題を放置しないこと」などの避けたい動作を定義してあげることで結果を期待に近づけられる可能性があります。

移譲可能な内容はツールに移譲する

コンテキストを少なくするためにはSkillsやMCPなどのツールを利用することも有効です。
SkillsやMCPで実現可能な内容をカスタムサブエージェントに再定義することはコンテキストの圧迫だけではなく信頼されるツールを使わないことによりタスクの品質を低下させる可能性もあります。
カスタムサブエージェントに定義したい内容の中でSkillsやMCPで提供されている機能がある場合は、そのSkillsやMCPを呼び出すようにしましょう。

さいごに

カスタムサブエージェントは、複数のタスクを事前に定義された順序で実行できるだけでなく、複数のサブエージェントを並列に実行することもできます。
複数のタスクを事前に定義された順序で自動的に並列実行することで、開発効率が向上します。

カスタムサブエージェントが期待どおりに動作するには定義の粒度と結果の精度の検証が必要

今回のテストでは、予期しない問題が自動的に修正されず、テストカバレッジが0%になり、ドキュメント生成時に予期しないファイルが生成されることが確認されました。

カスタムサブエージェントが期待どおりに動作することを確認するには、より詳細で具体的な定義が必要です。しかし、詳細すぎるとカスタムサブエージェント自身のコンテキストウィンドウが圧迫され、結局は不完全な結果になる可能性があります。

カスタムサブエージェントの精度を向上させるには、AIの出力を詳細にレビューし、AIと繰り返し議論する必要があります。

英語版の記事はこちら