playbooks

home / skills / pedrosantiagodev / buildup / planning

planning skill

/.claude/skills/planning

This skill guides Java Spring project planning and architecture decisions, emphasizing simplicity, Spring robustness, and observability from requirements to

npx playbooks add skill pedrosantiagodev/buildup --skill planning

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.2 KB
---
name: planning-java
description: Project planning and architecture decision workflow for Java/Spring. Use when starting new projects, designing microservices, or making architectural decisions. Emphasizes simplicity, Spring-based robustness, and observability.
---

# Project Planning (Java/Spring Boot)

Workflow for project planning, architecture decisions, and technical design in the Spring ecosystem.

## 1. Understand Requirements
- What problem are we solving?
- What are the constraints (time, performance, scale)?
- What are the non-functional requirements (Security, Observability)?

## 2. Technology Choices (Spring Ecosystem)
- **Main Framework:** Spring Boot
- **Build:** Maven or Gradle
- **Data Access:** Spring Data JPA (for SQL) or Spring Data MongoDB (for NoSQL).
- **Database:** PostgreSQL, MySQL, or H2 (for testing/development).
- **Communication:** `WebClient` for HTTP calls.
- **Security:** Spring Security
- **Observability:** Spring Boot Actuator + Micrometer (for Prometheus/Grafana).
- **Testing:** JUnit 5, Mockito, Testcontainers.

## 3. Architecture Design

### Core Principles
- **KISS** (Keep It Simple, Stupid)
- **YAGNI** (You Aren't Gonna Need It)
- **Composition > Inheritance**
- **Code to the Interface**

### Layered Architecture Pattern
- **`Controller` (Web Layer):** Responsible for exposing REST endpoints (`@RestController`). Receives DTOs (Data Transfer Objects) and calls the Service.
- **`Service` (Business Layer):** Contains business logic (`@Service`). Orchestrates calls to Repositories and other services.
- **`Repository` (Data Layer):** Spring Data interface (`@Repository`) for database access.
- **`DTOs`:** Use DTOs to transfer data between the Controller layer and the client, avoiding exposure of domain entities.
- **`Entities`:** Domain classes (e.g., annotated with `@Entity` from JPA).

### Architecture Checklist
- [ ] Constructor-based Dependency Injection
- [ ] Type-safe configuration via `@ConfigurationProperties`
- [ ] Security (Spring Security) planned from the start
- [ ] Observability (`Actuator`) included
- [ ] Exception handling strategy (e.g., `@ControllerAdvice`)

## 4. Testing Strategy
- **Unit Tests:** Test `Service` classes in isolation (using Mockito for mocks).
- **Test Slices (Integration):**
    - `@WebMvcTest`: Tests the `Controller` layer (mocking the `Service`).
    - `@DataJpaTest`: Tests the `Repository` layer (using in-memory DB or Testcontainers).
- **Integration Tests (Full):**
    - `@SpringBootTest`: Loads the full application context.
    - **Testcontainers:** Use to test real integration with the database.

## 5. Observability Planning
- **`Actuator`:** Include the starter (`/health`, `/metrics`, `/info`).
- **Logging:** Configure structured logging.
- **Tracing:** If using microservices, plan for Tracing (e.g., Micrometer Tracing).

## 6. Security Planning (Spring Security)
- [ ] Define authentication strategy (e.g., JWT, OAuth2).
- [ ] Define authorization on endpoints (e.g., `antMatchers` or `@PreAuthorize`).
- [ ] Handle CORS.

## 7. Decisions
- **Avoid Premature Optimization:** Write a good program first. Use a profiler to optimize bottlenecks.
- **Avoid Over-Engineering:** Don't use complex patterns (e.g., CQRS, Event Sourcing) unless required. Start simple with CRUD.

Overview

This skill guides project planning and architecture decision-making for Java projects built on the Spring ecosystem. It emphasizes simple, testable designs, Spring-native best practices, and observability from day one. Use it to shape initial architecture, technology selection, and testing/operational plans for microservices or monoliths.

How this skill works

The workflow walks teams through requirements gathering, technology choices, layered architecture, testing strategy, observability, and security planning. It prescribes concrete Spring components (Spring Boot, Spring Data, Spring Security, Actuator, Micrometer) and practical patterns (DTOs, constructor injection, configuration properties). It also provides a checklist and decision guidelines to avoid premature optimization and over-engineering.

When to use it

  • Starting a new Java/Spring Boot service or monolith and defining architecture
  • Designing microservices and choosing inter-service communication and observability
  • Evaluating technology choices (database, build, testing stack) for a project
  • Creating a test strategy that balances unit, slice, and integration tests
  • Defining security and operational requirements early in the project

Best practices

  • Keep It Simple: start with CRUD and iterate; avoid complex patterns unless necessary
  • Favor composition and program to interfaces; use constructor-based DI
  • Use DTOs at the API boundary to avoid leaking domain entities
  • Enable observability from day one: Actuator, Micrometer, structured logging, and tracing plan
  • Write tests at the right levels: unit tests for logic, slice tests for layers, Testcontainers for real integrations
  • Prefer type-safe configuration via @ConfigurationProperties and centralized exception handling

Example use cases

  • Designing a new user-management microservice with JWT auth, PostgreSQL, and Prometheus metrics
  • Scoping a greenfield monolith that may split into microservices later—start simple, add tracing and Actuator
  • Choosing between SQL and NoSQL for a service: pick Spring Data JPA for relational or Spring Data MongoDB for document stores
  • Setting up CI pipelines with integration tests that use Testcontainers for database verification
  • Creating an API with clear Controllers, Services, Repositories, DTOs, and centralized @ControllerAdvice error handling

FAQ

Should I start with microservices or a monolith?

Start with the simplest deployable unit that meets requirements. A modular monolith often reduces early complexity; split into microservices when clear boundaries and scaling needs emerge.

When should I introduce tracing and distributed tracing?

Plan tracing architecture from the start for microservices. Implement basic metrics and logging immediately; add distributed tracing once you have multiple services or complex flows to diagnose.