Getting started with spec driven development

© 2025, Amazon Web Services, Inc. or its aﬃliates. All
rights reserved. Amazon Conﬁdential and Trademark. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. What the heck! Getting started with spec driven development Spec driven development for everyone Ricardo Sueiras (vi/vim) B U I L D W I T H O U T L I M I T S Developer Advocate, AWS

© 2025, Amazon Web Services, Inc. or its affiliates. All
rights reserved. Amazon Confidential and Trademark. 3 Helping developers write code faster 2023 Completing development tasks end-to-end with human in the loop Generating larger pieces of code and answering questions Unprecedented pace of change AUTO-COMPLETE 2024 ASSISTANTS 2025 AGENTS

rights reserved. Amazon Confidential and Trademark. 4 • Rapid, conversational code generation (CHOP) • Iterative, back and forth • Ephemeral • Point in time prompts • Transient context AI unleashed

rights reserved. Amazon Confidential and Trademark. 5 Vibe Coding is awesome…

rights reserved. Amazon Confidential and Trademark. 6 …but…

rights reserved. Amazon Confidential and Trademark. Vibe Coding: Prompt and Pray

rights reserved. Amazon Confidential and Trademark. AI coding tools excel at small tasks but can fail with complex projects Scaling AI development Existing tools make it diﬃcult to collaborate with and manage agents Limited control Challenges with AI development

rights reserved. Amazon Confidential and Trademark. 9 Challenges with AI development Getting a project from proof-of- concept to production while maintaining quality control becomes increasingly diﬃcult Code quality

rights reserved. Amazon Confidential and Trademark. 10 how do we fix this?

rights reserved. Amazon Confidential and Trademark. 11 Good practices emerged Emergence of good practices to help keep AI on a short leash Developers learned how to manually break down large problems into smaller units and build incrementally Break down large problems Specificity and Clarity Context and Prompt engineering Precision and clarity are key in directing AI coding assistants to generate good outputs Providing the right context is key to producing consistency and control

rights reserved. Amazon Confidential and Trademark. 12 “You don’t program by chatting. You program by writing documents.”

rights reserved. Amazon Confidential and Trademark. 14 What the heck is a spec?

rights reserved. Amazon Confidential and Trademark. 15

rights reserved. Amazon Confidential and Trademark. 16 Spec driven development

rights reserved. Amazon Confidential and Trademark. 17 17 Core Philosophy Invest time to understand what you are trying to build Clarity before Code Iterative refinement Code via docs Iterate and capture evolution of what you are trying to build From ephemeral chat to persistent documents that can be shared with your stakeholders

rights reserved. Amazon Confidential and Trademark. 18 18 Spec Driven Development Create clear requirements and design speciﬁcations Define the vision Make architectural decisions Deliver in small units Provide supporting context via “steering” files Break down development into smaller tasks

rights reserved. Amazon Confidential and Trademark. 20 Spec driven workflows are nascent and evolving quickly

rights reserved. Amazon Confidential and Trademark. 22 Start with intent

rights reserved. Amazon Confidential and Trademark. Start with intent Creating a spec starts with intent - what are trying to do? We use an initial prompt to bootstrap the spec creation and start the workflow. It is not too important whether your initial prompt is perfect as you will be spending lots of time reviewing and editing them.

rights reserved. Amazon Confidential and Trademark. 24 Shape and direct with context

rights reserved. Amazon Confidential and Trademark. 25 Start with intent Steering SELECT Adding Context As you think about INTENT, you should be thinking about what additional CONTEXT you need to bring in. • Context might include technical and domain knowledge. • Context can be dynamically managed • Review and defined Model Context Protocol (MCP) servers Steering documents and intent have a close relationship. The steering documents that you create will be aligned to the intent you have.

rights reserved. Amazon Confidential and Trademark. 26 Smart Context Selection • Automatic • Pattern Match • Manual Generation • Generate context from existing code bases (brownfield) • Generate context files from MCP servers Strategies • Start small and include just the core needs you want to influence • Use the different inclusion modes to help the AI coding assistant optimize which steering files to use and optimize your context window utilization • Use clear and descriptive names when naming your steering files (e.g. api-rest-conventions.md - REST API standards) • Provide examples - use code snippets, example input/outputs, style and structure guides • Security first - make sure you do NOT include sensitive information in your steering docs. Never include API keys, passwords, or sensitive data • Review and maintain your steering files as you iterate and improve them (treat them as first class citizens)

rights reserved. Amazon Confidential and Trademark. 27 Transform rough ideas into crisp requirements

rights reserved. Amazon Confidential and Trademark. Requirements Start with intent Refine and iterate The INTENT is translated into a set of requirements. These REQUIREMENTS are specified using a consistent format (Easy Application Requirements Syntax, EARS). This format is optimised for readability, understanding and for LLMs Steering SELECT

rights reserved. Amazon Confidential and Trademark. 29 • Transform vague feature ideas into concrete, measurable requirements • Establish clear acceptance criteria for feature success • Create a shared understanding between stakeholders • Provide a foundation for design and implementation decisions

rights reserved. Amazon Confidential and Trademark. Requirements Start with intent ITERATE Refine your requirements • Review with Stakeholders: Get feedback on completeness and accuracy • Identify Gaps: Look for missing scenarios or unclear requirements • Clarify Ambiguities: Resolve any vague or conflicting requirements • Add Missing Details: Include edge cases and error handling Steering SELECT

rights reserved. Amazon Confidential and Trademark. 32 From requirements, create a candidate technical design

rights reserved. Amazon Confidential and Trademark. Requirements Start with intent ITERATE Design APPROVAL Steering SELECT Generate the design From the REQUIREMENTS supported by CONTEXT files (Steering), a candidate technical design is created. • Design generated meets the requirements defined in the requirements document • Design is guided by the context files o Architecture o Components and Interfaces o Data Models o Error Handling o Test Strategy o Security Considerations o Performance Optimizations

rights reserved. Amazon Confidential and Trademark. Requirements Start with intent ITERATE Design APPROVAL Steering SELECT Correctness Properties A property is a characteristic or behaviour that should hold true across all valid executions of a system. Properties serve as the bridge between human- readable specifications and machine-verifiable correctness guarantees. A property is a universal statement about how your system should behave. Properties express the invariants and contracts that should always be true in your system, regardless of the specific data involved. What is a "Property"?

rights reserved. Amazon Conﬁdential and Trademark. Requirements Start with intent ITERATE Design APPROVAL REFINE Steering SELECT Refine the design • Include examples - throughout the document you should see relevant examples that will help steer the AI coding agent when generating code • Edit ruthlessly - as these are generated by an LLM, design documents can be longer and more verbose than they need to. They often over-engineer, so look out for this and edit as needed based on your use case • Missing items - check and ﬁnd out what is missing - missing components or missing details are frequent things that you will catch during the review • Alignment - review to make sure design choices make sense (context) • Clarity - ensure that technology choices are clear - do these line up with what you expect? do they match your steering documents?

rights reserved. Amazon Confidential and Trademark. 36 Break down implementation into small units of work

rights reserved. Amazon Confidential and Trademark. Requirements Start with intent ITERATE Design APPROVAL REFINE Tasks APPROVAL Steering SELECT Steering SELECT Implementation phase After approving the design, the next step in the workﬂow is to create a series of tasks that will be used to generate code. • Two-Level Maximum - Uses only top-level tasks and sub-tasks (to avoid deep nesting) • Logical Grouping - Group related tasks under meaningful categories • Sequential Dependencies - Order tasks so each builds on previous work • Testable Increments - Each task should result in testable functionality

rights reserved. Amazon Confidential and Trademark. 38 Tasks show implementation detail including traceability back to the requirement

rights reserved. Amazon Confidential and Trademark. Requirements Start with intent ITERATE Design APPROVAL REFINE Tasks APPROVAL ADJUST Steering SELECT Steering SELECT Review task sequence Whilst the generated implementation plan and task sequence is typically ok, you should review and adjust as needed. • Core First - Build essential functionality before optional features • Risk First - Tackle uncertain or complex tasks early • Value First - Implement high value features that can be tested quickly

rights reserved. Amazon Confidential and Trademark. 41 Managing task dependencies One thing you need to think about as you review and potentially update the tasks is how your tasks related to each other, specifically which tasks depend on others and whether some tasks need to be completed before others can be started. • Technical - Code components that must exist before others can be built. For example, Database models before services that use them, Authentication middleware before protected endpoints, or Configuration setup before feature implementation • Logical - Features that build conceptually on others. For example, User profile editing requires user registration, Password reset requires user authentication,Advanced search requires basic search • Data - Tasks that require specific data or state to exist. For example, User dashboard requires user data, Reporting features require transaction data, or Admin features require user roles

rights reserved. Amazon Confidential and Trademark. 42 Circular dependencies In some situations you might encounter a situation where you have a circular dependency. For example, you might have a User service that depends on an Auth service, but that Auth service itself depends on the User service. Three strategies that can help:

rights reserved. Amazon Confidential and Trademark. Requirements Start with intent ITERATE Design APPROVAL REFINE Tasks APPROVAL ADJUST Steering SELECT Steering SELECT Review task sequence Whilst the generated implementation plan and task sequence is typically ok, you should review and adjust as needed. • Core First - Build essential functionality before optional features • Risk First - Tackle uncertain or complex tasks early • Value First - Implement high value features that can be tested quickly

rights reserved. Amazon Confidential and Trademark. 44 Ready to generate code now?

rights reserved. Amazon Confidential and Trademark. 45 Start code generation for a task Completed tasks Start code generation for all tasks

rights reserved. Amazon Confidential and Trademark. 47 Updating your specification

rights reserved. Amazon Confidential and Trademark. 48 Minor updates that do not functionally change design or implementation but might help improve precision Clariﬁcation Changes Discoveries Changes to existing specifications (requirements or design) or the additional of new requirements During the implementation phase you might discover implementation details (tech) that lead to changes in design Triggers for updating your specification Technical Constraints Integration Challenges Feedback During code generation you identified sub optimization choices: limitations with libraries or APIs, performance issues, security concerns Data or interface format issues, complexities with authentication and authorization, new/updated interfaces Testing or user feedback – accessibility, mobile support, responsiveness, browser compatibility

rights reserved. Amazon Confidential and Trademark. 49 After revising your speciﬁcation, you work through those changes by using the “Update” or “Reﬁne” links

rights reserved. Amazon Confidential and Trademark. Lifecyle: Spec-driven development AI under control: Speciﬁcation driven lifecycle REFINE and UPDATE ISSUES FOUND Test/QA Implementation Intent Spec-driven development Context Steering documents Requirements Generate requirements Design Create initial Design Tasks Define tasks needed Maintenance INFLUENCES ITERATE ITERATE OPINIONATED WORKFLOW Deployment UPDATE or NEW

rights reserved. Amazon Confidential and Trademark. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. How does spec driven development compare to… 51

rights reserved. Amazon Confidential and Trademark. 52 Test Driven Development (TDD) Similarities: • Both emphasize defining success criteria before implementation • Both use an iterative red-green- refactor cycle (requirements- design-implementation) Key Differences: • SDD operates at a higher level of abstraction • Includes business requirements and system design, not just test cases • Can incorporate TDD practices within the implementation phase • Provides broader context beyond just testing Waterfall Similarities: • Both emphasize upfront planning and documentation • Both follow a sequential phase approach Key Differences: • SDD is more iterative within each phase • Specs are designed to be living documents that evolve • The methodology is optimized for feature-level development rather than entire projects • Greater emphasis on AI-assisted development and collaboration Behaviour Driven Development Similarities: • Both prioritize design and planning before coding • Both create detailed technical specifications Key Differences: • SDD includes explicit requirements gathering • More structured approach to task breakdown and implementation planning • Designed specifically for AI-assisted development workflows • Includes specific methodologies like EARS for requirements

rights reserved. Amazon Conﬁdential and Trademark. 54 I want to keep the vibe alive

rights reserved. Amazon Conﬁdential and Trademark. 55 The Vibe • Rapid, conversational code generation (CHOP) • Iterative, back and forth • Ephemeral • Point in time prompts • Transient context Spec driven • Focus on upfront planning and intent • Break down requests into discrete tasks • Steering documents ground agentic outputs • Lineage between intent and code Prompts to chase implementations Preserve intent, improve visibility

rights reserved. Amazon Confidential and Trademark. 56 The Vibe Use Vibe Coding to explore and experiment – get a better handle on what you really want Spec driven Take inputs from your vibe sessions, to drive specification driven development

rights reserved. Amazon Conﬁdential and Trademark. 58 Managing requirements and features

rights reserved. Amazon Conﬁdential and Trademark. 59 the new waterfall…?

rights reserved. Amazon Conﬁdential and Trademark. 60 Lifecycle management (of specs)

rights reserved. Amazon Conﬁdential and Trademark. 61 Everyone is developing their own spec driven development workflow

rights reserved. Amazon Conﬁdential and Trademark. 63 If only I had a tool that could help me…

rights reserved. Amazon Conﬁdential and Trademark. 64 Get started today! https://kiro.dev/download/

rights reserved. Amazon Conﬁdential and Trademark. Spec driven workshop https://s12d.com/kiro-workshop Builder ID https://s12d.com/builder-id

rights reserved. Amazon Conﬁdential and Trademark. Thank you! © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. https://www.linkedin.com/in/ricardosueiras 094459.bsky.social https://github.com/094459

Getting started with spec driven development

Getting started with spec driven development

More Decks by Ricardo Sueiras

Featured

Transcript