IDEとCLIにそれぞれ適切なファイルを読み込ませるためのKiroステアリングファイルの分割方法 (2026年ガイド)

Kiro のステアリングに関するページは機能一覧表から始まっており、その行の構成が設計のすべてを物語っています。「ワークスペースステアリング（.kiro/steering/）」は IDE、CLI、Web、Mobile で利用可能です。「グローバルステアリング（~/.kiro/steering/）」は IDE と CLI で利用可能で、Web と Mobile では利用不可とマークされています。「Web設定で管理されるクラウドステアリング」は Web のみです。「UIを介したファウンデーションファイルの生成」は IDE のみです。「インクルージョンモード（always, fileMatch, manual）」は、4つのサーフェスすべてで利用可能とマークされています。

混乱の原因はまさにこの最後の行にあります。ページの下部にある注記で、さらに仕様が絞り込まれているからです。CLI では現在インクルージョンモードがサポートされておらず、ディレクトリ内のすべてが自動的に読み込まれます。したがって、正しいメンタルモデルは「自分のルールがどこにでもついてくる」ではなく、「ファイルはついてくるが、制限（ゲート）はついてこない」というものになります。

グローバルディレクトリにも、同様の制約が存在します。「Web上では、『グローバルステアリング』はローカルの ~/.kiro/steering/ ディレクトリを指しますが、クラウドサンドボックスはこれを読み取ることができません。」ドキュメントで推奨されているルートは Configuration Sync（設定同期）です。「クラウドセッション間で個人のステアリングを再利用するには、Configuration Sync を介してアップロードしてください。これにより、クラウドコピーがすべてのクラウドセッションに適用されます。」

独自のエージェントを構築し始めた人々が陥りやすい4つ目のケースもあります。ドキュメントには次のように書かれています。「カスタムエージェントを使用する場合、ステアリングファイルは自動的には含まれません。ステアリングコンテキストを読み込むには、エージェントの resources 設定に明示的に追加する必要があります。」エージェントの resources に file://.kiro/steering/**/*.md のようなグロブを指定することで、これらを読み込ませることができます。

そして、1つのファイル名だけは制限を完全に回避します。Kiro は AGENTS.md 標準をサポートしていますが、ページには次のような警告があります。「AGENTS.md ファイルはインクルージョンモードをサポートしておらず、常に含まれます。」リポジトリのルートにツール間で共有するファイルを置く場合、他の場所でどれだけ厳密にフロントマターを管理していても、定義上それは「常時オン」のファイルになります。

フロントマターを削除して最初からやり直す。 条件付きファイルが意図しない挙動を示したとき、直感的に YAML が間違っていると考えがちです。しかし、多くの場合そうではありません。ドキュメントには「インクルージョン設定はファイルの最初のコンテンツでなければならず、その前に空行やコンテンツを置いてはならない」という警告があり、一度確認する価値はありますが、ファイルが IDE で動作し、CLI で動作しないのであれば、フロントマターは正常であり、サーフェス側が変数（原因）です。

すべてを3つのファウンデーションファイルに移動する。 product.md、tech.md、structure.md は実際に存在し、有用です。ドキュメントには「これらのファウンデーションファイルはデフォルトで毎回のインタラクションに含まれ、Kiro のプロジェクト理解のベースラインを形成します」とあります。ここでの失敗パターンは、これを「統合してよい」という許可と捉えてしまうことです。統合したものはすべて、あらゆる場所で常時オンになり、まさに避けようとしていた結果を招きます。

個人の好みをグローバルディレクトリに置き、それがどこにでも引き継がれると仮定する。 これらは IDE と CLI には引き継がれます。しかし、クラウドサンドボックスはそのディレクトリを読み取れないとドキュメントに明記されているため、ウェブセッションでは設定が静かに適用されなくなります。そして、それを知らせる通知はありません。

CLI が正常に動作するまでディレクトリを削る。 読み込まれるファイルが減るという意味では機能します。しかし、同時に IDE から条件付きの優れたガイダンスを奪うことにもなります。結果として、一方のサーフェスを劣化させることで、もう一方のサーフェスを調整することになります。

これを他のツールのルールトリガーモードと同じ問題だと仮定する。 似ているように見えますが、失敗の本質が異なります。ツールがすべての場所でトリガーモードをサポートしているにもかかわらずルールが起動しない場合、問題はどのモードを選択したかであり、これは how to choose Windsurf rule trigger modes でカバーされている領域です。今回のケースでは、モードは正しいものの、サーフェスがそれを無視しています。

ステップ 1：ディレクトリを「常時オン」層と「制限付き」層に分割する

.kiro/steering/ 内のすべてを、次の1つの質問によって2つの山に分類します。「これがすべてのタスク、すべてのサーフェスで、永久に読み込まれても許容できるか？」

「はい」の山が「常時オン」層です。これにはファウンデーションファイルと、真に普遍的な内容が含まれます。Kiro 自身の説明が良いフィルターになります。product.md は「製品の目的、ターゲットユーザー、主要機能、ビジネス目標を定義する」、tech.md は「選択したフレームワーク、ライブラリ、開発ツール、技術的制約を文書化する」、structure.md は「ファイルの構成、命名規則、インポートパターン、アーキテクチャの決定を概説する」となっています。CLI ではこの層しか存在しないため、この層は意図的に小さく抑えてください。

「いいえ」の山が「制限付き」層です。フレームワーク固有の規約、移行手順、トラブルシューティングガイドなど、長文のものがこれに該当します。これらにはフロントマターを付与します。CLI ではこれらも読み込まれてしまうことを受け入れる必要がありますが、だからこそこの山が無限に肥大化するのを防ぐことが重要になります。

作業のついでに、命名に関するアドバイスにも従いましょう。ドキュメントでは、api-rest-conventions.md、testing-unit-patterns.md、components-form-validation.md のように、スコープを示す名前を付け、「1ファイルにつき1ドメイン」にすることを推奨しています。すべてが読み込まれるサーフェスにおいては、ファイル名がそのファイルの目的を示す唯一のシグナルとなるため、名前は通常以上に重要です。

ステップ 2：ファイルの導入方法に合ったインクルージョンモードを選択する

4つのモードがドキュメント化されており、これらは相互に置き換え可能ではありません。

inclusion: always はデフォルトであり、その挙動をさせるためにフロントマターは不要です。inclusion: fileMatch は fileMatchPattern を受け取り、components/**/*.tsx のような単一のグロブ、または ["**/*.ts", "**/*.tsx", "**/tsconfig.*.json"] のような配列を指定できます。inclusion: manual は、ファイルを「チャットメッセージ内で #steering-file-name を使用して参照することで、オンデマンドで利用可能」にします。ドキュメントには「手動ステアリングファイルはスラッシュコマンドとしても表示されます。チャットで / を入力して表示・選択してください」とあります。inclusion: auto は、name（「ステアリングファイルの識別子。表示とマッチングに使用される」）と description（「このファイルを含めるタイミング。Kiro はこれをリクエストと照合する」）の2つのフィールドを必要とし、ファイルは「リクエストが説明と一致したとき」に引き込まれます。

ドキュメント化されたユースケースは、独自に再発明するよりも、そのまま従う価値があります。Manual（手動）は「最適：特殊なワークフロー、トラブルシューティングガイド、移行手順、またはたまにしか必要とされないコンテキストの多いドキュメント」。Auto（自動）は「最適：関連性がある場合のみ読み込むべきコンテキストの多いガイダンス（専門的なドメイン知識、複雑なワークフロー、または常時オンのステアリングを圧倒してしまうような詳細なリファレンス資料など）」。

もう1つのメカニズムもここで紹介します。仕様をステアリングファイルに直接貼り付ける代わりに、#[[file:<relative_file_name>]] を使用して実際のファイルを参照します。ドキュメントでは、#[[file:api/openapi.yaml]]、#[[file:components/ui/button.tsx]]、#[[file:.env.example]] が例として挙げられています。ポインタは常に最新の状態を保ちますが、コピペしたものは書いたその日から乖離し始めます。同じ理由は、文章ではなくパスによって指示のスコープを制限する場合にも当てはまります。詳細は how to scope Amp instructions to files を参照してください。

ステップ 3：サーフェスごとに各ファイルを配置し、実際に使用するサーフェスで検証する

慣習ではなく機能一覧表を参考に、各ファイルが物理的にどこに配置されるべきかを決定します。

リポジトリの標準は .kiro/steering/ に配置し、コミットします。個人の好みは ~/.kiro/steering/ に配置します。競合時のルールはドキュメントに次のように記載されています。「グローバルステアリングとワークスペースステアリングの間で指示が競合する場合、Kiro はワークスペースステアリングの指示を優先します。」クラウドセッションの場合は、Kiro Web の「Settings and Sync（設定と同期）」から個人のステアリングをアップロードし、「Settings and Steering（設定とステアリング）」でクラウドコピーを作成または編集します。

チーム向けのドキュメント化されたルートもあります。「グローバルステアリング機能を使用して、チーム全体に適用される集中管理されたステアリングファイルを定義できます。チームのステアリングファイルは、MDMソリューションやグループポリシーを介してユーザーのPCにプッシュするか、ユーザーが中央リポジトリからPCにダウンロードして ~/.kiro/steering フォルダに配置できます。」

その後、重要な場所で検証を行います。一日の大半を過ごすサーフェスを開き、制限付きファイルがトリガーされるべきではないタスクと、トリガーされるべきタスクを実行します。CLI では、ワークスペースディレクトリ内のすべてが読み込まれることを想定してください。その想定通りになること自体が検証です。カスタムエージェントを使用している場合は、resources グロブが存在することを確認してください。これがないと、そのエージェントのステアリングコンテキストは一切読み込まれません。

ステアリングファイルは、規約、スタック、構造といった「常設の指示書」です。しかし、プロジェクト知識のもう半分、つまり「何を、いつ決定したか、なぜ代替案を却下したか」を管理するには不向きです。その半分の知識は、すべてのタスクで読み込まれるのではなく、オンデマンドで検索可能であるべきであり、IDE を開いているかターミナルを開いているかによって形が変わるべきではありません。MemoryLake に意図的にエントリーを書き込んでおくことで、その記録を一元管理できます。エントリーはあなた自身の言葉で記述します。Kiro のディレクトリから何かが読み取られたり、書き込まれたり、削除されたりすることはありません。

ステップ 1：API キーを作成する

サインインし、ワークスペースの設定から API キーを生成します。これはエージェントや統合機能が使用する認証情報であるため、移行作業を始める前に作成してください。

ステップ 2：最初のメモリをアップロードする

ステアリングファイルが暗示しているものの、明記はされていない決定事項から始めましょう。なぜそのスタックなのか、どの手法をどのような理由で却下したのか、なぜ誰も覚えていないような制約が存在するのか。それぞれを短い独立したノートとして書き、個別に検索できるようにします。

ステップ 3：AI とエージェントを接続する

使用しているアシスタントやエージェントを接続します。これにより、特定のセッションがどのディレクトリを読み取れるかに依存することなく、サーフェスやツールをまたいで記録があなたに追従するようになります。

「常時オン」層は、単なるフォルダではなく「予算（バジェット）」になります。あるサーフェスがすべてを読み込むことを受け入れると、そのディレクトリのサイズは、自然に蓄積されるものではなく、意図的に決定すべきものになります。この予算は、長いセッションの後半でどれだけの空き容量が残るかに直接影響します。これは what survives Kiro compaction で検証されているトレードオフと同じです。

レビューに第2のチャネルが加わります。Kiro Web では、プルリクエストへのフィードバックがステアリングになります。「常に標準のエラーハンドリングを使用してください」といったガイダンスをコメントすると、「エージェントはそれらのパターンを学習し、すべてのリポジトリにわたる今後の作業に適用」します。ただし、これには重要な制限が併記されています。「タスクを作成したユーザー（あなた）のフィードバックのみがエージェントの学習に影響します。他のレビューアのコメントはエージェントの学習に影響しません。」シニアレビューアが他人のタスクに残したコメントは、エージェントに何も教えていません。

ツール間共有ファイルは、無条件のメリットではなくなります。ルートの AGENTS.md は便利で常に含まれますが、これは制限付きコンテンツではなく、常時オンの予算の一部として扱うべきであることを意味します。複数のエージェントにわたって1つのファイルを維持する場合、各ツールの読み込み規約は異なるため、共有ファイルの有用性は、最も制限の緩い（何でも読み込んでしまう）リーダーの仕様に引っ張られます。

ツール間の移行計画が立てやすくなります。制限がツール固有の UI ではなくフロントマターに存在する場合、他のツールで何を再表現する必要があるかが一目でわかります。これは how to migrate from Kiro to Claude Code の実践的な側面です。

ファイル内にサーフェスの前提条件を記述する。制限付きファイルの先頭に「src/components でのみ読み込まれることを想定」という1行を書いておくだけで、コストをかけずに、別の場所に表示されたときに次の人が何を確認すべきかを伝えることができます。

「常時オン」層を定期的に見端す。これは、すべてのサーフェスのすべてのタスクでコストが発生する層であり、意図せず肥大化しやすい層でもあります。

コンテンツの貼り付けよりもファイル参照を優先する。実際の仕様を指す #[[file:...]] ポインタは、コピーされた抜粋のように古くなることがありません。

自動インクルードファイルの description には、概要ではなくトリガーのように読める説明を記述する。このフィールドのドキュメント上の役割は「このファイルを含めるタイミング」であるため、「APIエンドポイントを作成または変更するときに使用する」といった条件として表現された説明は、単なるトピックラベルよりも効果的に機能します。共有コンテキストファイルは、他のツールでも同様に動作します。詳細は how Cursor Projects share context files を参照してください。

自分が書いた記憶ではなく、実際に何が利用可能かを監査する。ディレクトリのリストは読み込みリストと同じではありません。その2つの間のギャップは、how to find Zed skills missing from your catalog で説明されている問題と同じです。

Kiro は、4つのインクルージョンモード、2つのディレクトリ、そして5つのサーフェスにまたがる1つのエージェントを提供し、どこで制限が適用され、どこで適用されないかを明確にドキュメント化しています。CLI はワークスペースディレクトリ内のすべてを読み込みます。クラウドサンドボックスはグローバルディレクトリを読み取れません。カスタムエージェントは、resources にリストしない限りステアリングを読み込みません。ルートの AGENTS.md は常に含まれます。

ファイルを、どこでも許容できる「常時オン」層と、意図的に小さく抑えた「制限付き」層に分類し、個人の好みは使用するサーフェスが実際に読み取れる場所に配置し、最初にたまたま動作したサーフェスではなく、実際に使用するサーフェスで検証を行ってください。そして、それらの規約の背後にある決定事項を検索可能な場所に保管し、次回ファイルレイアウトが変更されたときにもその理由が失われないようにしましょう。