Writing the Design Document

Duration: 5 min

Once requirements are agreed, Kiro generates design.md — the technical blueprint. This is where architecture decisions, data models, and API contracts are captured. It's the bridge between 'what' and 'how'.

What goes in design.md

A typical design document covers:

• Architecture overview — which components are involved
• Data models — database schemas or TypeScript interfaces
• API contracts — endpoint signatures, request/response shapes
• Error handling strategy
• Dependencies and libraries to use
• Security considerations

# Profile Photo Upload — Design

## Architecture
Express route → multer middleware → sharp (resize) → AWS SDK v3 (S3 upload)

## API Contract
POST /api/profile/photo
Content-Type: multipart/form-data
Authorization: Bearer <token>

Request body: { photo: File }

Response 200:
{ url: "https://cdn.example.com/photos/user-123.jpg" }

Response 413: { error: "File too large. Max 5MB." }
Response 415: { error: "Unsupported format. Use jpeg, png, or webp." }

## Data Model
User.profilePhotoUrl: string | null  // stored in users table

## Libraries
- multer: multipart parsing
- sharp: image resizing (already in package.json)
- @aws-sdk/client-s3: S3 upload

Try it in Google Colab:

💡 Tip: If Kiro's design choices don't match your stack, edit design.md before generating tasks. Changing the design doc is free — changing generated code costs time.

Iterating on the design

You can ask Kiro to revise the design: 'Use presigned URLs instead of uploading server-side' or 'Add a queue for async processing'. Kiro updates design.md and you review again. This iteration loop is cheap — you're editing markdown, not debugging code.

Design doc as living documentation

After implementation, design.md stays in your repo as documentation. Future developers (and future AI agents) can read it to understand why the code is structured the way it is — not just what it does.