Kiro Steering File Priority Guide: Fundamentals of Managing Multiple Rules

Introduction: Why Steering File Priority Matters

Hello! This is Matsuura from the DX Solution Sales Division.

Kiro's Steering files are a powerful feature for defining rules and guidelines for entire projects or specific tasks. However, when multiple Steering files exist, failing to understand their priority can lead to unintended behavior or conflicting rule applications.

Concrete examples of problems caused by misunderstanding priority:

In this article, we systematically explain the priority rules for multiple Steering files in Kiro and describe effective management methods tailored to project scale.
(If you're wondering, "What exactly is Steering?", please check out this hands-on article by our colleague, Goto!)

1. Fundamental Principles of Priority

When multiple Steering files exist in Kiro and their contents conflict, the following priority rules are applied.

1-1. Scope-Based Priority (Most Important)

The most basic priority is determined by the scope where the Steering file is placed.

Concrete Location Examples

Let's look at the specific locations on an actual file system.

Workspace Level (Inside project folder):

C:\Users\YourName\Projects\my-web-app\
├── src/
├── package.json
└── .kiro/
    └── steering/
        ├── project-rules.md        ← Project-specific
        └── coding-standards.md     ← Project-specific

Global Level (User home directory):

C:\Users\YourName\
├── Documents/
├── Desktop/
├── Projects/
│   ├── my-web-app/      ← Project 1
│   ├── api-server/      ← Project 2
│   └── mobile-app/      ← Project 3
└── .kiro/
    └── steering/
        ├── personal-style.md       ← Active for all projects
        └── security-policy.md      ← Active for all projects

Key Point:
Global-level files are automatically applied to all projects like my-web-app, api-server, and mobile-app. Conversely, workspace-level files are only valid within that specific project folder.

Path Examples by OS

Windows:

• Workspace: C:\Users\YourName\Projects\my-project\.kiro\steering\
• Global: C:\Users\YourName\.kiro\steering\

Mac/Linux:

• Workspace: /Users/yourname/Projects/my-project/.kiro/steering/
• Global: /Users/yourname/.kiro/steering/ or ~/.kiro/steering/

The Tilde (~) Symbol:
~ represents the "User Home Directory". On Windows, it points to C:\Users\YourName\, and on Mac/Linux, it points to /Users/yourname/ or /home/yourname/.

Priority Principle:

Workspace Level > Global Level

Official Specification:
The Kiro official documentation clearly states:

"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."

Choosing Between Global and Workspace Levels

Global Level (~/.kiro/steering/) Use Cases:

• Personal Work Style: Common preferences like "Write code comments in Japanese" or "Use camelCase for variables" across all projects.
• Security Policies: Universal security rules such as "Do not hardcode API keys or passwords."
• Coding Standards: Personal core policies like "Keep functions under 50 lines" or "Always implement error handling."

Workspace Level (.kiro/steering/) Use Cases:

• Project-Specific Rules: "Use TypeScript strict mode for this project" or "Only use React Hooks; class components are prohibited."
• Team Conventions: Rules agreed upon by the team, such as "Write commit messages in English" or "Always include test code in PRs."
• Stack-Specific Rules: Rules related to technology choices, like "Infrastructure as Code via AWS CDK" or "Database is PostgreSQL."

Scenario Examples

Scenario 1: Overriding Language Settings

Global Setting (~/.kiro/steering/global-rules.md):

---
inclusion: always
---

# Global Rules

- Create documentation in English
- Keep comments concise

Workspace Setting (.kiro/steering/project-rules.md):

---
inclusion: always
---

# Project Rules

- Create documentation in Japanese (for a Japan-based project)
- Provide detailed comments

Result: Workspace settings take precedence, and detailed documentation is created in Japanese.

1-2. Priority in Multi-Root Workspaces

Kiro features "Multi-Root Workspaces" which allow you to open multiple project folders simultaneously. In this case, workspaces added later have higher priority.

User Level < Workspace 1 < Workspace 2 < Workspace 3

What is a Multi-Root Workspace?

This is useful when managing frontend and backend in separate folders or in monorepo configurations.

Kiro Workspace
├── [Workspace 1] frontend/
│   └── .kiro/steering/frontend-rules.md    ← "Use React Hooks"
└── [Workspace 2] backend/
    └── .kiro/steering/backend-rules.md     ← "Use Node.js + Express"

Priority Application:

• Editing files in frontend/ → frontend-rules.md applies.
• Editing files in backend/ → backend-rules.md applies (Higher priority).
• Conflicting rules → backend-rules.md (added later) wins.

1-3. Priority Within the Same Scope

If there are multiple inclusion: always files in the same directory:

• No explicit priority rule exists.
• All files are loaded, and Kiro judges based on context.
• Best Practice: Do not write conflicting content within the same scope.

2. Understanding Inclusion Modes

Steering files can have three inclusion modes set in the front matter.

2-1. inclusion: always

• Behavior: Automatically loaded in all interactions with Kiro.
• Use Case: Rules or guidelines you want applied project-wide.

2-2. inclusion: manual

• Behavior: Only loaded when explicitly referenced by the user.
• Referencing: Use # in chat.

2-3. inclusion: fileMatch

• Behavior: Automatically applied when files matching the specified pattern are loaded.
• Use Case: Rules for specific file types or directories (e.g., 'src/**/*.ts').

3. Best Practices

3-1. Strategies to Avoid Conflict

✅ Good Design: Each file covers a different aspect (e.g., style.md, security.md, testing.md) without contradiction.

❌ Design to Avoid: Multiple always files in the same scope giving conflicting instructions (e.g., Version 1 says "English", Version 2 says "Japanese").

4. Strategies for File Placement and Organization

4-1. File Placement

Start with a simple flat structure. It's predictable, low-maintenance, and works for all project sizes.

4-2. Visual Organization via Naming Conventions

Using prefixes improves visibility. Note that these numbers do not affect Kiro's priority; they are purely for human organization and editor sorting.

.kiro/steering/
├── 00-project-common-rules.md
├── 10-security-policy.md
├── 20-aws-s3-guide.md (manual)

Summary: For Effective Steering Management

Understanding the priority of multiple Steering files allows you to manage project rules effectively.

• Workspace level overrides global level.
• Use the right inclusion mode (always/manual/fileMatch).
• Start flat, then organize as needed.
• Clearly separate responsibilities to avoid conflict.

 ↓QES will continue to share information about Kiro, so stay tuned!

We aim to become Japan's #1 resource for Kiro! Our mission is to evangelize this technology by empowering end-users with top-tier education and technical support.

If you have requests like "I want to know more about this service" or need help with "AWS environment construction/migration," please feel free to contact us via our inquiry form. For complex inquiries, a sales representative will contact you directly. Also, please check out the following links!

<QES Related Solutions/Blogs>

<The AWS Security Promotion Consortium (ASC-J), in which QES participates, has released a white paper>

※Amazon Web Services, the "Powered by Amazon Web Services" logo, and other AWS trademarks used in this blog are trademarks of Amazon.com, Inc. or its affiliates in the United States and other countries.