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.

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. 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.
• 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 runs agents in the cloud against your repositories; check your organization’s policy first. (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.