Steering Files

Steering files are markdown files that Kiro loads into context automatically, every session. They’re how you give the agent durable knowledge about your project instead of repeating yourself in every prompt. Good things to put in a steering file:

• The purpose of the project: what it does and who it’s for.
• The technologies used: language, frameworks, and key libraries.
• Organizational coding standards: conventions that go beyond general language style, like how your team handles money, errors, naming, or comments.

Steering files live under .kiro/steering/ in your project (or ~/.kiro/steering/ for personal, machine-wide rules). Each file’s YAML frontmatter carries an inclusion field that tells Kiro when to load it — mark a file inclusion: always and it joins every conversation.

When a steering file loads

The inclusion field controls when a file enters context. This matters because anything loaded on every turn costs context whether it’s relevant or not. There are three modes:

inclusion	When the file loads	Use it for
always	Every turn of every session	Project-wide rules that always apply
fileMatch	Only when a file matching fileMatchPattern is in context	Rules scoped to one part of the codebase
manual	Only when you reference it with # in a prompt	Occasional context you pull in by hand

A fileMatch file declares the glob it reacts to:

.kiro/steering/test-conventions.md

---
inclusion: fileMatch
fileMatchPattern: '**/*.Tests.cs'
---

# Test conventions

- Name the test class after the class under test, like `MoneyTests`.
- Use Arrange-Act-Assert, with one descriptive method per case.

That file stays out of context until you open or reference a matching *.Tests.cs file. Then it loads, whole, automatically.

`fileMatch` is conditional inclusion, not progressive disclosure

A fileMatch matcher loads the entire file the moment a matching path is in context. That’s one stage, triggered by your file tree. It’s different from a skill’s progressive disclosure (covered later), where the agent always sees a short description and pulls in the full body only when your request matches. Same goal, which is to not pay for context you aren’t using, reached two different ways. Steering scopes by which files you’re touching, a skill discloses by what you’re asking for.

Prose vs. rules

The best steering files read less like documentation and more like a checklist: “Do this, not that.” Agents follow concrete, imperative rules far better than paragraphs of explanation. For anything specific, a short before/after example beats a description.

Exercise: teach Kiro your money convention

The budget tracker follows one firm rule throughout its code: money is integer cents (long), never decimal or float, and every money value shown to a user goes through Money.Format (see Money.cs). That’s a project decision. Nothing forces it, and the agent only follows it if it happens to notice. A steering file turns “happens to notice” into “always.”

1. Add a feature with no steering

Open the budget tracker in Kiro and ask it to extend the summary:

Add a GET /summary/by-category endpoint that returns each category
and how much was spent in it this month.

Run it:

curl "http://localhost:5000/summary/by-category"

What to notice

Look at how the amounts come back. There’s a real chance they don’t match the rest of the app. You might get raw cents like 60000, a bare decimal, or some inline ToString("C"), instead of the "$600.00" strings /transactions and /summary return. The agent had a coin-flip at your convention, because it was never written down. (If it happened to match, good. Read on: the point is turning that coin-flip into a guarantee.)

2. Write the rule, in your own words

Don’t paste a prepared file. In one or two imperative sentences, write the convention the way you’d say it to a new teammate:

.kiro/steering/money.md

---
inclusion: always
---

# Money

- All monetary amounts are integer **cents** (`long`). Never use `decimal`, `double`, or `float` for money.
- Every money value returned from an API or shown to a user is formatted with `Money.Format`.

Keep it terse and imperative. “Do this, not that” lands far better than a paragraph.

`always`, on purpose

This rule applies anywhere money is touched, so it gets inclusion: always and loads every turn. Set the mode explicitly — in the CLI a steering file isn’t pulled in until you do. Contrast it with a rule scoped to one area, which belongs in a fileMatch file (above). One topic per file, and keep always files short: they cost context on every turn.

3. Predict, then regenerate

Before you run anything: what will change in the /summary/by-category output once the rule is loaded? Say it out loud or jot it down.

1. Save the rule and restart Kiro so it loads.

   • Directory.kiro/

     • Directorysteering/

       • money.md

2. Confirm it’s in context:

   /context show

   You should see money.md listed. If not, check it’s directly under .kiro/steering/, ends in .md, and has the inclusion: always frontmatter at the top.

3. Remove the previous attempt (delete the endpoint, clear the context) and ask for the exact same feature again.

4. Compare against your prediction

curl "http://localhost:5000/summary/by-category"

What changed

The amounts now come back as "$600.00" strings via Money.Format, consistent with the rest of the app, and you’ll see the agent reach for Money.Format in its reasoning. Same model, same prompt. The only difference is the rule you gave it.

Steering shifts the odds; it doesn't enforce

A steering file makes the convention far more likely, but the model still writes the code, so it’s not a guarantee. That’s why the rule is short and concrete. This same money convention returns in Act 3, where a guardrail (a hook) can make part of it genuinely non-negotiable.