java-backend-team: Instructions file for Codex

AGENTS.md

Repository purpose

This is a production Java backend project used by a team.
Primary goals: correctness, stability, minimal-risk changes, reviewability, maintainability.

Working mode

When working in this repository:

1. Read relevant code before editing.
2. Prefer the smallest safe change that solves the task.
3. Do not refactor unrelated code.
4. Reuse existing patterns before introducing new abstractions.
5. Preserve compatibility unless the task explicitly allows breaking changes.
6. Keep changes easy to review and easy to roll back.

Architecture expectations

Follow the project's existing layered architecture.

Typical responsibilities:

• Controller: request parsing, basic validation, response shaping
• Service: business orchestration, transaction boundaries, core business logic
• Manager / Domain service: reusable business capabilities
• Repository / DAO / Mapper: persistence and data access
• DTO / Request: inbound transport objects
• VO / Response: outbound transport objects
• Entity / DO / PO: persistence models

Do not:

• Put complex business logic in controllers
• Put business rules into mapper/repository/DAO classes
• Return persistence entities directly to clients unless the project already standardizes that pattern
• Introduce cross-layer shortcuts for convenience

Change scope rules

Unless the user explicitly asks otherwise:

• Only modify files directly related to the task
• Do not rename files, packages, or public symbols without clear need
• Do not change API contracts casually
• Do not modify database schema casually
• Do not modify auth, billing, order, payment, tenant isolation, or core shared infrastructure unless the task requires it

If the task touches high-risk areas, call that out explicitly before making changes.

Java coding rules

• Prefer clear, business-meaningful names
• Avoid needless abstraction
• Avoid duplicate utility methods if similar ones already exist
• Avoid loose typing patterns; keep types explicit
• Keep methods focused and readable (ideally < 50 lines)
• Use Stream only when it improves readability
• Handle null and empty cases deliberately
• Use project-standard exceptions, result wrappers, and enums
• Add meaningful comments for complex business logic
• Follow Alibaba Java Coding Guidelines and Google Java Style Guide
• Use @NotNull, @Nullable annotations to express nullability intent
• Prefer composition over inheritance
• Use enums for fixed value sets instead of magic strings/numbers