🥷

Kiro CLIのPlan AgentとCustom Agentを利用して設計書の品質を上げる

Yuki Matsumoto

2026/01/01に公開

1. はじめに

ITアーキテクトを務めています松本と申します。
Kiro CLIに新しくPlan Agentが導入されました。
これはプロンプトを入力すると実装計画を考えてくれる機能になっております。
今まではプロンプトで明示的に「計画を作ってください。まだ、実装はしないでください」のように、実装を止めるように指示を出さなければなりませんでしたが、Plan Agentを利用するとそのような指示を出す必要はありません。
今回はPlan Agentと独自に作った設計書レビュー用Custom Agentを行き来しながら、設計書の品質を上げてみましょう。

2. Plan Agentとは？

Kiro CLIに新しく導入された組み込みのエージェントになります。
Plan Agentの大きな特徴は以下の通りになります。

実装計画を立てることに集中している
プログラミングを行うことはない
コードやファイルを読み取りはするが、書き込みはしない
どういう方針で計画を立てるのか、Plan Agentの方から何回か質問をしてくる
Plan AgentはWeb検索を実行できるが、MCPは利用できない

Kiro CLIのエージェントなので/agent swapのスラッシュコマンドで、デフォルトのエージェントとPlan Agentを切り替えることができます。エージェントの一覧にはkiro_plannerというエージェントが表示され、選択するとエージェントを切り替えることができます。Kiro CLIを起動した直後のエージェントはkiro_defaultと呼ばれているようです。

> /agent swap

 Choose one of the following agents 
❯ kiro_default
  kiro_planner

Plan Agentへの切り替えにはショートカットも用意されており、Shift + tabでPlan Agentに素早く切り替えることができます。
また、Plan Agentに切り替えている状態でもう一度Shift + tabを押すと、直前まで利用していたエージェントに戻ります。このショートカットはかなり便利なので、ぜひご活用ください。

3. Custom Agentとは？

Custom Agentは、特定の用途だけを実行させるように定義した、Kiro CLI上で実行できるユーザー独自のエージェントです。使用できるMCPやToolsを指定することができ、含めたいコンテキストを指定する(特定のディレクトリ配下のファイルを読み込ませるなど)ことで、特定の用途に沿ったエージェントを作成することができます。今回は設計書がどれぐらい要件定義書の要件を満たしているのかをレビューする「設計書レビューエージェント」を作成していきます。

4. Plan Agentと設計書レビューエージェントのタスクフロー

Plan Agentと設計書レビューエージェントは以下のフロー図のようにタスクを進めます。

要件定義書と設計書をマークダウン形式で作成します。今回はこの部分は割愛して、別途作成したファイルを利用します。
設計書レビューエージェントがレビューを行います。出力されるレビュー結果もマークダウン形式で出力します。
レビュー結果をPlan Agentに読み込ませ、設計書の修正計画を立案させます。
デフォルトのエージェントに修正計画を渡し、設計書を修正させます。

5. AGENTS.mdの作成

タスクフローを実装する前にAGENTS.mdの作成を行います。
AGENTS.mdはAIコーディングエージェント用のREADMEのようなファイルです。「AGENTS.md」というファイルを作成すると、Kiro CLIは自動でコンテキストにその内容を追加してくれます。Kiro CLIは、起動したディレクトリに存在する「AGENTS.md」ファイルを読み込みます。
AGENTS.mdとREADME.mdをわざわざ分割する理由は、AI向けの指示をREADME.mdから削除するためです。AIしか読む必要がない指示をAGENTS.mdにまとめると、README.mdを綺麗に保つことができます。「AGENTS.md」自体はKiro CLIだけではなく、他の多くのAIコーディングエージェントでサポートされております。

今回はKiro CLIからの返答を日本語化するために利用します。

Kiro CLIからの返答を日本語化

Kiro CLIに日本語で問い合わせても、英語で返答されることがあります。
全てを日本語で返答してもらいたいですが、毎回「日本語で返答して」とプロンプトに記載するのは少々不便です。

> おはようございます。

> おはようございます！How can I help you today? I'm here to assist with coding, AWS management, system operations, or any development tasks you're 
working on.

返答を全て日本語にするために、AGENTS.mdをプロジェクトルートディレクトリに作成してみましょう。内容は以下の通りにします。

# ルール
- 英語で考えて、日本語で返答すること

AGENTS.md作成後に、AGENTS.mdが存在するディレクトリでKiro CLIを起動してみます。
AGENTS.mdがコンテキストに追加されているのかを確認するためには、/context showのスラッシュコマンドを実行するとよいです。

> /context show

Agent (kiro_default)
  - AmazonQ.md (no matches)
  - AGENTS.md /projects/main/AGENTS.md
  - README.md (no matches)

Session (temporary)
  <none>

1 matched file in use
- /projects/main/AGENTS.md (0.0% of context window)

コンテキストに追加されていることを確認できました。
では、先ほどと同じようにプロンプトを入力してみましょう。

> おはようございます。

> おはようございます！何かお手伝いできることはありますか？

全て日本語で返答してくれていることが確認できました。

6. 要件定義書と設計書の格納

要件定義書と設計書は事前に別途作成しておきます。要件定義書と設計書はdocディレクトリ配下に格納します。ディレクトリはプロジェクトルート配下ならどこでも良いので、わかりやすい名前をつけておきましょう。今回は以下のような構成にしておきます。designフォルダ配下の設計書が、requrementsフォルダ配下の要件定義書の要件をどれぐらい満たしているのかをレビューし、実行計画を立てて、計画に基づき修正するところまでKiro CLIに行ってもらいます。

doc
├── design
│   ├── ARCHITECTURE_DOCUMENT.md # システム構成、アーキテクチャ図など
│   └── DESIGN_DOCUMENT.md       # 画面遷移図、画面項目定義、テーブル定義など
└── requrements
    └── REQUREMENTS.md           # 要件定義書

7. Custom Agent「設計書レビューエージェント」の作成

Cutom Agentの作成は/agent genereteのスラッシュコマンドを利用すると簡単に作成できます。このコマンド実行すると対話的にエージェントを作成でき、最後にGNU nanoが起動して詳細な設定を行うことができます。

> /agent generate

✔ Enter agent name:  · design-review
✔ Enter agent description:  · 設計書が要件定義書を満たしているかをレビューするエージェントです
✔ Agent scope · Local (current workspace)
Select MCP servers (use Space to toggle, Enter to confirm): 

✓ Agent 'design-review' has been created and saved successfully!

Agent scopeとして「Local」を選択しているので、
.kiro/agentsディレクトリの配下にCustom Agentの設定ファイルが配置されおります。
中身を見てみましょう。

{
  "name": "design-review",
  "description": "設計書が要件定義書を満たしているかをレビューするエージェントです",
  "prompt": "あなたは設計書レビューの専門家です。あくまでレビュアーなのでドキュメントの修正は行わないでください。設計書が要件定義書の内容を適切に満たしているかを分析し、評価してください。\n\n主な評価観点：\n- 要件定義書で定義された機能要件が設計書に反映されているか\n- 非機能要件（性能、セキュリティ、可用性など）が適切に考慮されているか\n- 設計の整合性と完全性\n- 実装可能性と技術的妥当性\n- 不足している要素や改善点の特定\n\n分析結果は具体的で建設的なフィードバックとして提供してください。",
  "mcpServers": {},
  "tools": [
    "*"
  ],
  "toolAliases": {},
  "allowedTools": [],
  "resources": [
    "file://AGENTS.md",
    "file://README.md",
    "file://doc/**/*.md"
  ],
  "hooks": {},
  "toolsSettings": {},
  "useLegacyMcpJson": false,
  "model": null
}

今回はresourcesに修正を加えております。resourcesではCustom Agentに読み込ませるコンテキストを指定することができます。要件定義書や設計書をdocディレクトリ配下に格納するため、このディレクトリを追加しております。
promptを確認すると、Custom Agentに対する詳細な指示が自動で追加されていることをがわかります。独自の指示をpromptに追加することもできます。例えば、レビュー観点のリストを追加したい場合は、promptに追加するとよいです。

8. ディレクトリ構造の確認

ここまでで必要な設定が完了しました。プロジェクト内のディレクトリ構成とファイルを確認してみましょう。以下のようになっております。

project
├── .kiro
│   └──agents
│       └── design-review.json       # Custom Agentの設定ファイル
├── AGENTS.md                        # AIコーディングエージェント向けの指示
└── doc
    ├── design
    │   ├── ARCHITECTURE_DOCUMENT.md # システム構成、アーキテクチャ図など
    │   └── DESIGN_DOCUMENT.md       # 画面遷移図、画面項目定義、テーブル定義など
    └── requrements
        └── REQUREMENTS.md           # 要件定義書

9. タスクフローの実行

では、上述したタスクフローの通りに処理を実行させてみます。

設計書レビューエージェントにレビューを行ってもらう

Kiro CLIを起動し、/agent swapのスラッシュコマンドを使って、設計書レビューエージェントに切り替えます。

> /agent swap

 Choose one of the following agents 
  kiro_planner
❯ design-review
  kiro_default

✔ Choose one of the following agents · design-review

[design-review] >

次にレビューを行うように指示を出します。

[design-review] > 設計書のレビューを行ってください。

下記がレビュー結果になります。
非機能要件と運用要件に対する設計が甘いようです。

設計書のレビュー結果

 📋 設計書レビュー結果
 ✅ 優秀な点要件定義との整合性
管理者機能・利用者機能の全要件が設計書に適切に反映
APIエンドポイントが要件定義と完全に一致
画面遷移図で両ユーザータイプの機能が明確に分離
技術設計の完成度
9テーブルの正規化されたER図
37のAPIエンドポイントの詳細仕様
JWT認証・bcryptハッシュ化のセキュリティ設計
PostgreSQL + Node.js + Reactの適切な技術選択
実装可能性
具体的なディレクトリ構造とファイル配置
テスト戦略（77%+カバレッジ目標）
Docker環境での開発・テスト環境構築

 ⚠️ 改善が必要な点非機能要件の不足

【重要度: 高】
性能要件（レスポンス時間、同時接続数）の明記なし
可用性要件（稼働率、ダウンタイム許容値）の定義なし
容量設計（想定利用者数、書籍数、データ増加率）の記載なし
セキュリティ設計の詳細不足

【重要度: 高】
パスワードポリシー（複雑度、有効期限）の定義なし
セッション管理（タイムアウト、同時ログイン制御）の詳細なし
監査ログ（操作履歴、アクセスログ）の設計なし
データ暗号化（保存時、通信時）の方針なし
エラーハンドリング設計の不備

【重要度: 中】
システム障害時の復旧手順が不明
データ整合性エラー時の対処方法なし
外部依存（DB接続失敗等）のフォールバック戦略なし
運用・保守設計の不足

【重要度: 中】
バックアップ・リストア手順の詳細なし
システム監視（メトリクス、アラート）の設計なし
ログローテーション・保存期間の方針なし
障害対応・エスカレーション手順なし

 🔧 具体的な改善提案非機能要件の追加
レスポンス時間: 95%のリクエストが2秒以内
同時接続数: 100ユーザーまで対応
稼働率: 99.5%以上（月間ダウンタイム3.6時間以内）
セキュリティ強化
パスワード: 8文字以上、英数字記号混在必須
セッション: 15分無操作でタイムアウト
監査ログ: 全CRUD操作の記録・90日保存
運用設計の詳細化
日次自動バックアップ・30日保存
システムメトリクス監視（CPU、メモリ、DB接続数）
障害時の連絡体制・復旧手順書

 📊 総合評価

項目
評価
コメント


機能要件適合性
⭐⭐⭐⭐⭐
要件を完全に満たす設計

技術的妥当性
⭐⭐⭐⭐⭐
適切な技術選択と実装可能な設計

設計の完全性
⭐⭐⭐⭐
基本設計は完備、運用面で不足

セキュリティ
⭐⭐⭐
基本対策あり、詳細化が必要

実装可能性
⭐⭐⭐⭐⭐
具体的で実装しやすい設計

総合評価: 4.2/5.0 - 優秀な設計書だが、非機能要件と運用設計の強化で完璧になる

 🎯 推奨アクション即座に対応: 非機能要件（性能・可用性）の定義
短期対応: セキュリティポリシーの詳細化
中期対応: 運用・保守手順書の作成
長期対応: 拡張性を考慮したアーキテクチャの見直し
この設計書は実装に十分な品質を持っていますが、上記改善により本格運用に耐える完全な設計書になります。

項目	評価	コメント
機能要件適合性	⭐⭐⭐⭐⭐	要件を完全に満たす設計
技術的妥当性	⭐⭐⭐⭐⭐	適切な技術選択と実装可能な設計
設計の完全性	⭐⭐⭐⭐	基本設計は完備、運用面で不足
セキュリティ	⭐⭐⭐	基本対策あり、詳細化が必要
実装可能性	⭐⭐⭐⭐⭐	具体的で実装しやすい設計

Plan Agentに計画を立ててもらう

次にPlan Agentに修正計画を立ててもらいましょう。
上記レビュー結果が表示されているセッションでそのままShift + tabを押してPlan Agentに切り替えます。セッションにレビュー結果が出力されているので、特に追加のコンテキストを渡すことなく、簡単にPlan Agentに指示を出せます。

[design-review] > 
Switching to the Kiro [plan] agent.
Transform any idea into fully working code. What do you want to build today?

[plan] >

では、Plan Agentに計画を立ててもらいましょう。
Plan Agentに指示を出すとAgent側からいくつか質問が来ます。それに回答していきましょう。
回答形式は1=a,2=b,3=bのようになっております。追加で質問されることもあり、今回は合計9つの質問に回答しました(追加された質問は割愛します)。

[plan] > レビュー結果に基づいて設計書を修正する計画を立ててください。

> 設計書修正の計画を立てさせていただきます。まず、現在の状況を確認させてください。

## 📋 現状理解

レビュー結果に基づいて、図書館管理システムの設計書を修正したいということですね。主な修正対象は：
- 非機能要件の追加
- セキュリティ設計の詳細化
- エラーハンドリング設計の強化
- 運用・保守設計の追加

## 🔍 要件確認のための質問

修正計画を適切に立てるため、以下について教えてください：

[1]: この設計書修正の優先度と制約はどのようなものですか？
a. 緊急対応 - 1週間以内に完成版が必要
b. 通常対応 - 2-3週間で段階的に修正
c. その他 - 具体的なスケジュール要件を教えてください

[2]: 修正作業のリソースと体制について教えてください
a. 個人作業 - 一人で全ての修正を実施
b. チーム作業 - 複数人で分担して修正
c. その他 - 具体的な作業体制を教えてください

[3]: 特に重点的に修正したい領域はありますか？
a. セキュリティ強化 - 本格運用に向けたセキュリティ設計
b. 運用設計 - 保守・監視体制の整備
c. 全領域均等 - レビュー指摘事項を全て同等に対応
d. その他 - 特定の重点領域があれば教えてください

(チャットで回答例: "1=b, 2=a, 3=a" のように答えてください)

[plan] > 1=a,2=b,3=b

質疑応答の後に実装計画が出力されます。
実際に出力された計画は以下の通りです。こちらの注意点なのですが、Plan Agentは読み取り専用のエージェントなので、「ファイル」として出力することはできないです。
もし計画をファイルに取っておきたい場合は、自分でファイルとして保存しておく必要があります。

修正計画

 📋 実装計画 - 図書館管理システム設計書修正
 問題定義
レビュー指摘事項（非機能要件、セキュリティ、エラーハンドリング、運用設計の不足）を1週間で完全修正し、本格運用可能な設計書を完成させる。

 要件まとめ

期限: 1週間以内の緊急対応

体制: 技術者+運用担当の混成チーム、役割別分担

重点: 保守・メンテナンス中心の運用設計

成果物: 修正された設計書（Markdown形式）

品質: 妥協なしの完全版

 背景
現在の設計書は機能要件と基本技術設計は優秀（4.2/5.0評価）だが、本格運用に必要な非機能要件と運用設計が不足している。

 提案ソリューション
役割別分担による並行作業で、技術者が非機能・セキュリティ設計を、運用担当が運用・保守設計を担当し、1週間で完全版を完成させる。

 タスク分解
Task 1: プロジェクト準備とベースライン確立
現在の設計書をMarkdown形式で構造化
修正対象セクションの洗い出しと優先順位付け
チーム内での作業分担とスケジュール確定
共有リポジトリ・作業環境の準備

Demo: 修正用の構造化された設計書テンプレートと作業計画書
Task 2: 非機能要件設計（技術者担当）
性能要件（レスポンス時間、同時接続数、スループット）の定義
可用性要件（稼働率、ダウンタイム許容値、復旧時間）の設定
容量設計（想定利用者数、データ増加率、ストレージ要件）の策定
拡張性要件（将来の機能追加、負荷増加への対応）の検討

Demo: 具体的な数値目標を含む非機能要件仕様書
Task 3: セキュリティ設計詳細化（技術者担当）
認証・認可ポリシー（パスワード複雑度、セッション管理）の詳細化
データ保護設計（暗号化方式、キー管理、個人情報保護）の策定
監査ログ設計（記録対象、保存期間、アクセス制御）の作成
脆弱性対策（入力検証、SQLインジェクション、XSS対策）の強化

Demo: 包括的なセキュリティ設計仕様とチェックリスト
Task 4: 運用・保守設計（運用担当担当）
日常運用手順（起動・停止、ヘルスチェック、ログ確認）の作成
バックアップ・リストア手順（自動化、検証、復旧テスト）の詳細化
障害対応手順（障害分類、エスカレーション、復旧手順）の策定
メンテナンス計画（定期保守、アップデート、容量管理）の作成

Demo: 実行可能な運用手順書とチェックリスト一式
Task 5: 監視・アラート設計（運用担当担当）
システム監視項目（CPU、メモリ、ディスク、ネットワーク）の定義
アプリケーション監視（レスポンス時間、エラー率、セッション数）の設計
アラート設定（閾値、通知先、エスカレーション）の策定
ログ管理（収集、保存、ローテーション、分析）の設計

Demo: 監視ダッシュボード設計とアラート設定仕様
Task 6: エラーハンドリング・例外処理設計（技術者担当）
システム例外処理（DB接続失敗、外部API障害）の設計
ユーザーエラー処理（入力検証、権限エラー）の標準化
障害時フォールバック機能（縮退運転、代替処理）の設計
エラーログ・通知機能（分類、重要度、通知方法）の詳細化

Demo: 包括的なエラーハンドリング仕様と実装ガイド
Task 7: 設計書統合とレビュー
各担当者の作業成果を統合し、設計書を完成
内部レビューによる整合性・完全性の確認
不足項目・矛盾点の洗い出しと修正
最終版の品質チェックと承認

Demo: レビュー完了した完全版設計書（本格運用対応）
この計画で1週間以内に本格運用可能な完全版設計書が完成します。計画はいかがでしょうか？調整が必要な部分があれば教えてください。

修正計画に基づいて設計書を修正してもらう

次に設計書の修正に移ります。Shift + tabでPlan Agentから抜けることもできますが、抜けた先は元いたCustom Agentである設計書レビューエージェントなので、設計書の修正はできません。よって、今回は/agent swapを利用してKiro CLIのデフォルトエージェントに切り替えます。

[plan] > /agent swap

 Choose one of the following agents 
  kiro_planner
  design-review
❯ kiro_default

✔ Choose one of the following agents · kiro_default

>

では、デフォルトエージェントに実装計画に基づいた修正を行ってもらいましょう。
実装計画も同一セッション内であれば特にコンテキストを追加することなく修正指示を出すことができます。

> 実装計画に基づいて、設計書を修正してください。

------------中略------------

### 🎯 達成した要件

- ✅ 1週間以内の緊急対応 - 1日で完全版を完成
- ✅ チーム作業対応 - 技術者・運用担当の役割別分担設計
- ✅ 運用設計重点 - 保守・メンテナンス中心の詳細設計
- ✅ 妥協なしの完全版 - 本格運用に必要な全要素を網羅

この修正により、図書館管理システムは本格運用に向けた完全な設計書を持つことになりました。運用チームは即座に手順書を使用して運用準備を開始でき、開発チームは包括的な設計に基づいて実装を進めることができます。

修正箇所は多岐にわたるため、一部の項目だけを掲載します。
要件から見るとどれも妥当な修正だと思いました。

パフォーマンスに対する設計項目の追加

データベースのテーブルに対してインデックスを張る
キャッシュ戦略
ページネーション

セキュリティに対する設計項目の追加

認証/認可フロー
入力検証・サニタイゼーション

運用設計項目の追加

CI/CDパイプライン
バックアップ戦略
コンテナ化によるデプロイ戦略

10. まとめ

新しく追加されたPlan Agentを利用して、設計書の品質向上を図ってみました。
Agentから質問される内容でこちらも抜けていた観点に気付かされることがあります。
計画を立てるときにはぜひ使っていきたい機能だと思いました。

デロイトトーマツグループ　エンジニアリングブログPublication

デロイトトーマツグループのエンジニアリングプロフェッショナルが最新のクラウド技術とビジネスにおけるエッジの利いた最新知見と洞察などをお届けするブログです。発信するテーマの性質上、投稿内容には発信時点の技術状況やエンジニア個人の見解が含まれることがありますので予めご了承ください。

1. はじめに

2. Plan Agentとは？

3. Custom Agentとは？

4. Plan Agentと設計書レビューエージェントのタスクフロー

5. AGENTS.mdの作成

Kiro CLIからの返答を日本語化

6. 要件定義書と設計書の格納

7. Custom Agent「設計書レビューエージェント」の作成

8. ディレクトリ構造の確認

9. タスクフローの実行

設計書レビューエージェントにレビューを行ってもらう

📋 設計書レビュー結果

✅ 優秀な点

⚠️ 改善が必要な点

🔧 具体的な改善提案

📊 総合評価

🎯 推奨アクション

Plan Agentに計画を立ててもらう

📋 実装計画 - 図書館管理システム設計書修正

問題定義

要件まとめ

背景

提案ソリューション

タスク分解

修正計画に基づいて設計書を修正してもらう

パフォーマンスに対する設計項目の追加

セキュリティに対する設計項目の追加

運用設計項目の追加

10. まとめ

Discussion