Agent Coding – Prompt Guide

PROMPT
  └─► PLAN  (okosabb, "architect" model – pl. Opus 4.8 / Fable 5)
        └─► EXECUTE  (gyorsabb, olcsóbb "coder" model – pl. GPT-5.4)

FEATURE: <short human-readable title>

CONTEXT:                   ← optional, skip if LOOKUP is self-explanatory
    <which module / layer / service is involved>

LOOKUP:                    ← core
    <ClassName or path/to/file.ext>   ← existing files the agent MUST read before planning
    <ClassName or path/to/file.ext>
    ...

ENDPOINT / TRIGGER:        ← optional, only for API / event features
    <HTTP method + path, or event name>

BEHAVIOR:                  ← core
    <step-by-step happy path only; errors go in the ERRORS section>

ERRORS:                    ← optional, only if there are non-trivial error branches
    <condition>  ->  <HTTP status or exception type>

CONSTRAINTS:               ← core
    <what must NOT be done>
    <existing pattern that must be followed>
    <what must not be replaced or introduced>

TEST:                      ← core, but can be one line for small tasks
    - If a test file already exists for the affected class: update it, do not create a new one
    - Cover: happy path + every ERRORS case
    - Run the modified tests; fix any that break
    - Do not mock anything that CONSTRAINTS marks as an existing, working component

FEATURE: List users endpoint

LOOKUP:
    UserController
    UserRepository
    UserDto

ENDPOINT:
    GET /users

BEHAVIOR:
    1. Fetch all users via UserRepository.findAll()
    2. Map each to UserDto and return as a list

CONSTRAINTS:
    use the existing repository pattern, no raw SQL
    do not add pagination unless it already exists

TEST:
    update UserControllerTest: happy path + empty list; run it

FEATURE: User Balance Lookup

CONTEXT:
    user-service module, controller / service / repository layers already exist

LOOKUP:
    UserRepository
    BalanceService
    UserDto
    UserController

ENDPOINT:
    GET /users/{id}/balance

BEHAVIOR:
    1. Load user via UserRepository.findById(id)
    2. Fetch balance via BalanceService.getBalance(userId)
    3. Map to UserDto and return

ERRORS:
    user not found         ->  404 Not Found
    BalanceService timeout ->  503 Service Unavailable

CONSTRAINTS:
    use the existing repository pattern — do not add a new query layer
    no raw SQL
    do not introduce new dependencies
    do not change the BalanceService interface

TEST:
    - Update UserControllerTest or UserServiceTest if it exists
    - Cover: successful lookup, user 404, timeout 503
    - Run all User* tests; fix any that break

FEATURE: Add Phone Number to User Profile Response

CONTEXT:
    user-service / profile module
    phoneNumber already exists on the User entity and in the database

LOOKUP:
    UserProfileDto
    UserProfileService
    UserProfileController
    User (entity)

ENDPOINT:
    GET /users/{id}/profile   ← existing endpoint, only the response shape changes

BEHAVIOR:
    1. Add phoneNumber field to UserProfileDto
    2. Map User.phoneNumber into the DTO in the existing mapping logic
    3. If phoneNumber is null: return null, do not throw

ERRORS:
    user not found  ->  404 (unchanged)

CONSTRAINTS:
    do not change the User entity
    do not change the DB schema (the column already exists)
    do not modify any other DTOs
    must remain backward compatible: the field is optional in the response

TEST:
    - Update UserProfileControllerTest
    - Add cases: phoneNumber populated, phoneNumber null
    - Run all UserProfile* tests; fix any that break

FEATURE: Graceful Handling of External Payment Service Errors

CONTEXT:
    payment-service module
    PaymentGatewayClient already exists and can throw TimeoutException / connection errors

LOOKUP:
    PaymentGatewayClient
    PaymentService
    GlobalExceptionHandler

BEHAVIOR:
    happy path is unchanged — only error branches are affected

ERRORS:
    TimeoutException    ->  503, log at WARN
    ConnectionException ->  503, log at ERROR
    external 4xx        ->  422, pass through the original message body

CONSTRAINTS:
    do not change the PaymentGatewayClient interface
    use the existing GlobalExceptionHandler — do not create a new handler class
    do not touch the successful payment flow

TEST:
    - Update PaymentServiceTest
    - Each ERRORS case gets its own test
    - Assert that log calls happen (log capture / spy)
    - Run all Payment* tests; fix any that break

FEATURE: Input Validation for Order Creation

CONTEXT:
    order-service module
    CreateOrderRequest, OrderController, OrderService already exist
    currently no input validation is in place

LOOKUP:
    CreateOrderRequest
    OrderController
    OrderService

ENDPOINT:
    POST /orders   ← existing endpoint, only input validation is added

BEHAVIOR:
    1. quantity:        required, min 1, max 1000
    2. productId:       required, not null or empty
    3. shippingAddress: required, not blank
    4. On validation failure: return 400 with a list of { field, message } objects

ERRORS:
    validation failure  ->  400 Bad Request, body: [{ field, message }]

CONSTRAINTS:
    use whatever validation mechanism is already present in the project
    (inspect the codebase before deciding how to implement)
    do not change OrderService business logic
    do not change the success response structure
    do not introduce a new validation library if one is already present

TEST:
    - Update OrderControllerTest
    - Test: each field missing or invalid (separate cases)
    - Test: valid request passes through unchanged
    - Run all Order* tests; fix any that break

FEATURE: Invalidate User Cache on Profile Update

CONTEXT:
    user-service module
    UserCacheService and UserProfileService.updateProfile() already exist
    UserCacheService already caches user profiles

LOOKUP:
    UserCacheService
    UserProfileService

BEHAVIOR:
    1. After UserProfileService.updateProfile() succeeds:
       call UserCacheService.invalidate(userId)
    2. If cache invalidation throws: log at WARN but do NOT rethrow —
       return the successful update response regardless

ERRORS:
    cache error  ->  log WARN, still return 200 OK (silent fail)

CONSTRAINTS:
    do not change the UserCacheService interface
    do not change the return type of UserProfileService.updateProfile()
    cache invalidation must NOT block the response (must not become a synchronous failure path)
    do not introduce an async framework if one is not already present

TEST:
    - Update UserProfileServiceTest
    - Assert: successful update -> invalidate() was called
    - Assert: cache error -> no exception is thrown, 200 is returned
    - Run all UserProfile* tests; fix any that break