Kiro Steeringファイル優先順位の仕様解説：複数ルール管理の基礎

はじめに：Steeringファイルの優先順位が重要な理由

こんにちは。DXソリューション営業本部の松浦です。

KiroのSteeringファイルは、プロジェクト全体やタスク固有のルールとガイドラインを定義する便利な機能です。しかし、複数のSteeringファイルが存在する場合、それらの優先順位を正しく理解していないと、意図しない動作や矛盾したルールの適用が発生する可能性があります。

優先順位を理解しないことで起こる問題の具体例：

本記事では、Kiroにおける複数Steeringファイルの優先順位ルールを体系的に解説し、プロジェクト規模に応じた効果的な管理方法をご説明します。
(Steeringとはなんぞや？という方は、よろしければ弊社後藤が執筆した以下の使ってみた記事も読んでみてもらえると嬉しいです！)

1. 優先順位の基本原則

Kiroで複数のSteeringファイルが存在し、内容に矛盾がある場合、以下の優先順位ルールが適用されます。

1-1. スコープによる優先順位（最重要）

最も基本的な優先順位は、Steeringファイルが配置されているスコープによって決定されます。

配置場所の具体例

実際のファイルシステム上での配置場所を具体的に見てみましょう。

ワークスペースレベル（プロジェクトフォルダ内）：

C:\Users\YourName\Projects\my-web-app\
├── src/
├── package.json
└── .kiro/
    └── steering/
        ├── project-rules.md        ← このプロジェクト専用
        └── coding-standards.md     ← このプロジェクト専用

グローバルレベル（ユーザーホーム直下）：

C:\Users\YourName\
├── Documents/
├── Desktop/
├── Projects/
│   ├── my-web-app/      ← プロジェクト1
│   ├── api-server/      ← プロジェクト2
│   └── mobile-app/      ← プロジェクト3
└── .kiro/
    └── steering/
        ├── personal-style.md       ← 全プロジェクトで有効
        └── security-policy.md      ← 全プロジェクトで有効

ポイント：
グローバルレベルのファイルは、my-web-app、api-server、mobile-app のすべてのプロジェクトで自動的に適用されます。一方、ワークスペースレベルのファイルは、そのプロジェクトフォルダ内でのみ有効です。

実際のパス例（OS別）

Windows環境：

• ワークスペース：C:\Users\YourName\Projects\my-project\.kiro\steering\
• グローバル：C:\Users\YourName\.kiro\steering\

Mac/Linux環境：

• ワークスペース：/Users/yourname/Projects/my-project/.kiro/steering/
• グローバル：/Users/yourname/.kiro/steering/ または ~/.kiro/steering/

チルダ（~）の意味：
~ は「ユーザーのホームディレクトリ」を表す記号です。Windowsでは C:\Users\YourName\、Mac/Linuxでは /Users/yourname/ または /home/yourname/ を指します。

優先順位の原則：

ワークスペースレベル > グローバルレベル

公式仕様：
Kiroの公式ドキュメントでは、以下のように明記されています：

「In case of conflicting instructions between global and workspace steering, Kiro will prioritize the workspace steering instructions. This allows you to specify global directives that generally apply to all your workspaces, while preserving the ability to override those directives for specific workspaces.」

（訳：グローバルとワークスペースのSteeringで矛盾する指示がある場合、Kiroはワークスペースのステアリング指示を優先します。これにより、すべてのワークスペースに一般的に適用されるグローバルな指示を指定しながら、特定のワークスペースに対してそれらの指示を上書きする機能を保持できます。）

グローバルレベルとワークスペースレベルの使い分け

グローバルレベル（~/.kiro/steering/）の使用例：

• 個人の作業スタイル： 「コードコメントは日本語で記述する」「変数名はキャメルケースを使用」など、すべてのプロジェクトで共通する個人の好み
• セキュリティポリシー： 「APIキーやパスワードをコードに直接記述しない」など、全プロジェクト共通のセキュリティルール
• コーディング規約： 「関数は50行以内に収める」「エラーハンドリングを必ず実装する」など、個人の基本方針

ワークスペースレベル（.kiro/steering/）の使用例：

• プロジェクト固有のルール： 「このプロジェクトではTypeScriptの厳格モードを使用」「React Hooksのみを使用しクラスコンポーネントは禁止」
• チーム規約： 「コミットメッセージは英語で記述」「PRには必ずテストコードを含める」など、チーム全体で合意したルール
• 技術スタック固有： 「AWS CDKを使用してインフラをコード化」「データベースはPostgreSQLを使用」など、プロジェクトの技術選定に関するルール

具体的なシナリオ例

シナリオ1：言語設定の上書き

グローバル設定（~/.kiro/steering/global-rules.md）：

---
inclusion: always
---

# グローバルルール

- ドキュメントは英語で作成する
- コメントは簡潔に記述する

ワークスペース設定（.kiro/steering/project-rules.md）：

---
inclusion: always
---

# プロジェクトルール

- ドキュメントは日本語で作成する（日本国内向けプロジェクトのため）
- 詳細なコメントを記述する

結果： ワークスペース設定が優先され、日本語で詳細なドキュメントが作成されます。

シナリオ2：複数プロジェクトでの使い分け

3つのプロジェクトを掛け持ちしている担当者の場合：

• グローバル設定： 「セキュリティベストプラクティスを遵守」「テストカバレッジ80%以上」（全プロジェクト共通）
• プロジェクトA（社内ツール）： 「開発速度優先、ドキュメントは最小限」
• プロジェクトB（顧客向けAPI）： 「詳細なAPIドキュメント必須、OpenAPI仕様書を作成」
• プロジェクトC（レガシー移行）： 「既存コードとの互換性を最優先、段階的なリファクタリング」

各プロジェクトのワークスペース設定が、グローバル設定に追加される形で適用されます。

シナリオ3：チーム開発での活用

チームメンバーそれぞれが異なるグローバル設定を持ちながら、プロジェクトのワークスペース設定で統一：

• メンバーA（グローバル）： 「コメントは日本語」
• メンバーB（グローバル）： 「コメントは英語」
• プロジェクト（ワークスペース）： 「コミットメッセージとPRは英語、コードコメントは日本語」

結果： 個人の好みに関わらず、プロジェクトのワークスペース設定が優先され、チーム全体で統一されたルールが適用されます。

1-2. マルチルートワークスペースでの優先順位

Kiroでは、複数のプロジェクトフォルダを同時に開く「マルチルートワークスペース」機能があります。この場合、後に追加されたワークスペースほど優先度が高くなります。

ユーザーレベル < ワークスペース1 < ワークスペース2 < ワークスペース3

マルチルートワークスペースとは

マルチルートワークスペースは、フロントエンドとバックエンドを別々のフォルダで管理している場合や、モノレポ構成のプロジェクトで便利な機能です。

具体例：フロントエンドとバックエンドを同時に開く場合

Kiroワークスペース
├── [ワークスペース1] frontend/
│   ├── src/
│   └── .kiro/
│       └── steering/
│           └── frontend-rules.md    ← 「React Hooksを使用」
└── [ワークスペース2] backend/
    ├── api/
    └── .kiro/
        └── steering/
            └── backend-rules.md     ← 「Node.js + Expressを使用」

優先順位の適用：

• frontend/ フォルダ内のファイルを編集中 → frontend-rules.md が適用
• backend/ フォルダ内のファイルを編集中 → backend-rules.md が適用（より優先）
• 両方のルールが競合する場合 → 後に追加された backend-rules.md が優先

実用的なシナリオ

シナリオ：モノレポでの言語設定

グローバル（~/.kiro/steering/）: 「コメントは英語」
ワークスペース1（shared-lib/）: 「ドキュメントは英語（ライブラリは公開用）」
ワークスペース2（internal-tools/）: 「ドキュメントは日本語（社内ツール）」

結果：

• shared-lib/ で作業中 → 英語でドキュメント作成
• internal-tools/ で作業中 → 日本語でドキュメント作成（ワークスペース2が最優先）

注意：
マルチルートワークスペースは高度な機能です。通常の単一プロジェクトでは、ワークスペースレベルとグローバルレベル 2階層のみを意識すれば十分です。

1-3. 同一スコープ内での優先順位

同じディレクトリ内に複数の inclusion: always ファイルがある場合：

• 明確な優先順位ルールは存在しません
• すべてのファイルが読み込まれ、Kiroが文脈から判断します
• ベストプラクティス： 矛盾を避けるため、同じスコープ内では矛盾する内容を記述しないこと

2. inclusionモードの理解

Steeringファイルには、フロントマター（---で囲まれた部分）で3つのinclusionモードを設定できます。

2-1. inclusion: always（常に適用）

---
inclusion: always
---

• 動作： すべてのKiroとのやり取りで自動的に読み込まれます
• 用途： プロジェクト全体に適用したいルールやガイドライン
• 使用例： プロジェクト共通ルール、コーディング規約、セキュリティポリシー

2-2. inclusion: manual（手動で適用）

---
inclusion: manual
---

• 動作： ユーザーが明示的に参照した時のみ読み込まれます
• 参照方法： チャットで # を使って参照
• 用途： 特定のタスク用ガイドライン、手順書作成ルール

参照例：

#aws-console-login-guide AWSコンソールのログイン手順を作成してください

または、ファイル名で参照：

#.kiro/steering/aws-console-login-guide.md を参照して手順書を作成してください

2-3. inclusion: fileMatch（ファイルパターンで自動適用）

---
inclusion: fileMatch
fileMatchPattern: 'src/**/*.ts'
---

• 動作： 指定したパターンに一致するファイルが読み込まれた時に自動適用
• 用途： 特定のファイルタイプやディレクトリに対するルール
• 使用例： TypeScriptファイル用のルール、特定ディレクトリのコーディング規約

2-4. inclusionモードの使い分け

3. ベストプラクティス

3-1. 矛盾を避けるための戦略

✅ 良い設計：

.kiro/steering/
├── project-common-rules.md      (always) - 一般的なルール
├── coding-standards.md          (always) - コーディング規約
└── aws-specific-guide.md        (manual) - 特定タスク用

各ファイルは異なる側面をカバーし、矛盾しない

❌ 避けるべき設計：

.kiro/steering/
├── rules-v1.md    (always) - 「英語で書く」
└── rules-v2.md    (always) - 「日本語で書く」

同じ内容について矛盾する指示

3-2. 階層的な設計

• グローバル： 全プロジェクト共通の基本ルール
• ワークスペース： プロジェクト固有のルール（より具体的）

3-3. 責任の分離

各 always ファイルは異なる領域を担当：

• style.md - スタイルガイド
• security.md - セキュリティポリシー
• testing.md - テスト規約

3-4. manualの活用

特定のタスクやコンテキストに依存するルールは manual に設定し、必要な時だけ明示的に参照することで、コンテキストを効率的に管理できます。

4. ファイル配置と整理の戦略

4-1. ファイル配置

Steeringファイルの配置は、まずシンプルなフラット構造から始めましょう。
(フォルダを階層分けしsteeringにより優先順位付けを行う方法も考えられるため、検証を行っています！)

.kiro/steering/
├── project-common-rules.md          (always)
├── aws-console-login-guide.md       (manual)
└── s3-bucket-creation-guide.md      (manual)

メリット：

• シンプルで理解しやすい
• 管理コストが低い
• 動作が確実で予測可能
• すべてのプロジェクト規模に対応可能

4-2. 命名規則による視覚的整理

命名規則を定義づけることで視認性が向上します。

.kiro/steering/
├── 00-project-common-rules.md       (always)
├── 10-security-policy.md            (always)
├── 20-aws-console-login-guide.md    (manual)
├── 20-aws-s3-guide.md               (manual)
└── 30-terraform-guide.md            (manual)

重要：
ファイル名の番号（00-、10-、20-など）は、Kiroの優先順位には影響しません。
これは人間が視覚的に整理しやすくするための命名規則であり、ファイルがエクスプローラーやエディタで自動的にソートされるようにすることが目的です。
優先順位は「1-3. 同一スコープ内での優先順位」で説明した通り、Kiroが文脈から判断します。

メリット：

• 視覚的に分類が明確
• ファイルが自動的にソートされる
• フラット構造の利点を維持
• チームメンバーが目的のファイルを見つけやすい

命名規則の例：

• 00-: プロジェクト共通ルール
• 10-: セキュリティ・品質基準
• 20-: タスク固有ガイドライン
• 30-: 特殊なケース

注意点：

• 番号は優先順位を決定しない（あくまで整理のため）
• 同じスコープ内で矛盾するルールを避けることが重要
• inclusionモード（always/manual）の使い分けで制御する

4-3. フォルダ階層による整理（要検証）

Steeringファイルが増えてきた場合、フォルダによる階層化も検討できます。
ただし、フォルダ階層による優先順位制御については、steeringの定義方法含め検証が必要なため、
動作が確認できたら改めてご紹介します！

フォルダ構造の例：

.kiro/steering/
├── project-common-rules.md          (always)
└── aws/
    ├── console/
    │   ├── login-guide.md           (manual)
    │   └── s3-guide.md              (manual)
    └── cli/
        └── cli-guide.md             (manual)

期待される効果：

• 関連するファイルをグループ化
• 責任範囲の明確化
• 大規模プロジェクトでの管理性向上

まとめ：効果的なSteering管理のために

Kiroの複数Steeringファイルの優先順位を理解することで、プロジェクトのルールを効果的に管理できます。

重要なポイント：

• ワークスペースレベルがグローバルレベルより優先される
• inclusionモード（always/manual/fileMatch）を適切に使い分ける
• まずはフラット構造から始め、必要に応じて整理する
• 矛盾を避けるため、責任を明確に分離する

 ↓QESではKiroについて積極的に情報発信していきますので是非ご覧ください！

もし「このサービスについて知りたい」「AWS環境の構築、移行」などのリクエストがございましたら、弊社お問合せフォームまでお気軽にご連絡ください。 複雑な内容に関するお問い合わせの場合には直接営業からご連絡を差し上げます。 また、よろしければ以下のリンクもご覧ください！
＜QES関連ソリューション/ブログ＞

＜QESが参画しているAWSのセキュリティ推進コンソーシアムがホワイトペーパーを公開しました＞

※Amazon Web Services、”Powered by Amazon Web Services”ロゴ、およびブログで使用されるその他のAWS商標は、米国その他の諸国における、Amazon.com, Inc.またはその関連会社の商標です。