Steering

Steering files are Markdown documents that give Kiro permanent knowledge about your project, so the agent starts every session already knowing your stack, your conventions, and your constraints. They are the difference between an assistant you brief for five minutes each morning and a teammate who read the onboarding binder once and never forgot it.

What is steering?

Steering is context the agent loads automatically, written by you, stored in your repository. Kiro recognizes three foundational files and includes them in every interaction by default:

• product.md: what the product is, who it serves, what the business goals are
• tech.md: frameworks, libraries, tools, technical constraints
• structure.md: file organization, naming conventions, architecture patterns

Beyond those three you add whatever your project needs: an API conventions file, a testing policy, a “how we handle money” file. Each one is plain Markdown and belongs in code review like any other file.

Why it exists

Without steering, every conversation starts from zero. You explain that the project uses PostgreSQL 16, that errors return a specific JSON shape, that the mobile team generates a client from docs/api.md. Then you close the session, and the next one starts from zero again. The agent is not forgetful in an interesting way; it simply has no place to keep long-lived facts.

Steering is that place. It also solves a subtler problem: consistency across people. When the rule lives in a committed file rather than in the prompt habits of whoever is at the keyboard, every teammate’s agent follows the same rule, and changing the rule is a pull request instead of an announcement.

How it works

Where files live. Workspace steering goes in .kiro/steering/ and personal steering in ~/.kiro/steering/. Kiro’s configuration documentation puts steering in the group that merges across scopes, so a global file and a project file both apply rather than one silently replacing the other. KIRO_HOME relocates the global directory if you want separate profiles.

Inclusion modes. Not every rule belongs in every conversation, and a steering folder that loads in full on every turn is just an expensive way to waste context. YAML front matter, which must be the very first content in the file, controls when each file loads:

Mode	Loads when
always	Every interaction. The default
fileMatch	The conversation involves files matching fileMatchPattern
manual	You reference it explicitly with #steering-file-name
auto	Kiro matches your request against the file’s name and description

A conditional file looks like this:

---
inclusion: fileMatch
fileMatchPattern: "src/api/**"
---

fileMatchPattern also accepts a list of globs. In auto mode you add name and description fields so Kiro can tell when the file is relevant.

What a good file looks like. Short, single-domain, and explicit about the reason:

# API conventions

- Every endpoint validates input before touching the database.
- Errors return the shape { "error": { "code", "message" } }, never bare strings.
- New endpoints need an entry in docs/api.md. Why: our mobile team
  generates their client from that file.

The why is doing real work there. A rule with a reason survives contact with a situation its author did not anticipate; a bare rule gets applied literally in a case where it makes no sense.

AGENTS.md. Since CLI v2.18.0 and IDE v1.0.309 (August 2026), Kiro loads AGENTS.md files as steering context, and it finds them anywhere in the workspace tree rather than only at the root. Two rules make them different from .kiro/steering/ files. They do not support inclusion modes and are always included. And they can be nested, so services/api/AGENTS.md and packages/ui/AGENTS.md can each carry instructions for their own directory. A global AGENTS.md in ~/.kiro/steering/ works too. The two systems are complementary: each AGENTS.md loads alongside your other steering files. Kiro’s documentation does not state a precedence rule between them, so this site does not claim one.

Common mistakes

One giant file. Dumping the wiki into steering.md means every conversation pays for every rule, and the rules that matter get buried. The fix: one domain per file, and fileMatch or auto for anything that is not universally relevant.

Secrets in steering. API keys, internal hostnames, and customer names in a committed Markdown file are a leak with extra steps, and the agent may repeat them back in output. The fix: never put credentials in steering. Use environment variables through MCP configuration instead, and keep sensitive paths out of reach with .kiroignore.

Rules with no reason. “Always use the repository pattern” gets applied to a two-line script. The fix: one sentence of why per rule.

Steering that has quietly gone stale. A file that still describes last year’s architecture actively misleads the agent, which trusts it. The fix: review steering when you review architecture, and delete rules you no longer enforce.

Where it fits

Steering is the standing context underneath everything. Specs rely on it so requirements do not have to restate your stack. Powers ship steering of their own: a POWER.md is a steering file that tells the agent which MCP tools it now has and when to use them. Custom agents can be pointed at particular resources so a scoped agent reads a scoped slice of your knowledge. And skills are the on-demand counterpart: steering describes the project, a skill describes how to do a job.

Every surface reads steering, and because it lives in the repository it travels into cloud sessions automatically. Since September 1, 2026, cloud configuration sync also pushes steering created in Kiro Web down to local IDE and CLI sessions, where it appears as a read-only preview and is edited in the browser.

Learn more

• Write your first steering file is the ten-minute version.
• AGENTS.md as steering covers the cross-tool option.
• Advanced Tutorial uses steering on a real multi-file change.
• Cheat Sheet lists the modes and paths in card form.
• Common Mistakes has more on steering that backfires.