Spec-Driven Planning for Spring Boot

Spec-Driven Planning for Spring Boot

Overview

Spec-driven development separates PLANNING from IMPLEMENTATION. This skill defines how to create implementation specifications that enable reliable, predictable code generation.

Why Spec-Driven Development?

1. Reduces errors: Planning catches design issues before coding
2. Enables parallelization: Multiple implementers can work from specs
3. Improves quality: Tests are designed upfront, not afterthought
4. Documents decisions: Specs serve as implementation record

Specification Structure

Required Sections

# Implementation Specification

## Task Type
NEW_FEATURE | BUG_FIX | ENHANCEMENT

## Summary
One paragraph describing the deliverable.

## Requirements
Numbered list of what must be achieved.

## Existing Code Analysis
(Required for BUG_FIX and ENHANCEMENT)
- Files analyzed with line references
- Current behavior description
- Patterns to follow

## Implementation Plan
### Phase 1: Test Specification (RED)
Exact test code to write.

### Phase 2: Implementation (GREEN)
File-by-file checklist of changes.

### Phase 3: Verification
Commands to run and expected results.

## Acceptance Criteria Mapping
Table linking requirements → tests → implementation.

Planning by Task Type

NEW_FEATURE Planning

Focus on:

• API contract design (request/response DTOs)
• Service layer interfaces
• Data model design
• Error scenarios and handling
• Test scenarios covering happy path + edge cases

Do NOT:

• Look at existing code (unless for patterns)
• Over-engineer or add unnecessary features
• Plan more than what requirements specify

BUG_FIX Planning

Critical: Must analyze existing code before planning fix.

1. Reproduce understanding

   • Document EXPECTED vs ACTUAL behavior
   • Identify reproduction steps

2. Code analysis

   • Find the bug location (file, method, line)
   • Trace execution path
   • Identify root cause (not just symptom)

3. Fix design

   • Specify exact code changes
   • Design regression test that would have caught this
   • Assess blast radius (what else might break)

ENHANCEMENT Planning

Critical: Must deeply understand existing code before extending.

1. Existing code inventory

   • List all files that will be touched
   • Document current method signatures
   • Note test patterns already in use

2. Extension design

   • Add new, don't modify existing signatures
   • Maintain backward compatibility
   • Follow existing naming conventions

3. Test design

   • New tests only (don't modify existing)
   • Cover new functionality
   • Verify no regressions

Test Specification Guidelines

Test Structure

@Test
void should_[expectedBehavior]_when_[condition]() {
    // Given - setup

    // When - action

    // Then - assertions
}

Coverage Requirements

• Happy path (main success scenario)
• Edge cases (empty inputs, boundaries)
• Error cases (invalid inputs, failures)
• For bugs: regression test that fails without fix

Specificity Level

BAD (too vague):
- Write tests for the service

GOOD (specific):
- Test: should_returnUser_when_validIdProvided
  - Given: User with ID=1 exists in repository
  - When: findById(1) called
  - Then: Returns Optional containing user

Implementation Checklist Guidelines

File Change Format

#### File: `src/main/java/com/example/UserService.java`
- [ ] Add method: `public User findByEmail(String email)`
- [ ] Add null check for email parameter
- [ ] Throw `IllegalArgumentException` if email is blank
- [ ] Call `userRepository.findByEmail(email)`
- [ ] Return result or throw `UserNotFoundException`

Dependency Order

List implementation tasks in dependency order:

1. Models/Entities first
2. Repository interfaces
3. Service implementations
4. Controllers
5. Integration points

Verification Specification

Always include exact commands:

### Phase 3: Verification
```bash
# 1. Compile check
mvn compile

# 2. Run specific tests
mvn test -Dtest=UserServiceTest,UserControllerTest

# 3. Run all tests
mvn test

# 4. Run with coverage
mvn test jacoco:report
# Expected: >80% coverage on new code

# 5. Integration tests
mvn verify

## Common Planning Mistakes

| Mistake | Impact | Prevention |
|---------|--------|------------|
| Skipping code analysis for bugs | Wrong fix | Always read existing code first |
| Vague test descriptions | Tests miss cases | Use Given/When/Then |
| Missing error scenarios | Bugs in production | Explicitly list error cases |
| Ignoring existing patterns | Inconsistent code | Document patterns before planning |
| Over-engineering | Wasted effort | Plan only what's required |

## Quality Checklist for Plans

Before finalizing a plan, verify:

- [ ] Task type is clearly identified
- [ ] All requirements are listed and numbered
- [ ] For bugs/enhancements: existing code is analyzed
- [ ] Test cases have Given/When/Then structure
- [ ] Implementation checklist is file-by-file
- [ ] Verification commands are exact and runnable
- [ ] Acceptance criteria maps to tests
- [ ] No ambiguous instructions