git:20260909.298c930 to git:20260921.de5eb9f

+ # AGENTS.md — Global Agent Instructions

+ > Source of truth for agent behavior in this repo.

+ > Adapters (`CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`) point here and must not diverge.

+ > Canonical skills live in `.agents/skills/`; detailed domain rules live in `skills/backend/`; reference docs live in `docs/agent/`.

+ ## 1. Project

+ General-purpose / open-source Spring Boot backend.

+

+ Backend scope only:

+

+ - `src/main/java/com/bekaku/api/spring/`

+ - `src/main/resources/`

+ - `src/test/`

+ - `build.gradle`

+

+ There is no `backend/` or `frontend/` directory here. The frontend lives in an external repository. Frontend/root application concerns are out of scope unless explicitly requested.

+

+ ## 2. Stack

+

+ Primary stack (declarations in `build.gradle`, not upgrade recommendations):

+

+ - Java 25, Spring Boot 4.1, Spring MVC / Tomcat

+ - Spring Data JPA + PostgreSQL + Flyway, MyBatis for read-model projections

+ - Optional Spring AI / Qdrant modules (Ollama, SSE chat)

+ ## 3. Repository Layout

+ - `AGENTS.md` — this file, global instructions (§§1–14)

+ - `SKILLS.md` — canonical skill pointer list

+ - `.agents/skills/` — canonical skills (Agent Skills spec, frontmatter `name` + `description`)

+ - `skills/backend/` — detailed domain references (preserved, loaded narrowly)

+ - `tasks/TASK_TEMPLATE.md` — canonical task template; `tasks/README.md` — task workflows

+ - `docs/tasks/` — task instances (`<number>-<short-name>.md`)

+ - `docs/agent/` — agent reference docs (project reference, known issues, CRUD template, split map, original source)

+

+ Read `docs/agent/PROJECT_REFERENCE.md` only when repository layout, dependency, naming, or architecture context is required.

+

+ ## 4. Layered Architecture

+

+ Binding layering:

+

+ ```text

+ controller/api/* → service/* interface → serviceImpl/* → repository/* (JPA)

+ and/or mybatis/* + src/main/resources/mybatis/*.xml

+ DTO mapping at transport boundary via mapper/* (MapStruct)

+ ```

+

+ - Controllers call services, never `EntityManager` / `JdbcTemplate` / `VectorStore` directly. AI tool classes under `ai/*Tool.java` are the documented exception.

+ - Services own business logic and transaction boundaries.

+ - Controllers must not perform direct database / business writes.

+ - Do not call controllers from services.

+

+ JPA vs MyBatis (binding):

+

+ - JPA for CRUD + `JpaSpecificationExecutor` filtering + simple lookups.

+ - MyBatis + `vo/Paging` for join/paging read-model DTO projections.

+ - Do not add new MyBatis writes; do not use MyBatis for single-table CRUD that JPA already covers.

+

+ ## 5. Core Working Rules

+

+ - Preserve intentional legacy spellings unless the task explicitly changes them: `serviceImpl`, `DevelopmentContoller`, `/api/faceRegconition`, `AiFaceRegconitionServiceClient`.

+ - Cite file-path evidence (`path:line`) when claiming a convention. Do not invent conventions.

+ - Report verification commands and actual results. Do not claim deployment, security, integration, or production success without evidence.

+ ## 6. Required Reading / Skill Routing

+ For every backend implementation task, always read:

+ ```text

+ AGENTS.md

+ SKILLS.md

+ .agents/skills/backend-core/SKILL.md (= skills/backend/SKILL.md core)

+ <this-task> (when a task file exists)

+ ```

+ Then read only the relevant canonical skill + detailed guide:

+ ```text

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

+ JPA/MyBatis/Flyway/data changes -> .agents/skills/backend-data/SKILL.md + skills/backend/DATA.md

+ Auth/authorization/ownership/cookies -> .agents/skills/backend-security/SKILL.md + skills/backend/SECURITY.md

+ Files/uploads/downloads/CDN/storage -> .agents/skills/backend-files/SKILL.md + skills/backend/FILES.md

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

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

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

+ ```

+ - Ordinary CRUD/auth/file/messaging work must not load AI/RAG.

+ - Read `docs/agent/KNOWN_ISSUES.md` only when debugging or touching a listed legacy area.

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

+ - Do not load unrelated skill/reference files by default.

+ ## 7. Task Tracking (Mandatory)

+ For every task that has a task file (see `tasks/TASK_TEMPLATE.md`, instances in `docs/tasks/`):

+ - **Before editing code:** set Resume State `Overall Status` to `IN_PROGRESS`, record the initial `Current Step` and `Files Currently Being Modified`.

+ - **During implementation:** update the task file incrementally — tick off `Progress Checklist` items only after each item is actually done and evidenced, and keep `Current Step`, `Completed Work`, and `Partially Completed Work` current. Never leave all updates until the work is finished.

+ - **After implementation, before final verification:** set `Overall Status` to `IMPLEMENTATION_COMPLETE`.

+ - **After verification:** set `Overall Status` to `COMPLETED` and fill the Completion Report. If blocked, set `BLOCKED` and describe the blocker under `Known Issues / Blockers`.

+

+ ## 8. API / Data Contracts

+

+ - No universal `ApiResponse` envelope: `BaseApiController.responseEntity` passes body + status through.

+ - Standard verbs/status: `GET /` → `200 ResponseListDto`, `GET /{id}` → `200 DTO`, `POST /` → `201 DTO`, `PUT /{id}` → `200 DTO`, `DELETE /{id}` → `200` delete message (not `204`).

+ - Paged shape `ResponseListDto` = `{dataList, totalPages, totalElements, last}`; some file endpoints return bare lists — verify per endpoint.

+ - `@Valid @RequestBody` on all mutating endpoints, then manual `*Validator` checks.

+ - Errors via `ApiException` / `BaseResponseException` → `GlobalExceptionHandler` → `ApiError`; JWT filter 401s use separate `{"error":"..."}` shape.

+ - IDs are Snowflake `Long` via `@PrePersist`; never mix `IDENTITY`/`SEQUENCE`. Soft delete requires field + `@SQLDelete` + `@SQLRestriction`; MyBatis/native SQL must add `deleted=false` + ownership predicates.

+ - Flyway: `src/main/resources/db/migration/`, `V{version}__{snake_case}.sql`; never rewrite deployed migrations. Validate PG/pgvector SQL on disposable PostgreSQL, not H2.

+ - Full rules: see §6 guides, do not duplicate them here.

+

+ ## 9. Security / Files / Async / AI Boundaries

+

+ - Trace all three boundaries: (1) `WebSecurityConfig` routes, (2) `JwtTokenFilter` skip-list + verification, (3) method/service ownership checks. `AuthorizationInterceptor` (returns `true`) and `CustomPermissionEvaluator` (stub) enforce nothing.

+ - Admin resources: `@PreAuthorize("@permissionChecker.hasPermission('...')")`. Owner-scoped rows (chat, files, faces): additionally scope by creator/owner (`findByIdAndCreator`).

+ - Never log/expose raw refresh tokens, JWT/AES secrets, password hashes, API keys, or MCP credentials. `X-User-Id` is input, never identity.

+ - Files: DB transactions do not roll back filesystem effects; preserve real-path containment + server-generated filenames; keep secrets/logs/private data out of the public storage mapping; chunk merge is non-atomic.

+ - Async/messaging: no active `@RabbitListener` in this checkout; adding a consumer requires idempotency + retry/DLQ + duplicate-delivery tests; pass actor identity explicitly into async work.

+ - AI/RAG is optional: MVC SSE (not WebFlux server); disabled Qdrant stores fail at runtime unless explicitly gated; treat prompts/retrieved text/model SQL as untrusted.

+

+ ## 10. Validation

+

+

+ See `.agents/skills/backend-testing/SKILL.md` + `skills/backend/TESTING.md` for the evidence matrix. Report exact commands + actual results.

+

+ ## 11. Safe Stop / Resume

+

+ Before stopping incomplete work: finish the current safe atomic change where practical; update checklist + Resume State; inspect `git status`, `git diff`, `git diff --stat`; record partial work and the exact next action.

+

+ When resuming: read `AGENTS.md` → `SKILLS.md` → canonical core skill → this task → only relevant domain skills; inspect checklist + Resume State + repo diff; continue from Next Recommended Steps.

+

+ ## 12. Prohibited Behaviors

+

+ - No new global API envelope, HATEOAS links, class-level `@Validated`, `IDENTITY`/`SEQUENCE` IDs on Snowflake entities, Lombok `@Data` on relational entities, or `${...}` interpolation of request text in MyBatis XML.

+ - No new MyBatis writes for JPA-covered CRUD.

+ - No secrets/logs/backups under the public storage mapping.

+ - Do not treat legacy stubs, prompt text, `UrlUtil` alone, OTP throttle, or YAML-only Qdrant/consumer settings as complete security boundaries.

+ - Do not run the code generator (`DevelopmentContoller`) as a read-only diagnostic; never hand-edit `build/generated` as a lasting change.

+

+ ## 13. Reference Index

+

+ ```text

+ Skills (canonical): .agents/skills/*/SKILL.md (see SKILLS.md)

+ Skills (detailed): skills/backend/SKILL.md, API.md, DATA.md, SECURITY.md,

+ FILES.md, ASYNC_MESSAGING.md, AI_RAG.md, TESTING.md

+ Tasks: tasks/TASK_TEMPLATE.md, tasks/README.md, docs/tasks/

+ References: docs/agent/PROJECT_REFERENCE.md

+ docs/agent/KNOWN_ISSUES.md

+ docs/agent/STANDARD_CRUD_SERVICE_REPOSITORY.md

+ docs/agent/SPLIT_MAP.md

+ docs/agent/ORIGINAL_SKILLS.md (archive, do not load by default)

+ Adapters: CLAUDE.md, GEMINI.md, .github/copilot-instructions.md (pointers only)

+ ```

+

+ ## 14. Authority Hierarchy

+

+ 1. `AGENTS.md` (this file) — global behavior, binding unless the user explicitly overrides in-session.

+ 2. `SKILLS.md` + `.agents/skills/*/SKILL.md` — canonical skill routing, binding.

+ 3. `skills/backend/*.md` + `docs/agent/*.md` — detailed/reference rules, binding within their domain.

+ 4. `CLAUDE.md` / `GEMINI.md` / `.github/copilot-instructions.md` — adapters only, never the source of truth. On conflict, §§1–13 above win.

+ 5. Legacy code under `Known Issues` — explicitly not a pattern to copy.

+

+ If a request conflicts with a documented rule, flag the conflict explicitly before proceeding — never silently pick a side.