A Complete Spec-Driven Workflow

Duration: 5 min

Let's walk through a complete example from idea to deployed feature using Kiro's full spec-driven workflow.

The feature: rate limiting

You want to add rate limiting to your API: 100 requests per minute per user, with a clear error response when exceeded. Let's spec it.

Step 1: Describe the feature

Create a spec for rate limiting our Express API.
Rules:
- 100 requests per minute per authenticated user
- 1000 requests per minute per IP for unauthenticated routes
- Return HTTP 429 with Retry-After header when exceeded
- Use Redis for the counter store
- Must work across multiple server instances

Try it in Google Colab:

Step 2: Answer clarifying questions

Kiro asks: Should rate limits be configurable per route? What happens if Redis is unavailable — fail open or closed? Should limits reset on a rolling window or fixed window? You answer, and these become acceptance criteria.

Step 3: Review and approve the spec

Kiro generates all three files. You read requirements.md and add a missing edge case: 'Admin users are exempt from rate limiting'. You edit design.md to change the Redis key format to match your existing naming convention. You approve tasks.md as-is.

Step 4: Execute

# In Kiro chat:
"Implement the tasks in .kiro/specs/rate-limiting/tasks.md"

# Kiro works through each task, checking them off:
# ✓ 1. Create RateLimiter class with Redis backend
# ✓ 2. Implement sliding window counter logic
# ✓ 3. Add Express middleware factory
# ✓ 4. Apply middleware to router with per-route config
# ✓ 5. Add 429 response with Retry-After header
# ✓ 6. Handle Redis unavailability (fail open)
# ✓ 7. Write tests for limit enforcement and Redis failure

💡 Tip: Review each task's diff before saying 'continue'. The spec gives you confidence in the direction, but you still own the code.

Step 5: The spec stays in your repo

Commit .kiro/specs/rate-limiting/ alongside the code. Six months later, when someone asks 'why does the rate limiter fail open?', the answer is in requirements.md. When you need to extend it, Kiro can read the original spec and design to understand the intent.