Steering Files

Steering files are markdown files that give Kiro persistent knowledge about your project. Instead of repeating the same explanations every session, steering files ensure consistent behavior across all interactions.

Where to Place Steering Files

Steering files have two scopes:

Scope	Location	Applies To
Workspace	.kiro/steering/	Current project only
Global	~/.kiro/steering/	All projects

When workspace steering conflicts with global steering, workspace takes precedence.

The Three Foundational Files

Every project should have these three core files:

product.md — Business Context

# Product Overview

## Purpose
An e-commerce platform for handmade crafts.

## Target Users
- Craft artisans selling their products
- Customers looking for unique handmade items

## Key Features
- Product listing with image galleries
- Shopping cart and checkout
- Seller dashboard with analytics

## Business Goals
- Support 1,000 active sellers by Q3
- Achieve 99.9% uptime for checkout flow

tech.md — Technology Stack

# Technology Stack

## Frontend
- React 19 with TypeScript
- Tailwind CSS for styling
- Vite for build tooling

## Backend
- Node.js with Express
- PostgreSQL for data storage
- Redis for caching

## Constraints
- All API responses must be under 200ms
- Support for IE11 is NOT required
- Use ESM modules exclusively

structure.md — Code Organization

# Project Structure

## Directory Layout
- `src/components/` — React UI components
- `src/hooks/` — Custom React hooks
- `src/api/` — API client functions
- `src/pages/` — Route page components
- `src/utils/` — Shared utility functions

## Naming Conventions
- Components: PascalCase (e.g., `UserProfile.tsx`)
- Hooks: camelCase with `use` prefix (e.g., `useAuth.ts`)
- Utils: camelCase (e.g., `formatDate.ts`)
- Tests: `*.test.ts` colocated with source files

Custom Steering Files

Add project-specific rules and guidelines as additional steering files:

.kiro/steering/
├── product.md
├── tech.md
├── structure.md
├── api-standards.md
├── testing-standards.md
├── security-policies.md
└── code-conventions.md

AGENTS.md Support

Kiro CLI supports the AGENTS.md standard. Place an AGENTS.md file in ~/.kiro/steering/ or your workspace root and it loads automatically.

Important Note for Custom Agents

Steering files are NOT auto-loaded for custom agents. You must explicitly include them via the resources field:

{
  "resources": ["file://.kiro/steering/**/*.md"]
}

Best Practices

Principle	Description
Single responsibility	One domain per file
Descriptive names	Content should be clear from filename
Explain "why"	Include reasoning, not just rules
Include code examples	Concrete examples improve accuracy
No secrets	Never include API keys or passwords
Review process	Treat steering files like code

Context Management

Kiro CLI provides four distinct approaches to context management. Choose based on task requirements.

The Four Approaches

Method	Token Usage	Persistence	Best For
Agent Resources	Always (every request)	Cross-session	Essential project files
Skills	On demand	Cross-session	Large guides, references
Session Context	Always (every request)	Current session only	Temporary files, experiments
Knowledge Bases	Only when searched	Cross-session	Large codebases, extensive docs

Choosing the Right Approach

flowchart TB
    Start["Need to add context"] --> Size{"Over 10MB or<br/>thousands of files?"}
    Size -->|Yes| KB["Knowledge Base"]
    Size -->|No| Frequency{"Needed in every<br/>conversation?"}
    Frequency -->|Yes| Persistent{"Needed across<br/>sessions?"}
    Frequency -->|No| Session["Session Context"]
    Persistent -->|Yes| AgentRes["Agent Resources"]
    Persistent -->|No| Session
    style KB fill:#ef4444,color:#fff
    style AgentRes fill:#3b82f6,color:#fff
    style Session fill:#22c55e,color:#fff
    style Start fill:#8b5cf6,color:#fff

Session Context Operations

Temporarily add files to your context:

> /context add README.md

> /context add docs/*.md

> /context show

> /context remove README.md

> /context clear

/context show displays token usage breakdown by category and individual file.

Context Window Management

Context files consume tokens on every request regardless of whether they're used. Even unused files in context cost tokens, so management matters.

Limit: Context files are capped at 75% of the model's context window. Excess files are automatically excluded.

Conversation Compaction

Long conversations consume context window space. Compact manually or automatically:

> /compact

Older messages are summarized while recent ones are preserved.

Auto-compaction settings:

# Minimum message pairs to retain (default: 2)
kiro-cli settings compaction.excludeMessages 3

# Minimum context window % to retain (default: 2)
kiro-cli settings compaction.excludeContextWindowPercent 5

# Disable auto-compaction
kiro-cli settings chat.disableAutoCompaction true

Context Usage Indicator

An experimental feature showing real-time context window usage as a percentage:

kiro-cli settings chat.enableContextUsageIndicator true

Color-coded status:

• Green: Under 50% (plenty of room)
• Yellow: 50-89% (caution)
• Red: 90-100% (compaction recommended)

Team Steering Distribution

Git Repository Sharing

Include steering files in .kiro/steering/ under version control:

.kiro/
└── steering/
    ├── product.md
    ├── tech.md
    ├── structure.md
    ├── api-standards.md
    └── security-policies.md

Everyone who clones the repository gets the same steering files.

MDM / Group Policy

Distribute global steering (~/.kiro/steering/) via MDM solutions or group policies for organization-wide consistency.

Summary

Topic	Details
Steering files	Markdown files in .kiro/steering/
Foundational files	product.md, tech.md, structure.md
Scopes	Workspace (priority) and Global
Context management	Agent Resources, Skills, Session Context, Knowledge Bases
/context	Session context operations
/compact	Manual conversation compaction
Team distribution	Git repository sharing, MDM

In Day 8, you'll learn about MCP integration and knowledge management.