kiroの公式ドキュメントをざっと眺めてみる

この記事は人力で書きましたが、一部機械翻訳を利用した箇所や校正/誤字脱字の修正にAI(Claude)を利用しました。

まとめ

今回参照したドキュメントはこちら。

• 基本的には触りながら試すのが一番ですが、ベストプラクティス系は一度目を通すと良いかもしれないです
  Specs
  Hooks
  Steering
  MCP（使い方）
  MCP（セキュリティ）
• とりあえず試してみたい方はLearn by Playingをやってみましょう

Get started

kiroの特徴が記載されています。

Kiro is an agentic IDE that helps you do your best work with features such as specs, steering, and hooks.
Kiroは、スペック、ステアリング、フックなどの機能を使用して最高の作業を行うのに役立つエージェントIDEです。

Installation

現在（2025/7/21）ダウンロードするためにはWishlistへの登録が必要です。インストール後、ログインが必要ですが、現在は下記認証方法が提供されています。お好きな認証方法で良いと思います。（私はBuilder IDを利用しました）

• GitHub
• Google
• AWS Builder ID
• AWS IAM Identity Center

もし既にVSCodeを利用していたら、ログイン後にVSCodeの設定や拡張機能をインポート可能です。

Language support

kiroではほとんどのプログラミング言語をサポートしているようですが、下記言語についてはベストプラクティスについてガイドがあります。
TypeScript and JavaScript
Python
Java

利用推奨の拡張機能も紹介されていますので、これらの言語を利用する場合は一読すると良いでしょう。

Your First Project

プロジェクトを開くと、kiroのチャット機能などが使えるようになります。

Set Up Steering Files

kiroの特徴機能の一つです。

Steering files provide context about your project, helping Kiro understand your codebase, conventions, and requirements.
ステアリング ファイルはプロジェクトに関するコンテキストを提供し、Kiro がコードベース、規則、要件を理解するのに役立ちます。

詳しくはSteering参照。

Build Features with Specs

これもkiroの特徴です。チャットからやりたいこと・作りたいものを入力すると、要件定義、設計を実施してから実装を行なってくれます。

この方法ではタスクリストがtasks.mdとして生成され、細かいタスク単位で実行が可能となります。

Automate Workflows with Hooks

ファイルが作成、保存、削除されたタイミングで任意の処理を実行することができます。

詳しくはHooks参照。

Extend Capabilities with MCP

MCPにも対応しています。他のMCPクライアントのようにJSONを編集したり、kiroに依頼することでMCPサーバを設定することができます。

Editor

Kiro Interface

UI面についての解説です。見た目を変更したりしたい人はこちらを参照すると良いでしょう。

Keyboard Shortcuts

kiroで使えるショートカット一覧です。

Codebase Indexing

プロジェクトを開いた時や、ファイルを変更したときにインデックスが作成され、これにより常に最新のファイルを参照した上でコード提案や実装を進めてくれるようです。

Specs

specは、ここでは仕様のことですが、kiroでは下記のようなことを提供してくれます。

• Break down requirements into user stories with acceptance criteria
  要件を受け入れ基準を含むユーザーストーリーに分解する

• Build design docs with sequence diagrams and architecture plans
  シーケンス図とアーキテクチャプランを使用して設計ドキュメントを作成します

• Track implementation progress across discrete tasks
  個別のタスクにわたる実装の進捗状況を追跡する

• Collaborate effectively between product and engineering teams
  製品チームとエンジニアリングチーム間で効果的に連携する

この機能については実際に触ってみると一番理解しやすいと思いますので、是非使ってみてください。

Concepts

kiroでは仕様駆動開発を始めると、下記ドキュメントを順に生成します。

• requirements.md：ユーザーストーリと受け入れ基準を記載（要件定義相当）
• design.md：技術アーキテクチャやシーケンス図などを記載（基本設計相当）
• tasks.md：詳細な実装タスクを記載（詳細設計相当）

また、これらのドキュメントは連続で生成されるのではなく、requirements.md生成後、ユーザによる承認を挟みます。問題がなければ次のdesign.mdを生成し、ユーザの承認後tasks.mdが生成されるという流れになります。

requirements.mdはEARS(Easy Approach to Requirements Syntax)記法という書き方で記載されるようです。EARS記法の詳しい解説は他の記事に譲るとして、下記のような書き方をするようです。

WHEN a user submits a form with invalid data
THE SYSTEM SHALL display validation errors next to the relevant fields

Best practices

既に要件がある場合

1. 要件が記載されているツール等にMCPサーバが提供されていれば、接続してインポートする
2. 手動でインポートする。kiroに要件を読ませると、そのあと設計を行う

要件や設計が更新されたら

1. 要件の更新：requirements.mdファイルを直接変更する or 最初からSpecセッションを行う
2. 設計の更新：design.mdファイル「Refine」を行う
3. タスクの更新：tasks.mdファイルの「Update tasks」を行う

チームと仕様を共有するには

バージョン管理ツールでプロジェクトリポジトリに保存する

複数チーム間で仕様を共有するには

1. central specs repository（中央仕様リポジトリ）を作成して共有仕様専用のリポジトリを作成する
2. Gitサブモジュールまたはパッケージ参照を使用する
3. リポジトリ間のワークフローを実装する

ViveセッションからSpecセッションを開始可能か

できる。ViveセッションからGenerate specと入力することでSpecセッションが始まる

タスクが既に実装されている場合

1. tasks.mdのUpdate tasksを行う
2. Specセッションにてkiroにスキャンを依頼する

1つのリポジトリに複数の仕様を含めることはできるか

可能。機能ごとに複数の仕様を作成することをお勧めする。

Chat

他のツールと同じような機能を持っているが、#でコンテキストプロバイダーを使うことで、明示的に情報をkiroに提供することができる。

Autopilot

自律実行モード。デフォルトではONになっている。OFFにするとSupervised(監視、監督)モードとして動作する。

Autopilotに向いているケース

• Kiroの機能に精通した経験豊富なユーザー
• 反復的なタスクまたは明確に定義されたタスク
• 迅速に進めたいプロジェクト
• 複数のファイルにまたがるタスクや複数のステップを必要とするタスク

Supervisedに向いているケース

• Kiroに慣れてきた新規ユーザー
• 重要なコードベース
• Kiroが問題にどのように取り組むかを学ぶ
• 各変更を注意深く確認したい場合
• 馴染みのないコードや複雑なシステムを扱う

Autopilotで行なった変更も、後から元に戻すことが可能です。

Vive vs. Spec

Viveに向いているケース

1. インタラクティブなQ&A形式:Vibeセッションは、コードに関する双方向の会話に最適化されており、質問してすぐに回答を得ることができます
2. クイック アシスタンス:コーディングに関する質問への回答やコードの動作の説明をすぐに得たり、正式な仕様プロセスを経ずに概念を理解したりするのに最適です
3. コンテキスト理解: 他のKiroセッションと同様に、Vibeセッションではコンテキストプロバイダーを活用してコードベースを理解しますが、広範なコード生成ではなく説明に重点が置かれます
4. 柔軟なアプローチ:Vibeセッションは、Specセッションに比べてより流動的で構造化されていないアプローチを提供するため、探索的なコーディングと学習に適しています

Specに向いているケース

1. 複雑な開発タスク: 複雑な機能、アプリケーション全体、または慎重な計画と実行を必要とする大幅なリファクタリングを構築する場合は、Specセッションを使用します
2. 構造化アプローチ: 要件と実装の詳細を明確に文書化した、系統的かつ段階的な開発アプローチが必要な場合
3. チームコラボレーション: 複数のチームメンバーが実装計画を理解し、仕様に対する進捗状況を追跡する必要があるプロジェクト向けです
4. ドキュメントのニーズ: 将来の参照や知識の共有のために、コード実装とともに詳細なドキュメントを生成する場合

Terminal

チャット中、何かコマンドを実行する必要が出てきた場合は上記のような画面になります。画像右上のアイコンは左から「コマンドの変更」「拒否」「信頼して実行」「1回実行」を表します。

「信頼して実行」ではFull Command（画像ではpip install requests）のみ許可する、Partial（画像ではpip install）を許可、Base（画像ではpip）を許可と、コマンドによって信頼する内容を決めることができます。

信頼されたコマンドは以降、許可した内容によって自動で実行されます。

Hooks

IDE内で特定のイベント発生時に、事前に定義したアクションを自動で実行する仕組みです。

Hook Types

フックの種類は下記3つです。

On File Create(ファイル作成時)

ユースケースとしては

• 新しいコンポーネントの定型コードを生成する
• 新しいファイルにライセンスヘッダーを追加する
• 実装ファイルを作成するときにテストファイルを設定する

On File Save(ファイル保存時)

ユースケースとしては

• リンティングとフォーマットを実行する
• 関連ファイルを更新する
• ドキュメントを生成する
• 変更されたファイルのテストを実行する

On File Delete(ファイル削除時)

ユースケースとしては

• 関連ファイルをクリーンアップする
• 他のファイルのインポート参照を更新する
• プロジェクトの整合性を維持する

その他、フック自体を手動でトリガーすることもできるようです。

Best Practices

Hook Design

Be Specific and Clear（具体的に、明確に）

詳細かつ明確な指示を書く

フックごとに1つの特定のタスクに焦点を当てる

複雑な操作には番号付きの手順を使用する

Test Thoroughly（徹底的にテストする）

デプロイ前にサンプルファイルでフックをテストする

エッジケースでフックが機能することを確認する

拡張する前に、限定されたファイルパターンから始める

Monitor Performance（パフォーマンスを監視する）

フックがワークフローを遅くしないようにする

トリガーイベントの頻度を考慮する

効率化のためにプロンプトを最適化する

Security Considerations

Validate Inputs（入力を検証する）

フックが予期しないファイルコンテンツを適切に処理できるようにする

ファイル形式の潜在的なエッジケースを考慮する

不正な入力や予期しない入力でテストする

Limit Scope（範囲を制限する）

可能な場合は特定のファイルタイプまたはディレクトリをターゲットにする

不要な実行を避けるために正確なファイルパターンを使用する

フックがコードベース全体に与える影響を考慮する

Review Regularly（定期的に確認する）

プロジェクトの進化に合わせてフックロジックを更新する

不要になったフックを削除する

実際の結果に基づいてプロンプトを調整する

Team Collaboration

Document Hooks

フックの目的を明確に文書化する

期待される行動の例を含める

制限事項やエッジケースを文書化する

Share Configurations（設定を共有する）

チームメンバー間で一貫したフックを使用する

フックの設定をバージョン管理に保存する

一般的なチームワークフロー用の標準フックを作成する

Version Control Integration（バージョン管理統合）

バージョン管理システムと統合するフックを検討する

コードレビューワークフローのフックを作成する

フックを使用してチームの標準を強化する

フックの例として幾つか紹介されていました。

Troubleshooting Hooks

よくある問題とその対処法が記載されていました。

フックがトリガーされない

ファイルパターンがターゲットファイルと一致することを確認します

フックが有効になっていることを確認する

イベントタイプが正しいことを確認してください

予期しないフックの動作

フックの説明書をよく読んで理解を深めましょう

競合するフックを確認する

ファイルパターンが広すぎないことを確認する

パフォーマンスの問題

より具体的なファイルパターンでフックのスコープを制限する

複雑なフック命令を簡素化

トリガーとなるイベントの頻度を減らす

Steering

ステアリングファイルはkiroに把握しておいて欲しい内容を記載するものです。

メリットとして下記点が挙げられていました。チームにおけるAI駆動開発にも大きく寄与してくれそうです。

Consistent Code Generation - Every component, API endpoint, or test follows your team's established patterns and conventions.
一貫したコード生成 - すべてのコンポーネント、API エンドポイント、またはテストは、チームの確立されたパターンと規則に従います。

Reduced Repetition - No need to explain project standards in each conversation. Kiro remembers your preferences.
繰り返し作業の削減 - 毎回の会話でプロジェクトの基準を説明する必要はありません。Kiro があなたの好みを記憶します。

Team Alignment - All developers work with the same standards, whether they're new to the project or seasoned contributors.
チームの調整 - プロジェクトに新しく参加した開発者でも、経験豊富な開発者でも、すべての開発者が同じ基準で作業します。

Scalable Project Knowledge - Documentation that grows with your codebase, capturing decisions and patterns as your project evolves.
スケーラブルなプロジェクトナレッジ - コードベースとともに拡張され、プロジェクトの進化に合わせて決定とパターンを記録するドキュメント。

kiroでは3つのステアリングファイルが自動的に生成されます。

• product.md：プロダクトの目的や、ターゲット、主要機能、ビジネス目標を定義するファイル。kiroはこのファイルに記載されている内容を基にコード提案を行うようです
• tech.md：選択したフレームワーク、ライブラリ、開発ツール、技術的制約を記載するファイル。これにより既存の技術スタックが優先して利用されるようです
• structure.md：ファイル構成、命名規則、イベントパターン、アーキテクチャ上の決定事項を記載するファイル(ADR(Architecture Decision Record)のようなものでしょうか)

これら以外にも任意のステアリングファイルを作成可能です。ファイル自体もkiroに作成してもらうことが可能なので、自然言語で指示してファイル作成をお願いすることも可能です。
このページで紹介されていた他のステアリングファイルは下記のようなものがありました。

• API Standards (api-standards.md)
• Testing Approach (testing-standards.md)
• Code Style (code-conventions.md)
• Security Guidelines (security-policies.md)
• Deployment Process (deployment-workflow.md)

Inclusion Modes

ステアリングファイルに3点ダッシュ（---）を記載することで、ステアリングファイルを適用する条件を設定できます。例えば、テストファイルにだけ適用するルールなどを作成することもできそうです。

Example
---
inclusion: fileMatch
fileMatchPattern: "components/**/*.tsx"
---

File References

ステアリングファイル中にファイルへのリンクを含めることができます。

#[[file:<relative_file_name>]]

Example
API specs: #[[file:api/openapi.yaml]]
Component patterns: #[[file:components/ui/button.tsx]]
Config templates: #[[file:.env.example]]

Best Practices

• Keep Files Focused：ドメイン（APIデザイン、テスト、デプロイ手順）ごとにファイルを用意する
• Use Clear Names：わかりやすい名前をつける
• Include Context：基準や（アーキテクチャ選定などの）決定の背景を記載する
• Provide Examples：コードスニペットなどで例を挙げる
• Security First：APIキーやパスワード、機密データを記載しない
• Maintain Regularly：定期的にファイルのレビューを行う

MCP

MCP自体の説明は他にお願いするとして、設定自体はjsonファイルを編集するだけで利用できます。

• ワークスペースにのみ適用する場合：.kiro/settings/mcp.json
• 全てのワークスペースに適用する場合：~/.kiro/settings/mcp.json

MCPサーバとして設置例がいくつか紹介されていました。

• AWS Documentation Server
• GitHub MCP Server
• Web Search Server(BraveSearch)

Tools

全体的にMCPの話でしたので、ここではトラブルシューティングとベストプラクティスを取り上げます。

Troubleshooting Tool Usage

Tool Not Responding(ツールが応答しません)

KiroパネルでMCPサーバーのステータスを確認します

MCPログでエラーメッセージを確認します

必要に応じてMCPサーバーを再起動します

Incorrect Results(誤った結果)

リクエストをより具体的に言い換えてみましょう

タスクに適切なツールを使用しているか確認してください

MCPサーバーに必要な権限があることを確認する

Tool Not Available(ツールが利用できません)

MCPサーバーが適切に設定されていることを確認する

サーバーが実行中で接続されていることを確認してください

ツールを使用するために必要な権限があることを確認してください

Best Practices

• 最も関連性の高い結果を得るには、リクエストを具体的にしてください
• 明示的なツール参照を使用する前に、直接の質問から始める
• 信頼でき、頻繁に使用するツールのみを自動承認します
• 最良の結果を得るために、 MCPツールとローカルコンテキストを組み合わせてください
• 承認前にツールパラメータをチェックして正しいことを確認します

Best Practices

上記のBest Practicesはツールを使うときの話ですが、こちらはMCP全般のBest Practicesがまとめられています。特にセキュリティ面の話が記載されています。

Secure Configuration

Protecting API Keys and Tokens

機密トークンを含む設定ファイルをバージョン管理にコミットしないでください

可能な場合は値をハードコーディングする代わりに環境変数を使用する

MCPサーバーが機能するために必要な最小限の権限を持つトークンを作成する

構成で使用されるAPIキーとトークンを定期的にローテーションする

{
  "mcpServers": {
    "github": {
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

export GITHUB_TOKEN=your-token-value

mcp.jsonへのアクセス制限も推奨されています。

# Set restrictive permissions on user-level config
chmod 600 ~/.kiro/settings/mcp.json

# Set restrictive permissions on workspace-level config
chmod 600 .kiro/settings/mcp.json

Safe Tool Usage

Tool Approval Process

承認前に各ツールのリクエストを慎重に確認する

ツールに渡されるパラメータを確認する

承認する前にツールが何をするのかを理解する

現在のタスクに一致しない疑わしいリクエストを拒否します

Auto-approval Guidelines

次のツールのみを自動承認します

機密システムへの書き込み権限がない

検証済みのコードを持つ信頼できるソースから入手

ワークフローで頻繁に使用される

アクセスできる範囲が限られている

Server-Specific Security

AWS Documentation Server、GitHub MCP Server、Custom MCP Serversについて記載がありました。

AWS Documentation Server

AWSドキュメントサーバーは、次の理由により一般的に安全です

公開ドキュメントのみを読む

AWSアカウントやリソースにアクセスしません

AWS認証情報は不要

GitHub MCP Server

GitHub MCPサーバーを使用する場合:

最小限の権限でKiro専用のトークンを作成する

リポジトリへのアクセスを必要な人だけに制限する

絶対に必要な場合を除き、削除権限を付与しないでください

従来のトークンの代わりにきめ細かな個人アクセストークンの使用を検討してください

Custom MCP Servers

カスタム MCP サーバーを作成または使用する場合:

使用する前にソースコードを確認してください

可能な場合は隔離された環境で実行する

サーバーに付与される権限を制限する

予期しない動作がないかサーバーのアクティビティを監視する

Workspace Isolation

プロジェクト固有のMCPサーバーにワークスペースレベルの構成を使用します。

project-a/
├── .kiro/
│   └── settings/
│       └── mcp.json  # Project A specific servers
project-b/
├── .kiro/
│   └── settings/
│       └── mcp.json  # Project B specific servers

Monitoring and Auditing

Checking MCP Logs

定期的に MCP ログを確認して、サーバーのアクティビティを監視します

Kiroパネルを開く

出力タブを選択します

ドロップダウンから「Kiro - MCP Logs」を選択します

Auditing Tool Usage

承認したツールを定期的に確認します

自動承認ツールのMCP設定を確認してください

MCPログでツールの使用パターンを確認する

頻繁に使用しなくなったツールの自動承認を削除する

Responding to Security Incidents

MCP サーバーにセキュリティ上の問題があると思われる場合は、次の手順に従ってください。

• 設定でサーバーを直ちに無効にする
• サーバーに関連付けられたトークンまたはAPIキーを取り消します
• 接続されたサービスにおける不正なアクティビティを確認する
• MCPサーバーのメンテナーに問題を報告してください

Additional Security Measures

Network Security

ファイアウォールを使用して、MCP サーバーからの送信接続を制限する

機密性の高いMCPサーバー接続にはVPNの使用を検討してください

MCP サーバーとの間のネットワーク トラフィックを監視する

System Security

セキュリティパッチを適用してシステムを最新の状態に保つ

最小限の権限でMCPサーバーを実行する

機密性の高いMCPサーバーを実行するには別のユーザーアカウントを使用する

Guides

Language Support

「TypeScript」「JavaScript」「Python」「Java」については言語特有の推奨事項等が記載されています。

Learn by Playing

チュートリアルのようなものです。実際にゲームを作りながらkiroを試すことができるようです。こちらは別途試してみようと思います。

Migrating from VSCode

VSCodeからの移行について記載があります。VSCodeからプロファイルをkiroにインポートすることができますので、普段VSCodeを使っていた人も移行自体は簡単だと思います。

Reference

Troubleshooting

「kiroのインストール関連」「認証関連」「シェル（ターミナル）関連」「Windows固有の問題」「MCPサーバー接続関連」のお問題について解決するヒントが記載されています。

Auth Methods

Installationで記載した内容の通り、kiroへのログイン方法が記載されています。

Privacy & Security

組織で利用する際には一読した方が良いでしょう。全部は紹介しませんが、個人的に気になった箇所は以下の通りです。

• AWS Regions where content is stored and processed

Your content, such as prompts and responses, will be stored in the US East (N. Virginia) Region.
プロンプトや応答などのコンテンツは、米国東部 (バージニア北部) リージョンに保存されます。

• Kiro content used for service improvement

We may use certain content from Kiro for service improvement. Kiro may use this content, for example, to provide better responses to common questions, fix Kiro operational issues, for de-bugging, or for model training. Content that Kiro may use for service improvement includes, for example, your questions to Kiro and the responses and code that Kiro generates.
Kiroは、サービス向上のため、Kiroから取得した特定のコンテンツを利用する場合があります。Kiroは、例えば、よくある質問へのより良い回答の提供、Kiroの運用上の問題の修正、デバッグ、モデルのトレーニングなどのために、これらのコンテンツを利用する場合があります。Kiroがサービス向上のために利用するコンテンツには、例えば、お客様からのKiroへの質問や、Kiroが生成する回答やコードなどが含まれます。

If you have an Amazon Q Developer Pro subscription and access Kiro through your AWS account with the Amazon Q Developer Pro subscription, then Kiro will not use your content for service improvement.
Amazon Q Developer Pro サブスクリプションをお持ちで、Amazon Q Developer Pro サブスクリプションを持つ AWS アカウントを通じて Kiro にアクセスする場合、Kiro はサービスの改善のためにコンテンツを使用しません。

• Types of telemetry collected(収集されるテレメトリデータ)

Usage data — Information such as the Kiro version, operation system (Windows, Linux, or macOS), and the anonymous machine ID.
使用状況データ- Kiro のバージョン、オペレーティング システム (Windows、Linux、または macOS)、匿名マシン ID などの情報。
Performance metrics — The request count, errors, and latency for various features:
パフォーマンス メトリック- さまざまな機能のリクエスト数、エラー、レイテンシ:
Login
Tab completion
Code generation
Steering
Hooks
Spec generation
Tools
MCP

• Trusted commands

By default, the Kiro agent in Autopilot or Supervised mode is only allowed to run the following read-only commands without human approval:
デフォルトでは、Autopilot モードまたは Supervised モードの Kiro エージェントは、人間の承認なしで次の読み取り専用コマンドのみを実行できます。
ls
cat
echo
pwd
which
head
tail
find
grep