Kiro Steering Files — Complete Guide

Every time you start a new session with an AI coding assistant, you face the same problem: it knows nothing about your project. You find yourself re-explaining the same architecture decisions, naming conventions, and technology choices over and over again. Kiro solves this with steering files.

---

What Is a Steering File?

A steering file is a plain Markdown document that lives inside your project and gives Kiro persistent, always-on context about your codebase. Whatever you write in a steering file, Kiro reads it automatically at the start of every session — no prompting required.

Think of it as the onboarding document you’d hand to a new developer joining your team:

• “We use Clean Architecture — business logic never goes in controllers”
• “All API responses follow this envelope format”
• “Database columns are snake_case; C# properties are PascalCase”
• “We use FluentValidation, not DataAnnotations”

Without steering, Kiro defaults to generic patterns that may not match your project at all. With steering, it codes in your style, respects your constraints, and speaks your domain language from the very first message.

---

Where Steering Files Live

All steering files belong in the .kiro/steering/ folder at the root of your project:

your-project/
├── .kiro/
│   ├── steering/
│   │   ├── product.md       ← what the project is and who it's for
│   │   ├── tech.md          ← languages, frameworks, key packages
│   │   └── structure.md     ← folder layout, architecture, conventions
│   ├── hooks/
│   └── mcp.json
├── src/
└── ...

Every .md file in this folder is loaded automatically. You can have as many files as you need — splitting by topic (product, tech, structure, coding-style) keeps each file focused and easy to update.

---

The inclusion Property

Each steering file can include a frontmatter property that controls when Kiro uses it:

---
inclusion: always
---

# Your steering content here

Value	Behaviour
always	Loaded in every session — use for core context like product overview and tech stack
manual	Only loaded when you explicitly reference it — useful for rarely-needed reference docs

If you omit the property, Kiro defaults to always. Start with always for all your steering files until you have a reason to change it.

---

How to Create Steering Files

You have two options: let Kiro generate them automatically from your existing codebase, or write them manually from scratch.

---

Option 1 — Auto-Generate (Recommended for Existing Projects)

If you already have a codebase, Kiro can analyse it and write your steering files for you. This is the fastest way to get started.

Step 1 — Open the Kiro panel and click Generate Steering Docs

In the left sidebar, click the Kiro icon to open the agent panel. Under AGENT STEERING & SKILLS, click Generate Steering Docs ①.

Step 2 — Kiro analyses your project

Kiro scans your files, reads your folder structure, package configs, and existing code. You will see it working in the chat panel as it builds an understanding of your project.

Step 3 — Kiro creates the steering files

Once analysis is complete, Kiro generates the steering files and writes them to .kiro/steering/. You’ll see a summary of what was created and what each file covers. The files also appear immediately in the sidebar under AGENT STEERING & SKILLS → Workspace.

For the BankyBluePrints project, Kiro generated three files:

• product.md — what the site is, its purpose, audience, and UX principles
• tech.md — Astro + Starlight stack, styling approach, local and deployment setup
• structure.md — folder layout and the two page types (content docs vs custom quiz pages)

---

Option 2 — Create Manually (New Projects or Custom Needs)

For new projects, or when you want precise control over what Kiro knows, create the files by hand.

1. Create the folder: mkdir -p .kiro/steering
2. Create a new .md file: .kiro/steering/tech.md
3. Add your frontmatter and content (see examples below)
4. Save — Kiro picks it up immediately

---

Viewing and Editing Steering Files

You can open any steering file directly in the editor by clicking it in the sidebar under AGENT STEERING & SKILLS → Workspace. The file opens as a standard Markdown document — edit it like any other file.

The generated product.md for BankyBluePrints includes the site overview, its purpose (concise, production-focused technical guides), the target audience (developers and software architects), and deployment information. This is exactly the kind of context Kiro needs to give useful, project-aware responses.

---

Refining Steering Files

Auto-generated steering files are a great starting point, but they won’t always capture every nuance of your project. You should review and refine them after generation.

You can ask Kiro directly to update a steering file: open a chat session and say “Update the product steering file to include our new API documentation section.” Kiro reads the existing file, makes the targeted changes, and shows you the diff for approval.

---

What to Put in Steering Files

Product Context

Tell Kiro what the project is, who it’s for, and what it is NOT:

---
inclusion: always
---

# Product: OrderFlow

OrderFlow is a B2B order management platform for wholesale distributors.
Customers (distributors) place orders. Suppliers fulfil them.

## Key Concepts
- **Distributor** — the buying organisation (our customer)
- **Supplier** — the selling organisation (their vendor)
- **Order** — a purchase order from distributor to supplier

## What We Are NOT
- Not an e-commerce storefront (no consumer shopping cart)
- Not a payment processor (payments happen outside the system)

Technology Stack

List languages, frameworks, and key packages — especially non-obvious choices:

---
inclusion: always
---

# Technology Stack

## Backend
- ASP.NET Core 8 Web API — C# 12
- Entity Framework Core 8 with SQL Server
- MediatR for CQRS pattern
- FluentValidation — NOT DataAnnotations
- Serilog for structured logging

## Frontend
- React 18 with TypeScript
- TanStack Query for server state
- Tailwind CSS — no inline styles, no CSS modules

## Testing
- xUnit + Testcontainers (real SQL Server, not mocked)
- Playwright for end-to-end tests

Architecture Conventions

Document your patterns and — critically — your rules:

---
inclusion: always
---

# Architecture

We follow Clean Architecture with four layers:

Presentation (API controllers) ↓ Application (commands, queries, handlers) ↓ Domain (entities, value objects) ↓ Infrastructure (EF Core, external services)

## Rules
- Controllers call ONLY MediatR.Send() — no business logic in controllers
- Domain entities never reference EF Core or infrastructure
- Application layer never references HttpContext
- Use the Result pattern for expected failures — not exceptions

Coding Standards

Naming conventions, API formats, do’s and don’ts:

---
inclusion: always
---

# Coding Standards

## Naming
- Classes, methods, properties: PascalCase
- Private fields: _camelCase
- Database columns: snake_case (EF Core mapping translates to PascalCase)

## API Response Envelope
All endpoints return this format:
{
  "success": true,
  "data": { ... },
  "errors": []
}

## Do
- Use `record` types for DTOs and value objects
- Prefer `IReadOnlyList<T>` over `List<T>` for return types

## Do NOT
- Never use `dynamic`
- Never concatenate strings in SQL — always parameterised queries or EF Core
- Never swallow exceptions with empty catch blocks

---

Steering vs Specs vs Hooks

These three Kiro features are often confused. Here’s how they differ:

	Steering	Specs	Hooks
Purpose	Persistent project context	Plan for a specific feature	Automate actions on events
Scope	Whole project, always active	One feature or task	Specific trigger events
When active	Every session	During that spec’s implementation	When the event fires
Lives in	.kiro/steering/	.kiro/specs/	.kiro/hooks/

• Steering answers: “What should Kiro always know about this project?”
• Specs answer: “What should Kiro build right now?”
• Hooks answer: “What should Kiro do automatically when X happens?”

---

Best Practices

Be explicit, not descriptive. “We follow Clean Architecture” is vague. “Controllers call only MediatR.Send() — no business logic in controllers” is actionable. Kiro needs instructions it can directly apply.

Include negative guidance. “We do NOT use X” is as important as “we use Y”. Without it, Kiro defaults to popular patterns that may not match your project.

Split by topic. One focused 80-line file per concern is easier to update than a single 400-line mega-file.

Use code examples. A snippet showing the correct pattern is worth more than a paragraph describing it.

Keep it current. When your team makes an architectural decision, add it to the relevant steering file the same day. Stale steering is worse than no steering.

Commit it to git. The .kiro/steering/ folder should be in source control so the whole team shares the same context.

---

Minimal Starter Setup

If you’re adding steering for the first time, start with just two files:

.kiro/steering/tech.md — your languages, frameworks, and key packages, especially non-obvious choices.

.kiro/steering/conventions.md — naming rules, the patterns you always follow, and the things you never do.

These two files alone will eliminate most of the “Kiro used the wrong pattern” frustrations from day one.