Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• kiro-web-app/src/App.tsx
• mcp-server/src/kiro_mcp_server/server.py
• spec-process-guide/methodology/overview.md
• spec-process-guide/process/design-phase.md
• skills/create-steering-documents/SKILL.md
• spec-process-guide/templates/design-template.md
• spec-process-guide/resources/standards.md
• skills/spec-driven-development/SKILL.md
• spec-process-guide/prompting/best-practices.md
• spec-process-guide/process/README.md
• skills/requirements-engineering/SKILL.md
• spec-process-guide/templates/tasks-template.md
• spec-process-guide/methodology/philosophy.md
• skills/design-documentation/SKILL.md
• commands/create-steering-documents-standalone.md
• spec-process-guide/resources/tools.md
• spec-process-guide/prompting/templates.md

The Kiro System architecture is a comprehensive framework for Spec-Driven Development, a methodology designed to systematically transform feature ideas into well-defined, implementable solutions. This approach emphasizes thorough planning, clear documentation, and structured collaboration, particularly with AI assistants. The architecture is not defined by a single application, but rather by a process, a set of documentation standards, and a collection of "skills" and "templates" that guide the development lifecycle.

The core philosophy is "Clarity Before Code," which posits that investing time in understanding requirements, designing solutions, and planning implementation reduces uncertainty and minimizes rework. The system is designed to be iterative, with distinct phases for Requirements, Design, and Tasks, each serving as a quality gate before proceeding to the next. This structured approach is particularly effective for managing cognitive load and enabling effective AI collaboration by providing clear, structured input at each stage of development.

Sources: spec-process-guide/methodology/overview.md, spec-process-guide/methodology/philosophy.md, skills/spec-driven-development/SKILL.md

Core Architectural Concept: The Three-Phase Workflow

The foundation of the Kiro system is a three-phase workflow that guides a feature from conception to implementation readiness. Each phase produces a specific document artifact and must be approved before the next phase begins.

This diagram illustrates the sequential and iterative nature of the Spec-Driven Development process.

The purpose and key activities of each phase are summarized below:

Phase	Purpose	Key Activities	Output Artifact
1. Requirements	Transform vague ideas into clear, testable requirements.	Capture user stories, define acceptance criteria using EARS, identify edge cases.	Requirements Document
2. Design	Create a comprehensive technical blueprint for implementation.	Research approaches, define system architecture, specify data models and interfaces, plan error handling.	Design Document
3. Tasks	Break down the design into actionable, sequential coding steps.	Convert design into tasks, sequence tasks to manage dependencies, define completion criteria.	Tasks Document

Sources: spec-process-guide/methodology/overview.md, skills/spec-driven-development/SKILL.md, spec-process-guide/templates/requirements-template.md, spec-process-guide/templates/design-template.md, spec-process-guide/templates/tasks-template.md

System Components

The architecture is composed of several key informational and process components rather than traditional software modules.

Process Guide

This component is the documented, step-by-step walkthrough of the three-phase workflow. It provides detailed instructions for each phase, including how to conduct research, make design decisions, and manage changes.

Sources: spec-process-guide/process/README.md, spec-process-guide/process/design-phase.md

Skills

Skills are structured guides on how to perform specific activities within the development process. They act as reusable knowledge modules for core competencies. Examples include:

• requirements-engineering: Teaches how to use the EARS format to capture requirements.
• design-documentation: Guides the creation of technical blueprints from requirements.
• create-steering-documents: Explains how to set up project-specific guidelines for AI assistants.

Sources: skills/requirements-engineering/SKILL.md, skills/design-documentation/SKILL.md, skills/create-steering-documents/SKILL.md

Templates

Templates provide a standardized structure for the key artifacts produced in each phase. They ensure consistency and completeness. The primary templates are:

• Requirements Template: For structuring user stories and acceptance criteria.
• Design Template: A comprehensive framework for documenting architecture, components, data models, and more.
• Tasks Template: For breaking down the design into a detailed implementation plan.

Sources: spec-process-guide/templates/requirements-template.md, spec-process-guide/templates/design-template.md, spec-process-guide/templates/tasks-template.md

Steering Documents

A key architectural component for AI collaboration, steering documents are contextual guidelines that influence how AI assistants perform development tasks. They are stored in a .kiro/steering/ directory and contain project-specific standards, conventions, and best practices.

Their inclusion in the AI's context is governed by front-matter rules:

inclusion Value	Description
always	Included in every interaction (default).
fileMatch	Included when files matching fileMatchPattern are in context.
manual	Included only when explicitly referenced.

This diagram shows the structure and conditional inclusion logic of steering documents.

Document and Data Architecture

The system's "data" is the documentation itself. The architecture of these documents is critical. The Design Document, created from the design-template.md, is a central artifact that defines the technical architecture of a feature.

Design Document Structure

A design document translates requirements into a technical blueprint. Its structure is hierarchical, ensuring all aspects of the design are considered.

This diagram shows the major sections of a standard Design Document.
Sources: spec-process-guide/templates/design-template.md, skills/design-documentation/SKILL.md

Requirements Architecture: EARS

The most granular architectural element is the requirement itself, which is structured using the Easy Approach to Requirements Syntax (EARS). This syntax ensures every requirement is unambiguous and testable.

EARS Keyword	Format	Purpose
WHEN	WHEN [event/trigger] THEN [system] SHALL [response]	For event-driven requirements.
IF	IF [condition] THEN [system] SHALL [response]	For state-driven requirements.
WHILE	WHILE [condition] [system] SHALL [continuous behavior]	For requirements that must hold true during an ongoing state.
WHERE	WHERE [location/context] [system] SHALL [behavior]	For requirements specific to an optional feature or context.

Sources: spec-process-guide/resources/standards.md, skills/requirements-engineering/SKILL.md

Data Flow and Interactions

While the system is primarily a methodology, the templates define common interaction patterns. The data flow for a typical feature involves a user interacting with a frontend, which communicates with an API that queries a database.

The following sequence diagram, taken from the design template, illustrates this standard data flow.

AI Collaboration Architecture

A core aspect of the system's architecture is its design for effective human-AI collaboration. This is achieved by providing structured, high-quality context to the AI at every step.

The interaction flow is as follows:

1. Context Setting: The user provides rich context about the project, technology, and goals.
2. Structured Input: The user leverages templates and prompting strategies to make specific, structured requests for each phase (Requirements, Design, Tasks).
3. AI Processing: The AI assistant receives the user's prompt, along with any relevant "Steering Documents" that provide project-specific rules.
4. Iterative Refinement: The AI generates a structured output (e.g., a requirements document), which the user then reviews and provides feedback on for refinement.

This flow ensures the AI's output is consistently aligned with the project's standards and goals.

Conclusion

The architecture of the Kiro System is a holistic methodology for software development that prioritizes planning, documentation, and structured thinking. It is not a single piece of software but a process framework composed of guides, skills, templates, and standards. Its primary components—the three-phase workflow, EARS for requirements, structured design documents, and AI-guiding steering documents—work together to reduce ambiguity, improve quality, and enable highly effective collaboration between human developers and AI assistants. This documentation-centric architecture ensures that clarity of purpose precedes implementation, leading to more robust and maintainable software.

Sources: spec-process-guide/methodology/overview.md, spec-process-guide/methodology/philosophy.md