AGENTS.md：让 Codex 真正理解你的项目

就近优先（Closest wins）

子目录 AGENTS.md  →  覆盖  →  仓库根 AGENTS.md  →  覆盖  →  全局 AGENTS.md

## Build & Test
​
- Build: `./mvnw clean compile -pl refinex-system -am`
- Unit test: `./mvnw test -pl refinex-system`
- Integration test: `./mvnw verify -pl refinex-system -P integration`
- Full build: `./mvnw clean package -DskipTests`
- Lint: `./mvnw spotless:check`
- Format: `./mvnw spotless:apply`

## Code Conventions
​
- Java 21, use records for DTOs, sealed interfaces for ADTs
- All public API methods must have Javadoc
- Use `@Slf4j` (Lombok), never `System.out.println`
- Exception handling: throw `BusinessException(ErrorCode)`, never raw exceptions
- REST controllers return `R<T>` wrapper; never return raw entities

## Review Expectations
​
- Every PR must include unit tests for new logic
- Database schema changes require migration scripts in `db/migration/`
- API changes must update OpenAPI spec in `docs/api/`
- No `@SuppressWarnings` without a comment explaining why

## Directory Routing
​
- Gateway config & filters: `refinex-gateway/`
- Auth (Sa-Token + JWT): `refinex-auth/`
- System CRUD services: `refinex-system/`
- AI dialogue & RAG: `refinex-ai/`
- Media generation: `refinex-media/`
- Knowledge base & vector store: `refinex-knowledge/`
- Shared modules (core, redis, mybatis, log, security): `refinex-common/`
- Database migrations: `db/migration/`
- Deploy manifests: `deploy/`

Update AGENTS.md so this fix persists in future sessions.

@codex We always use constructor injection in this project. Add this to AGENTS.md.

┌─────────────────────────────────────────────────┐
│                  AGENTS.md                      │
│         （意图层：告诉 Codex 该怎么做）             │
└──────────────────────┬──────────────────────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
   Pre-commit      Linters     Type Checkers
   Hooks                        
   （执行层：自动阻止违规提交）

## Pre-commit
​
项目使用 pre-commit hooks 自动执行以下检查：
- `spotless:check` — 代码格式
- `checkstyle` — 编码规范
- `mvn test` — 单元测试
​
Codex 在提交代码前应运行 `./mvnw spotless:apply` 确保格式正确。

# Refinex-Cloud AGENTS.md
​
## Project Overview
​
Spring Boot 3.5 + Spring Cloud Alibaba 2025 microservice backend.
Java 21, Maven multi-module, Sa-Token (JWT mixin) for auth.
​
## Build & Test
​
- Full build: `./mvnw clean package -DskipTests`
- Single module: `./mvnw clean compile -pl refinex-system -am`
- Unit tests: `./mvnw test -pl <module>`
- Integration tests: `./mvnw verify -pl <module> -P integration`
- Lint check: `./mvnw spotless:check`
- Lint fix: `./mvnw spotless:apply`
- Always run `spotless:apply` before committing.
​
## Code Conventions
​
- Java 21: use records for DTOs, sealed interfaces for ADTs,
  pattern matching for instanceof
- Logging: `@Slf4j` only, never `System.out.println`
- Exceptions: throw `BusinessException(ErrorCode)`, never raw exceptions
- REST controllers: return `R<T>`, never raw entities
- Dependency injection: constructor injection only, no `@Autowired` on fields
- Database: MyBatis-Plus for all CRUD, no raw SQL unless justified in comment
- Config: `@ConfigurationProperties` bind, no `@Value` for groups of related properties
​
## Review Expectations
​
- Every new feature includes unit tests
- DB schema changes require Flyway migration in `db/migration/`
- API changes must update OpenAPI spec in `docs/api/`
- No `@SuppressWarnings` without explanatory comment
- No `TODO` without linked issue number
​
## Directory Routing
​
- API Gateway (filters, rate limiting): `refinex-gateway/`
- Authentication (Sa-Token, JWT, OAuth2): `refinex-auth/`
- System management (RBAC, user, role, menu): `refinex-system/`
- AI dialogue, RAG, Agent orchestration: `refinex-ai/`
- Media generation (image, video, audio): `refinex-media/`
- Knowledge base, vector store: `refinex-knowledge/`
- Monitoring & alerting: `refinex-monitor/`
- Shared modules: `refinex-common/` (sub-modules: core, redis, mybatis, log, security, web)
- Database migrations: `db/migration/`
- Deploy manifests (Docker, K8s): `deploy/`
​
## Infrastructure Stack
​
- Registry & Config: Nacos 2.x
- Flow control: Sentinel
- Distributed TX: Seata (AT mode)
- Message queue: RocketMQ 5.x
- Cache: Redis 7 (Lettuce client)
- Vector DB: Milvus / PGVector
- Object storage: MinIO
- Observability: Prometheus + Grafana + Jaeger + ELK
​
## Git Workflow
​
- Branch naming: `feat/<issue-id>-<short-desc>`, `fix/<issue-id>-<short-desc>`
- Commit style: Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)
- One logical change per commit

# refinex-ai AGENTS.md
​
## Module Specifics
​
This module handles AI dialogue, RAG pipeline, and Agent orchestration
using Spring AI.
​
## Key Conventions
​
- AI model calls go through `AiModelManager`, never call provider SDKs directly
- RAG pipeline: Document → Splitter → Embedding → VectorStore → Retriever → Prompt
- Conversation history stored in Redis with TTL, key pattern: `chat:{sessionId}`
- Streaming responses use SSE (`SseEmitter`), handle timeout and error callbacks
- All AI-generated content must be logged to `ai_audit_log` table for compliance
​
## Test
​
- Unit tests mock all external AI providers
- Integration tests use WireMock for provider API simulation
- `./mvnw test -pl refinex-ai`

# Unified Personal Agent Rules
​
- Reply to my questions in Chinese, unless the code context is in English
- Use Chinese for code comments
- Provide concise, data-driven explanations
- When reviewing code, prioritize: **security > correctness > performance > readability**
- Always show reasoning before the conclusion
- Prefer showing **diffs** over full file rewrites
- Prefer functional programming style
- Follow standard Git conventions for commands and write commit messages in Chinese

需要 Codex 遵守的持久规则？
  ├─ 是 → AGENTS.md
  └─ 否 → 是可复用的多步骤工作流？
              ├─ 是 → Skills
              └─ 否 → 需要访问外部系统？
                        ├─ 是 → MCP
                        └─ 否 → 直接在 Prompt 中说明