5.6 KiB
Repository Guidelines
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.
Build, Test, and Development Commands
# Build (produces target/*-bin.zip: jar + doc + sql + html)
mvn package -Pdev -DskipTests
# Run
mvn spring-boot:run
# Test
No automated tests (manual smoke only)
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>.
Architecture & Coding Style
Use Java, 4-space indentation, max line width 120. 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.