AGENTS.md is the cross-vendor contributor guide (Claude, Codex, and others read it). Keep it in English by convention. It overlaps CLAUDE.md on purpose — this is the canonical version for non-Claude agents.
## Authority & Required Reading
Rules in `.project.agents/CLAUDE.md` apply to every agent working here. Direct user instructions still take precedence.
The canonical contributor guide is `.project.agents/AGENTS.md`. Do not create or maintain a root-level `AGENTS.md` unless the user explicitly asks for one.
Before any code-changing task, read `.project.agents/SELF_CONSTRAINTS.md` and `.project.agents/VIBECODING_GUIDE.md`, then run `git status --short`. For product work, also read the relevant sections of `PRD.md`, `ARCHITECTURE.md`, `ROADMAP.md`, and `CONVENTIONS.md` under `.project.agents/docs/context/`. Shared front-backend constraints live in the workspace-level `docs/` (see `../../../docs/coding-standards.md`) — read the referenced sections instead of duplicating them here.
## Project Structure & Module Organization
`abacus.springboot.example` is a Spring Boot Maven microservice template (multi-database + abacus framework), parent `abacus.framework:abacus.springcloud.pom:1.5.0`. Business code lives in `src/main/java/abacus/springboot.<app>.{api,controller,dao,esb,pi,impl,repository,wsi,config,util,vo}/` (reference template: the `example` JcBill vertical slice, copy-and-rewrite); config in `src/main/resources/config/{dev,test,prod}/`; SQL in `src/main/resources/sql/`. No automated tests.
Target architecture is documented in `ARCHITECTURE.md`: layered packages (api/controller → esb/wsi → pi/impl/repository → dao) with unified response-body wrapping and BusinessException-based errors.
## Source-of-Truth Rules
`PRD.md` defines behavior and scope.
`ARCHITECTURE.md` is the authority for modules, dependencies, contracts, and directory layout. Derived documents follow upstream changes, not the other way around.
Feature changes must update `PRD.md`. Module, dependency, entity, or invariant changes must update `ARCHITECTURE.md` in the same commit. Do not let code and architecture drift for more than 24 hours.
Environment: Nacos must be reachable (bootstrap.yml: server-addr/namespace; extension-configs pull abacus-database/discovery/acas/redis/actuator/xxljob); build depends on the company Maven private repo (abacus framework jars); set `<artifactId>` to `abacus.springboot.<app>`.
Use Java, 4-space indentation, max line width 120. **Every method must carry a one-line responsibility comment** (Javadoc style preferred; manual-review friendly). Controllers: `@RestController` + `@RequestMapping` + springdoc `@Tag`/`@Operation`; `throws Exception`; `@RequestParam(required=false)`; blank-param guard throws `BusinessException`; **return business objects directly** (the wrapper builds the unified response). Services orchestrate in `esb/`; raw SQL lives in `impl/` and MUST use `?` placeholders (no string concatenation). Entities: `@Entity @Table @JsonIgnoreProperties(ignoreUnknown=true) @Schema`, `@Id String`, `@Version Integer`, `STATUS_*` constants, hand-written getters/setters. Business IDs come from `DaoIdGenerator` beans — never hand-craft UUIDs.
Do not add modules that are not registered in `ARCHITECTURE.md`. Preserve the dependency DAG; no reverse dependencies, no cross-feature imports, and no direct access to another module's private implementation. Avoid empty names such as `Manager`, `Helper`, `Util`, or `Common` for new code (legacy `util/`/`vo/` files are reference-only — cite but do not add).
UI/presentation code should consume state and send intents only — put business logic in services/use cases, and keep data-model types thin. Controllers must not write SQL or touch repositories directly; orchestration goes through `esb` services.
## Testing Guidelines
No automated test framework. Required validation from `ARCHITECTURE.md`: manual smoke per API (list / query / create / edit / export) plus real-environment checks. Multi-datasource routing, Kafka consumption, XXL-JOB scheduling, Nacos config pull, and real database migrations require real-environment validation; mock/simulator-only evidence is not enough for those claims.
## Git, Logs, and PRs
Do not pile new work onto unrelated dirty changes without calling it out. Prefer Conventional Commits such as `feat: ...`, `fix: ...`, `docs: ...`. This repository is part of a single git repo rooted at the workspace (`D:\workBuddySpace\member`); commit scope should stay within this subproject unless the change is cross-project (docs/).
Each independently verifiable feature, milestone, non-trivial fix, or refactor needs an execution log in `.project.agents/log/YYYY-MM-DD-<slug>.md` unless it is only a minor documentation edit. Logs must include what changed, relevant commits (or "uncommitted" with reason), verification performed, and next steps. Feature updates also append to `src/main/resources/doc/升级日志.md` per the shared spec §5.11.
Pull requests should include scope, linked issues, screenshots for UI changes, environment/device coverage, and any documentation updates.
## Security & Configuration
Do not commit secrets, credentials, build output, or personal IDE files. Nacos credentials and datasource settings live in `src/main/resources/config/<env>/` (git-tracked per team convention) — do not add new secrets outside those files. Agent configuration and generated agent notes belong under `.project.agents/`, not the repository root, `.claude/`, or a global home directory.
