Use Cases

By now you know what specs, steering, hooks, and agents are. This chapter answers the next question: which one do you reach for, and when? Nine everyday jobs, each in the same shape: the situation, the feature that fits, a small example flow, and one thing to watch out for.

1. Building a new app

You have an idea and an empty folder. The danger is building the wrong thing quickly, not typing speed.

This is the home turf of spec-driven development. Ask Kiro for a spec and it works through three files with you before any code exists: requirements.md (what, written as testable EARS Easy Approach to Requirements Syntax: structured requirement sentences like WHEN … THE SYSTEM SHALL … that can each become a test. lines), design.md (how), and tasks.md (in what steps). Feature specs offer three workflows (Requirements-First, Design-First, or Quick Plan) so you can match the ceremony to the stakes.

A typical flow:

1. Describe the app in chat and ask Kiro to start a spec.
2. Read requirements.md slowly and fix wrong assumptions there. Words are cheaper to change than code.
3. Optionally run the requirements analysis, which flags ambiguity, contradictions, and gaps before you approve.
4. Approve design.md, then execute tasks.md. Kiro runs independent tasks concurrently in “waves”.

When is a spec overkill? Kiro’s own guidance is a clean split:

Reach for a spec	Stay in vibe chat
Complex features	Exploration and experiments
Risky bug fixes	Quick prototypes
Work teammates must understand later	Throwaway scripts

(Vibe chat here means freeform conversation where the agent codes immediately, with no written plan.)

2. Refactoring existing code

The code works, but its shape is wrong: a module grew too big, or a pattern needs replacing everywhere. Behavior must not change while the structure does.

Three features work together here. Steering files (your structure.md and tech.md, or a dedicated conventions file) tell the agent what the target style looks like, so refactored code lands in your patterns instead of generic ones. Supervised mode pauses the agent after each turn that edits files, letting you accept or reject every hunk A small block of changed lines in a diff: the unit you approve or reject during review. . Checkpoints are restore points you can roll back to if a session goes sideways.

A safe flow:

1. Update steering with the target convention, and the why behind it.
2. Switch the chat to supervised mode.
3. Ask for one slice: “Extract the payment logic from orders.py into a service class. Only that, no other cleanup.”
4. Review each hunk, run the tests, commit. Then ask for the next slice.

3. Writing documentation

Docs always lag the code, because updating them is the chore everyone defers.

Kiro helps three ways: the agent reads code and drafts or updates docs on request; a steering file keeps the voice and structure consistent across sessions and teammates; and a hook can refresh docs automatically whenever the relevant code is saved.

A typical setup:

1. Write a small steering file, docs-style.md: who the reader is, the tone, and one or two structure rules.
2. Prompt: “Read #folder src/api and update docs/api.md to match the current endpoints.”
3. Add a hook: when a file under src/api/ is saved, prompt the agent to update the matching section of docs/api.md if the public behavior changed.

4. Writing tests

You have new code with no tests, or old code you are afraid to touch for exactly that reason.

Asking for tests works best with precise context: point at the module with #file rather than describing it. For features built through a spec, Kiro’s property-based testing Testing that checks a general rule holds across many generated inputs, instead of a few hand-picked examples. (added at GA) verifies that the implementation actually matches the spec. And because hook actions can be shell commands, a hook can run the matching tests on every save in a folder.

A typical flow:

1. “#file src/cart.ts, write unit tests: the happy path plus edge cases (empty cart, duplicate items, quantity zero).”
2. Read every assertion and check it against what the code should do.
3. Add a hook: on save under src/, run that module’s test command.

5. Debugging

Something is broken: a stack trace in the terminal, red squiggles in the editor, a behavior nobody can explain.

Kiro offers two levels. For quick fixes, context providers feed the agent real error data without copy-paste: #problems pulls your editor’s current diagnostics, and #terminal pulls recent terminal output. For gnarly or risky bugs, start a bugfix spec: the structured analysis lands in bugfix.md (taking the place of requirements.md), followed by design and fix tasks you approve before anything changes.

A typical flow:

1. Reproduce the failure in your terminal.
2. Prompt: “#terminal #problems: why does checkout return a 500 for empty carts?”
3. If the root cause is deep or the fix is risky, start a bugfix spec and read the analysis in bugfix.md before approving the fix.

6. Code review

Code arrives faster than it can be reviewed, especially once an agent is writing some of it.

Three tools fit. Supervised mode is built-in review of the agent’s own work: every file edit pauses for hunk-level accept or reject. A custom agent makes a strict reviewer: give it read-only tools and a critical prompt, and it physically cannot “fix” things while reviewing (the Core Concepts chapter has a full reviewer JSON example). And Kiro 0.9 added granular code review to the IDE, alongside custom subagents, while CLI v2.5.0 added subagent review loops on the terminal side.

A typical flow:

1. Create the persona: /agent create reviewer -D "strict read-only code reviewer", with tools limited to reading.
2. Switch to it with /agent swap.
3. Prompt: “Review #git diff for correctness bugs and convention violations. Report findings. Do not fix anything.”
4. Swap back to your default agent and fix the findings one by one.

The separation matters for the same reason humans don’t review their own pull requests: a fresh persona with a critical prompt catches what the writer persona glossed over.

7. Data engineering workflows

You maintain pipelines: SQL transformations, scheduled jobs, maybe a dbt-style A project organized as layered SQL models with strict naming conventions, in the style popularized by the dbt tool. project. The work is convention-heavy, and mistakes fail quietly: a wrong join produces plausible numbers, not an error.

Steering is the anchor: a warehouse.md file encoding your layer rules, naming scheme, and partitioning habits means every generated model lands in your house style. MCP connects the agent to your data tools: if your database, warehouse, or orchestrator exposes an MCP server, the agent can inspect real schemas instead of guessing column names. And because schema changes are risky by nature, pipeline changes are good spec material.

A typical setup:

1. Write warehouse.md steering: layers, naming (stg_, fct_), partition rules, and why each rule exists.
2. Add your database’s MCP server to .kiro/settings/mcp.json, keeping credentials in environment variables via ${VAR} expansion, never hardcoded.
3. Spec the new pipeline so design.md spells out the schema and the backfill plan before any SQL is written.
4. Let the agent write the models, then review the SQL like any other code.

Be deliberate with autoApprove on a database MCP server: auto-approving tools that can write to a production warehouse is how quiet disasters start. Approve read-only tools, and only those.

8. Data science project support

Your project is notebooks, experiment runs, and half-written analysis docs: iterative work that resists tidy process.

To Kiro, notebooks and analysis scripts are just files in the repo: the agent can read them, refactor a sprawling notebook cell into a tested function, or draft the writeup from your results files. A steering file holding your metric definitions and data dictionary keeps every summary using the same terms. And when the work lives on a remote machine (a training box or a shared server with no desktop), the CLI brings the same agent, steering, hooks, and MCP into the terminal.

A typical remote flow:

1. SSH into the machine and run kiro-cli.
2. Pull in your results: /context add "experiments/**".
3. Prompt: “Summarize this week’s runs into experiments.md: a table of run, parameters, headline metric, and verdict.”
4. Use !command for quick shell checks (like !ls runs/) without leaving the session.

One honest limit: the agent drafts the writeup, but it cannot validate your science. Recompute the headline numbers yourself before anyone makes a decision on them.

9. CI/CD and headless automation

This one is advanced. Most readers can file it away for later.

The situation: you want Kiro to work with nobody at the keyboard (a nightly docs refresh, scheduled dependency triage, automated report drafts). The Kiro CLI supports headless Running a tool non-interactively, with no human present, typically inside a script or CI job. use with API-key authentication, which makes it usable inside CI/CD pipelines. Pair it with a custom agent restricted to exactly the tools the job needs.

The safe shape:

1. Create an API key and store it in your CI system’s secret store, never in the repository.
2. Define a narrowly scoped custom agent in .kiro/agents/ so it is versioned with the repo.
3. Have the CI job run the CLI headless with that agent, and make its output land as a pull request.
4. Humans review that pull request exactly like any other.

The verified mechanics: the CI job sets the KIRO_API_KEY environment variable from your secret store and runs kiro-cli chat --no-interactive "…", pre-approving only narrow tool categories with --trust-tools (for example --trust-tools=read,grep for a review-only job). The full reference lives in the CLI Guide.