
Steering File Design Patterns: What to Actually Write
You clicked Generate Steering Docs, got product.md, tech.md, and structure.md, and Kiro's output barely changed. The files aren't the problem — what's in them is. This post covers the patterns that separate steering which changes what Kiro generates from steering that quietly burns context, the one test that should decide every line you keep, and the inclusion-mode decisions most teams get wrong.
The Blank File Problem
Part 1 argued steering files are the linchpin of AI-DLC. Part 2 showed you three ways to get them across an enterprise. Both left the same question unanswered: what do you actually write in them?
Here's the failure I see most. A developer opens the Steering panel, clicks Generate Steering Docs, and Kiro produces the three foundation files —
product.md , tech.md , and structure.md . These are included in every interaction by default , which sounds like exactly what you want. The developer skims them, sees a reasonable description of their project, and gets back to work.Then the output doesn't change much. And they conclude steering doesn't work.
The foundation files are a scaffold, not a finished artifact. I said as much in Part 1 — "not perfect on Day 1" — and then never said what Day 2 looks like. This post is Day 2.
The One Test
Start here, because every pattern below is a corollary.
If a line in your steering file describes something Kiro could work out by reading your code, delete it. What cannot be inferred is what steering is for.
That sounds obvious until you apply it. Most generated
structure.md files describe the directory layout. Kiro can see the directory layout. What it cannot see is why the layout is that way, which of those boundaries are load-bearing, and which one directory deliberately breaks the pattern.There's now hard evidence behind this, and it comes from upstream of Kiro rather than from outside it. Kiro runs on Claude models, and in July Anthropic published that they removed over 80% of Claude Code's system prompt for their newest models "with no measurable loss on our coding evaluations." Their word for the problem they'd created was overconstraining. Their own transcripts carried instructions that contradicted each other inside a single request — one source saying "leave documentation as appropriate" while another said "DO NOT add comments." The model could still infer intent, but it burned reasoning resolving the conflict before it could start the work.
That finding is not an argument against steering. It's an argument about which 20% is load-bearing. The 80% they cut was scaffolding for weaker models, left standing after the building went up. As the models underneath Kiro get better at reading your code, the value of telling them what your code already says trends to zero — and the cost of telling them anyway goes up, because every redundant line competes for attention with the line that mattered.
What Actually Belongs In There
If you want to know what experienced teams put in these files, there's now data.
Researchers analyzed 328 agent configuration files from public projects to catalog which engineering concerns developers specify. The dominant one by a wide margin was architecture — the structural decisions the agent is expected to honor. A second study of 253 agent manifests across 242 repositories found content dominated by operational commands, technical implementation notes, and high-level architecture.
Both studies looked at
CLAUDE.md files, which is the format with the most public data. The mechanism is identical to Kiro steering, and the bridge is direct: Kiro natively supports the AGENTS.md standard alongside its own steering files, so the same authoring question applies whichever format you use. One caveat worth knowing — AGENTS.md files don't support inclusion modes and are always included, which makes everything in Pattern 4 more important, not less.The convergence is what matters. Across hundreds of real projects, the thing developers reach for these files to communicate is not style. It's structure and intent — the decisions that live in senior engineers' heads and nowhere in the source tree. Which is precisely what survives the deletion test.
Five Patterns
Pattern 1: Specific Beats Aspirational
"Write secure code" changes nothing. Kiro already believes it writes secure code.
Aspirational (delete) | Specific (keep) |
|---|---|
Handle errors properly | Handlers return Result types; we never throw across a service boundary. Thrown exceptions bypass our error-mapping middleware and surface as 500s. |
Follow security best practices | All DynamoDB access goes through repositories/. Never construct a client inside a handler — handlers have no IAM context of their own. |
Write good tests | Every bug fix starts with a failing test that reproduces the bug. If you can't write the failing test, you haven't found the bug yet. |
The left column is a sentiment. The right column changes what gets generated.
There is a live tension here worth naming, because you'll hit it. Kiro's own documentation recommends providing examples and before/after comparisons. Anthropic's newest guidance says examples can constrain a model into a narrower exploration space than you intended. Both are right, at different altitudes. Use an example when the shape of the output is what matters — a canonical error response, a repository method signature. Use a rule when the judgment is what matters, and aim it at the reasoning rather than the syntax.
Anthropic's own rewrite is the cleanest demonstration I've seen. The old prompt said:
In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max.
The new one says:
Write code that reads like the surrounding code: match its comment density, naming, and idiom.
Shorter, and it generalizes to cases nobody enumerated. That's what specificity buys when you point it at the right thing.
Pattern 2: Spend Your Tokens on Gotchas
Kiro's docs put this as "include context — explain why decisions were made, not just what the standards are." I'd push further: after a brief statement of what the repo is for, spend nearly all your remaining tokens on gotchas.
A gotcha is anything that surprised a new engineer. The migration that has to run before the seed script. The service that looks stateless but caches in module scope. The suite that passes locally and fails in CI on timezone. The one directory where the usual pattern deliberately doesn't apply, and why.
None of that is inferable. All of it is expensive to rediscover. This is the highest-value content you can put in a steering file, and it's what most teams leave out — because it's tacit, and writing it down feels like admitting your codebase has warts.
Your codebase has warts. Write them down.
Pattern 3: Anti-Patterns Are First-Class Content
Telling Kiro what not to do is often higher leverage than telling it what to do, and the reason is structural. Training data is full of patterns that are perfectly reasonable in general and wrong in your codebase. Left alone, an agent will produce them confidently, because everywhere else on earth they're correct.
This is the actual mechanism behind the complaint I opened Part 1 with — that agents "default to generic patterns." They aren't defaulting to bad patterns. They're defaulting to common ones. If your team moved off a common pattern deliberately, the only way Kiro learns that is if you say so.
Name the pattern, then name the reason:
Don't add a new field toUserProfile. It's serialized into three caches with independent TTLs, and adding a field silently breaks deserialization on the older two. New user attributes go inUserAttributeswith an explicit migration.
The reason isn't decoration. It's what lets Kiro generalize correctly to the case you didn't write down — which it will hit constantly, because you cannot enumerate your way to completeness.
Pattern 4: Scope Aggressively, and Know Your Surface
Part 1 introduced Kiro's inclusion modes and never told you how to choose. Closing that gap:
Mode | Front matter | Use it when |
|---|---|---|
always (default) | inclusion: always | The rule genuinely applies to every interaction |
fileMatch | inclusion: fileMatch plus fileMatchPattern | The rule applies to a knowable subset of files |
auto | inclusion: auto plus name and description | Context-heavy guidance Kiro should pull when your request matches |
manual | inclusion: manual | Specialized workflows you invoke with #filename or / |
The front matter has to be the very first content in the file — no blank line above it, or it won't parse.
Two things people get wrong. First,
auto requires both name and description , and the description is the routing decision — Kiro matches your request against it. A vague description means the file loads when it shouldn't, or doesn't load when it should.Second, and this is the one that bites: on Kiro CLI, inclusion modes are not currently supported. Every file in
.kiro/steering/ loads automatically. If your team runs the CLI in CI or headless pipelines — exactly the autonomous scenario Part 2 was about — your careful scoping evaporates and everything loads on every invocation. Plan your always set as though it were your whole set, because on that surface it is. The same applies to AGENTS.md on any surface, and to custom agents, which don't load steering unless you add it explicitly:{ "resources": ["file://.kiro/steering/**/*.md"]}
With that context, here's the test: before setting anything to
always , ask whether there is any subset of files it applies to. If there is, use fileMatch .API conventions aren't universal. They're universal within your routes directory. Test standards belong on your test glob. The set of rules that genuinely applies to every request is much smaller than it feels while you're writing them.
This matters more than a token count suggests, and it's where the overconstraining finding cuts deepest. Every
always file imposes its cost on every interaction regardless of relevance, and the cost isn't only budget — two files that each made sense alone can contradict each other once both are loaded, and Kiro spends reasoning reconciling them instead of doing the work.Pattern 5: Point at the Source of Truth, Don't Copy It
Steering rots. The fix is to stop duplicating and start referencing.
Kiro supports live file references inside steering files:
#[[file:api/openapi.yaml]]
Your API contract, your example env file, your canonical component — reference them instead of describing them, and the steering can't drift from the code, because it is the code.
The same principle applies one level up. If a rule is enforceable by a linter, make it a lint rule, then generate the steering file from the lint configuration as a build step and commit it with a header saying it's generated. One source of truth, mechanical enforcement, and Kiro stops producing code your own CI is about to reject.
The corollary is the anti-pattern: hand-writing steering that duplicates your linter is pure waste. Telling an agent to use two-space indentation when your formatter runs on save is a rule that cannot fail and therefore cannot help. Spend those tokens on gotchas instead.
Steering Anti-Patterns
The failure modes are consistent enough to name. I've seen every one of these, usually around week six of an adoption.
The wiki dump. Someone pastes the existing standards page in wholesale. Four thousand words, half of it about a framework the team migrated off, set to
always . This is how you manufacture the overconstraining problem in a single file.The aspiration list. Rules describing the codebase the team wishes it had. Kiro now generates code matching the aspiration, which doesn't match the code it has to integrate with. A wrong instruction is worse than a missing one, because a missing instruction leaves the agent free to read the surrounding code and match it.
The stale file. Steering that contradicted the code six months ago and contradicts it more now. Two conflicting signals and no way to know which is wrong. Pattern 5 exists to prevent this.
The everything-always file. No scoping, so every request pays for every rule. And if you're on the CLI, this is the default state rather than a mistake — which is why it needs deliberate management there.
The unowned file. Nobody's job to update it, so nobody trusts it, so nobody updates it. Kiro's own guidance is to treat steering changes like code changes and require reviews. Part 2's argument was that steering is a versioned, reviewable artifact; that only holds if a human is accountable for it.
One more, and it's the serious one: never put credentials, secrets, customer data, or PII in a steering file. Kiro's own guidance spells out why — steering files are plain text markdown, they get shared and synced constantly, and they are not encrypted by default. Add the distribution mechanisms from Part 2 and those files land in agent context on machines you don't administer. Reference the secret manager. Never the secret.
So How Long Should It Be?
Shorter than you think, and trending shorter.
I won't quote a token ceiling, because the honest answer is that the number moves with every model release — the 80% cut is the evidence. What holds across releases is the ratio. A focused file of a few dozen lines routinely beats a sprawling one of several hundred, because every token you spend competes with the code, the conversation, and the tool output Kiro also needs.
Treat your
always set as a budget rather than a limit. If a new rule matters enough to load universally, something else probably needs to move to fileMatch .Then let the codebase tell you when to write more. The best maintenance trigger I know: when you leave the same code review comment twice, you've found a steering rule you haven't written down. Kiro Web now has a native version of this — comment guidance on a pull request and the agent carries it forward across your repositories. The Kiro team gives the same advice for building a steering set in the first place: expand gradually and let the files grow organically as you notice repetition , rather than authoring the whole thing on day one.
Steering that grows from observed friction stays useful. Steering written speculatively in a planning meeting is where governance turns into overhead, which is the bureaucratic-bottleneck risk I flagged in Part 2.
Getting Started: Three Moves
1. Run the deletion test on what you have. Line by line, ask whether Kiro could work it out from the code. Delete what fails. Most teams cut a third on the first pass and the remainder gets more effective, because you've removed instructions that were competing with the ones you meant.
2. Mine your last ten code reviews. The comments you leave repeatedly are your real conventions, already validated by the fact that you keep having to say them. Turn each into one specific rule with its reason attached.
3. Scope everything non-universal, then check your surface. Move what you can to
fileMatch . Then confirm where your team actually runs Kiro — if the CLI is in your pipelines, your always set is your whole set there, and it needs to be small enough to survive that.Closing the Loop
Three posts, one argument.
Part 1 made the case that AI agents without steering give you velocity without direction. Part 2 showed how to deliver steering at enterprise scale, from a shared Git repo through to a Steering MCP server on AgentCore. This post is about what goes in the files, and it lands somewhere I didn't expect when I started.
Remember the team I opened Part 1 with — six engineers who rebuilt the Amazon Bedrock inference engine in 76 days, against an estimate of 40 engineers and a full year. They did not get there by turning an agent loose. They worked inside a structured workflow with persistent context, and steering was part of that context. Nothing here argues against what they did. It argues about what belongs in the files they were using.
The instinct, once you believe steering matters, is to write more of it. The evidence points the other way — and that turns out to be the strongest version of the argument, not a retreat from it. Steering was never a place to restate your codebase. It's where you record the things your codebase cannot say: why you chose this architecture, which pattern you abandoned and what it cost you, the migration that has to run first, the constraint your regulator imposed.
That's your team's judgment. It's the one input no model can infer and no amount of context window can replace. Cut everything else so that part lands cleanly — a short steering file full of things only your team knows will beat a long one every time, and it gets more true with every model release.
So the work was never writing more steering. It's cutting everything Kiro can already read for itself, until what's left is the part only you know.
Further Reading
- Kiro Steering Documentation — Inclusion modes, file references, AGENTS.md support, and surface-by-surface behavior
- Stop repeating yourself: why global steering is the AI context layer you've been missing — The Kiro team on global vs workspace precedence, team distribution, and what never belongs in a steering file
- Kiro Skills — On-demand instruction packages, and the right home for workflows that don't belong in always-on steering
- The new rules of context engineering for Claude 5 generation models — Anthropic on cutting 80% of Claude Code's system prompt, and the best practices that became myths
- Effective context engineering for AI agents — The "right altitude" framing and context as a finite resource
- Decoding the Configuration of AI Coding Agents — Empirical study of 328 agent configuration files; architecture dominates
- On the Use of Agentic Coding Manifests — 253 manifests across 242 repositories (PROFES 2025)
- AI-Driven Development Life Cycle: Reimagining Software Engineering — The foundational AI-DLC methodology blog by Raja SP
- AI-DLC Workflows (Open Source) — The phase-gate workflow rules
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article