From ai-skills
Controller-layer rules for Clean Architecture backend services. Use when writing REST, Kafka, gRPC, or other entry-point adapters.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ai-skills:clean-architecture-controllerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill converts `backend-engineer/clean-architecture/controller-rule.md` into Claude Code plugin skill guidance while preserving the source rules for production fintech development.
This skill converts backend-engineer/clean-architecture/controller-rule.md into Claude Code plugin skill guidance while preserving the source rules for production fintech development.
Controller layer is the entry point of the system.
Its job is only to:
Rule:
Controller must be thin. No business logic allowed.
Controller is allowed to handle:
Controller must NOT contain:
Bad Example:
if(balance<amount){throw new
Exception(); }
repo.
save(...);
HTTP Request
-> Controller
-> Validate DTO
-> Map to Command
-> Call UseCase
-> Map Result to Response
-> Return HTTP Response
Use dedicated DTOs:
Examples:
Never expose:
Use Bean Validation:
@NotBlank
@NotNull
@Positive
@Size(max = 50)
Example:
public record TransferRequest(
@NotBlank String fromWallet,
@NotBlank String toWallet,
@Positive BigDecimal amount
) {
}
Validation belongs to controller boundary.
Use MapStruct preferred.
Mappings:
Example:
TransferCommand toCommand(TransferRequest req);
TransferResponse toResponse(TransferResult result);
No manual repetitive mapping if avoidable.
Use consistent envelope if project standard requires:
{
"code": "00",
"message": "SUCCESS",
"data": {}
}
HTTP status examples:
Use GlobalExceptionHandler.
Controller should NOT try/catch every endpoint.
Bad:
try{...}catch(Exception e){...}
Good:
Controller may:
Example:
@PreAuthorize("hasRole('ADMIN')")
Controller should NOT verify JWT manually.
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1/transfers")
public class TransferController {
private final TransferUseCase useCase;
private final TransferMapper mapper;
@PostMapping
public ResponseEntity<TransferResponse> transfer(
@Valid @RequestBody TransferRequest request) {
var result = useCase.execute(mapper.toCommand(request));
return ResponseEntity.ok(mapper.toResponse(result));
}
}
Controller tests must cover:
Use:
@WebMvcTest
MockMvc
Transfer endpoint:
Bill payment:
OTP verify:
Refund:
Controllers only orchestrate HTTP boundary.
Avoid:
When generating controller:
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub silverpham08091998/ai-skills --plugin ai-skills