A demo project accompanying a talk on Spec-Driven Development with the AI Unified Process (AIUP).
It revisits the classic Spring PetClinic sample, but built from the ground up using specifications first — use cases, an entity model, and UI flows — and then letting AI assistants implement the code against those specs.
Spec-Driven Development (SDD) flips the usual "prompt and pray" workflow on its head. Instead of asking an AI to produce code from a one-line request, you invest upfront in a precise, machine-readable specification of what the system should do. The AI then works against that spec — generating code, tests, and documentation that can be verified against a stable source of truth.
The AI Unified Process (AIUP) is a lightweight adaptation of the Unified Process for AI-assisted development. It keeps the artifacts that matter — use cases, domain models, architectural decisions — and drops the ceremony that doesn't. The result is a workflow where humans stay in charge of intent and AI handles the mechanical translation to code.
This repository is the running example used in the talk.
The repository is tagged at key milestones so you can follow the progression of the talk step by step.
| Tag | Description |
|---|---|
initial |
Project setup — Maven Wrapper, Spring Boot, Vaadin, Testcontainers, use case docs, and entity model. No implementation yet. |
use-case-review |
Refined use case specifications (infinite scrolling instead of pagination, terminology cleanup). |
first-use-case |
UC-001 implemented — welcome page, main layout with navigation menu, tests, and styling. |
full-implementation |
All use cases implemented with complete tests. |
To check out a specific tag:
git checkout <tag-name>
# for example, start from the beginning:
git checkout initialThis puts you in "detached HEAD" state, which is fine for browsing. To get back to the latest code:
git checkout mainIf you want to experiment on top of a tag, create a branch from it:
git checkout -b my-experiment initial- Java 25
- Spring Boot 4.0
- Vaadin 25 — UI
- jOOQ — type-safe SQL
- Flyway — database migrations
- PostgreSQL (via Testcontainers for tests)
The specifications that drive the implementation live in docs/:
docs/entity_model.md— the domain modeldocs/use_cases.puml— PlantUML use case diagramdocs/use_cases/— individual use case specifications
./mvnw spring-boot:test-runA PostgreSQL instance is required. Tests use Testcontainers and need Docker running:
./mvnw testdocs/ — specifications (the source of truth)
src/main/ — implementation derived from the specs
src/test/ — tests verifying the implementation against the specs