Pixel Piston

Spec Driven Development: A Practical Guide with SpecKit

Sat, 11 Jul 2026 00:00:00 GMT

Spec-Driven Development: A Practical Guide with SpecKit

Starting features with enthusiasm and ending three days later wondering what you were actually building is common. Spec-driven development fixes this.

The Problem

A feature request arrives: "add comments to blog posts." Your brain jumps to implementation: GitHub API, markdown rendering, localStorage caching.

Two weeks later:

Caching is overly complex
Repo name hardcoded in five places
No rate limit handling
Mobile layout broken
Forgot the "disable comments per post" requirement

The issue isn't coding skills—it's jumping into implementation before understanding what you're building.

Spec-Driven Development

Write a detailed specification before writing code. This isn't waterfall documentation. It's lightweight and practical.

The process:

Specify what you're building (what and why, not how)
Plan how you'll build it (technical decisions, trade-offs)
Break down into actionable tasks
Implement with confidence

Each step forces thinking at the right abstraction level. You clarify user needs before designing schemas. You understand constraints before picking libraries.

SpecKit

SpecKit codifies this workflow with opinionated structure.

Four main commands:

speckit specify   # Create the feature specification
speckit plan      # Generate the implementation plan
speckit tasks     # Break down into actionable tasks
speckit implement # Execute the tasks

Each command builds on the previous one. Here's a real example.

Example: Adding Giscus Comments

I recently added comments to this blog. Instead of diving into code, I used SpecKit.

Step 1: Specification

Ran speckit specify with:

"Comment section under each post using GitHub comments"

SpecKit generated:

# Feature Specification: Giscus Comments Integration

## Feature Overview

Enable blog post comments using **Giscus** - a comments system 
powered by GitHub Discussions. Readers can discuss posts using 
their GitHub accounts without leaving the blog.

## User Stories

### US1: Display Giscus Comments Widget (P1)

**As a** blog reader  
**I want to** see a comments section under blog posts  
**So that** I can read and participate in discussions

**Acceptance Criteria**:
- Giscus widget loads on posts where commentsEnabled: true
- Widget displays existing discussion comments from GitHub
- Widget matches blog's light/dark theme automatically
- Loading state shows graceful placeholder
- Widget is responsive on all screen sizes

Notice what's missing: no React vs Vue, no database schemas, no API endpoints. Just user-facing requirements.

The spec included non-goals:

## Non-Goals

- Custom comment UI (use Giscus default)
- Email notifications (handled by GitHub)  
- Comment editing within blog (use GitHub Discussions)
- Anonymous comments (GitHub authentication required)

Non-goals define scope boundaries. Write them down so future-you doesn't waste time on features you explicitly decided against.

Step 2: Implementation Plan

speckit plan generated the technical plan—actual engineering decisions:

# Implementation Plan: Giscus Comments Integration

## Constitution Compliance Check

✅ Preservation-First: Fuwari template structure untouched
✅ Minimal Change: Single new component
✅ Component Isolation: Zero dependencies on existing components
✅ Configuration Over Code: All settings in src/config.ts
✅ Development Validation: TypeScript strict mode enabled

## Tech Stack Analysis

**Existing Stack**:
- Framework: Astro 5.x (SSG)
- UI: Svelte 5
- Styling: Tailwind CSS 3.x
- Package Manager: pnpm

**New Dependencies**:
- Giscus: CDN-hosted script (no npm dependencies needed)

## Implementation Strategy

### Phase 1: Setup & Configuration
- Create src/types/giscus.ts
- Add giscusConfig to src/config.ts
- Extend content schema

### Phase 2: Component Implementation
- Create GiscusComments.svelte
- Dynamic script injection via onMount
- Handle theme synchronization

The plan also showed file changes:

src/
├── components/
│   └── GiscusComments.svelte          (NEW - 50 lines)
├── types/
│   └── giscus.ts                       (NEW - 20 lines)
├── config.ts                           (MODIFY - add 15 lines)

Before writing code, I knew I'd touch three files and add about 85 lines. No surprises.

Step 3: Task Breakdown

Running speckit tasks broke the work into 47 concrete tasks:

## Phase 1: Setup & Type Definitions

- [ ] T001 Create specs/002-giscus-comments/ directory structure
- [ ] T002 Create src/types/giscus.ts with interfaces
- [ ] T003 Verify existing dependencies

## Phase 2: Configuration & Schema

- [ ] T004 Add giscusConfig export to src/config.ts
- [ ] T005 Extend postsCollection schema with commentsEnabled field
- [ ] T006 Update .gitignore if needed

## Phase 3: Component Implementation

- [ ] T007 [US1] Create GiscusComments.svelte skeleton
- [ ] T008 [US1] Implement onMount hook for script injection
- [ ] T009 [US1] Set all data-* attributes from config

Each task is actionable, testable, and scoped. Tasks are tagged with user stories [US1] for tracking.

Step 4: Implementation

I implemented manually using the task list as a guide. One evening instead of the usual weekend of refactoring.

Final component (50 lines):

<script lang="ts">
  import { onMount } from "svelte";
  import { giscusConfig } from "@/config";

  interface Props {
    discussionNumber?: number;
    class?: string;
  }

  let { discussionNumber, class: className = "" }: Props = $props();
  let container: HTMLDivElement;

  onMount(() => {
    const script = document.createElement("script");
    script.src = "https://giscus.app/client.js";
    script.setAttribute("data-repo", giscusConfig.repo);
    script.setAttribute("data-repo-id", giscusConfig.repoId);
    script.setAttribute("data-category", giscusConfig.category);
    script.setAttribute("data-category-id", giscusConfig.categoryId);

    if (discussionNumber) {
      script.setAttribute("data-mapping", "number");
      script.setAttribute("data-discussion-number", discussionNumber.toString());
    } else {
      script.setAttribute("data-mapping", giscusConfig.mapping);
    }

    script.setAttribute("data-strict", "0");
    script.setAttribute("data-reactions-enabled", 
      giscusConfig.reactionsEnabled ? "1" : "0");
    script.setAttribute("data-theme", giscusConfig.theme);
    script.setAttribute("data-lang", giscusConfig.lang);
    script.crossOrigin = "anonymous";
    script.async = true;

    container.appendChild(script);
  });
</script>

<div bind:this={container} class="giscus-container w-full {className}"></div>

Clean, simple, no scope creep. Just the feature, shipped.

vs. Other Methodologies

Test-Driven Development (TDD): Write tests first, implement to pass. Great for algorithms and correctness, but doesn't help figure out what to build. TDD starts at code level; SDD starts at product level. They're complementary.

Behavior-Driven Development (BDD): Uses Gherkin scenarios to bridge product and engineering. Similar to SDD but test-focused. Specs are broader—they include architecture, trade-offs, and non-functional requirements.

Documentation-First: Usually either too detailed (becomes outdated immediately) or too vague (doesn't constrain implementation). Specs are the middle ground.

Ad-Hoc Development: Works for prototypes, very small features, or problems you've solved repeatedly. For everything else, you end up refactoring because requirements weren't thought through.

Benefits and Trade-offs

Benefits:

Clarity before code
Easy PR reviews with context
Onboarding documentation
Less refactoring (catch design flaws in planning)
Better estimates

Trade-offs:

Upfront time investment
Overhead for tiny changes
Can feel slow at first
Requires discipline

The key is knowing when to use it. Greenfield features? Yes. Bug fixes? No. Infrastructure changes? Yes. Typo in README? No.

Getting Started

# Install SpecKit
npm install -g speckit-cli

# Initialize in your project
cd your-project
speckit init

# Create your first spec
speckit specify "Add user authentication with OAuth2"

SpecKit interviews you about the feature, generates a spec. Edit it, then:

speckit plan    # Generate implementation plan
speckit tasks   # Break into tasks

Implement manually or use speckit implement for AI assistance.

Lessons Learned

After six months:

Specs evolve: Your first spec won't be perfect. Update it as you discover edge cases.

Write for future-you: Document decisions. You won't remember why in three months.

Keep specs focused: If it's 10+ pages, it's either multiple features or too detailed. Good specs are 1-3 pages, readable in 10 minutes.

Use a constitution: Document development principles. SpecKit can check plans against it. Mine includes: preserve template structure, minimal changes, configuration over code, component isolation.

Customize templates: Codify your team's practices. My templates include constitution compliance, performance considerations, security implications, and rollback plans.

When NOT to Use This

Prototypes (you're exploring and learning)
Trivial changes (typo fixes)
Emergency fixes (production down? Fix first, spec later)
Solo side projects (overhead may not be worth it)

The sweet spot: greenfield features in production systems with multiple contributors.

Wrapping Up

Spec-driven development forces you to think before coding. SpecKit codifies a workflow good teams already follow informally.

If you're getting lost mid-implementation or constantly clarifying requirements, try it. Next feature, spend 30 minutes writing a spec—just user stories and acceptance criteria. See how it feels.

Resources: SpecKit Docs • Spec-Driven Development Manifesto

Building AI-Powered Spring Boot Apps with Spring AI

Sat, 11 Jul 2026 00:00:00 GMT

Building AI-Powered Spring Boot Apps with Spring AI

If you're working with Spring Boot and feeling left out of the AI wave, don't. Spring AI brings AI integration to the Spring ecosystem without forcing you to rewrite everything in Python.

I'll walk through building an AI powered REST API using real code. We'll create an article summarizer that actually works in production.

Why Bother?

Your stack is already Spring Boot. Your team knows Spring. Your infrastructure runs Spring. Why add Python microservices or learn new frameworks when Spring AI works with what you have?

You get familiar patterns (ChatClient feels like RestTemplate), dependency injection, auto configuration, and support for multiple AI providers like OpenAI, Azure, Anthropic, or local models via Ollama.

The Project

We're building a REST API that takes articles and returns AI-generated summaries. You'll be able to specify summary length and get actual production-ready code.

Setup

Here are the Maven dependencies:

<project>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
    </parent>
    
    <dependencies>
        <!-- Spring Boot Web for REST API -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- Spring AI for OpenAI integration -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
            <version>1.0.0-M1</version>
        </dependency>
        
        <!-- For API documentation (optional but recommended) -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.3.0</version>
        </dependency>
    </dependencies>
</project>

Configuration in application.yml:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4
          temperature: 0.7
          max-tokens: 500

# Application-specific settings
app:
  ai:
    rate-limit:
      requests-per-minute: 10
    timeout-seconds: 30

Set your API key as an environment variable:

export OPENAI_API_KEY=sk-your-key-here

Core Concepts

ChatClient

The main interface. Send a string, get a string back:

@Autowired
private ChatClient chatClient;

public String chat(String message) {
    return chatClient.call(message);
}

ChatOptions

Control AI behavior with options:

ChatOptions options = OpenAiChatOptions.builder()
    .withModel("gpt-4")
    .withTemperature(0.7)  // 0 = deterministic, 1 = creative
    .withMaxTokens(500)
    .build();

Temperature controls randomness (0 = deterministic, 1 = creative). Max tokens limits response length. Set these globally or per-request.

PromptTemplate

Don't hardcode prompts. Use templates:

String template = """
    Summarize the following article in {length} sentences.
    
    Title: {title}
    Content: {content}
    
    Summary:
    """;

PromptTemplate promptTemplate = new PromptTemplate(template);
Prompt prompt = promptTemplate.create(Map.of(
    "length", "3",
    "title", article.getTitle(),
    "content", article.getContent()
));

String summary = chatClient.call(prompt).getResult();

Building the Summarizer

Domain Model

package com.example.aisummary.model;

public record Article(String title, String content) {
    public Article {
        if (title == null || title.isBlank()) {
            throw new IllegalArgumentException("Title cannot be blank");
        }
        if (content == null || content.isBlank()) {
            throw new IllegalArgumentException("Content cannot be blank");
        }
    }
}

public record SummaryRequest(Article article, SummaryLength length) {}

public enum SummaryLength {
    SHORT(3),
    MEDIUM(5),
    LONG(10);
    
    private final int sentences;
    
    SummaryLength(int sentences) {
        this.sentences = sentences;
    }
    
    public int getSentences() {
        return sentences;
    }
}

public record SummaryResponse(String summary, int tokensUsed) {}

The Service

package com.example.aisummary.service;

import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.ChatResponse;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.ai.openai.OpenAiChatOptions;
import org.springframework.stereotype.Service;

import java.util.Map;

@Service
public class ArticleSummarizerService {

    private static final String SUMMARY_TEMPLATE = """
        You are a professional editor summarizing articles for busy readers.
        
        Summarize the following article in exactly {length} concise sentences.
        Focus on the main points and key takeaways.
        
        Article Title: {title}
        
        Article Content:
        {content}
        
        Summary (exactly {length} sentences):
        """;

    private final ChatClient chatClient;
    private final PromptTemplate promptTemplate;

    public ArticleSummarizerService(ChatClient chatClient) {
        this.chatClient = chatClient;
        this.promptTemplate = new PromptTemplate(SUMMARY_TEMPLATE);
    }

    public SummaryResponse summarize(SummaryRequest request) {
        // Build the prompt with variables
        Prompt prompt = promptTemplate.create(Map.of(
            "title", request.article().title(),
            "content", truncateContent(request.article().content()),
            "length", String.valueOf(request.length().getSentences())
        ));

        // Configure for this specific request
        OpenAiChatOptions options = OpenAiChatOptions.builder()
            .withTemperature(0.5)  // Lower for consistent summaries
            .withMaxTokens(calculateMaxTokens(request.length()))
            .build();

        // Make the AI call
        ChatResponse response = chatClient.call(
            new Prompt(prompt.getContents(), options)
        );

        // Extract the result
        String summary = response.getResult()
            .getOutput()
            .getContent();
        
        int tokensUsed = response.getMetadata()
            .getUsage()
            .getTotalTokens();

        return new SummaryResponse(summary, tokensUsed);
    }

    private String truncateContent(String content) {
        // Limit to ~4000 tokens worth of text (~3000 words)
        // GPT-4 has 8k context window, leave room for prompt + response
        int maxChars = 15000;
        return content.length() > maxChars 
            ? content.substring(0, maxChars) + "..."
            : content;
    }

    private int calculateMaxTokens(SummaryLength length) {
        // Rough estimate: each sentence needs ~20-30 tokens
        return length.getSentences() * 30 + 50; // +50 for buffer
    }
}

Key points:

Truncate content: GPT-4 has an 8k token limit (~6k words). We truncate long articles.
Dynamic token limits: Different summary lengths need different token budgets.
Track metadata: Response includes token usage for cost monitoring.

Error Handling

package com.example.aisummary.exception;

public class AiServiceException extends RuntimeException {
    public AiServiceException(String message, Throwable cause) {
        super(message, cause);
    }
}

@ControllerAdvice
public class GlobalExceptionHandler {
    
    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(AiServiceException.class)
    public ResponseEntity<ErrorResponse> handleAiServiceException(AiServiceException ex) {
        log.error("AI service error", ex);
        return ResponseEntity
            .status(HttpStatus.SERVICE_UNAVAILABLE)
            .body(new ErrorResponse(
                "AI service temporarily unavailable",
                "Please try again later"
            ));
    }

    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<ErrorResponse> handleValidationException(IllegalArgumentException ex) {
        return ResponseEntity
            .status(HttpStatus.BAD_REQUEST)
            .body(new ErrorResponse(
                "Invalid request",
                ex.getMessage()
            ));
    }

    record ErrorResponse(String error, String message) {}
}

And update the service to use it:

public SummaryResponse summarize(SummaryRequest request) {
    try {
        // ... existing code ...
    } catch (Exception e) {
        throw new AiServiceException(
            "Failed to generate summary for: " + request.article().title(),
            e
        );
    }
}

REST Controller

package com.example.aisummary.controller;

import com.example.aisummary.model.*;
import com.example.aisummary.service.ArticleSummarizerService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/summaries")
@Tag(name = "Article Summarization", description = "AI-powered article summarization")
public class SummaryController {

    private final ArticleSummarizerService summarizerService;

    public SummaryController(ArticleSummarizerService summarizerService) {
        this.summarizerService = summarizerService;
    }

    @PostMapping
    @Operation(
        summary = "Summarize an article",
        description = "Generate an AI-powered summary of the provided article"
    )
    public ResponseEntity<SummaryResponse> summarizeArticle(
            @Valid @RequestBody SummaryRequest request) {
        
        SummaryResponse response = summarizerService.summarize(request);
        return ResponseEntity.ok(response);
    }
}

Testing

Start your application:

mvn spring-boot:run

Then make a request:

curl -X POST http://localhost:8080/api/v1/summaries \
  -H "Content-Type: application/json" \
  -d '{
    "article": {
      "title": "The Future of Java",
      "content": "Java has been around for nearly 30 years, and it is not going anywhere. With modern features like records, pattern matching, and virtual threads, Java is faster and more expressive than ever. The JVM ecosystem continues to innovate, with frameworks like Spring, Quarkus, and Micronaut pushing boundaries..."
    },
    "length": "SHORT"
  }'

Response:

{
  "summary": "Java remains relevant after 30 years with modern features like records and virtual threads. The JVM ecosystem continues to thrive with innovative frameworks. Java's combination of performance and expressiveness ensures its future.",
  "tokensUsed": 127
}

You get a clean three-sentence summary as requested.

Production Patterns

Streaming for Long Responses

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamSummary(@Valid @RequestBody SummaryRequest request) {
    
    Prompt prompt = buildPrompt(request);
    
    // Stream tokens as they arrive
    return chatClient.stream(prompt)
        .map(response -> response.getResult().getOutput().getContent());
}

Users see progress as the AI generates text.

Rate Limiting

@Component
public class RateLimiter {
    
    private final Bucket bucket;

    public RateLimiter(@Value("${app.ai.rate-limit.requests-per-minute}") int requestsPerMinute) {
        Bandwidth limit = Bandwidth.classic(
            requestsPerMinute,
            Refill.intervally(requestsPerMinute, Duration.ofMinutes(1))
        );
        this.bucket = Bucket.builder().addLimit(limit).build();
    }

    public void checkLimit() {
        if (!bucket.tryConsume(1)) {
            throw new RateLimitExceededException("Too many requests");
        }
    }
}

// In service
public SummaryResponse summarize(SummaryRequest request) {
    rateLimiter.checkLimit();
    // ... rest of implementation ...
}

Monitoring and Caching

Track usage with Micrometer metrics and cache identical requests:

@Component
public class AiMetrics {
    
    private final MeterRegistry registry;
    private final Counter requestCounter;
    private final Timer responseTimer;
    private final Counter tokensCounter;

    public AiMetrics(MeterRegistry registry) {
        this.registry = registry;
        this.requestCounter = Counter.builder("ai.requests")
            .description("Total AI requests")
            .register(registry);
        this.responseTimer = Timer.builder("ai.response.time")
            .description("AI response time")
            .register(registry);
        this.tokensCounter = Counter.builder("ai.tokens.used")
            .description("Total tokens consumed")
            .register(registry);
    }

    public void recordRequest() {
        requestCounter.increment();
    }

    public void recordResponse(long milliseconds, int tokens) {
        responseTimer.record(milliseconds, TimeUnit.MILLISECONDS);
        tokensCounter.increment(tokens);
    }
}

@Service
public class CachedSummarizerService {
    
    @Cacheable(value = "summaries", key = "#request")
    public SummaryResponse summarize(SummaryRequest request) {
        return summarizerService.summarize(request);
    }
}

Use Redis for distributed caching in production.

Switching AI Providers

Spring AI supports multiple providers. Switching is easy:

# OpenAI
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}

# Or Azure OpenAI
spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}

# Or Anthropic (Claude)
spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}

# Or local models with Ollama
spring:
  ai:
    ollama:
      base-url: http://localhost:11434

The ChatClient interface stays the same regardless of provider. Great for testing with cheaper models or avoiding vendor lock-in.

Common Mistakes

Ignoring token limits: Know your model's context window. Truncate or chunk content.
Wrong temperature: Use 0.0-0.3 for facts, 0.7-1.0 for creative content.
No retry logic: Add @Retryable with exponential backoff.
Exposing raw responses: Validate AI output before returning to users.
Hardcoded prompts: Store prompts in config so you can update without redeploying.

Where This Makes Sense

AI works well for content generation (summaries, descriptions, emails), analysis (sentiment, classification), conversational interfaces (support bots, Q&A), and code assistance (reviews, documentation).

The key is augmentation, not replacement. AI assists; it doesn't replace humans.

Performance Tips

Batch requests when possible
Use GPT-3.5 for simple tasks (10x cheaper, 2x faster)
Process AI calls asynchronously with @Async
Use local models (Ollama) for development

Wrapping Up

Spring AI integrates cleanly with the Spring ecosystem. The code we built is production-ready—add authentication, persistence, and deploy it.

If you're wondering how to add AI without rewriting everything in Python, this is your path. Spring AI meets you where you are.

Resources: Spring AI Docs • OpenAI API Reference • Prompt Engineering Guide

SDD with Spring boot

Mon, 06 Jul 2026 00:00:00 GMT

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:

Requirements
     ↓
 Developer writes code
     ↓
 Tests
     ↓
 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:

Business Requirement
↓
Developer interpretation
↓
Implementation
↓
Tests
↓
Documentation

Notice that the original requirement is lost.

In Spec Driven Development:

Business Requirement
↓
Specification
↓
AI / Developer
↓
Generated Code
↓
Generated Tests
↓
Verification

The specification never disappears.

Core Principles

1. The specification is the source of truth

Instead of saying

"Create a UserService"

we describe

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

- uppercase
- lowercase
- digit
- minimum length 10

Duplicate email returns HTTP 409.

Notice there is zero Java code.

2. Specifications are executable

A specification should answer

What inputs exist?
What outputs exist?
Validation rules
Error cases
Security
Constraints

The implementation should satisfy the specification.

3. AI writes code

Developers review.

AI generates.

Developers validate.

Project Structure

A Spring Boot project might look like this

specs/
    user-registration.md
    login.md
    order.md

src/
    main/
    test/

prompts/
    generate-controller.md
    generate-tests.md

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

Example Specification

File

specs/user-registration.md

# User Registration

## Endpoint

POST /api/users

## Request

{
  "email": "john@example.com",
  "password": "Password123"
}

## Validation

Email

- required
- valid email
- unique

Password

- minimum length 10
- uppercase required
- lowercase required
- digit required

## Success

HTTP 201

{
   "id": UUID,
   "email": "john@example.com"
}

## Errors

400 Invalid request

409 Duplicate email

No implementation.

Only behavior.

From Spec to Spring Boot

An AI assistant can generate

Controller
↓
DTO
↓
Validation
↓
Service
↓
Repository
↓
Tests

Generated DTO

public record UserRegistrationRequest(

    @Email
    @NotBlank
    String email,

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

) {}

Notice how validation rules came directly from the specification.

Generated Controller

@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService service;

    public UserController(UserService service) {
        this.service = service;
    }

    @PostMapping
    public ResponseEntity<UserResponse> register(
            @Valid
            @RequestBody UserRegistrationRequest request
    ) {

        UserResponse response =
                service.register(request);

        return ResponseEntity
                .status(HttpStatus.CREATED)
                .body(response);
    }

}

Nothing magical.

The controller simply reflects the specification.

Service Layer

@Service
public class UserService {

    private final UserRepository repository;

    public UserResponse register(UserRegistrationRequest request) {

        if(repository.existsByEmail(request.email())) {
            throw new DuplicateEmailException();
        }

        User entity = new User(
                UUID.randomUUID(),
                request.email(),
                passwordEncoder.encode(request.password())
        );

        repository.save(entity);

        return UserResponse.from(entity);

    }

}

Again, Business rules came from the specification.

OpenAPI First

Spec Driven Development fits naturally with OpenAPI.

Example

paths:
  /users:
    post:
      summary: Register user
      requestBody:
        required: true
      responses:
        "201":
          description: User created
        "409":
          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

@Test
void duplicateEmailReturns409() {

    given(repository.existsByEmail(any()))
            .willReturn(true);

    mockMvc.perform(post("/api/users")
            .contentType(APPLICATION_JSON)
            .content(json))

            .andExpect(status().isConflict());

}

The specification explicitly required HTTP 409.

Example Prompt

Using the specification below,
generate:

- DTO
- Controller
- Service
- Unit tests
- Integration tests

Requirements:

Use Spring Boot 4

Use Jakarta Validation

Use Problem Details

Do not invent business rules.

Only implement what is specified.

AI Workflow

Business
↓
Specification
↓
Git
↓
AI
↓
Generated Code
↓
Developer Review
↓
Tests
↓
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

order-service/
    specs/
        create-order.md
        cancel-order.md
        payment.md
    src/
    prompts/
    docs/

Each pull request updates

specification
implementation
tests

together.

Example Evolution

Version 1

Password minimum length

10

Later..

Password minimum length

12

AI regenerates

validation
tests
documentation

without developers hunting through dozens of files.

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

Keep specifications small

One specification per use case.

Good:

Register User

Bad:

Entire User Management Module

Focus on behavior

Good

Return HTTP 404 if user not found.

Bad

Use Optional.orElseThrow(...)

Specifications should never prescribe implementation.

Define edge cases

Always specify

invalid input
duplicate data
unauthorized access
concurrency
expected HTTP codes

Let AI generate boilerplate

Spring Boot contains plenty of repetitive code:

DTOs
Controllers
Validation
Mapping
Tests

These are ideal candidates for AI generation.

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. Write specification
↓
2. Review with stakeholders
↓
3. Commit specification
↓
4. Generate implementation
↓
5. Review generated code
↓
6. Execute tests
↓
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.

Pixel Piston

Spec Driven Development: A Practical Guide with SpecKit

Spec-Driven Development: A Practical Guide with SpecKit

The Problem

Spec-Driven Development

SpecKit

Example: Adding Giscus Comments

Step 1: Specification

Step 2: Implementation Plan

Step 3: Task Breakdown

Step 4: Implementation

vs. Other Methodologies

Benefits and Trade-offs

Getting Started

Lessons Learned

When NOT to Use This

Wrapping Up

Building AI-Powered Spring Boot Apps with Spring AI

Building AI-Powered Spring Boot Apps with Spring AI

Why Bother?

The Project

Setup

Core Concepts

ChatClient

ChatOptions

PromptTemplate

Building the Summarizer

Domain Model

The Service

Error Handling

REST Controller

Testing

Production Patterns

Streaming for Long Responses

Rate Limiting

Monitoring and Caching

Switching AI Providers

Common Mistakes

Where This Makes Sense

Performance Tips

Wrapping Up

SDD with Spring boot

Spring Boot + Spec Driven Development

Introduction

Why Spec Driven Development?

Core Principles

1. The specification is the source of truth

2. Specifications are executable

3. AI writes code

Project Structure

Example Specification

From Spec to Spring Boot

Generated DTO

Generated Controller

Service Layer

OpenAPI First

Testing from Specifications

Example Prompt

AI Workflow

Keeping Specifications Close to Code

Example Evolution

Version 1

What Should Developers Still Do?

Best Practices with Spring Boot

Keep specifications small

Focus on behavior

Define edge cases

Let AI generate boilerplate

Advantages

Challenges

A Typical Development Cycle

Conclusion

Further Reading