Spec-Driven Development on AWS
Hey, it’s Lefteris 👋 I’m the voice behind the weekly newsletter “The Cloud Engineers.”
We’ve all been there. A service gets deployed, an API route goes live, and three weeks later someone asks, “Wait, what does this endpoint actually do?” The answer lives in someone’s head, a Slack thread, or a Confluence page nobody has updated since the initial design meeting. That’s the problem Spec-Driven Development (SDD) solves, and on AWS, it changes how you build, test, and evolve systems regardless of whether you’re running Lambda, ECS, EKS, or EC2.
This hands-on Spec-Driven Development workshop is built for that exact problem. Instead of watching demos, you’ll build a real application while learning how to define clear specs and guide AI to produce reliable, production-ready outputs.
After a sold-out first cohort, Cohort 2 is now open.
👉 Register here: https://www.eventbrite.co.uk/e/hands-on-spec-driven-development-workshop-cohort-2-tickets-1985498625838?aff=lefteris
Use code SD40 for 40% off
What Is Spec-Driven Development?
Spec-Driven Development is a practice where the contract, also know as specification, is written before any implementation begins. The spec becomes the single source of truth. Everything else, the application logic, the infrastructure configuration, the event schemas, derives from it.
This isn’t documentation-first development in the old sense. It’s not about writing a Word document before you code. It’s about defining the shape of your system - inputs, outputs, events, errors - in a machine-readable format that your tooling, your tests, and your team can all reason about simultaneously.
Why It Matters Across AWS Architectures
The need for specs is a distributed systems problem, and AWS workloads are distributed by nature, whether you’re running microservices on ECS Fargate, a data pipeline on EMR, a real-time processing layer on Kinesis, or a containerized platform on EKS.
Every boundary between components is a contract. A service on ECS calling another service over HTTP, a Kafka consumer reading from MSK, an EKS pod publishing to an SQS queue, each of these is an implicit agreement about shape, behavior, and failure modes. Without a spec, that agreement is undocumented and fragile.
We’ve seen this break in predictable ways. A team running microservices on ECS changes the response schema of an internal API. The downstream service starts returning 500s. No contract test caught it. No spec was ever written. The failure surfaces in production, during peak traffic, after a deployment that passed all unit tests. A spec would have made that breaking change visible before it shipped.
The same pattern plays out in data engineering. A Glue job changes the shape of a Parquet file it writes to S3. The Athena queries downstream start failing. The schema was never formally defined, it was inferred from the data. An explicit schema contract, enforced at write time, would have caught the drift immediately.
Where Kiro Changes the Game
This is where AWS’s agentic IDE, Kiro, becomes directly relevant to how we practice SDD.
Kiro inverts the model most AI coding tools use. Kiro starts with the spec. When you describe a feature or a system in natural language, Kiro doesn’t generate code. It generates a structured specification first. That spec lives in three artifacts: requirements.md, design.md, and tasks.md.
The requirements file expands your prompt into user stories with acceptance criteria written in EARS notation, a structured format that captures preconditions, triggers, and expected system responses, including edge cases that would otherwise surface during implementation. The design file produces a technical design document covering architecture decisions and sequence diagrams. The tasks file breaks the design into discrete, sequenced implementation steps with dependency tracking. Only after you review and approve those artifacts does Kiro begin writing code.
This is spec-driven development operationalized inside your IDE. The spec isn’t a side artifact you produce reluctantly. It’s the primary artifact the entire workflow is built around. Code becomes the build output of the spec, not the other way around.
For teams building on AWS, this matters because it forces the contract conversation to happen before a single line of application or infrastructure code is written. Whether you’re defining an API contract between two ECS services, an event schema for an EventBridge rule, or the interface between a CDK construct and the team consuming it, all of it gets defined and reviewed at the spec level, not discovered during a production incident.
The Spec as the Center of Gravity
The shift SDD requires is treating the spec as the artifact that drives everything else, not as something you generate after the fact.
When we start a new API, the OpenAPI spec is written first. The service is built to satisfy it. The tests validate against it. When a consumer team needs to integrate, we hand them the spec, not a Slack message. The same principle applies to infrastructure. Before a new CDK construct is published for internal use, its interface contract is defined and reviewed. Breaking changes are explicit. They show up in the diff before they show up in a broken pipeline.
This approach forces clarity early. You can’t write a spec for something you haven’t thought through. The act of speccing a service or an event forces you to answer questions you’d otherwise defer: What are the required fields? What are the error states? What does a partial failure look like? What’s the versioning strategy?
The Discipline It Demands
Adopting SDD, with or without Kiro, requires a workflow shift.
Design reviews happen at the spec level. Before any service is built, the team reviews the OpenAPI, AsyncAPI, or infrastructure spec. This is where architectural decisions get made, not in code review.
Mocking becomes trivial. A spec-first API can be mocked immediately. Consumer teams don’t wait for implementation. Parallel development becomes the default.
Breaking changes become visible. When the spec is versioned and diffed, breaking changes are explicit. A field removal or type change shows up in the diff before it shows up in a production incident.
Onboarding accelerates. A new engineer joining the team can understand the system’s boundaries by reading the specs. The spec is the architecture, expressed precisely.
The temptation is always to skip the spec and start building, especially under deadline pressure. But the cost of that shortcut compounds. Every undocumented contract is technical debt that accrues interest in the form of production incidents, integration failures, and onboarding friction. Kiro makes that discipline easier to maintain by making the spec the default starting point, not an afterthought.
Write the spec first. Build to it. Everything else follows.
AI can get you to the first feature fast, but most developers struggle when the system starts to grow.
This hands-on Spec-Driven Development workshop is built for that exact problem. Instead of watching demos, you’ll build a real application while learning how to define clear specs and guide AI to produce reliable, production-ready outputs.
After a sold-out first cohort, Cohort 2 is now open.
Register here: https://www.eventbrite.co.uk/e/hands-on-spec-driven-development-workshop-cohort-2-tickets-1985498625838?aff=lefteris
Use code SDD40 for 40% off