From 67825a8c5cc466425aaf8ad7e3b474cd18e01fb5 Mon Sep 17 00:00:00 2001
From: meowrain <meowrain@126.com>
Date: Wed, 28 Jan 2026 00:02:18 +0800
Subject: [PATCH] docs: update agents guidelines

---
 AGENTS.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f69e5c1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,96 @@
+# Repository Guidelines
+
+This repository is a Maven multi-module Spring Boot microservices system for an Online Judge (AIOJ). Use the notes below as the contributor guide for structure, workflow, and expectations.
+
+## Tech Stack (Reference)
+
+- Java 17
+- Spring Boot 3.5.7
+- Spring Cloud 2025.0.0
+- Spring Cloud Alibaba 2025.0.0.0
+- Maven build, Spring Java Format, JIB for Docker images
+
+## Project Structure & Module Organization
+
+- Root `pom.xml` aggregates all modules.
+- Shared libraries live in `aioj-backend-common`:
+  - `aioj-backend-common-bom` (dependency management)
+  - `aioj-backend-common-core` (core utilities + Spring extensions)
+  - `aioj-backend-common-security` (JWT/Spring Security)
+  - `aioj-backend-common-feign` (OpenFeign + Sentinel integration)
+  - `aioj-backend-common-log` (AOP logging)
+  - `aioj-backend-common-mybatis` (MyBatis extensions)
+  - `aioj-backend-common-starter` (auto-config starter)
+- Service modules live at the repo root:
+  - `aioj-backend-gateway`, `aioj-backend-auth`, `aioj-backend-user-service`,
+    `aioj-backend-upms`, `aioj-backend-file-service`,
+    `aioj-backend-judge-service`, `aioj-backend-question-service`,
+    `aioj-backend-ai-service`, `aioj-backend-blog-service`
+- Supporting folders include `docs`, `db`, `sentinel`, `logs`, `uploads`, and `generator`.
+
+## Build, Test, and Development Commands
+
+Use Maven from the repo root:
+
+```bash
+mvn clean compile                         # build all modules (no tests)
+mvn clean install                         # build + run tests
+mvn clean compile -pl aioj-backend-auth   # build a single module
+mvn clean install -DskipTests             # build all modules, skip tests
+mvn spring-boot:run -pl aioj-backend-gateway  # run a single service
+mvn test -pl aioj-backend-user-service        # test a single service
+mvn spring-javaformat:apply               # format code
+mvn spring-javaformat:check               # verify formatting
+```
+
+Docker image build (JIB):
+
+```bash
+mvn package jib:build -pl <module-name>      # build & push
+mvn package jib:buildTar -pl <module-name>   # build tar
+```
+
+## Coding Style & Naming Conventions
+
+- Follow existing formatting and run `mvn spring-javaformat:apply` before submitting changes.
+- Indentation follows Java defaults (4 spaces; no tabs unless already present).
+- Use standard Java naming: `PascalCase` for classes, `camelCase` for methods/fields, `UPPER_SNAKE_CASE` for constants.
+- Controllers: `<Resource>Controller`; Services: `<Resource>Service` / `<Resource>ServiceImpl`;
+  Mappers: `<Resource>Mapper`; DTOs: `<Operation><Resource>DTO`.
+- Module names follow the `aioj-backend-*` pattern; keep new module names consistent.
+
+## Development Guidelines
+
+- Service modules should depend on common modules, not on other service modules.
+- Use Feign clients for inter-service communication.
+- Keep classes focused and single-purpose; prefer Lombok to reduce boilerplate.
+- Validate and sanitize user input; use `@PreAuthorize` for method security.
+- Use custom exceptions + global handlers; return consistent DTO responses.
+- Externalize configuration; use Nacos for centralized config management.
+- Never commit sensitive credentials.
+
+## Architecture Notes
+
+- Auth uses JWT via `common-security`.
+- Gateway handles routing, auth checks, Sentinel-based flow control.
+- Question service uses Chain of Responsibility for validation.
+- Sentinel + Nacos provide dynamic flow control and rules.
+- Redis used for cache/session; MyBatis for persistence.
+- Blog service supports Markdown (Flexmark) + Redis caching.
+
+## Testing Guidelines
+
+- Tests live under `src/test/java` in each module.
+- Name tests clearly after the unit under test (e.g., `UserServiceTest`).
+- Run `mvn test` for full coverage or `mvn test -pl <module>` for targeted runs.
+
+## Commit & Pull Request Guidelines
+
+- Commit messages follow a conventional prefix pattern (e.g., `feat: add rate limiting`, `refactor: simplify DTO mapping`). Keep the subject imperative and concise.
+- PRs should include: a short summary, affected services/modules, testing performed, and any config or port changes.
+- If a change affects API behavior or configuration, update `README.md` or relevant docs.
+
+## Local Service Ports (Reference)
+
+- Gateway `18085`, Auth `18081`, User `18082`, UPMS `18083`, File `18066`.
+  Update this list if you add or change service ports.