Spec-driven Development with AI

In many projects, specifications and code drift apart over time. Requirements change, documentation becomes outdated, and developers rely mainly on the code. This increases risk and makes changes harder, especially in long-lived business applications.

This talk presents a spec-driven approach where system use cases are the central artifact. A system use case describes observable system behavior and acts as a stable contract for the application. Code is derived from these use cases instead of treating the code itself as the source of truth.

AI is used as a supporting tool to generate and update code and tests from system use cases in small, controlled steps. The focus is not on full regeneration, but on keeping existing code and specifications aligned over time.
Using concrete examples, the talk shows how backend logic, database access, and UI behavior can evolve together. It also explains when code is generated, when it is updated, and how version control and reviews help keep changes small and understandable.

The session shares concrete workflows and lessons learned from daily Java development, including limitations and trade-offs of using AI in this way.

Transcript

1. Spec-Driven Development with AI Simon Martinelli
3. About Me • 30 years in Software Engineering • 25 years with Java • Self-employed since 2009 • Teaching at four universities • Co-lead Berne, JUG Switzerland Get 20% off: APAUT
4. AI Native Development Spec-Driven Development • Clear intent/specs guide AI to generate meaningful code Context-Aware Development • AI agents understand full codebase context Agent Experience AX • Autonomous AI tasks enhancing developer throughput
5. Three Levels of SDD Spec-first 1 • You write a spec before you write code. • The spec becomes the input for the AI coding agent. • When the feature is done, the spec is not needed anymore. • For the next change, you write a new spec. Spec-anchored 2 • The spec stays in the repository after the feature is done. • When the feature changes, you update the spec and the code together. • The spec is the longterm reference for humans and for the AI. Spec-as-source 3 • The spec is the only thing a human edits. • The code is always (re-)generated from the spec. • Humans never touch the code. Source: https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
6. Five Frameworks at a Glance Framework Core idea Main artifacts Sweet spot Checks code against spec OpenSpec Change proposals on top of living specs Proposal, spec deltas, tasks Changes in existing code, lightweight /opsx:verify, AI review (optional) BMAD A team of agent personas (analyst, PM, architect, dev) PRD, architecture, stories Greenfield, full agile flow with AI roles Parallel AI code review GitHub Spec Kit Constitution, then specify, clarify, plan, tasks, implement Constitution, spec, plan, tasks Greenfield features, works with many agents /analyze, /converge, AI review Kiro AWS Spec-centric IDE with steering and hooks Requirements EARS, design, tasks One developer or small team, one tool Property-based tests from requirements AI Unified Process Iterative process based on use cases Requirements, use cases, entity model, test cases Enterprise, brownfield, long-lived systems /coverage-check per flow and rule, sensors in CI 6
7. AI Unified Process https://unifiedprocess.ai
8. At a Glance Vision and requirements Use cases, entity model, architecture AI generates code and tests, you review Delivery and acceptance
9. Vision and Requirements
10. Use Cases and Architecture
11. Code, Tests and Delivery
12. Greenfield Workflow
13. Brownfield Workflow
14. Why Use Cases?
15. Behavior, Not Code CODELEVEL REQUIREMENT BEHAVIOR SPECIFICATION Add POST /owners/new and a column telephone VARCHAR(10) to the owners table. “A clinic user can register a new owner with a 10-digit telephone number. The system then shows the owner’s details.” ✕ Describes the how ✓ Describes the what ✕ Only developers can read it ✓ Every stakeholder can read it ✕ Outdated after the next refactoring ✓ Stays valid when the code changes ✕ Repeats what the framework already does ✓ Can be tested from the outside
16. https://leanpub.com/writing-use-cases-for-ai 16
17. https://github.com/ AIUnified-Process/ petclinic
18. Harness Engineering GUIDES steer before it acts SENSORS check after it acts Context Computational Specs, CLAUDE.md, constraints Skills Reusable know-how per stack Compiler, tests, ArchUnit, static analysis. Deterministic and fast, on every edit AI Agent Inferential Tools MCP servers, CLI, platform APIs Review agent, /coverage-check against the spec. AI-based, semantic The human steers: when a mistake happens twice, improve the harness, not the prompt The model is the same for everybody. The harness makes the difference.
19. Turn Guidelines into Guardrails A WISH A FACT A rule in CLAUDE.md A failing build The agent may follow it, or it may not 1 Hooks after every edit Formatter, compiler and tests run right after the agent changes a file The agent cannot ignore it 2 Architecture tests on every build ArchUnit checks layers, packages and dependencies 3 Quality gates in CI on every pull request Static analysis, dependency check, test coverage The agent fixes its own errors: it sees the failing check and corrects it in the same session If a rule matters, enforce it.
20. Review Is The Bottleneck 1 2 3 Before the PR Agent runs build, tests, linter. A subagent reviews the diff in a fresh context AI review on every PR Parallel agents hunt bugs, verifiers vote. Only confirmed findings are posted Security review Separate pass. Open findings block the merge 4 CI and merge queue 5 Human approval by risk Lint, types, tests, build. Re-run against the latest main Human approvals by risk 0 Low: docs, additive change behind a flag 1 Medium: ordinary product change 2 High: billing, CI workflows, auto-updater What stays human • • • • Should we build this at all? Architecture decisions Reading the evidence: tests, findings Owning the outcome The change sets the tier, not the author 14 automated · 5 human, only where the risk needs it Source: claude.dev/blog/solving-code-review-at-anthropic
21. Impact on the Architecture • Modular architecture reduces the context size • Self-contained Systems • Single ecosystem simplifies guardrails • Full-stack frameworks
22. Impact on Teams • Smaller team size • 12 developers per self-contained system • No more sprints • Continuous flow • From Scrum to Kanban • Progress tracking on use cases
23. Conclusion • Specify behavior, not code • Keep the spec in the repo • The harness makes the difference • Review is the new bottleneck • AI speeds you up, but you own the outcome
24. Thank you! • Web martinelli.ch • EMail simon@martinelli.ch • Bluesky @martinelli.ch • X/Twitter @simas_ch • LinkedIn https://linkedin.com/in/ simonmartinelli