Kiro Methodology

1. Overview & Principles

← Back to Table of Contents | Next: Team Modes →

1.1 What This Methodology Solves

When multiple AI assistants generate code in the same repository without structure, the result is chaos: merge conflicts, architectural drift, duplicated logic, and exponential technical debt.

This methodology provides a structured framework to:

1.2 Scope: Small Teams Only

This methodology is designed for a single small team: either one solo developer with a Kiro assistant, or a Scrum team of 3 to 7 developers each with their own Kiro assistant. All members work within the same Git repository.

Scaling Beyond 7 Developers

For larger products requiring more than 7 developers, do not scale this methodology by adding more people to the same repository. Instead:

  1. Decompose the product into smaller autonomous teams (3–7 persons each), following the microservices bounded context principle.
  2. Each team owns its own Git repository where its Kiro assistant(s) operate independently.
  3. Teams interact exclusively through well-defined interfaces: API contracts, event schemas, shared type packages published as versioned libraries.
  4. Each team applies this methodology independently within its own repository.
Product (large)
│
├── Team A (3–5 devs) → repo-auth-service      → Kiro agents work here
├── Team B (3–5 devs) → repo-billing-service    → Kiro agents work here
├── Team C (4–7 devs) → repo-order-service      → Kiro agents work here
├── Team D (3–5 devs) → repo-frontend           → Kiro agents work here
└── Platform Team     → repo-infra              → Kiro agents work here

Cross-team integration:
├── API contracts (OpenAPI specs) versioned in a shared contract repo
├── Event schemas (AsyncAPI) versioned in a shared schema repo
└── Shared type packages published to a private registry

Key rules for multi-team scaling: - No team's Kiro agent ever modifies another team's repository - Contract changes require cross-team review and versioning - Each repository has its own CI/CD pipeline, Terraform config, and Kiro steering rules - Integration testing happens at the platform level, not within individual repos

1.2 Core Principles

Principle 1: Module Isolation (Bounded Contexts)

Each developer + Kiro pair owns a specific module. A Kiro agent never modifies code outside its assigned module. Cross-module interactions happen only through APIs, interfaces, and shared types.

Principle 2: Trunk Stability Above All

The main branch must always compile, pass tests, and be deployable. No exceptions. Every merge is validated by CI before reaching trunk.

Principle 3: Small Changes, High Frequency

AI assistants generate code fast. This means: - Commits every 5–20 minutes - Branches live less than 24 hours - PRs are small and focused

Principle 4: Mandatory Unit Tests

Every code modification must include corresponding unit tests. This is enforced by Kiro steering rules and CI pipeline gates. No test = no merge.

Principle 5: Minimal Documentation

Documentation is limited to what is explicitly specified in Kiro steering rules: - API contracts between modules - Architecture decision records (when rules change) - README per module (auto-maintained)

No verbose design documents. The code and its tests are the documentation.

Principle 6: Infrastructure as Code

All AWS resources are managed by Terraform. No manual console changes. Infrastructure follows the same trunk-based workflow as application code.

1.3 AI Agent Model

Developer + Kiro = 1 Development Unit

Each unit:
├── Owns a module (bounded context)
├── Operates within strict steering rules
├── Commits frequently to short-lived branches
├── Generates code + tests together
└── Never touches other modules

1.4 When to Use This Methodology

Scenario Recommended?
New microservices product from scratch Yes — see Section 9
Integrating existing codebase for AI maintenance Yes — see Section 10
Monolithic application Partially — modularize first
Single throwaway script No — overkill

← Back to Table of Contents | Next: Team Modes →