Kiro Files Explained: The .kiro Directory, Steering Files, and Specs

What Is the .kiro Directory?

When you run npx cc-sdd@latest in a project, it creates a .kiro/ directory at the root of your codebase. This directory is the foundation of Spec-Driven Development (SDD) — it gives every AI coding tool you work with persistent memory of your project's architecture, conventions, and active feature work.

Without .kiro/, every AI session starts from zero. The AI has no idea what patterns you use, what libraries you've chosen, what naming conventions you follow, or what the broader architecture looks like. You spend the first part of every session re-explaining context that hasn't changed. With .kiro/, that context lives in version-controlled files that every AI tool reads automatically.

The directory has three subdirectories:

• .kiro/steering/ — project memory (persistent across all sessions)
• .kiro/specs/ — feature specifications (per-feature, created as you work)
• .kiro/settings/ — templates and custom slash command rules

The steering/ Directory

Steering files are the core of the .kiro/ system. They capture everything an AI tool needs to understand your project without you having to re-explain it. Think of them as the onboarding docs you wish you'd written — but generated from your actual codebase rather than written from scratch.

Running the /kiro:steering slash command in Claude Code (or the equivalent in Cursor, Copilot, or any other supported tool) analyzes your project and generates three files:

product.md

Describes what the product does and who it's for. The AI uses this to understand context when you ask it to build new features. It prevents the AI from suggesting solutions that don't fit the product's purpose — for example, adding complexity appropriate for an enterprise platform to a tool meant for individual developers.

A typical product.md includes: product description, target users, core features, and product goals. You write it once and update it when the product direction changes.

tech.md

Describes your technical stack, key dependencies, and technology decisions. When you ask the AI to add a feature, it reads tech.md to know:

• Which frontend framework you're using (React, Vue, Angular, etc.)
• Which database and ORM
• Whether you're using TypeScript
• Which test runner and assertion library
• Deployment environment and CI/CD setup

Without tech.md, the AI might suggest a Redux solution when your project uses Zustand, or a Jest test when your project runs Vitest. With it, the AI uses your actual stack automatically.

structure.md

Describes your project's file organization and architectural patterns. This is the most technical of the three steering files. It captures:

• Directory layout and what lives where
• Naming conventions for files, components, functions
• How you structure components (co-located styles? separate hooks file?)
• How data flows through the application
• Any domain-specific patterns (how you handle authentication, how you structure API calls)

When an AI tool reads structure.md, it knows to put a new React component in src/components/feature-name/ rather than the root of src/, to use camelCase for functions and PascalCase for components, and to follow your existing patterns rather than inventing new ones.

The specs/ Directory

While steering files capture project-wide context, spec files capture feature-specific intent. Each feature gets its own subdirectory under .kiro/specs/.

Running /kiro:spec-init "feature description" creates a subdirectory with four empty template files:

requirements.md

Written in EARS (Easy Approach to Requirements Syntax) format — a structured plain language format for requirements that eliminates ambiguity. Each requirement follows the pattern: "When [trigger], the system shall [behavior]."

EARS requirements are precise enough that an AI can use them as a specification without needing to infer intent. They're also precise enough that acceptance tests can be derived directly from them.

Example:

When an authenticated user submits the registration form with a valid email and password,
the system shall create a user account and redirect to the dashboard.

When a user submits the registration form with an email that already exists,
the system shall display an inline error: "An account with this email already exists."

design.md

Describes the architecture for the feature: which components will be created or modified, how data flows, what database changes are needed, and how the feature integrates with existing systems. Written before implementation, reviewed by a human before the AI builds anything.

tasks.md

A numbered, ordered task breakdown derived from the requirements and design. Tasks are small enough that each one can be implemented and verified independently. The numbering matters: you can ask the AI to implement tasks 1.1, 1.2, and 1.3 separately, reviewing each before proceeding.

implementation notes

Notes captured during implementation — decisions made, edge cases discovered, things to revisit. These persist after the feature ships so future AI sessions understand why things were built the way they were.

The settings/ Directory

The settings directory holds templates that customize how the slash commands work. If your project uses a specific requirements format, a particular design document structure, or custom task breakdown conventions, you can modify the templates here. Most projects use the defaults.

The Slash Command Pipeline

The .kiro/ directory is designed to work with a set of slash commands:

/kiro:steering           → generate steering files from your codebase
/kiro:spec-init          → create a new spec directory for a feature
/kiro:spec-requirements  → generate EARS requirements from a description
/kiro:spec-design        → generate architecture design document
/kiro:spec-tasks         → generate ordered task breakdown
/kiro:spec-impl          → implement specific tasks
/kiro:validate-impl      → verify implementation against requirements

Each command reads the relevant .kiro/ files before doing anything. This is what makes the context persistent: you don't need to re-explain your stack, your patterns, or your requirements. The files do it automatically.

Putting It in Version Control

The .kiro/ directory belongs in git. This is not optional — it's central to how the system works.

When .kiro/ is in version control:

• Every team member gets the same project context in every AI session
• New developers onboard faster because the context is already documented
• The AI never contradicts itself between sessions because the steering files are the single source of truth
• Feature specs serve as a record of why things were built the way they were

The one exception: if your .kiro/specs/ directory accumulates specs for completed features that you don't want cluttering the history, you can archive them. But the steering files should always be current.

.kiro/ vs Other Context Approaches

Some developers manage AI context through other methods: long system prompts, manually pasted documentation, README files. The .kiro/ approach has three advantages over these:

It's structured. AI tools are designed to read steering files in a specific way. The separation between product context, tech context, and structural context maps to how AI tools actually use the information.

It's automatic. You don't have to remember to paste context at the start of every session. Any tool configured to work with .kiro/ reads the files automatically.

It's versioned. When your stack changes or your architecture evolves, you update the steering files and commit the change. Every future AI session uses the updated context.

Getting Started

If you have an existing project and want to set up .kiro/:

npx cc-sdd@latest

This creates the directory structure. Then run /kiro:steering to generate the three initial steering files from your existing codebase. Review each file, make corrections where the AI misunderstood something, and commit.

From that point on, every AI coding session in that project starts with full context. For new features, create a spec with /kiro:spec-init, generate requirements and design documents for human review, then hand the spec to the AI for implementation.

The cc-sdd Tutorial walks through the full pipeline with a complete hands-on example. The Design & Specify pillar covers the underlying philosophy of why structured specifications produce better AI output.