Engineering standards

Framework-native usage

Prefer Spring Boot and Spring Security capabilities over parallel custom infrastructure when the framework already provides the required boundary.

• Keep controller, service, persistence, configuration, and security responsibilities explicit.
• Avoid hidden runtime conventions that are not documented in the repository.

Local run

Released BuildBaseKit boilerplates use a run, try, and develop workflow as the repository baseline.

• Include the Maven wrapper so system Maven is not required.
• Start without creating .env or configuring local values.
• Use in-memory H2 when a database-backed project needs persistence for evaluation.
• Use local providers and keep external integrations disabled for the default path.
• Supply clearly limited demo data or credentials only when an API flow needs them.

Browser API testing

A project-hosted page at http://localhost:8080/api-test provides a dependency-free way to exercise the available APIs immediately after startup.

• List the product's available API operations and prerequisites.
• Support its authentication, token, role, session, CSRF, or API-key flows without bypassing them.
• Show request payloads, status codes, and response bodies.
• Keep sensitive runtime tokens in memory rather than persistent browser storage.
• Use a same-origin implementation without a separate frontend build or runtime.

External configuration and secrets

• Keep runnable local defaults in application.properties.
• Provide a documented .env.example and import the root .env file only when present.
• Use .env for further development overrides, never as a prerequisite for evaluation.
• Keep environment-specific values outside source code and version control.
• Commit safe local defaults and placeholders, never production credentials.
• Validate deployment configuration early and document every supported override name.

Security and validation

• Define authentication and authorization at explicit boundaries.
• Validate request data and file constraints before state changes.
• Use predictable error handling without exposing internal failures.
• Document security responsibilities that remain application-specific.

Persistence and schema changes

• Use controlled migrations where the released product provides them.
• Keep schema and entity behavior aligned.
• Review any source edition that still relies on automatic schema updates before production deployment.

Automated verification

• Make ./mvnw clean verify work without Docker or external services for the default path.
• Test important happy paths, failure paths, security rules, and configuration boundaries.
• Test both the zero-configuration defaults and production-oriented override validation.
• Keep commands repeatable from the repository.
• Describe semantic expected outcomes instead of invented console output.

Documentation and AI context

• Maintain setup, configuration, API, architecture, and known-limit documentation with behavior changes.
• Keep AGENTS.md, ARCHITECTURE.md, AI_RULES.md, and contribution guidance accurate where provided.
• Treat AI-assisted changes as normal code changes that still require review and verification.

Release and version hygiene

• Track current product and framework versions centrally.
• Keep changelogs factual and scoped to released behavior.
• Do not publish compatibility, capability, or timing claims for unreleased products.