AI-Assisted / Agentic Engineering

Before any code is written for a new service (say, the Library Events Producer), a short PRD is written describing: what the service does, its API contract, the events it publishes, and its non-functional requirements (error handling expectations, testing expectations). This becomes the artifact the AI agent is grounded against — instead of "build me a Kafka producer service" (which is under-specified and will produce something different every time you ask), the prompt becomes "implement the attached PRD."

# Library Events Producer — PRD

## Purpose
Accept LibraryEvent create/update requests via REST and publish them to the
`library-events` Kafka topic. This service owns no database.

## API
- POST /v1/libraryevent  -> publish a NEW event (no key; auto topic partition)
- PUT  /v1/libraryevent  -> publish an UPDATE event, keyed by libraryEventId

## Non-functional requirements
- All publish failures must be logged with the failed payload and partition (if known)
- Unit tests required for controller (MockMvc) and producer (mocked KafkaTemplate)
- Integration tests required using Embedded Kafka

A PRD says what; an implementation plan says in what order, and how — broken into discrete, independently verifiable steps (bootstrap project → domain model → controller skeleton → KafkaTemplate wiring → error handling → tests). This matters specifically for agentic workflows because it gives you natural checkpoints to review the agent's output before it compounds — reviewing one 40-line diff per step is tractable; reviewing a 2,000-line diff for an entire service at once is not.

An AGENTS.md file lives at the project root and gives any AI coding agent working in that repo standing context it would otherwise need to be re-taught every session: naming conventions, which Java version and Spring Boot version the project targets, how to run tests, and hard constraints ("never commit application-secrets.yml," "always add a Flyway migration instead of editing an existing one").

# AGENTS.md — library-events-consumer

## Stack
Java 21, Spring Boot 4.x, Spring Kafka, Spring Data JPA, PostgreSQL, Flyway.

## Conventions
- Package by feature, not by layer: com.library.events.producer / .consumer / .config
- Every new consumer error path must be covered by an Embedded Kafka integration test
- Never edit an existing Flyway migration file — always add a new versioned one

## Commands
- Run tests: `./mvnw test`
- Run locally: `docker compose up -d && ./mvnw spring-boot:run`

Where AGENTS.md is project-wide, a skill is narrower and reusable across projects: a self-contained instruction set for one recurring kind of task. Two used while building the reference app:

• Testing Skill — a fixed recipe for how this codebase writes tests: MockMvc pattern for controllers, Embedded Kafka setup pattern for integration tests, naming convention for test classes. Invoking it produces a consistent test every time, regardless of which class is being tested.
• Controller Skill — a fixed recipe for REST controllers: validation annotations, @RestControllerAdvice error shape, response status conventions.

A good skill is narrow, concrete, and includes a worked example — "write unit tests" is too vague to be a skill; "here is exactly how this project's MockMvc controller tests are structured, with a full example class" is.