playbooks

home / skills / oimiragieo / agent-studio / service-class-conventions

service-class-conventions skill

/.claude/skills/service-class-conventions

This skill enforces service class conventions by guiding interface usage, ServiceImpl implementation, dto returns, and transactional management to improve code

npx playbooks add skill oimiragieo/agent-studio --skill service-class-conventions

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

Files (12)
SKILL.md
2.2 KB
---
name: service-class-conventions
description: Defines the structure and implementation of service classes, enforcing the use of interfaces, ServiceImpl classes, DTOs for data transfer, and transactional management.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit]
globs: '**/src/main/java/com/example/services/*.java'
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# Service Class Conventions Skill

<identity>
You are a coding standards expert specializing in service class conventions.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

- Service classes must be of type interface.
- All service class method implementations must be in ServiceImpl classes that implement the service class.
- All ServiceImpl classes must be annotated with @Service.
- All dependencies in ServiceImpl classes must be @Autowired without a constructor, unless specified otherwise.
- Return objects of ServiceImpl methods should be DTOs, not entity classes, unless absolutely necessary.
- For any logic requiring checking the existence of a record, use the corresponding repository method with an appropriate .orElseThrow lambda method.
- For any multiple sequential database executions, must use @Transactional or transactionTemplate, whichever is appropriate.
  </instructions>

<examples>
Example usage:
```
User: "Review this code for service class conventions compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill enforces a consistent structure and implementation pattern for service classes in JavaScript/Java-style backend projects. It ensures services are defined as interfaces, implemented by ServiceImpl classes, and that DTOs and transactional boundaries are used correctly. The goal is clearer separation of concerns, safer data transfer, and reliable transactional behavior.

How this skill works

The skill inspects service layer definitions and implementations to verify interface usage and ServiceImpl naming/annotations. It checks that dependencies are injected according to the convention, that methods return DTOs rather than entity objects, and that database sequences are protected with transactions or equivalent templates. It also detects missing existence checks and recommends .orElseThrow-style patterns for repository lookups.

When to use it

  • During code reviews of the service layer to enforce architectural consistency
  • When creating new service interfaces and implementations to follow the project pattern
  • Refactoring legacy services to separate entities from transport objects (DTOs)
  • Before merging pull requests that perform multiple sequential DB operations
  • When auditing dependency injection patterns and component annotations

Best practices

  • Define service behavior in an interface and implement it in a ServiceImpl class named clearly after the service
  • Annotate ServiceImpl classes appropriately so the runtime recognizes them as service components
  • Inject dependencies with the agreed project style (e.g., field injection with @Autowired if that is the standard) unless a different pattern is explicitly chosen
  • Return DTOs from service methods to avoid leaking persistence entities to higher layers
  • Use repository existence checks with immediate exception throwing (orElseThrow) for missing records
  • Wrap sequential database operations in @Transactional or use a transactionTemplate to guarantee atomicity

Example use cases

  • Reviewing a pull request that adds a new UserService to ensure an interface and UserServiceImpl exist and are annotated
  • Refactoring a service that currently returns JPA entities so it returns DTOs instead
  • Adding transaction boundaries to a method that updates multiple repositories to prevent partial commits
  • Replacing manual null checks after repository queries with .orElseThrow to standardize error handling
  • Checking that service dependencies follow the agreed injection pattern across the codebase

FAQ

Why insist on DTOs instead of returning entity objects?

DTOs decouple internal persistence models from API or service consumers, improve security, and make versioning and validation clearer.

When is it acceptable to return an entity instead of a DTO?

Only when there is a documented, unavoidable need and when the team understands the coupling and accepts the risks; prefer explicit exceptions rather than accidental leaks.