AWS Builder Center

Builder Center

# Your .kiroignore Is a Context Tool, Not Just a Security File

# Your .kiroignore Is a Context Tool, Not Just a Security File

Most developers treat .kiroignore like .gitignore — a place to hide secrets. But its real power is context control. Every file Kiro can read is a file it can get distracted by, costing tokens, latency, and accuracy. Use it to focus the agent on one part of a monorepo, hide generated code, and stop it learning from legacy patterns.

Vitor

Most people meet .kiroignore the same way they meet .gitignore: as a place to hide secrets. Drop in .env, add *.pem, move on. That works, and it matters. But if that is all you use it for, you are leaving the most valuable part on the table.
The real power of .kiroignore is context control. Every file the agent can read is a file it might pull into context, and context is not free. It costs tokens, it costs latency, and it costs accuracy. The more irrelevant code the agent can see, the more chances it has to anchor on the wrong file, copy an old pattern, or "helpfully" refactor something you never asked it to touch.
So the better mental model is this: .kiroignore is how you tell the agent what to pay attention to, by telling it what to forget.

Quick refresher on how it works

.kiroignore uses the same syntax as .gitignore. You put patterns in a file, and Kiro skips anything that matches when it reads or searches your workspace. A few things worth knowing before the patterns below:
  • It works at the workspace root, and also in subdirectories, where subdirectory rules take precedence for that subtree.
  • There is a global version at ~/.kiro/settings/kiroignore for patterns you want everywhere.
  • You can stack it with .gitignore through the kiroAgent.agentIgnoreFiles setting, for example [".gitignore", ".kiroignore"].
  • You cannot re-include a file if its parent directory is ignored. If you exclude secrets/, then !secrets/public.txt will not bring that one file back. Use a narrower pattern instead of excluding the whole directory.
  • Surface support differs. In the IDE it is enforced across agent tools. In CLI V3 it currently filters content and filename search results. Web and mobile do not support it yet.
That is the whole mechanism. Everything interesting is in how you use it.

The monorepo focus trick

This is the pattern that changed how I work. Say you have a monorepo with frontend/, backend/, and infra/, and today you are only touching the frontend. The backend is thousands of files the agent does not need right now. Worse, when you ask "where is the checkout flow," the agent can wander into backend controllers, API handlers, and tests that have nothing to do with your React work.
Temporarily ignore what you are not working on:
1
2
3
4
# Focus session: frontend only
backend/
infra/
**/*.test.snap
Now search stays clean, suggestions stay relevant, and the agent stops proposing changes to services you did not open. When you switch to backend work, flip it around. Some people keep a couple of these as named files and swap which one is active through the agentIgnoreFiles setting.
The key insight: ignore is not permanent. Treat it like a lens you change per task.

Keep generated and vendored code out

Generated files are the biggest source of context noise, and almost none of it helps the agent reason about your intent. Things worth ignoring:
  • Build output like dist/, build/, .next/, target/
  • Dependency directories like node_modules/, vendor/, .venv/
  • Lockfiles when you are not debugging dependencies, like package-lock.json, poetry.lock
  • Compiled protobufs, generated GraphQL types, ORM schema dumps
  • Minified bundles and source maps, like *.min.js and *.map
You probably already .gitignore most of this. The point is that git ignoring it keeps your repo clean, while Kiro ignoring it keeps your agent's reasoning clean. Those are two different goals, and the second one is easy to forget.

Protect the agent from bad examples

Language models imitate what they see. If your repo still has a legacy/ folder full of patterns you are actively migrating away from, the agent will read it, learn from it, and reproduce it. That is the opposite of what you want during a refactor.
1
2
3
4
# Do not learn from the old world
legacy/
deprecated/
**/*_old.*
This is subtle but real. When you are moving from a class-based component style to hooks, or from callbacks to async/await, ignoring the old code makes the agent default to the new style instead of pattern-matching on the majority of files that still use the old one.

Big data and fixtures

Large data files rarely help the agent write code, and they can blow up search and context fast. Test fixtures are the sneaky ones: a directory of 500 JSON snapshots looks like signal to a search tool but is almost always noise for the actual task.
1
2
3
4
5
6
# Data that is heavy and low-signal
data/
*.csv
*.parquet
fixtures/**/*.json
**/__snapshots__/
If you are debugging a specific fixture, un-ignore that narrow path for the session. The rest of the time, keep them out.

Docs-vs-code separation

If you are deep in implementation, a large docs/ tree can pull the agent toward documentation phrasing instead of code. If you are writing docs, the reverse is true and you might ignore parts of src/. Whichever mode you are in, ignore the other one:
1
2
3
4
# Implementation session
docs/
*.mdx
content/
This one is easy to overlook because docs feel harmless. They are harmless for correctness, but they still spend context and can steer tone.

Multi-language repos

In a repo that mixes, say, a Python service and a Go sidecar, a task is almost always about one of them. Ignore the language you are not in so search results and grep stay on target:
1
2
3
# Working the Python service today
sidecar-go/
*.go

A few habits that make this work

  • Comment every block. Future-you and your teammates need to know why a path is ignored, especially when the reason is "focus for this task" rather than "secret."
  • Prefer the global file for personal preferences. Editor scratch files, your own notes directory, personal TODO files. Keep these in ~/.kiro/settings/kiroignore so they do not clutter the shared repo config.
  • Keep secrets in the repo-level file, not the global one. Security patterns should travel with the project and apply for everyone, not just on your machine.
  • Test your patterns. Ask Kiro to read a file you think you ignored. If it reports the read is blocked, the pattern works. If it reads it anyway, your pattern is off.
  • Review it when the project changes shape. A new top-level directory or a finished migration is a good moment to revisit what should be ignored.
  • Remember the re-include limitation. If you need most of a directory but not all, ignore the specific files rather than the directory, so you can still reach the ones you want.

The mindset shift

Security use of .kiroignore is about what the agent must not see. Context use is about what the agent should not bother seeing right now. The second category is much larger, and it is where you get faster, sharper, more predictable results.
Start with secrets, because that part is non-negotiable. Then add generated code, then add a focus pattern for your current task. Once you feel the difference in how relevant the agent's answers get, you will start reaching for .kiroignore the same way you reach for a new branch: a small setup step that makes the actual work go better.
# kiro# ai-for-developers# developer-productivity# developer-tools# productivity
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article