Coding agents need more than the current user request. They need stable project knowledge: where code lives, how tests run, which libraries are preferred, what architectural decisions are already settled, and which constraints should override a tempting quick fix. If that knowledge only exists in chat history, every new session starts cold and every long session risks losing the most important context under irrelevant output.
Repository steering files solve this by storing durable agent guidance as plain text files near the code or in a user-level configuration directory. Kiro’s steering model is one implementation: workspace files live under .kiro/steering/, global files can live under ~/.kiro/steering/, foundational files describe product, technology, and structure, and inclusion modes decide when each file enters the model context. Similar patterns appear in AGENTS.md and CLAUDE.md workflows.
The transferable technique is to treat agent guidance as versioned context infrastructure. A good steering system separates universal rules from file-specific rules, keeps heavy context out of the default path, makes precedence explicit, and links guidance to real repository files when possible. This is context engineering for software agents: curating the right durable instructions before the model plans, edits, or runs commands.
Scope defines where a steering file applies. Workspace scope is checked into or colocated with a repository and should describe that repository’s stack, layout, style, and workflows. Global scope applies across many repositories and should hold personal defaults or organization-wide standards. Team scope distributes a shared global baseline through device management, internal templates, or a central repository.
Multiple instruction sources can conflict. A global preference might say to use one test runner, while a repository requires another. The steering system must define precedence so the agent does not improvise. A common rule is that workspace guidance overrides global guidance because local repository truth is more specific.
Inclusion mode controls when a steering file enters context. Always-on files are suitable for core constraints. File-match files activate only for relevant paths. Manual files load only when explicitly requested. Auto-included files include a short description that lets the agent decide when they matter. Inclusion is the main mechanism for balancing consistency against context bloat.
Steering files are powerful because they persist, but every included token competes with source code, test output, tool results, and the current task. The goal is not to include everything; it is to include the smallest set of high-authority guidance needed for the next decision.
The foundation layer gives the agent a compact map of the project. Kiro names three useful starting files: product purpose, technology stack, and project structure. Other systems can use different filenames, but the split is valuable because each document answers a different question: why the system exists, what tools it uses, and where changes belong.
.kiro/
steering/
product.md # Product goals, users, business constraints
tech.md # Runtime, framework, database, testing, deployment
structure.md # Directory map, naming rules, module boundariesSteering files can use front matter to define activation behavior. A TypeScript component guide should not consume context during a database migration, but it should be available automatically when editing component files. Inclusion metadata lets the harness load it only when a path or request matches.
---
inclusion: fileMatch
fileMatchPattern: ["src/components/**/*.tsx", "src/components/**/*.ts"]
---
# Component Patterns
Use controlled components for form fields.
Keep component-local styles in the co-located CSS module.
Prefer existing design tokens over ad hoc color values.Some guidance should point at canonical files instead of duplicating them. If the OpenAPI spec, deployment manifest, or design-token source is already in the repository, the steering file can reference it so the agent grounds decisions in current artifacts. This reduces drift between the guide and the source of truth.
# API Workflows
Before changing handlers, inspect:
#[[file:api/openapi.yaml]]
#[[file:src/server/routes.ts]]
Generated clients must be rebuilt with:
npm run generate:clientsA new coding agent can waste many tool calls rediscovering the repository layout. A structure steering file shortens orientation by listing key directories, ownership boundaries, generated-code locations, and commands for targeted verification. This is especially useful in monorepos where the same language appears in multiple unrelated packages.
Teams often have conventions that are obvious to humans but invisible to a model: repository-specific error types, logging wrappers, dependency-injection patterns, migration conventions, or UI component idioms. Steering files make these conventions explicit so generated code fits the existing system instead of introducing parallel patterns.
Some tasks require heavy context only occasionally. Security review, release migration, API compatibility work, accessibility checks, and performance debugging can each have focused steering files. Manual or auto inclusion keeps that specialized guidance available without paying for it in every interaction.
Each steering file should cover one domain. A single giant file that mixes product goals, database rules, frontend patterns, release commands, and security policy becomes hard to maintain and expensive to include. Focused files also make activation easier: a file-match pattern can include the frontend guide only for frontend paths.
.kiro/steering/
api-rest-conventions.md
testing-unit-patterns.md
components-form-validation.md
database-migrations.md
security-review.mdUseful guidance tells the agent what to do, when to do it, and why. “Use good tests” is too vague. Better guidance identifies the command, the expected scope, and the failure mode it catches. Include small examples when the rule is easy to misapply.
# Database Migrations
When adding a required column:
1. Add it nullable first.
2. Backfill existing rows in a separate migration.
3. Add the NOT NULL constraint after the backfill.
This avoids long table locks and prevents deploys from failing on existing data.Steering files influence future patches, so changes to them deserve the same care as code changes. Review whether a new instruction is too broad, conflicts with another file, leaks sensitive data, or encodes a temporary workaround as a permanent rule. Remove stale guidance when the repository changes.