The Complete Guide to Bolt.new: Prompts, Kiro Files, and Iterative Development

What Bolt.new Actually Is

Bolt.new is a browser-based AI development environment built by StackBlitz. It runs a complete Node.js runtime in the browser via WebContainers — a WebAssembly-based technology that lets real Node.js code execute, real npm packages install, and a live preview render without a local development environment.

The significance of this: Bolt's AI doesn't just generate code into a chat window. It writes code into a real project, runs it, and shows you the result. The generate → run → preview → iterate loop is tight enough to build real, production-starting applications in hours.

This guide covers everything you need to use Bolt productively — from the first prompt to multi-session iterative development.

The Five-Element Initial Prompt

The single most impactful habit in Bolt is writing a complete initial prompt. Most bad Bolt experiences trace back to vague first prompts that force the AI to guess at stack, features, and design choices.

A complete initial prompt has five elements:

1. Application Type and Purpose

One clear sentence describing what the app does. "Build a React + Supabase task manager where freelancers track projects and tasks" is enough. "Build a productivity app" is not.

2. Tech Stack Specification

TECH STACK:
- React 18 + TypeScript
- Tailwind CSS (no custom CSS files)
- Supabase (database + auth)
- React Router v6
- Lucide React for icons

Specify the icon library by name. Without this, Bolt mixes icon libraries across components.

3. Feature List with Behavioral Detail

Don't write "add filtering." Write: "Filter tasks by status (All/Active/Complete) using 3 segmented buttons. Filters persist in URL query params."

Behavioral specificity is what separates a prompt that generates working code from one that generates the right general shape with wrong behavior.

4. Design Constraints

DESIGN:
- White background, slate-700 sidebar (240px fixed)
- Primary action color: blue-600
- Cards with ring-1 ring-gray-200 and rounded-lg
- Clean and minimal — no decorative gradients

5. Explicit Exclusions

DO NOT INCLUDE:
- Multi-user team features
- File attachments
- Dark mode

Exclusions prevent well-intentioned scope expansion. Without them, Bolt adds features based on what similar apps typically have — not what you asked for.

Kiro Steering Files: Persistent Project Memory

Every Bolt session starts fresh. Without persistent context, Bolt makes decisions in each session that may contradict what was established in the last one — new library choices, different naming conventions, inconsistent patterns.

Kiro steering files solve this.

The .kiro/steering/ directory holds three files that Bolt reads at the start of every session:

product.md — What the product is, who uses it, core user flows, and explicit out-of-scope items.

tech.md — Full tech stack, library choices, and coding conventions. The most important file. Include rules like:

• "Always use Lucide React for icons. No other icon library."
• "All API calls go in /src/services/. Never in components."
• "Never use inline styles. Tailwind classes only."

structure.md — Directory layout and file naming patterns. Prevents Bolt from organizing new files inconsistently with what's been built.

Setting Up Kiro Files in Bolt

Create a .kiro/steering/ directory with product.md, tech.md, and structure.md.
Populate each file accurately based on the current project state.

Bolt inspects its own generated code and produces accurate steering files. Review them carefully — correct any conventions Bolt inferred incorrectly.

Starting Every Session

Once kiro files exist, begin every new session with:

Read .kiro/steering/product.md, tech.md, and structure.md.
Current state: [brief description of what's built]
Today's goal: [what you're implementing]
Confirm you've read the steering files before making changes.

This 30-second setup prevents hours of inconsistency cleanup.

Iterating Correctly

One Concern Per Prompt

This is the most important iterative practice. Bundling multiple changes multiplies risk. When something breaks, you can't identify which change caused it, and reverting undoes everything.

Wrong:

Fix the styling, add sorting to the task list, and handle the empty state.

Right:

Add sorting to the task list.
Sort by due date ascending by default.
Dropdown in the list header: "Due Date (asc)", "Due Date (desc)", "Priority", "Created".
Client-side sorting only — do not change the Supabase query.

Verify after every prompt. If it works, continue. If it breaks, revert immediately.

The State Matrix for Components

Before building any UI component, list every state it needs to handle:

Build the ProjectCard component.

STATE MATRIX:
| Condition | Display |
|-----------|---------|
| Loading | Skeleton placeholder |
| Error | "Couldn't load project" with retry |
| Empty (0 tasks) | Project name, "No tasks yet", Add Task CTA |
| Populated | Title, task count, completion bar, last updated |

LAYOUT: Card with project color as 4px left border accent.

The matrix ensures Bolt builds complete coverage, not just the happy path.

File-Targeted Prompts

When you want a change in a specific file:

In src/components/TaskCard.tsx, add a priority badge to the top-right.
Color mapping:
- low: bg-green-100 text-green-700
- medium: bg-yellow-100 text-yellow-700
- high: bg-red-100 text-red-700
Only modify TaskCard.tsx. Do not change any other files.

File-targeted prompts prevent unintended changes in neighboring files.

Bolt Commands

`/clear` — Resets conversation context. Use when Bolt starts contradicting earlier decisions or looping on a fix. Always re-establish context with a summary prompt after clearing.

`/fix [description]` — Triggers a targeted fix. More focused than a general prompt. Include the specific symptom, not just "fix it."

`/explain [code or concept]` — Asks Bolt to explain something in the context of the current project. Useful for reviewing AI-generated code you want to understand before shipping.

Revert — The history panel lets you return to any previous state instantly. Use it immediately when a change breaks something. Trying to fix forward from a broken state compounds complexity.

Lock — Protect configuration files from AI modification via the file explorer lock feature. Locked files are read for context but never written.

Feeding Design Files to Bolt

Bolt accepts image uploads. Upload wireframes, annotated screenshots, or reference UI alongside a structured behavioral prompt:

[Attached: wireframe of dashboard]

Build the dashboard layout shown.

IMPLEMENTATION NOTES:
- Left sidebar: fixed, 240px, slate-800
- Project cards: 3 columns desktop, 2 tablet, 1 mobile
- Each card: title, task count, completion %, last updated, color accent border
- "New Project" button opens a modal — build the modal too
- Follow .kiro/steering/tech.md for all patterns

Images communicate layout and visual reference. Your prompt communicates behavior, states, and responsive rules. Both are required.

The Sprint Model for Multi-Session Projects

Structure Bolt work as 1–3 day sprints with a clear definition of done. Before each sprint, write a kiro spec file in .kiro/specs/[sprint-name].md with requirements, design notes, and out-of-scope items. Then:

Read .kiro/specs/sprint-3.md and implement as specified.
Follow .kiro/steering/tech.md for all conventions.

Export or commit after each sprint completes. This gives you a known-good checkpoint.

Common Pitfalls

• Not specifying the stack — Changing mid-project is expensive. Specify before the first substantive build.
• Bundling changes — One concern per prompt. Every time.
• Not using revert — Revert immediately when something breaks. Don't fix forward.
• Accepting unrequested additions — Scan diffs for new libraries or features you didn't request.
• Not reading security-critical code — Auth flows, RLS policies, and data handling code must be read and understood before shipping.

Explore the full Bolt.new tutorial for lesson-by-lesson coverage of every workflow described here.