Spring Boot + Spec Driven Development#

Moving from code first development to specification first development with Spring Boot and AI.

Introduction#

For decades, software development looked like this:

1
Requirements
2
     ↓
3
 Developer writes code
4
     ↓
5
 Tests
6
     ↓
7
 Documentation

Unfortunately, the requirements were often forgotten after implementation. The source of truth eventually became the code, not the business requirements. With modern AI assistants (Claude, GPT-5.x, Copilot etc.), the workflow can fundamentally change.

Instead of asking:

“How do I write this code?”

we ask

“How do I specify exactly what the software should do?”

This is the main idea behind Spec Driven Development (SDD) discussed by Simon Martinelli in the Spring Office Hours podcast. podcast

The specification becomes the single source of truth. Code becomes an implementation artifact that can be generated, verified, regenerated, and tested.

Why Spec Driven Development?#

Traditional development usually evolves like this:

1
Business Requirement
2
↓
3
Developer interpretation
4
↓
5
Implementation
6
↓
7
Tests
8
↓
9
Documentation

Notice that the original requirement is lost.

In Spec Driven Development:

1
Business Requirement
2
↓
3
Specification
4
↓
5
AI / Developer
6
↓
7
Generated Code
8
↓
9
Generated Tests
10
↓
11
Verification

The specification never disappears.

Core Principles#

1
The system shall allow a user to register.
2
Email must be unique.
3
Password must contain:
4

5
- uppercase
6
- lowercase
7
- digit
8
- minimum length 10
9

10
Duplicate email returns HTTP 409.

Project Structure#

A Spring Boot project might look like this

1
specs/
2
    user-registration.md
3
    login.md
4
    order.md
5

6
src/
7
    main/
8
    test/
9

10
prompts/
11
    generate-controller.md
12
    generate-tests.md

Instead of hundreds of Jira tickets becoming stale, the specifications stay versioned with the code.

Example Specification#

File

1
specs/user-registration.md

1
# User Registration
2

3
## Endpoint
4

5
POST /api/users
6

7
## Request
8

9
{
10
  "email": "john@example.com",
11
  "password": "Password123"
12
}
13

14
## Validation
15

16
Email
17

18
- required
19
- valid email
20
- unique
21

22
Password
23

24
- minimum length 10
25
- uppercase required
26
- lowercase required
27
- digit required
28

29
## Success
30

31
HTTP 201
32

33
{
34
   "id": UUID,
35
   "email": "john@example.com"
36
}
37

38
## Errors
39

40
400 Invalid request
41

42
409 Duplicate email

No implementation.

Only behavior.

From Spec to Spring Boot#

An AI assistant can generate

1
Controller
2
↓
3
DTO
4
↓
5
Validation
6
↓
7
Service
8
↓
9
Repository
10
↓
11
Tests

Generated DTO#

1
public record UserRegistrationRequest(
2

3
    @Email
4
    @NotBlank
5
    String email,
6

7
    @NotBlank
8
    @Pattern(
9
        regexp = "^(?=.*[A-Z])(?=.*[a-z])(?=.*\\d).{10,}$"
10
    )
11
    String password
12

13
) {}

Notice how validation rules came directly from the specification.

Generated Controller#

1
@RestController
2
@RequestMapping("/api/users")
3
public class UserController {
4

5
    private final UserService service;
6

7
    public UserController(UserService service) {
8
        this.service = service;
9
    }
10

11
    @PostMapping
12
    public ResponseEntity<UserResponse> register(
13
            @Valid
14
            @RequestBody UserRegistrationRequest request
15
    ) {
16

17
        UserResponse response =
18
                service.register(request);
19

20
        return ResponseEntity
21
                .status(HttpStatus.CREATED)
22
                .body(response);
23
    }
24

25
}

Nothing magical.

The controller simply reflects the specification.

Service Layer#

1
@Service
2
public class UserService {
3

4
    private final UserRepository repository;
5

6
    public UserResponse register(UserRegistrationRequest request) {
7

8
        if(repository.existsByEmail(request.email())) {
9
            throw new DuplicateEmailException();
10
        }
11

12
        User entity = new User(
13
                UUID.randomUUID(),
14
                request.email(),
15
                passwordEncoder.encode(request.password())
16
        );
17

18
        repository.save(entity);
19

20
        return UserResponse.from(entity);
21

22
    }
23

24
}

Again, Business rules came from the specification.

OpenAPI First#

Spec Driven Development fits naturally with OpenAPI.

Example

1
paths:
2
  /users:
3
    post:
4
      summary: Register user
5
      requestBody:
6
        required: true
7
      responses:
8
        "201":
9
          description: User created
10
        "409":
11
          description: Duplicate email

From this specification you can generate

• Controllers
• DTOs
• Clients
• Documentation

using tools like OpenAPI Generator.

Testing from Specifications#

Instead of manually writing tests, AI can derive them.

Example

1
@Test
2
void duplicateEmailReturns409() {
3

4
    given(repository.existsByEmail(any()))
5
            .willReturn(true);
6

7
    mockMvc.perform(post("/api/users")
8
            .contentType(APPLICATION_JSON)
9
            .content(json))
10

11
            .andExpect(status().isConflict());
12

13
}

The specification explicitly required HTTP 409.

Example Prompt#

1
Using the specification below,
2
generate:
3

4
- DTO
5
- Controller
6
- Service
7
- Unit tests
8
- Integration tests
9

10
Requirements:
11

12
Use Spring Boot 4
13

14
Use Jakarta Validation
15

16
Use Problem Details
17

18
Do not invent business rules.
19

20
Only implement what is specified.

AI Workflow#

1
Business
2
↓
3
Specification
4
↓
5
Git
6
↓
7
AI
8
↓
9
Generated Code
10
↓
11
Developer Review
12
↓
13
Tests
14
↓
15
Production

Notice that AI is not replacing developers. It is replacing repetitive implementation work.

Keeping Specifications Close to Code#

A practical repository might look like this

1
order-service/
2
    specs/
3
        create-order.md
4
        cancel-order.md
5
        payment.md
6
    src/
7
    prompts/
8
    docs/

Each pull request updates

• specification
• implementation
• tests

together.

Example Evolution#

1
Password minimum length
2

3
10

1
Password minimum length
2

3
12

What Should Developers Still Do?#

Spec Driven Development does not eliminate engineering.

Developers still make architectural decisions:

• Domain modeling
• Security
• Transactions
• Performance
• Distributed systems
• Observability
• Monitoring
• Database design

AI accelerates implementation. Engineers remain responsible for correctness.

Best Practices with Spring Boot#

1
Register User

1
Entire User Management Module

1
Return HTTP 404 if user not found.

1
Use Optional.orElseThrow(...)

Advantages#

• Better communication with stakeholders
• Requirements remain the source of truth
• Easier onboarding
• Better AI-generated code
• Consistent APIs
• Easier test generation
• Less duplicated documentation

Challenges#

• Writing good specifications requires practice
• Ambiguous requirements still produce ambiguous code
• AI output must always be reviewed
• Architecture cannot be fully automated

A Typical Development Cycle#

1
1. Write specification
2
↓
3
2. Review with stakeholders
4
↓
5
3. Commit specification
6
↓
7
4. Generate implementation
8
↓
9
5. Review generated code
10
↓
11
6. Execute tests
12
↓
13
7. Deploy

Conclusion#

Spec Driven Development shifts the primary artifact of software engineering from code to specifications.

For Spring Boot teams, this approach works particularly well because:

• Spring’s conventions make generated code predictable.
• Validation rules map naturally from specifications.
• OpenAPI integrates seamlessly with REST APIs.
• AI assistants excel at generating controllers, DTOs, services, and tests from well defined requirements.

The key insight is simple:

Code changes frequently. Requirements should not.

When specifications become the single source of truth, Spring Boot becomes the execution platform, AI becomes the implementation assistant, and developers focus on solving business problems rather than writing repetitive boilerplate.

Further Reading#

• Spring Office Hours Podcast S5E14: Spec Driven Development with Simon Martinelli
• Spring Boot Reference Documentation
• OpenAPI Specification
• Spring REST Docs
• Spring AI
• OpenAPI Generator