AWS
Kiro ベストプラクティス
仕様書(Spec)から実装まで進める Kiro の IDE・CLI・Web について、Spec、ステアリング、Hooks、カスタムエージェント、権限の使い方を整理しています。
2026-11-02 に公式ドキュメント(kiro.dev/docs)と照合済み
最新アップデート
ニュースに収録済みの直近3件です。全件はニュースから確認できます。
2026-10-30Kiro CLI v2.37.0〜v2.37.1 — V3 セッション開始時に V2 形式のエージェントを既定で自動アップグレード
挙動変更: V3 セッションを始めると、V2 形式のエージェントが既定で自動アップグレードされます。変換前に各ファイルの .json.bak バックアップを保存。V2 のまま残すには chat.enableAutoAgentUpgrade を false にします。
サインアウト状態で kiro-cli acp を起動すると、対応する ACP クライアントに「Log in to Kiro」が表示されるように。ニュースを読む
2026-10-29Kiro CLI v2.35.0〜v2.36.0 — 日常的な操作を自動で承認する「Approve for me」、root での起動時に警告
対話型の V3 セッションに「Approve for me」を追加。日常的な操作は Kiro が承認し、リスクの高い操作はブロック、判断に迷う場合は確認します(既存の deny / ask / allow ルールが優先)。/permissions → Policies で有効にし、ワークスペース単位で保存されます。
セキュリティ: root / Administrator で起動したときに警告を表示。V3 セッションが組織の MCP サーバーや Web 検索の設定に従うように。ニュースを読む
2026-10-23Kiro IDE v1.4.26・CLI v2.34.0 — Workflows の起動頻度を選ぶ設定、解析できないシェルコマンドを拒否
チャット内で Kiro が Workflows を起動する頻度を選べるように(CLI は「Only when asked」「Only for large tasks」「As much as possible」)。MCP ツールがフォームなどで追加の入力を求められるように(MCP elicitation)。
挙動変更: V3 は解析できないシェルコマンドを拒否するように。サブエージェントは親エージェントがインラインで宣言した MCP サーバーを引き継がなくなりました。ニュースを読む
概要
- AWS 製。IDE(VS Code ベース)、CLI(
kiro-cli)、Web で使える - 要件 → 設計 → タスクの仕様書(Spec)を作ってから実装を進める
- ステアリングファイル(
.kiro/steering/)でプロジェクトの知識を渡す。AGENTS.md も読み込む - Hooks は JSON ファイルで定義し、ファイル保存やツール実行などをきっかけに動く
- 権限は capability ごとのルール(deny / ask / allow / evaluate)で管理
ベストプラクティス 8
- 新機能は Spec から始め、要件と設計をレビューしてから実装させる
- Spec はコードと同じリポジトリで管理し、仕様と実装のずれを防ぐ
- ステアリングは product / tech / structure の3ファイルを基本にする
- 特定のファイルにだけ必要な指示は
fileMatchで範囲を絞る - 危険な操作は Hooks(PreToolUse)と権限の deny ルールで止める
- 本番環境の削除や書き込みにつながる権限はエージェントに渡さない(IAM ロールは最小権限に)
- 信頼していないリポジトリは対話型 V3 で信頼しないまま開き、中身を確認してから信頼する(非対話の実行や V1 / V2 では信頼の確認がない)
- 使うモデルは明示的に選ぶ(モデルの提供終了後も自動では切り替わらない)
Spec(仕様書)
作りたいものを要件・設計・タスクの3つのファイルに分けて書き出し、それに沿って実装を進めます。
013つのファイルと進め方
| ファイル | 内容 |
|---|---|
requirements.md(バグ修正なら bugfix.md) | ユーザーストーリーと受け入れ条件。バグ修正では現在の動作・期待する動作・変えない動作 |
design.md | 技術的な構成・シーケンス図・実装上の考慮点 |
tasks.md | 実装のタスク一覧。進行中・完了がリアルタイムで更新される |
- 種類は、新機能向けの Feature Spec、バグ修正向けの Bugfix Spec、承認を挟まず3つを一度に作る Quick Spec
- すべてのタスクを実行すると、依存関係から独立したタスクをまとめて並列に実行します
出典: Specs
ステアリング
プロジェクトの目的や技術スタックなどを Markdown で書いておき、毎回の会話に読み込ませる仕組みです。CLAUDE.md にあたります。
01基本の3ファイルと置き場所
.kiro/steering/
product.md # プロダクトの目的・対象ユーザー・目標
tech.md # 技術スタック・ツール
structure.md # ファイル構成・命名などの決まり
- この3ファイルは既定ですべての会話に読み込まれます
- 全体用は
~/.kiro/steering/。ワークスペースと全体で矛盾した場合はワークスペースが優先 AGENTS.md(ワークスペースのルート・サブディレクトリ・~/.kiro/steering/)も常に読み込まれます
02読み込むタイミングの指定(inclusion)
---
inclusion: fileMatch
fileMatchPattern: "components/**/*.tsx"
---
# React コンポーネントの決まり
- 関数コンポーネントで書く
| inclusion | 読み込まれるとき |
|---|---|
always(既定) | すべての会話 |
fileMatch | パターンに一致するファイルを扱うとき |
manual | チャットで #ファイル名 と指定したとき |
auto | 依頼が説明に合うとき(name と description が必要) |
フロントマターはファイルの先頭に置き、前に空行を入れません。AGENTS.md ではこの指定は使えません。CLI V1 / V2 では always のファイルだけが自動で読み込まれます(fileMatch・manual は対象外)。
出典: Steering
Hooks
ファイルの保存やツールの実行などをきっかけに、シェルコマンドを実行したりエージェントに指示を追加したりする仕組みです。
01Hook ファイルの書き方
// .kiro/hooks/lint-on-save.json
{
"version": "v1",
"hooks": [
{
"name": "lint-on-save",
"trigger": "PostFileSave",
"matcher": "\\.ts$",
"action": { "type": "command", "command": "npm run lint" },
"timeout": 30,
"enabled": true
}
]
}
- ワークスペースの
.kiro/hooks/に置く JSON ファイル(ファイル名は自由)。CLI V3 は~/.kiro/hooks/の全体用 Hook も読み込みます action.typeは"command"(シェルコマンド)か"agent"(promptを会話に追加)timeoutの既定は60秒。Agent Stop トリガーの command Hook だけは、confirmで実行前に確認させられます(confirmCommandで確認内容を動的に変えることも可)
02トリガーの種類
| トリガー | タイミング | 使える場所 |
|---|---|---|
| Prompt Submit | プロンプト送信時(CLI ではブロック不可) | IDE・CLI |
| Agent Stop | エージェントが応答を終えたとき | IDE・CLI |
| Session Start / Session End | セッションの開始 / 終了(End は CLI V3 のみ) | IDE・CLI V3 |
| Pre Tool Use | ツールを呼ぶ前。ツールの使用を検証してブロックできる | IDE・CLI |
| Post Tool Use | ツールを呼んだ後(結果を参照できる) | IDE・CLI |
| File Create / File Save / File Delete | エージェントがファイルを作成・保存・削除したとき(人の操作では動かない) | IDE・CLI V3 |
| Pre / Post Task Execution | Spec のタスクの実行前 / 後 | IDE・CLI V3 |
ほかに CLI 2.x の agentSpawn(V3 でも別名として使える)があります。Manual の Hook は CLI V3 で一覧に出ますが /hooks から実行できず、IDE では 0.x で作った旧 Hook だけが残っています(新しく作る場合は manual のステアリングを使う)。ブロックの具体的な方法は公式ドキュメントの「Hook triggers」「Hook actions」で確認してください。
出典: Hooks · Hook triggers
カスタムエージェント
01定義ファイル
- JSON または Markdown で書けます(使える項目は同じ)
- プロジェクト用:
.kiro/agents/<name>.jsonまたは.md(ワークスペースを信頼している場合だけ読み込まれる)。全体用:~/.kiro/agents/。同じ名前ならプロジェクト側が優先 - 主な項目:
name・description・prompt・model・tools・excludedTools・resources(skill://参照を含む)・permissions - IDE と CLI ではメインのエージェントとして選べます。Web はプロジェクトのエージェントをサブエージェントとしてだけ使います
- CLI 2.x の
allowedToolsなどを使った定義は、V3 では/upgrade-agentで変換が必要です
出典: Custom agents
権限とワークスペースの信頼
approval_policy: "on-request" を本番の必須設定にする」と書いていましたが、これは Codex の設定で、Kiro にはありません。Kiro は下のルールで権限を管理します。01capability ごとのルール
- ルールは capability(
fs_read・fs_write・shell・web_fetch・mcp・sandbox_networkなど)・パターン・効果(deny/ask/allow/evaluate)で書きます - ルールが衝突したときは deny → ask → allow → evaluate の順に優先されます
- 全体のルールは
~/.kiro/settings/permissions.yaml、ワークスペースごとのルールは~/.kiro/workspace-roots/の下に保存されます(リポジトリには入らない) - 確認の画面で「Always allow」「Always deny」を選ぶと、全ワークスペース・このワークスペース・このセッションのどれかにルールとして保存されます
- IDE では Settings → Agent → Agent Autonomy(
kiroAgent.agentAutonomy)で Autopilot(許可された操作は確認なし)と Supervised(毎回確認)を切り替えます - ヘッドレス実行では、ask は deny として扱われます
02ワークスペースの信頼と Approve for me
- ワークスペースを信頼するまでは、そのワークスペースのカスタムエージェント・ステアリング・MCP 設定・Skills・Workflows は読み込まれません(CLI では hooks と言語サーバーの設定も)
- 確認画面が出るのは、Kiro CLI 2.33 以降の対話型の V3 セッションだけです。非対話の実行(
--no-interactive)や V1 / V2 のセッションは、確認なしでワークスペースの設定を読み込みます。--trust-workspaceはその1回の起動だけ信頼します。ホームディレクトリの信頼は保存されず、毎回確認されます - 「Approve for me」(
approve-for-meプリセット)は、ワークスペース内の編集と読み取り専用のシェルを許可し、その他は Kiro が判断します。CLI V3 では/permissionsで有効にします
出典: Permissions
モデルと設定ファイル
.kiro/settings.json に "model"・"provider": "bedrock"・"region" を書く例を載せていましたが、公式ドキュメントにそのような設定はありませんでした。01モデルの選び方
- モデルはモデル選択から選びます。Auto はリクエストを各社の上位モデルに振り分けます
- 2026-11-02 時点の例: Claude(Opus 5.5・Sonnet 5.5 など)、GPT-5.6(Sol・Terra・Luna)、オープンウェイト(GLM-5 など)
- 提供条件に注意: Fable 5.1 は Kiro Enterprise の組織向けで、管理者が承認リストに入れるまで表示されません。Haiku 5.5・Kimi K3・Qwen3 Coder Next は Experimental。Kimi K3 は出力の補償対象外(Excluded Model)で、US のみ・Free プラン対象外です
- Sonnet 4.0 は 2026-10-14 に提供終了。モデルが終了しても自動では切り替わらないので、選んでいるモデルを確認してください
- Enterprise の管理者は、使えるモデルを制限できます
02CLI の設定ファイル
# 全体の設定: ~/.kiro/settings/cli.json
kiro-cli settings chat.defaultModel "<モデル名>"
# ワークスペースの設定: .kiro/settings/cli.json(全体より優先)
kiro-cli settings --workspace chat.defaultAgent "<エージェント名>"
主な設定: chat.defaultModel・chat.defaultAgent・chat.enableWorkflows・toolSearch.enabled・telemetry.enabled など。CLI V3 では、全体の設定ディレクトリを環境変数 KIRO_HOME で変えられます(CLI 2.31.0 の changelog に記載)。
出典: Available models · Settings reference · CLI 2.31 changelog
定期実行(Kiro Web の Scheduled tasks)
01仕組みと設定
- Kiro Web のサイドバーの Schedule から作成します(2026-10-28 に Automations から名称変更)。GitHub / GitLab のリポジトリに対して、決めたスケジュールでプロンプトを実行します。エージェントは自律モードで動き、変更があれば PR / MR を作ります
- 1つのタスクに最大5つのスケジュール(Hourly・Daily・CRON)を設定できます。1時間より短い間隔は指定できず、時刻は UTC です
- 対象プラン: Pro・Pro+・Pro Max・Power
- IDE と CLI からの定期実行は公式ドキュメントに記載がないため、必要なら GitHub Actions などの外部のスケジューラーから CLI を実行します(実行ユーザーの権限は最小に)
更新ログ
PreToolUse hookがupdatedInputでツール入力を書き換え可能に、権限確認時に動くPermissionRequest hookを追加(denyがallowに優先)。/copy N、自動コンパクション開始閾値compaction.autoCompactionThreshold。Kiro IDE v1.4.178〜v1.4.215: 任意のターンからチャットをフォーク、コンパクション後にスキル/steeringを再読み込み、欧州(フランクフルト)でIDEからクラウドセッション。Ctrl+]//diagram)、OAuth設定のない一部MCPサーバーへのサインイン、V2シェルコマンドがHOME/XDG_CONFIG_HOMEを設定する前に確認。3.2.1で/settingsにツール出力の表示量設定PreCompactで拒否可・PostCompactで要約を受け取る、IDEはPre/Post Compaction Hook)を追加。CLIは/usage・ステータスライン・ワークフローの各ステップにセッションのクレジット消費を表示。サブエージェントが親のMemoryを読み取り可能に。詳細はニュース参照。kiro-cliに一本化し、Classic(V1)・デスクトップアプリ・インライン補完を廃止。autocomplete/inline/translate/theme/dashboardは使用不可。--trust-all-tools付きヘッドレス実行と新規ACPクライアントもV3で起動、V2継続はkiro-cli --v2。詳細はニュース参照。.json.bakを保存、chat.enableAutoAgentUpgradeをfalseで無効化)。サインアウト中のkiro-cli acp起動時にACPクライアントから「Log in to Kiro」でサインイン可能に。KIRO_RUNTIME_DIR追加。詳細はニュース参照。/permissions→Policiesでワークスペース単位に設定)。root/Administrator起動時に警告(app.warnOnElevatedPrivilegesで無効化)、V3が組織のMCP/web_search/web_fetch設定に従うように🏢。IDE v1.4.51〜v1.4.62はWindowsシステム全体インストーラー等。詳細はニュース参照。/memoriesでCtrl+D削除・/model edit・--trust-workspaceを追加~/.kiro/workspace-roots/に保存)。V3 Workflowsは依頼時のみ起動に⚠️。詳細はニュース参照。.mdファイルをレンダリング表示し、箇所ごとにコメントしてまとめてKiroに送れる「Markdown Review」パネルを追加。Specドキュメントのレビューボタンからも利用可能。詳細はニュース参照。DEFAULT_BLOCKED(既定)・COMMON_DEPENDENCIES・DEFAULT_ALLOWEDから選択、設定は.kiro/settings/sandbox.json。CLIは/autonomous onでサンドボックス有効化の上で承認なしに進めるLocal Autonomous Modeも追加。IDEは/workflow-runで保存済みWorkflowをチャットから起動。詳細はニュース参照。/memoriesのconfigでread & write / read only / off を選択、未信頼ワークスペースでは読み取りのみ)。チャット開始時にV3への切替を案内。IDE v1.2.56でhookマッチングの柔軟化・Power検索。詳細はニュース参照。/powers install・/powers uninstallでPower(Agent Plugin形式の拡張機能)管理コマンドを追加。V3カスタム出力スタイル・セッション終了時に発火するSessionEnd Hookトリガーも追加。詳細はニュース参照。~/.kiro)が書き換えられうる。v1.0.242以降で修正済み(現行v1.1系は対象外)。詳細はニュース参照。.envファイルがチャットセッションに自動読込されなくなり、意図しない環境変数・シークレットの露出リスクを低減。V3で/tools trust-allによるセッション全体のツール一括承認に対応。セッションダッシュボードにフィルター・ソート・グループ化を統合。詳細はニュース参照。/fullscreenによるフルスクリーンチャットモードを追加(TUI/Liteセッション向け)。/modelコマンドに推論(reasoning)コントロールを統合。V3クラウドセッションがリポジトリ接続前に起動を開始できるように変更し体感速度が向上。詳細はニュース参照。/settingsから「プロンプトのみ」「プロンプト+エージェント応答」で選択可能に(ツール出力は対象外)。--v2フラグで単発セッションをV2エージェントハーネス上で実行可能(保存済み設定は上書きしない)。設定メニューのキーボード操作を統一。詳細はニュース参照。/spec runにリアルタイム進捗とタスクスコープ選択が可能なフルスクリーンのタスク実行ビューを追加、「Preserve scrollback」トグルも追加。詳細はニュース参照。mキーでトグル)。ストリーム失敗からの自動復旧機能を追加(60秒でidle watchdog警告・300秒でキャンセル、スロットリング/5xx/接続断は自動リトライ、既定60分のストリーミングタイムアウト)。api.streamIdleSoftTimeout等の設定で調整可能。v2.19.1はパッチリリース。詳細はニュース参照。AGENTS.mdに対応(従来はルート限定)。アイドル時のリソース消費削減・長時間セッションでのコンテキスト保持を改善。詳細はニュース参照。AGENTS.mdがワークスペースツリーのどこからでもsteeringコンテキストとして読み込まれるように(従来はルート限定)。詳細はニュース参照。kiro-cli --cloudでマネージドなクラウドサンドボックス上にセッションを起動できるCloud Sessionsをプレビュー公開。--repoでリポジトリ添付・切断してもエージェントは継続・--resume-idで別マシンから再開可能。セッションピッカーはクラウド/ローカルをまとめて表示。スラッシュコマンドメニューが部分一致検索に対応。詳細はニュース参照。/tangentコマンド追加。会話全体を引き継いだ側道会話に分岐し元の会話へ復帰できる。/tangent lsで会話ツリーをビジュアル一覧、/tangent rootで本流へ即復帰。/contextにツール別トークン内訳表示も追加。詳細はニュース参照。/spec newが要件起草前にユーザー入力を土台とするガイド付き説明ステップを踏むように。Plan modeで計画を承認すると手動でモード切替せずに即実行開始(⚠️挙動変更)。詳細はニュース参照。/upgrade-agentコマンド追加。V2形式のカスタムエージェント設定をV2・V3どちらでも動作する共通フォーマットへその場で変換可能(V3セッション内で実行)。中断されたモデル応答の自動リトライも追加。詳細はニュース参照。~/.kiro/hooks/を全ワークスペースに自動適用)・検索可能なセッション履歴パネルを追加。企業プロキシ環境での信頼性を改善し、中断された応答から自動復旧・MCPツールを動的に再取得するように。詳細はニュース参照。