Common Mistakes & Don'ts

Every tool has a failure manual nobody writes. This is Kiro’s: collected don’ts, organized by the kind of trouble they cause.

Things beginners should avoid

• Don’t start in Autopilot. Supervised mode exists so you can build a mental model of what the agent does well and badly. Earn your way to autonomy.
• Don’t prompt vaguely. “Make it better” returns something confidently arbitrary. Say what, where, and what done looks like: “Reduce duplication in src/utils/dates.js without changing its public functions.”
• Don’t pick a huge first project. The beginner tutorial uses a tip calculator on purpose. Learn the loop on something you can fully read.
• Don’t paste code into chat when you can point. Context providers (#file, #codebase, #problems) give the agent live, accurate context. Pasted fragments go stale and lose their surroundings.
• Don’t skip the requirements review. Approving requirements.md unread converts spec-driven development back into vibe coding, with extra steps.

Wrong assumptions about AI coding tools

• “It understands my intent.” It models likely meanings of your words. Ambiguity gets resolved silently in whatever direction is statistically convenient. That is why EARS notation and written requirements exist.
• “It knows about the library version I’m using.” Models have knowledge cutoffs and gaps. APIs that changed recently are precisely where hallucinated methods appear. Give it docs via MCP/powers or #url context.
• “More context is always better.” Irrelevant context dilutes attention and burns credits. /context show exists so you can see the weight of what you’ve loaded. Curate.
• “It said it’s done, so it’s done.” Agents report completion optimistically. Done is defined by your verification (tests passing, behavior matching requirements), not by the message saying “I’ve completed the task.”
• “The agent is consistent.” The same request can produce different output tomorrow. What’s stable is your written record: specs, steering, tests.
• “The agent remembers the whole session.” It does not, once the context fills. Compaction summarises older history and is one-way, so anything before the compaction point is gone. Put decisions you need to survive into a file, not into the chat.

When not to trust generated output

Trust inversely with the cost of being wrong:

Treat with extra suspicion	Why
Authentication, crypto, permissions	Plausible-looking security code is the most dangerous kind
Money math, billing, rounding	Off-by-a-cent bugs look correct in review
Concurrency, async, locking	Race conditions don’t show up in a quick run
Data deletion or migration	Mistakes are unrecoverable, not just wrong
Calls to niche or brand-new APIs	Highest hallucination zone
”It compiles” performance claims	Measure; don’t believe adjectives

Verification habits that scale:

1. Read every diff (Supervised mode makes this structural).
2. Run the thing. Behavior beats inspection.
3. Make the agent write tests from the requirements, then check the tests test something.
4. Use property-based testing on spec’d work with invariants.
5. For risky logic, ask a second, read-only reviewer agent to critique the first agent’s work.

Source-control habits

• Commit (or stash) before every agent session. A clean working tree means the agent’s changes are perfectly visible with git diff, and perfectly reversible.
• Keep agent work on branches, exactly like human work. Review at the merge, not just at the hunk.
• Make small, labeled commits as tasks complete, rather than one “agent did stuff” mega-commit. Your future bisect will thank you.
• Don’t confuse checkpoints with git. Kiro’s checkpoints roll back a session. They’re invaluable mid-flight, but they are not history, not shared, and not a backup. They also only track files the agent changed with its built-in file tools, so manual edits, formatter runs, MCP tool changes, and bash edits are outside them. Git remains the source of truth.
• Read generated commit messages if you let the agent write them. They describe what it intended, which is not always what the diff does.

Security & privacy cautions

• Secrets never go in steering files, skills, or chat. Steering is committed to your repo; chat may leave your machine. Use ${ENV_VAR} expansion in mcp.json instead of literal keys, and add a .kiroignore for the paths the agent should never open. Treat that file as hygiene rather than a wall: support is full in the IDE, applies to search results in CLI V3, and is not yet in Web or Mobile.
• autoApprove is a loaded setting. "*" on an MCP server means the agent uses all its tools without asking. Reserve it for read-only servers you trust completely.
• Vet third-party powers and MCP servers before installing. They configure what your agent can do and how it thinks. Skim the POWER.md and server source the way you’d skim a shell script before piping it to bash.
• Know where your code goes. Kiro Web has always run agents in the cloud against your repositories, and since August 2026 the IDE and CLI can start cloud sessions too, so “I am working locally” is no longer something you can assume from the surface you opened. Check your organization’s policy first, and note that enterprises can disable the feature centrally. (For regulated workloads: Kiro’s IDE and CLI became HIPAA-eligible in May 2026, and the docs’ privacy-and-security pages are the authority here.)
• Restrict agents that touch production-adjacent things. A migrations agent with no destructive tools can’t have the worst day of your career on your behalf.

Over-automation risks

• Noisy hooks get disabled, silently. A full test suite on every save trains the team to turn hooks off, and then the useful automation dies too. Narrow triggers, light actions.
• Self-triggering loops. A hook that writes into the folder it watches is a perpetual-motion machine that spends credits instead of producing energy.
• Unwatched headless jobs. CI automation with API keys works, consumes credits, and makes changes while nobody’s looking. Start headless jobs read-only (report, don’t fix) until trust is earned.
• Automation rot. Steering, skills, and hooks describe your project as it was. Schedule a periodic review, because wrong steering is worse than no steering: the agent obeys it confidently.
• The dependency trap. If a junior teammate can’t explain code the team shipped, your process has failed, not the tool. Keep humans able to pass the “explain it at the whiteboard” test for everything that ships.

Mistakes with the new features

The features that arrived through 2026 came with new ways to hurt yourself. These four are the ones worth naming.

Turning on Autopilot without deny rules. Autopilot removes the pause before each action; it does not remove your responsibility for the result. Kiro’s permission system is capability-based, and a rule with the deny effect always wins regardless of scope and regardless of Autopilot. So write the deny rules first, then grant the autonomy. Deny beats ask, ask beats allow, and the ones worth writing on day one cover destructive shell commands, anything under a production configuration path, and any MCP tool that can write. Recipe: permissions.yaml.

Running Web Automations against repositories you don’t trust. The Kiro Web documentation is explicit about this: only select repositories you trust, because the agent follows instructions found in repository code. That is the same class of problem as running an unreviewed script, except it happens on a schedule with nobody watching. Before you point a scheduled automation at a repository, ask who can commit to it. A fork you accepted a pull request from is not the same trust level as your own main branch. Recipe: schedule a Web Automation.

Letting Kiro Crew run with the sandbox set to Off. Crew has three sandbox modes: Auto hides .gnupg, .gcloud, .azure, and .docker; Strict also hides .aws, .ssh, and .kube; Off is available on Linux and macOS only and removes the protection entirely. Off exists for cases where the sandbox genuinely blocks legitimate work, and it should be a deliberate, temporary choice on a machine you own, not the setting you leave on because something once failed. Crew is a persistent agent that keeps running, which makes an unsandboxed one a standing risk rather than a momentary one.

Syncing your host’s secrets onto a remote Crew. Crew can run on a remote Linux host and be reached over SSH, and its dashboard binds to loopback only by default for good reason. The mistake is treating that remote box like your laptop: copying ~/.aws credentials, SSH keys, or kubeconfig onto it so “things just work”. Use Crew’s encrypted secrets vault for what the agent genuinely needs, leave the Strict sandbox on so .aws, .ssh, and .kube stay hidden, and keep the dashboard on loopback with an SSH tunnel rather than exposing the port. Crew also keeps a signed audit log, which is only useful if you actually read it after an incident.

One more that is easy to miss: cloud configuration sync is not a backup. Cloud config (agents, MCP servers, powers, steering, skills, hooks) syncs down to local IDE and CLI sessions as read-only previews, and it does not overwrite your local files. Editing happens in Kiro Web. If you assume the sync runs the other way, you will eventually wonder why a local steering change never reached anyone else. Commit your project configuration to git, as always.