Using .kiro Files to Give Bolt Persistent Project Context

The Context Amnesia Problem

Every Bolt conversation starts fresh. Without persistent context, Bolt doesn't know:

• What tech stack you've chosen and why
• What conventions you're following (naming, file structure, component patterns)
• What constraints exist (e.g., "never use inline styles," "always use React Query for data fetching")
• What's already been built and how it fits together

The result: Bolt generates code that contradicts decisions you made earlier, introduces new libraries you didn't want, or names things inconsistently with your existing codebase.

Kiro files solve this.

What Kiro Files Are

Kiro files are plain text (usually Markdown) files stored in the .kiro/ directory at the root of your project. They give AI coding tools — including Bolt — persistent, project-specific context that gets loaded automatically at the start of every session.

The three standard steering files are:

Setting Up .kiro Steering Files in Bolt

Option 1: Create the files directly in Bolt

In your Bolt project, prompt:

Create a .kiro/steering/ directory with three files: product.md, tech.md,
and structure.md. Populate each file with accurate context based on the
current state of this project.

Bolt will inspect its own generated code and write accurate steering files based on what it built.

Option 2: Write them yourself

For maximum control, write the steering files manually using Bolt's file editor. This is recommended when you have specific constraints that Bolt might not infer correctly.

What to Put in Each Steering File

product.md

# Product

## Overview
[One paragraph describing what the product is and who uses it]

## Core User Flows
1. [Primary flow]
2. [Secondary flow]

## Out of Scope
- [Feature explicitly excluded]
- [Feature explicitly excluded]

## Tone and UX Principles
- [e.g., "Simple over powerful — every feature must be explainable in one sentence"]

tech.md

# Tech Stack

## Frontend
- React 18 with TypeScript (strict mode)
- Tailwind CSS — utility classes only, no custom CSS files
- React Router v6 for navigation
- Lucide React for all icons (no other icon libraries)
- React Query (TanStack Query v5) for all server state

## Backend / Database
- Supabase for database and authentication
- All DB access via @supabase/supabase-js client
- Environment variables via import.meta.env (Vite)

## Conventions
- Components: PascalCase, one component per file
- Hooks: camelCase, prefix with "use"
- Never use inline styles — Tailwind classes only
- All API calls go in /src/services/ — never in components directly
- Forms use uncontrolled inputs with FormData where possible

structure.md

# Project Structure

src/
  components/     # Shared UI components
    layout/       # Navbar, Sidebar, Footer
    ui/           # Buttons, Inputs, Cards, Modals
  pages/          # Route-level page components
  services/       # API and Supabase calls
  hooks/          # Custom React hooks
  types/          # TypeScript interfaces
  lib/            # Utilities and helpers
  context/        # React context providers

## Naming Conventions
- Page components: [Name]Page.tsx (e.g., DashboardPage.tsx)
- Shared components: descriptive noun (e.g., TaskCard.tsx)
- Services: [entity].service.ts (e.g., tasks.service.ts)
- Hooks: use[Description].ts (e.g., useTaskFilters.ts)

Using Kiro Files Across Sessions

Once your steering files exist, start every new Bolt session with:

Read the .kiro/steering/ files to load project context before making any changes.

This primes Bolt with your constraints and conventions before it touches any code.

Kiro Spec Files for Features

Beyond steering files, Kiro supports spec files for individual features. These live in .kiro/specs/ and follow a structured format:

# Feature: [Name]

## Requirements
- [Testable requirement 1]
- [Testable requirement 2]

## Design
[Description of UI/UX behavior]

## Technical Notes
[Implementation constraints or hints]

## Out of Scope
[What this feature does NOT do]

To implement a spec in Bolt:

Read .kiro/specs/[feature-name].md and implement the feature as specified.
Follow all constraints in .kiro/steering/tech.md.

Key Takeaways

• Kiro files give Bolt persistent project memory, solving context amnesia across sessions
• Three steering files cover product definition, tech stack, and file structure
• Ask Bolt to generate initial steering files from its own code — then review and refine
• Spec files for individual features create a clear, auditable implementation trail

---

Try It Yourself: In your current or next Bolt project, ask Bolt to generate .kiro/steering/tech.md based on the project's current dependencies and code patterns. Review the output carefully — correct any conventions or constraints Bolt got wrong. This file is the single source of truth for all future AI coding in this project.