wenzi/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• Spring Boot 3 (Java 17) Maven app.
• Key paths:
  • src/main/java — root package com.mosquito.project (modules: controller, service, domain, dto, job, exception).
  • src/main/resources — app config (application.properties), Flyway migrations in db/migration.
  • src/test/java — JUnit 5 tests mirroring main packages.
  • docs/, specs/ — documentation and specifications.
  • target/ — build outputs (generated).

Build, Test, and Development Commands

• Build: mvn clean package — compile, test, and create JAR in target/.
• Run (dev): mvn spring-boot:run — start app with live reload of resources.
• Run (JAR): java -jar target/mosquito-0.0.1-SNAPSHOT.jar.
• Test all: mvn test.
• Test one: mvn -Dtest=ActivityServiceTest test.
• Verify: mvn verify — full lifecycle checks.

Coding Style & Naming Conventions

• Java 17; 4-space indentation; one class per file; braces on same line.
• Packages: lowercase under com.mosquito.project.
• Classes: PascalCase; methods/fields: camelCase; constants: UPPER_SNAKE_CASE.
• DTOs end with Request/Response; exceptions end with Exception.
• Use Lombok where present (e.g., @Getter, @Builder); avoid wildcard imports.
• Validate inputs with Bean Validation annotations (e.g., @NotNull, @Size).

Testing Guidelines

• Frameworks: JUnit 5, Spring Boot Test, WebMvcTest/MockMvc; H2 and Embedded Redis for tests; Testcontainers available when needed.
• Location: src/test/java with names *Test.java; mirror package of code under test.
• Conventions: method names like shouldDoX_whenY(); prefer fast slice tests for controllers, @SpringBootTest for integration.
• Run: mvn test or a focused run via -Dtest=....

Commit & Pull Request Guidelines

• Use Conventional Commits: feat|fix|docs|test|refactor|chore(scope): message.
• Example: feat(activity): add graph endpoint with validation.
• PRs: include purpose, linked issues, API examples or reproduction steps, updated tests/docs, and ensure mvn -q verify passes.

Security & Configuration Tips

• App config in src/main/resources/application.properties (e.g., spring.redis.host/port); DB via SPRING_DATASOURCE_* env vars.
• Never commit secrets; prefer environment variables or an untracked application-local.properties.
• Database schema changes go through Flyway migrations in src/main/resources/db/migration.

Agent-Specific Notes

• Keep changes minimal and localized; match the existing package layout.
• Avoid introducing new dependencies without discussion; update tests and docs with behavior changes.