Starting a Spec with Kiro

Duration: 5 min

You start a spec by describing your feature to Kiro in natural language. Kiro asks clarifying questions, then generates the three spec documents. You review and edit them before any code is written.

Triggering the spec workflow

In the Kiro chat panel, describe what you want to build. Kiro recognises when you're describing a new feature and offers to create a spec. You can also explicitly ask: 'Create a spec for...' or use the /spec command.

# In Kiro chat:
Create a spec for a REST API endpoint that lets users
upload a profile photo, resize it to 200x200, and store
it in S3. Return the public URL.

Try it in Google Colab:

💡 Tip: Be specific about constraints upfront: language, framework, existing libraries, auth method. The more context you give, the less Kiro has to guess.

The clarifying questions phase

Kiro will ask questions like: What image formats should be accepted? What's the max file size? Should old photos be deleted? Should the endpoint require authentication? Answer these honestly — they become acceptance criteria in requirements.md.

Reviewing requirements.md

After the Q&A, Kiro generates requirements.md using a structured format with user stories and acceptance criteria written in EARS notation (Easy Approach to Requirements Syntax).

# Profile Photo Upload — Requirements

## User Stories

### US-1: Upload a profile photo
As a logged-in user, I want to upload a profile photo
so that other users can recognise me.

**Acceptance Criteria:**
- WHEN a user POSTs a valid image to /api/profile/photo
  THEN the system SHALL resize it to 200x200 pixels
- WHEN the upload succeeds
  THEN the system SHALL return the public S3 URL
- IF the file exceeds 5MB
  THEN the system SHALL return HTTP 413 with an error message
- IF the file is not jpeg, png, or webp
  THEN the system SHALL return HTTP 415

💡 Tip: Edit requirements.md directly before moving to design. Add missing edge cases, remove things you don't need. Kiro will use the final version as ground truth.