git:20260921.de5eb9f to git:20260923.b5acb6d

8 added, 0 removed. Audit A to A.

---

name: backend-core

description: Core Spring Boot backend rules for every implementation task. Layering, transactions, JPA-vs-MyBatis decision, coding conventions, do/dont, and task routing. Always load first.

---

# Backend Core — Canonical

> Canonical core skill. Detailed rules: `skills/backend/SKILL.md`.

> Global behavior: `AGENTS.md`. Index: `SKILLS.md`.

## When to load

Every backend implementation task. Load before any domain skill.

+ ## Start an implementation

+ 1. Read `AGENTS.md` and `SKILLS.md`. If the work has a file in `docs/tasks/`, read it and update its Resume State before editing code (`AGENTS.md §7`).

+ 2. Find the existing feature under `src/main/java/com/bekaku/api/spring/`. Trace its controller → service interface → `serviceImpl` → repository or MyBatis mapper/XML. Inspect DTOs, MapStruct mappers, entities, and resources only where the change crosses them.

+ 3. Identify the contract and the owner of each write before editing. Keep business logic and transaction boundaries in services. A DB transaction cannot undo file, vector, email, queue, or remote effects.

+ 4. Choose the relevant domain guides below, then verify the changed boundary with `backend-testing`. Use `docs/agent/PROJECT_REFERENCE.md` only when layout or dependency context is needed.

## Core rules (summary — details in `skills/backend/SKILL.md`)

- Layering: `controller/api/* → service/* → serviceImpl/* → repository/*` and/or `mybatis/*`; MapStruct at transport boundary.

- Controllers never call `EntityManager` / `JdbcTemplate` / `VectorStore` directly (AI `*Tool.java` is the documented exception).

- Services own transactions; DB transactions do not roll back filesystem/vector/email/remote effects.

- JPA for CRUD + specifications + simple lookups; MyBatis + `vo/Paging` for join/paging DTO projections; no new MyBatis writes.

- Preserve legacy spellings: `serviceImpl`, `DevelopmentContoller`, `/api/faceRegconition`, `AiFaceRegconitionServiceClient`.

- Constructor injection (`@RequiredArgsConstructor`); Log4j2/`@Slf4j` only; typed `@ConfigurationProperties` for new config groups.

- When creating a standard CRUD service/repository, read `docs/agent/STANDARD_CRUD_SERVICE_REPOSITORY.md` first.

+ - Treat legacy behavior listed in `docs/agent/KNOWN_ISSUES.md` as something to inspect, not a template to copy.

## Routing

After this file, load only the relevant domain skill(s) per `AGENTS.md §6`:

```text

API -> .agents/skills/backend-api/SKILL.md + skills/backend/API.md

Data -> .agents/skills/backend-data/SKILL.md + skills/backend/DATA.md

Security -> .agents/skills/backend-security/SKILL.md + skills/backend/SECURITY.md

Files -> .agents/skills/backend-files/SKILL.md + skills/backend/FILES.md

Async -> .agents/skills/backend-async-messaging/SKILL.md + skills/backend/ASYNC_MESSAGING.md

AI/RAG -> .agents/skills/backend-ai-rag/SKILL.md + skills/backend/AI_RAG.md (AI tasks only)

Testing -> .agents/skills/backend-testing/SKILL.md + skills/backend/TESTING.md

```