Kiro CLI 設定ガイド
1. 設定スコープの概要
Kiro CLI は、開発スタイルやチーム標準に合わせて柔軟に設定できます。
設定は以下の 3 つのスコープ で管理されます。
| スコープ | 説明 | パス |
|---|---|---|
| グローバル | すべてのプロジェクトに適用 | <user-home>/.kiro/ |
| プロジェクト | 特定プロジェクト専用 | <project-root>/.kiro/ |
| エージェント | エージェント定義ごとの設定 | <user-home or project-root>/.kiro/agents/ |
2. 設定ファイルの配置一覧
2.1 グローバル / プロジェクト共通項目
| 設定項目 | グローバルスコープ | プロジェクトスコープ |
|---|---|---|
| MCP サーバー | ~/.kiro/settings/mcp.json | .kiro/settings/mcp.json |
| プロンプト | ~/.kiro/prompts/ | .kiro/prompts/ |
| カスタムエージェント | ~/.kiro/agents/ | .kiro/agents/ |
| ステアリング | ~/.kiro/steering/ | .kiro/steering/ |
| CLI 設定 | ~/.kiro/settings/cli.json | ― |
3. 各スコープで設定可能な項目
| 設定項目 | ユーザースコープ | プロジェクトスコープ | エージェントスコープ |
|---|---|---|---|
| MCP サーバー | Yes | Yes | Yes |
| プロンプト | Yes | Yes | No |
| カスタムエージェント | Yes | Yes | N/A |
| ステアリング | Yes | Yes | Yes |
| CLI 設定 | Yes | N/A | N/A |
4. 設定競合の解決ルール
設定が複数スコープで定義されている場合、
Kiro CLI とやり取りしている場所に最も近いスコープが優先 されます。
例
- グローバルとプロジェクトの両方に
mcp.jsonが存在する - プロジェクトフォルダ内で Kiro CLI を使用している
→ プロジェクト側の設定が適用される
5. エージェント設定との競合
カスタムエージェントはグローバルおよびプロジェクトスコープで定義可能です。
ただし、同じレベルでエージェント設定と競合した場合は、エージェント設定が優先 されます。
6. 優先順位一覧
| 設定項目 | 優先順位 |
|---|---|
| MCP サーバー | Agent > Project > Global |
| プロンプト | Project > Global |
| カスタムエージェント | Project > Global |
| ステアリング | Project > Global |
7. MCP サーバーの特記事項
MCP サーバーは 3 つのスコープすべてで設定可能です。
さらに、エージェント設定には includeMcpJson オプションが存在するため、
MCP の読み込みはやや特殊な挙動を持ちます。
詳細は MCP サーバーの読み込み優先順位仕様 を参照してください。
まとめ
- 設定は「近いスコープほど強い」
- エージェント設定は最上位優先になる場合がある
- MCP サーバーのみ特別扱いがある
構造を理解しておかないと、意図しない設定が有効になる可能性があります。
特にチーム開発では、プロジェクトスコープの定義を明示的に管理することが重要です。