このシリーズ記事一覧
- kiro-cli 実務活用入門 ― agent / context＆compact / save＆load / todoをどう使い分けるか ―
- agentとcontextの違いと設計思想（今回）
- kiro-cliのはじめ方（近日公開）
- チーム運用ルール設計
※第１回を先に読むとより理解が深まります。
要点サマリー
- kiro-cli は「コマンド補助」ではなく 思考と作業の前提を構造化・外部化するためのCLI
- kiro-cli には agent / knowledge / context という役割の異なる3つの仕組みがある
- この3つは似ているが、設計思想と役割は明確に異なる
- 混同すると、再現性が失われ、作業が積み上がらなくなる
- 正しく使い分けることで、kiro-cli を 実務で破綻しない作業基盤として使える
※ 混同したまま使うと「便利だけど、あとで自分が一番困るツール」になります。
対象読者
- kiro-cli を使い始めたばかりの方
- agent /knowledge / context を何となく使っている方
- kiro-cli を実務で再利用可能な形にしたい方
はじめに
こんにちは！Dirbatoの社内技術横断支援組織Backbeatに所属している柴田です！
さて、みなさんが大好き（なはず！）のkiro-cliを触っていて、こんな違和感はありませんか？
（※「好き」と言いつつ、たまに「きみ（kiro-cli）さぁ…前回も言ったけど覚えてる？」と、AI相手に謎の説教をしてしまう瞬間、ありますよね、きっと）
- agent に何を書けばいいのか毎回迷う
- knowledge に入れた情報が、なんだかコンビニレシートまで混ざって検索結果に出てくる
- context に情報を入れすぎて会話が重量級になり、レスが筋トレレベル
- いろんな設定を試せば試すほど「正解」が霧のように消える
※弊社生成AIに作成させた「kiro-cliとケンカしている私」のイメージ図です。
多くの場合、その原因は
agent・knowledge・context を「なんとなく」で使っていることにあります。
この3つは似ているようで、設計思想はまったく別です。
混同したまま使うと、kiro-cli は次第に
- 再現性がなくなり
- 作業が積み上がらず
- 属人化した便利ツール
になっていきます。
本記事では、kiro-cli を 実務で破綻させないために最も重要なポイントである「agent・knowledge・context の違い」について、設計視点で整理します。
1. 一言で整理すると何が違うのか
まず結論です。
- agent：規律に厳しいプロジェクトマネージャー（手順とルールの番人）
- knowledge：物知りな司書（引き出しは多いが、整理しないとカオス化）
- context：現場を走り回る情報屋（その日の噂や最新のバグ情報を持ってくるが、翌日には忘れる）
| 観点 | agent | knowledge | context |
|---|---|---|---|
| 時間軸 | 永続（セッションを跨ぐ） | 永続（蓄積型） | 一時（会話中のみ） |
| 変更頻度 | 低い | 中程度 | 高い |
| スコープ | プロジェクト／チーム | プロジェクト／ドメイン | タスク／会話 |
| 目的 | 再現性の担保 | 知識の蓄積・検索 | 柔軟な対話 |
| 検索性 | なし | あり（セマンティック検索） | なし |
👉 agent は土台、ナレッジベースは図書館、context は載せ替える荷物
※ 土台（agent）がグラグラで、図書館（ナレッジベース）が散らかったまま荷物（context）を積むと、だいたい途中で崩れます。
2. agent の本質：能力・権限・動作ルール
agent は「プロジェクトマネージャー」的存在です。
常に守るべき前提条件を定義し、それを崩さないことに価値があります。
agent に入れるもの
- プロジェクト共通の動作ルール
- セキュリティ・権限に関わる設定
- 使用可能なツールの制限
- 基本的なリソース（変更頻度が低いもの）
（もしプロジェクトマネージャーが毎朝にプロジェクトルールを変えたら、現場は大混乱しますよね？）
{
"description": "設計レビュー専用エージェント",
"resources": [
"file://docs/review-guidelines.md"
],
"allowedTools": ["fs_read", "knowledge"],
"toolsSettings": {
"fs_read": {
"allowedPaths": ["./docs/**", "./src/**"]
}
}
}
👉 agent は「頻繁に変えない」こと自体が価値
3. knowledgeの本質：蓄積・検索可能な知識
knowledgeは「図書館の司書」です。何でも覚えてくれますが、棚の整理を怠ると本探しに半日かかります。
ナレッジベースに入れるもの
- プロジェクトドキュメント（仕様書、設計書）
- コードベース（実装パターン、ライブラリ使用例）
- 過去のトラブルシューティング記録
- チーム内のナレッジ・ベストプラクティス
※ ゴミ箱化したknowledgeは、技術書の間にスーパーのチラシやレシートが紛れて出てくる状態です。
以下はサンプルコマンドです。本番環境に適用する前に必ずテスト環境で動作確認してください。
**プロジェクトドキュメントを追加**
/knowledge add -n "project-docs" -p ./docs --include "**/*.md"
**コードベースを追加（ビルド成果物は除外）**
/knowledge add -n "source-code" -p ./src --exclude "**/target/**" --exclude "**/node_modules/**"
【メリット】
- セマンティック検索：自然言語で関連情報を発見
- エージェント間共有：各エージェントが独立したナレッジベースを持つ
- 永続化：セッションを跨いで知識が蓄積
【デメリット】
- インデックス時間：大量ファイルの初回処理に時間がかかる
- リソース消費：検索処理でCPU・メモリを使用
- 更新管理：ファイル変更時の手動更新が必要
👉 「後で検索したい情報」はknowledge（ナレッジベース）へ
4. context の本質：一時的・動的な前提情報
contextは「現場情報屋」。その場限りの情報を持ってきますが、翌日は忘れるタイプ。
context に入れるもの
- 今回のタスク内容
- その場限りの制約
- ログ・エラー・検討メモ
今回レビューするのは認証基盤で、
OAuth2.0 + Cognito を採用予定です。
👉 次のセッションでは不要になる情報
5. 混同すると起きる典型的な破綻パターン
パターン①：agentに一時情報を詰め込む
→ 「ルールは金曜のみ昼休み2時間」に設定され、永遠に変わらず現場が飢える。
パターン②：knowledgeをcontext代わりに使う**
→ 図書館に昨日の昼食メニューが残り続け、技術書検索で「カレーライス」がヒットする惨状。
パターン③：contextに永続情報を毎回入れる**
→ 毎朝「これはプロジェクト共通のルールです」と伝え続ける、ひたすら丁寧すぎる情報屋。
👉 3回以上使う情報は agent またはknowledgeへ
6. 実務フェーズ別の正しい使い分け
要件定義フェーズ
- agent：要件テンプレート、権限設定
- knowledge：過去案件の要件書、業界知識
- context：今回の案件概要、期間、制約条件
設計レビューフェーズ
- agent：レビュー手順、使用ツール制限
- knowledge：設計ガイドライン、過去レビュー結果
- context：今回レビュー対象、論点
実装支援フェーズ
- agent：コーディング規約、セキュリティ設定
- knowledge：実装パターン、ライブラリドキュメント
- context：発生中のエラー、該当コード
トラブルシューティングフェーズ
- agent：調査手順、アクセス権限
- knowledge：過去障害事例、解決方法
- context：現在の症状、ログ、環境情報
7. 図解で理解する agent / knowledge / context / save / todo
👉 agent（土台） を固定し、knowledge（図書館）を充実させると、下流（作業）が安定する！
8. 迷ったときの判断基準まとめ
agent に入れる判断基準
- 何度も使う動作ルール？ → agent
- プロジェクト共通の権限設定？ → agent
- 変更頻度が低い基本リソース？ → agent
knowledge に入れる判断基準
- 後で検索したい情報？ → knowledge
- プロジェクトで蓄積すべき知識？ → knowledge
- 大量のドキュメント・コード？ → knowledge
context に入れる判断基準
- 今回だけの情報？ → context
- 頻繁に変わる情報？ → context
- 会話の流れで生まれた情報？ → context
9. 実装例：3つを組み合わせた設計レビューエージェント
{
"description": "設計レビュー専用エージェント",
"allowedTools": ["fs_read", "knowledge"],
"resources": [
{
"type": "knowledgeBase",
"source": "file://./docs",
"name": "プロジェクトドキュメント",
"include": ["**/*.md", "**/*.pdf"]
},
{
"type": "knowledgeBase",
"source": "file://./past-reviews",
"name": "過去レビュー事例"
}
],
"toolsSettings": {
"fs_read": {
"allowedPaths": ["./current-design/**"]
}
}
}
使用時の流れ：
- agent：レビュー手順と権限を定義
- knowledge：過去事例とガイドラインを自動検索
- context：今回の設計書とレビュー観点を追加
まとめ
- agent = 厳格なPM
- knowledge = 物知り司書
- context = 現場情報屋
この3人を適切に配置すると、プロジェクトは安定します。逆に役割を混同すると、PMがスーパーのレシートを抱えて会議に現れ、昨日のお昼のカレーの指摘をするようなカオスな状況がうまれます。
特にknowledgeは、チームの知識を資産化する強力な機能です。
正しく活用することで、属人化を防ぎ、チーム全体の生産性向上につながります。
今回の内容は「agent・knowledge・context」の役割と設計運用に特化した解説でした。
kiro-cliそのものの基本思想や他機能の概要は、第1回にまとめています。
👉 第1回: kiro-cli 実務活用入門 ― agent / context＆compact / save＆load / todoをどう使い分けるか ―
次回予告
- kiro-cliのはじめ方
※劣後してしまいましたが、インストール方法などを解説したいと思います！