Spec-Driven Development From Specs to Code with AI Agents (Simon Martinelli)（Z-Library）
Code
Start your development process with a blueprint. Most teams jump into coding and leave documentation for later, if at all. Too often this leads to maintenance issues, stalled modernization, and poor business alignment. Spec-driven development flips the order: the specification becomes the single source of truth that drives code, tests, and validation. This pocket guide introduces the AI Unified Process, a lightweight framework that makes Spec-driven development practical in the age of generative AI. It shows how specs (requirements, use cases, entity models) can act as contracts, enabling AI agents and modern tools to generate, validate, and evolve software with far less guesswork. Designed for busy teams, this book focuses on the principles of spec-first development, with AI Unified Process skills and templates as the primary enabler. It also introduces emerging tools like Amazon Kiro and GitHub Spec Kit for context. Alongside practical methodology, you’ll work through a hands-on case study that takes you from requirements to executable code. By the end, you’ll understand how to apply Spec-driven Development in practice, avoid common pitfalls, and integrate AI into a disciplined, scalable workflow. What You Will Learn • Capture requirements in lightweight specs • Treat specs as executable contracts for code generation and testing • Apply the AI Unified Process to projects and team workflows • Integrate AI agents into a spec-driven lifecyce Who this Book is for: Software developers, tech leads, and architects with basic programming knowledge. No prior experience with requirements engineering or AI tools is required.
10
Views
Registered users can read the full content for free
Register as a Gaohf Library member to read the complete e-book online for free and enjoy a better reading experience.
Page
1
Spec-Driven Development From Specs to Code with AI Agents — Simon Martinelli
Page
2
Apress Pocket Guides
Page
3
Apress Pocket Guides present concise summaries of cutting-edge developments and working practices throughout the tech industry. Shorter in length, books in this series aims to deliver quick-to-read guides that are easy to absorb, perfect for the time-poor professional. This series covers the full spectrum of topics relevant to the modern industry, from security, AI, machine learning, cloud computing, web development, product design, to programming techniques and business topics too. Typical topics might include: • A concise guide to a particular topic, method, function or framework • Professional best practices and industry trends • A snapshot of a hot or emerging topic • Industry case studies • Concise presentations of core concepts suited for students and those interested in entering the tech industry • Short reference guides outlining ‘need-to-know’ concepts and practices. More information about this series at https://link.springer.com/ bookseries/17385.
Page
4
Spec-Driven Development From Specs to Code with AI Agents Simon Martinelli
Page
5
Spec-Driven Development: From Specs to Code with AI Agents ISBN-13 (pbk): 979-8-8688-2850-8 ISBN-13 (electronic): 979-8-8688-2851-5 https://doi.org/10.1007/979-8-8688-2851-5 Copyright © 2026 by Simon Martinelli This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation, broadcasting, reproduction on microfilms or in any other physical way, and transmission or information storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now known or hereafter developed. Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are not identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to proprietary rights. While the advice and information in this book are believed to be true and accurate at the date of publication, neither the authors nor the editors nor the publisher can accept any legal responsi- bility for any errors or omissions that may be made. The publisher makes no warranty, express or implied, with respect to the material contained herein. Managing Director, Apress Media LLC: Welmoed Spahr Acquisitions Editor: Melissa Duffy Editorial Assistant: Gryffin Winkler Cover designed by eStudioCalamar Distributed to the book trade worldwide by Springer Science+Business Media New York, 1 New York Plaza, New York, NY 10004. Phone 1-800-SPRINGER, fax (201) 348-4505, e-mail orders-ny@springer-sbm.com, or visit www.springeronline.com. Apress Media, LLC is a Delaware LLC and the sole member (owner) is Springer Science + Business Media Finance Inc (SSBM Finance Inc). SSBM Finance Inc is a Delaware corporation. For information on translations, please e-mail booktranslations@springernature.com; for reprint, paperback, or audio rights, please e-mail bookpermissions@springernature.com. Apress titles may be purchased in bulk for academic, corporate, or promotional use. eBook versions and licenses are also available for most titles. For more information, reference our Print and eBook Bulk Sales web page at http://www.apress.com/bulk-sales. This book represents the author’s personal work and opinions. It is not affiliated with, endorsed by, or representative of any employer. All architectural concepts are presented for educational purposes and do not describe any proprietary systems. Any source code or other supplementary material referenced by the author in this book is available to readers on GitHub. For more detailed information, please visit https://www.apress.com/gp/ services/source-code. If disposing of this product, please recycle the paper Simon Martinelli Erlach, Switzerland
Page
6
To my wife, Lisa. Thank you for the room to work on my ideas and projects, and for always supporting me.
Page
7
(This page has no text content)
Page
8
(This page has no text content)
Page
9
(This page has no text content)
Page
10
(This page has no text content)
Page
11
(This page has no text content)
Page
12
(This page has no text content)
Page
13
(This page has no text content)
Page
14
xv Simon Martinelli is a Java Champion, Vaadin Champion, and Oracle ACE Pro with over three decades of experience as a software architect, developer, consultant, and trainer. He is the creator of the AI Unified Process and a strong advocate of Spec-Driven Development. As the owner of Martinelli LLC, he coaches teams to get up to speed with AI-driven development. He regularly shares his insights through international conferences, articles, and his blog Keep IT Simple, where he writes about AI, architecture, and modern Java development. He is also a lecturer at two universities in Switzerland, where he teaches software architecture, persistence, DevOps, and cloud-native development. About the Author
Page
15
xvii Neerja Bhatnagar is a software engineer with more than 19 years of experience building complex systems, including nine years building large-scale backend systems at a major tech company. She has an MS in Computer Science from California State University, Chico, and currently works at an early-stage startup focused on agent governance. Outside of work, Neerja enjoys pursuing her hobbies and spending time with friends and family. About the Technical Reviewer
Page
16
xix Acknowledgments Writing a book is never the work of one person alone. Many people helped me along the way, and I want to thank them here. First, I want to thank the team at Apress who guided me through the whole process with patience and clear advice. I am grateful to my technical reviewer, who read the chapters with care and gave me honest and useful feedback. The book is stronger because of it. I also want to thank the colleagues, clients, and friends in the community who tried the ideas in this book, asked hard questions, and shared their own experience. The AI Unified Process grew out of many real projects and many conversations. You know who you are. And thank you to my wife Lisa for the patience and support.
Page
17
xxi Introduction For more than thirty years I have built business software. I started with COBOL and moved to Java, and along the way, I learned one thing again and again: the hard part of software is rarely the code. The hard part is knowing what to build, writing it down clearly, and keeping that shared understanding alive as the system grows. AI coding tools have changed how fast we can write code. They have not changed this hard part. In fact, they make it harder. When a tool can produce hundreds of lines in seconds, the risk is no longer slow typing. The risk is building the wrong thing quickly, with no clear record of what was intended or why. This book is about a way to work that keeps the intent at the center. It is called the AI Unified Process. The idea is simple. We describe the behavior we want as clear specifications, we tie those specifications to tests, and we let AI do the heavy lifting of writing the code. The specification stays the source of truth. The code follows from it, and we can always check one against the other. AI Unified Process builds on ideas that are not new. Use cases, introduced by Ivar Jacobson and refined by Alistair Cockburn, have helped teams capture behavior for a long time. What is new is how we connect these ideas to AI tools and to a working test suite, so the whole thing stays honest and stays in sync. The result is a process that works for new projects and for large existing systems, where most of us spend most of our time.
Page
18
xxii Who This Book Is For This book is for developers, software architects, technical leads, but also requirements engineers and testers who want to use AI tools without losing control of their systems. You do not need to work with any single framework. The examples use the stack I know best, but the method does not depend on it. If you care about clear requirements, maintainable code, and software you can still understand a year from now, this book is for you. How This Book Is Organized The book follows the same path you would take on a real project, from the first question to a working system and then to a whole team. Chapter 1 asks why we need spec-driven development at all, and what goes wrong without it. Chapter 2 gives you the AI Unified Process in a nutshell, so you have the full picture before we go into detail. Chapters 3–6 are the core of the method. We move from requirements to specs (Chapter 3), learn to write specifications that can be executed (Chapter 4), turn those specs into tests (Chapter 5), and then let them drive the code (Chapter 6). This is the heart of the AI Unified Process: the specification stays the source of truth, and everything else follows from it. Chapter 7 looks at the tools that support this way of working. Chapter 8 brings it all together in a case study, where we build a simple task manager step by step. The last two chapters take you beyond a single project. Chapter 9 shows how to scale spec-driven development in teams. Chapter 10 collects the best practices and the common pitfalls, so you can learn from mistakes without making them yourself. Each chapter builds on the one before it, but you can also jump to the topic you need. InTroduCTIon
Page
19
xxiii A note on the approach My guiding rule has always been to keep it simple. The AI Unified Process is not a heavy process with many roles and documents. It is a small set of practices that you can adopt one at a time. Start with one use case, write it down clearly, and let the rest grow from there. Let us begin. InTroduCTIon
Page
20
1© Simon Martinelli 2026 S. Martinelli, Spec-Driven Development, Apress Pocket Guides, https://doi.org/10.1007/979-8-8688-2851-5_1 CHAPTER 1 Why Spec-Driven Development? Code-first development often creates systems that are hard to understand, debug, maintain, and even harder to modernize. This chapter explains why this happens and how specifications as executable contracts restore clarity between business and IT. From Balcony Architecture to Clarity In many applications, code grows over years like a building with balconies added in different styles. Each “quick fix” or “urgent feature” adds another balcony. After a decade, the original structure is no longer visible. Developers must search through deeply nested conditions to understand what the system does. I call this “balcony architecture.” When modernizing such a system, the code is not the truth. It is only the result of many decisions over time. To rebuild or refactor safely, we must first understand the business rules and the real intent. Integration and unit tests might capture the correctness of behavior, but they do not also capture the decisions and the “why” of decisions. This knowledge should live in specifications, not in memories or comments.
The above is a preview of the first 20 pages. Register to read the complete e-book.
AI Reading Assistant
Whole-book reading guide from stratified index samples; jump to passages in the text
AI guide
【One-Line Pitch】
A concise, practical guide to making specifications—not code—the source of truth, showing how developers, tech leads, and architects can use the AI Unified Process to turn lightweight requirements, entity models, and system use cases into executable contracts that AI agents can generate, validate, and evolve.
【Book Arc】
- **Opening (~0%–10%)**: Frames the core problem—code-first and “vibe coding” produce fast output but lose the reasoning behind decisions—and introduces spec-driven development as the fix, with specifications driving code, tests, and validation.
- **Early (~10%–34%)**: Introduces the AI Unified Process: three lightweight artifacts (Requirements Catalog, Entity Model, System Use Cases), an iterative specify–generate–validate–review–refine life cycle, and Markdown/Git-based traceability.
- **Middle (~34%–55%)**: Moves from raw workshop material to structured specs—AI-assisted requirement capture, entity modeling, writing clear system use cases with flows and metadata, then making those specs executable and unambiguous.
- **Late (~55%–80%)**: Connects specs to code generation and tooling, including emerging tools such as Amazon Kiro and GitHub Spec Kit, and compares what different tools offer.
- **Ending (~80%–100%)**: A hands-on task-manager case study walks from vision to requirements to entity model to code, followed by guidance on scaling spec-driven development in teams and collecting best practices and pitfalls.
【Key Takeaways】
- **Specifications become the single source of truth** (Opening): Code shifts from “where decisions are made” to “where decisions are implemented,” which reduces rework, improves maintainability, and keeps documentation living rather than stale.
- **Three lightweight artifacts carry the method** (Early): A Requirements Catalog captures intent (functional, non-functional, constraints), an Entity Model defines domain vocabulary, and System Use Cases define observable behavior—together forming a complete, readable spec set.
- **User stories and system use cases serve different jobs** (Early): Stories express business intent (“As a… I want… so that…”), while use cases formalize that intent into testable behavior with main, alternate, and exception flows.
- **Executable means observable and unambiguous** (Middle): Specs must describe behavior precisely enough that two developers—or an AI agent—arrive at the same implementation; one rule per statement and strong preconditions/postconditions are emphasized.
- **Traceability is built in via stable IDs** (Middle): Requirements, use cases, entities, code, and tests are linked through identifiers stored in Markdown and Git, so teams can see why something exists and what must change.
- **AI accelerates but humans remain the quality gate** (Middle): AI helps summarize, extract, check consistency, and generate scaffolding and tests, but human review is the critical gate for correctness, architecture, and trade-offs.
- **The life cycle is iterative, not phase-based** (Early): Specify, generate, validate, review, and refine in short cycles—no handovers, just continuous alignment between specs and implementation.
- **Spec-driven development is modernization-ready** (Early): Technology-independent specs can be reused when moving to a new stack, making systems less coupled to a specific framework or platform.
【Reading Tips】
- **Read Chapters 1–2 closely** for the conceptual foundation and the AI Unified Process; skim if you already accept spec-first thinking, but don’t skip the artifact definitions.
- **Deep-read Chapters 3–5** if you will actually write specs—these cover requirement capture, use case structure, and what makes a spec executable; the templates and examples are the most reusable material.
- **Use Chapter 8 as a walkthrough, not a reference**: follow the task-manager case study end to end once to see how the artifacts connect, then return to specific steps as needed.
- **Treat Chapters 9–10 as a checklist** when adopting the method in a team; the pitfalls section is where you’ll recognize your own past failures.
- **Keep the book nearby during real work**: it is a pocket guide, so its value comes from applying the templates and reviewing your specs against its clarity rules.
【Coverage Limits】
The excerpts cover the book’s structure, core concepts, and several chapter openings in detail, but do not provide full chapter content for the tooling comparison (Chapter 7) or the complete case study and team-scaling chapters; specific tool features and some templates are only partially visible.
Passage locations
Excerpt 1
ents Simon Martinelli Table of Contents About the Author xv About the Technical Reviewer xvii Acknowledgments xix Introduction xxi Chapter 1: Why Spec-Driven...
View in text
Excerpt 2
business-specific. As a result, teams had to mix generated code with hand-written extensions, which increased complexity, reduced maintainability, and broke...
View in text
Excerpt 3
se case flows and business rules are implemented correctly. Validation can be automated in CI pipelines, ensuring that changes in code or specs do not break...
View in text
Excerpt 4
ision points and flow alternatives visible at a glance. 39 Chapter 3 From requirements to speCs Table 3-5. Use Case Relationships Relationship Meaning Exampl...
View in text
Recommended for You
{{#thumbnailUrl}}
{{/thumbnailUrl}}
{{^thumbnailUrl}}
{{/thumbnailUrl}}
Loading recommended books...
Failed to load, please try again later
Tip the Site
Scan the WeChat Pay or Alipay code to tip. No login required.
WeChat Pay
Alipay