@softspark/ai-toolkit 3.0.2 → 3.1.1

package/app/skills/golang-rules/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: golang-rules
+description: "Go coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .go, go.mod, go.sum, Gin, Echo, Gorilla, testing, gofmt. Load when writing, reviewing, or editing Go code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Go Rules
+
+These rules come from `app/rules/golang/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in Go. Apply them when writing or
+reviewing Go code.
+
+# Go Coding Style
+
+## Naming
+- MixedCaps/mixedCaps only. No underscores in Go names (except test functions).
+- Exported: `PascalCase`. Unexported: `camelCase`. Acronyms: `HTTPClient`, `userID`.
+- Short variable names in small scopes: `i`, `r`, `w`, `ctx`, `err`.
+- Descriptive names in larger scopes: `userRepository`, `requestTimeout`.
+- Package names: short, lowercase, singular (`auth`, `user`, not `utils`, `helpers`).
+
+## Packages
+- One package per directory. Package name = directory name.
+- Avoid `util`, `common`, `helpers` packages. Name by what it provides.
+- Keep package APIs small. Export only what consumers need.
+- Use `internal/` directory for packages not meant for external consumption.
+
+## Functions
+- Accept interfaces, return structs.
+- First parameter `ctx context.Context` if the function does I/O or may be cancelled.
+- Return `(result, error)` tuple. Error is always last return value.
+- Use named return values only for documentation, not for naked returns.
+- Keep functions short. If >40 lines, consider splitting.
+
+## Error Handling
+- Always check errors. Never use `_` to discard errors silently.
+- Wrap errors with context: `fmt.Errorf("fetching user %s: %w", id, err)`.
+- Use sentinel errors (`var ErrNotFound = errors.New(...)`) for expected conditions.
+- Use `errors.Is()` and `errors.As()` for error checking, not type assertions.
+
+## Formatting
+- Use `gofmt` / `goimports`. No formatting debates in Go.
+- Use `golangci-lint` with a `.golangci.yml` config in CI.
+- Use `go vet` as minimum static analysis.
+
+## Struct Design
+- Use struct embedding for composition, not inheritance.
+- Prefer value receivers for small structs, pointer receivers for large or mutable.
+- Be consistent: all methods on a type use the same receiver type.
+- Use struct literals with field names: `User{Name: "Ada", Age: 30}`.
+
+## Concurrency
+- Do not start goroutines without a plan to stop them.
+- Use `sync.WaitGroup` or `errgroup.Group` to coordinate goroutines.
+- Use channels for communication, mutexes for state protection.
+- Prefer `context.Context` for cancellation and timeouts over manual signaling.
+
+# Go Frameworks
+
+## Standard Library HTTP
+- Use `http.NewServeMux()` (Go 1.22+ with method patterns) for simple APIs.
+- Use `http.HandlerFunc` for handlers. Compose with middleware pattern.
+- Use `context.Context` from `r.Context()` in all handlers.
+- Use `http.TimeoutHandler` to prevent slow handlers from hanging.
+
+## Chi / Gorilla Mux
+- Use Chi for routing with middleware chains and URL params.
+- Use `chi.URLParam(r, "id")` to extract path parameters.
+- Use middleware groups: `r.Group(func(r chi.Router) { r.Use(authMiddleware) })`.
+- Prefer Chi over Gorilla Mux (Gorilla was archived, Chi actively maintained).
+
+## Gin / Echo
+- Use Gin for high-performance APIs with built-in validation.
+- Use binding tags: `binding:"required,email"` on struct fields.
+- Use middleware for cross-cutting: logging, recovery, CORS, auth.
+- Use `c.ShouldBindJSON()` over `c.BindJSON()` to handle errors yourself.
+
+## GORM / sqlx / pgx
+- Use `sqlx` for SQL-first with struct scanning (lightweight).
+- Use `pgx` directly for PostgreSQL-specific features and performance.
+- Use GORM only when rapid prototyping outweighs SQL control.
+- Always use prepared statements or parameterized queries.
+- Use `sqlx.In()` for dynamic IN clauses safely.
+
+## gRPC
+- Define services in `.proto` files. Generate Go code with `protoc`.
+- Use interceptors for auth, logging, and tracing (equivalent to middleware).
+- Use deadlines (context timeout) on every RPC call.
+- Use streaming RPCs for real-time data, unary for request-response.
+
+## Configuration
+- Use `envconfig` or `viper` for configuration from env/files.
+- Use struct tags for env mapping: `envconfig:"DATABASE_URL"`.
+- Validate config at startup. Fail fast on invalid configuration.
+- Use `flag` package for CLI arguments in tools and utilities.
+
+## Observability
+- Use `slog` (Go 1.21+) for structured logging. Replace `log` package.
+- Use OpenTelemetry for distributed tracing and metrics.
+- Export metrics via Prometheus endpoint.
+- Use `pprof` for CPU and memory profiling in development.
+
+## Project Layout
+- Follow Standard Go Project Layout: `cmd/`, `internal/`, `pkg/`.
+- Entry points in `cmd/appname/main.go`.
+- Business logic in `internal/`. Shared libraries in `pkg/`.
+- Use `Makefile` for common tasks: build, test, lint, run.
+
+# Go Patterns
+
+## Error Handling
+- Wrap errors with context at each call site: `fmt.Errorf("loading config: %w", err)`.
+- Define domain error types with `errors.New()` or custom error structs.
+- Use `errors.Is()` for sentinel errors, `errors.As()` for typed errors.
+- Return errors, do not panic. Reserve `panic` for truly unrecoverable states.
+- Handle errors immediately after the call. No deferred error checking.
+
+## Concurrency
+- Use `errgroup.Group` for concurrent operations that may fail.
+- Use `sync.Once` for one-time initialization (singleton pattern).
+- Use `sync.Map` only for append-mostly maps with concurrent access.
+- Use buffered channels as semaphores: `sem := make(chan struct{}, maxConcurrency)`.
+- Prefer `context.WithTimeout` over manual timers for deadline management.
+
+## Interface Design
+- Keep interfaces small: 1-3 methods. Compose larger interfaces from smaller ones.
+- Define interfaces where they are consumed, not where they are implemented.
+- Use `io.Reader`, `io.Writer`, `fmt.Stringer` and standard interfaces where applicable.
+- Avoid returning interfaces from functions. Return concrete types.
+
+## Options Pattern
+- Use functional options for constructors with many optional parameters.
+- Pattern: `func WithTimeout(d time.Duration) Option { return func(c *Client) { c.timeout = d } }`.
+- Provide sensible defaults. Options override defaults.
+- Use `Option` type alias: `type Option func(*Config)`.
+
+## Dependency Injection
+- Pass dependencies through constructor functions, not global variables.
+- Accept interfaces in constructors: `func NewService(repo UserRepo) *Service`.
+- Use `wire` or manual wiring in `main()` for dependency graph.
+- Avoid init() functions for anything other than simple registration.
+
+## Resource Management
+- Use `defer` for cleanup immediately after acquiring a resource.
+- Use `context.Context` for cancellation propagation across goroutines.
+- Close channels from the sender side, never the receiver.
+- Use `sync.Pool` for frequently allocated temporary objects (buffers).
+
+## Anti-Patterns
+- Global mutable state: use dependency injection instead.
+- `interface{}` / `any` everywhere: use generics (Go 1.18+) or specific types.
+- Goroutine leaks: always ensure goroutines can exit.
+- Ignoring `context.Context`: propagate it through all I/O paths.
+- Large interfaces: split into focused, composable pieces.
+
+# Go Security
+
+## Input Validation
+- Validate all input at API boundaries. Use struct tags or manual validation.
+- Use `validator` package for struct validation: `validate:"required,email"`.
+- Parse and validate numeric IDs: `strconv.Atoi()` with error checking.
+- Limit request body size: `http.MaxBytesReader(w, r.Body, maxBytes)`.
+
+## SQL Injection
+- Always use parameterized queries: `db.Query("SELECT * FROM users WHERE id = $1", id)`.
+- Never concatenate user input into SQL strings.
+- Use `sqlx.In()` for safe dynamic IN clauses.
+- Use ORM query builders (GORM, Ent) for dynamic query construction.
+
+## Command Injection
+- Use `exec.Command("binary", args...)` with separate arguments, not shell strings.
+- Never use `exec.Command("sh", "-c", userInput)`.
+- Validate and sanitize file paths against traversal attacks.
+- Use `filepath.Clean()` and verify paths are within allowed directories.
+
+## Cryptography
+- Use `crypto/rand` for random values, never `math/rand` for security.
+- Use `bcrypt` or `argon2` for password hashing: `golang.org/x/crypto/bcrypt`.
+- Use `crypto/subtle.ConstantTimeCompare()` for timing-safe comparisons.
+- Use `crypto/tls` with `tls.Config{MinVersion: tls.VersionTLS12}`.
+
+## Secrets
+- Load secrets from environment variables: `os.Getenv("SECRET_KEY")`.
+- Never hardcode secrets, tokens, or API keys in source code.
+- Use `go-envconfig` or similar for validated env var loading.
+- Use Go build tags or ldflags for build-time configuration.
+
+## HTTP Security
+- Set `ReadTimeout`, `WriteTimeout`, `IdleTimeout` on `http.Server`.
+- Use `helmet`-equivalent headers: HSTS, X-Content-Type-Options, X-Frame-Options.
+- Implement rate limiting with `golang.org/x/time/rate` or middleware.
+- Use `net/http` with TLS. Never serve production HTTP without encryption.
+
+## Concurrency Safety
+- Use `sync.Mutex` or `sync.RWMutex` for shared mutable state.
+- Run `go test -race` in CI to detect data races.
+- Avoid shared state where possible. Prefer channels for communication.
+- Use `atomic` package for simple counters and flags.
+
+## Dependencies
+- Run `govulncheck ./...` in CI to check for known vulnerabilities.
+- Use `go mod tidy` to remove unused dependencies.
+- Pin dependencies via `go.sum`. Review dependency changes in PRs.
+- Audit transitive dependencies. Use `go mod graph` to inspect the tree.
+
+## Error Information Disclosure
+- Never expose internal error messages to clients.
+- Log detailed errors server-side, return generic messages to clients.
+- Use error codes for machine-readable error classification.
+- Do not include stack traces in production API responses.
+
+# Go Testing
+
+## Framework
+- Use the standard `testing` package. No external test frameworks required.
+- Use `testify/assert` and `testify/require` for readable assertions.
+- Use `testify/mock` or `mockgen` for generating mocks.
+- Use `go test -race` in CI to detect data races.
+
+## File Naming
+- Test files: `*_test.go` in the same package.
+- Black-box tests: use `package foo_test` to test only exported API.
+- White-box tests: use `package foo` to test internals.
+- Test helpers: `testutil_test.go` or `testdata/` directory.
+
+## Table-Driven Tests
+- Use table-driven tests for functions with multiple input/output cases.
+- Name each case: `{name: "empty input returns error", input: "", wantErr: true}`.
+- Use `t.Run(tc.name, func(t *testing.T) { ... })` for subtests.
+- Use `t.Parallel()` in subtests when tests are independent.
+
+## Test Helpers
+- Use `t.Helper()` in helper functions for correct line reporting.
+- Use `t.Cleanup()` for teardown instead of defer in test functions.
+- Use `testing.TB` interface to share helpers between tests and benchmarks.
+- Use `testdata/` directory for test fixtures (excluded from build).
+
+## Mocking
+- Define interfaces at the consumer, not the provider.
+- Use `mockgen` to auto-generate mocks from interfaces.
+- Use `httptest.NewServer()` for HTTP integration tests.
+- Use `httptest.NewRecorder()` for handler unit tests.
+
+## Integration Tests
+- Use build tags: `//go:build integration` to separate from unit tests.
+- Use `testcontainers-go` for database/service containers in tests.
+- Use `t.Setenv()` (Go 1.17+) for environment variable testing.
+
+## Benchmarks
+- Use `func BenchmarkXxx(b *testing.B)` with `b.N` loop.
+- Use `b.ResetTimer()` after expensive setup.
+- Use `b.ReportAllocs()` to track allocations.
+- Run: `go test -bench=. -benchmem`.
+
+## Coverage
+- Run: `go test -coverprofile=coverage.out ./...`.
+- View: `go tool cover -html=coverage.out`.
+- Set minimum coverage threshold in CI.
+- Focus coverage on business logic, not generated code.

package/app/skills/java-rules/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: java-rules
+description: "Java coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .java, pom.xml, build.gradle, Spring, Spring Boot, JPA, Hibernate, JUnit, Maven, Gradle. Load when writing, reviewing, or editing Java code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Java Rules
+
+These rules come from `app/rules/java/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in Java. Apply them when writing or
+reviewing Java code.
+
+# Java Coding Style
+
+## Naming
+- PascalCase: classes, interfaces, enums, records, annotations.
+- camelCase: methods, variables, parameters.
+- UPPER_SNAKE: constants (`static final`).
+- Package names: lowercase, dot-separated, reverse domain (`com.company.project`).
+- No Hungarian notation. No `I` prefix on interfaces.
+
+## Modern Java (17+)
+- Use `record` for immutable data carriers. No need for Lombok in most cases.
+- Use `sealed` classes/interfaces for restricted hierarchies.
+- Use pattern matching: `if (obj instanceof String s)` instead of cast.
+- Use `switch` expressions with arrow syntax and exhaustiveness.
+- Use text blocks (`"""`) for multiline strings (SQL, JSON, HTML).
+
+## Types
+- Use `var` for local variables when the type is obvious from the right-hand side.
+- Use `Optional<T>` for return types that may be absent. Never for fields or params.
+- Prefer `List.of()`, `Map.of()`, `Set.of()` for immutable collections.
+- Use `Stream` for collection transformations. Avoid streams for simple iterations.
+
+## Classes
+- Prefer composition over inheritance. Use interfaces for abstraction.
+- Keep classes focused: single responsibility.
+- Use `final` on classes not designed for extension.
+- Use `private` constructors + static factory methods for controlled instantiation.
+- Records over POJOs for value types. Lombok only if records are insufficient.
+
+## Methods
+- Max 20-30 lines per method. Extract when longer.
+- Use `@Override` on every overridden method.
+- Return empty collections over `null`. Use `Collections.emptyList()` or `List.of()`.
+- Avoid checked exceptions for programming errors. Use runtime exceptions.
+
+## Formatting
+- Use project formatter (Google Java Format or IDE-configured).
+- Use `@SuppressWarnings` sparingly and with specific warning names.
+- Use `final` for parameters and local variables where practical.
+
+## Nullability
+- Annotate with `@Nullable` / `@NonNull` from JSpecify or JetBrains.
+- Use `Objects.requireNonNull()` at public API boundaries.
+- Never return `null` from collections or arrays. Return empty.
+- Use `Optional` for genuinely optional return values.
+
+## Documentation
+- Javadoc on all public classes and methods.
+- Use `@param`, `@return`, `@throws` tags for public API methods.
+- Skip Javadoc for obvious getters, `toString()`, and `equals()`.
+
+# Java Frameworks
+
+## Spring Boot
+- Use Spring Boot 3+ with Java 17+ minimum.
+- Use `@RestController` for REST APIs. Return `ResponseEntity` for status control.
+- Use `@Valid` + Jakarta Bean Validation for request validation.
+- Use profiles (`@Profile`) for environment-specific configuration.
+- Use `application.yml` over `application.properties` for readability.
+- Externalize config: env vars > config files > hardcoded defaults.
+
+## Spring Data JPA
+- Use repository interfaces extending `JpaRepository`.
+- Use `@Query` with JPQL for custom queries. Use native queries only when needed.
+- Use `@EntityGraph` to prevent N+1 queries in associations.
+- Use `Specification` for dynamic query building.
+- Always use `@Transactional` at the service layer, not repository.
+
+## Spring Security
+- Use `SecurityFilterChain` bean configuration (not `WebSecurityConfigurerAdapter`).
+- Use `@PreAuthorize` / `@Secured` for method-level authorization.
+- Use BCrypt for password encoding: `new BCryptPasswordEncoder()`.
+- Configure CORS, CSRF, and session management explicitly.
+- Use OAuth2 Resource Server for JWT validation in APIs.
+
+## Hibernate / JPA
+- Use `FetchType.LAZY` by default on all associations.
+- Use `@BatchSize` or `@Fetch(FetchMode.SUBSELECT)` to avoid N+1.
+- Use `@Version` for optimistic locking on entities.
+- Use DTOs (records) for read queries. Do not expose entities in APIs.
+- Use Flyway or Liquibase for schema migrations.
+
+## Quarkus / Micronaut
+- Use for microservices and serverless where startup time matters.
+- Use compile-time DI (Micronaut) or build-time optimization (Quarkus).
+- Use reactive patterns with Mutiny (Quarkus) or Reactor (Micronaut).
+- Use native image builds with GraalVM for production deployments.
+
+## Build Tools
+- Use Gradle (Kotlin DSL) for new projects. Maven for enterprise legacy.
+- Use dependency management to unify versions across modules.
+- Use Bill of Materials (BOM) imports for consistent Spring versions.
+- Use Spotless or Checkstyle for enforced code formatting.
+
+## Logging
+- Use SLF4J facade with Logback or Log4j2 backend.
+- Use structured logging with MDC for correlation IDs.
+- Use parameterized logging: `log.info("User {} created", userId)`.
+- Never log sensitive data (passwords, tokens, PII).
+
+# Java Patterns
+
+## Error Handling
+- Use unchecked exceptions for programming errors (`IllegalArgumentException`).
+- Use checked exceptions only for recoverable conditions the caller must handle.
+- Create domain exception hierarchy: `AppException` -> `NotFoundException`, etc.
+- Never catch `Exception` or `Throwable` broadly. Catch specific types.
+- Use `try-with-resources` for all `AutoCloseable` resources.
+
+## Immutability
+- Use `record` for immutable value objects (Java 16+).
+- Use `List.copyOf()`, `Map.copyOf()` to create unmodifiable copies.
+- Make fields `private final`. No setters unless mutation is required.
+- Return defensive copies of mutable collections from getters.
+- Use builder pattern for constructing immutable objects with many fields.
+
+## Optional
+- Use `Optional<T>` as return type for methods that may not return a value.
+- Chain: `optional.map(...).orElseThrow(...)`. Avoid `isPresent()` + `get()`.
+- Never use `Optional` for fields, method parameters, or collection elements.
+- Use `Optional.empty()` over `null`. Use `Optional.ofNullable()` at boundaries.
+
+## Streams
+- Use streams for transformations: `filter`, `map`, `collect`.
+- Avoid side effects in stream operations. Keep them pure.
+- Use `Collectors.toUnmodifiableList()` for immutable results.
+- Prefer `for` loop for simple iterations that do not transform data.
+- Use `Stream.of()` or `IntStream.range()` for generating sequences.
+
+## Dependency Injection
+- Use constructor injection exclusively. No field or setter injection.
+- Accept interfaces in constructors, not implementations.
+- Use `@Component`, `@Service`, `@Repository` for Spring-managed beans.
+- Keep the number of constructor dependencies under 5. Split if more.
+
+## Concurrency
+- Use `ExecutorService` and `CompletableFuture` for async operations.
+- Use `virtual threads` (Java 21+) for I/O-bound concurrent work.
+- Use `ConcurrentHashMap`, `AtomicInteger` for thread-safe operations.
+- Avoid `synchronized` blocks when possible -- use higher-level concurrency.
+- Use `ReentrantReadWriteLock` for read-heavy shared state.
+
+## Design Patterns
+- Use Strategy pattern (via interfaces) over switch/if-else chains.
+- Use Factory methods for flexible object creation.
+- Use Decorator pattern for composable behavior augmentation.
+- Avoid Singleton pattern -- use DI container for lifecycle management.
+
+## Anti-Patterns
+- Returning `null` from methods -- use `Optional` or empty collections.
+- Mutable DTOs with getters/setters -- use records.
+- God classes with 20+ dependencies -- split by responsibility.
+- String typing for domain values -- use types, enums, or value objects.
+
+# Java Security
+
+## Input Validation
+- Validate all input with Jakarta Bean Validation (`@NotNull`, `@Size`, `@Email`).
+- Use `@Valid` on controller parameters to trigger validation automatically.
+- Create custom validators for domain-specific rules.
+- Never trust client-provided IDs. Verify resource ownership server-side.
+
+## SQL Injection
+- Use JPA/Hibernate parameterized queries. Never concatenate input into JPQL/SQL.
+- Use `CriteriaBuilder` or Specifications for dynamic queries.
+- For native queries, use named parameters: `@Query(value = "... WHERE id = :id", nativeQuery = true)`.
+- Use `PreparedStatement` if using JDBC directly. Never `Statement` with concatenation.
+
+## Authentication
+- Use Spring Security with BCrypt (`BCryptPasswordEncoder`) for password hashing.
+- Use JWT with short expiration (15 min) + refresh tokens for APIs.
+- Implement account lockout after N failed attempts.
+- Use `@AuthenticationPrincipal` to access the current user in controllers.
+
+## Authorization
+- Use `@PreAuthorize("hasRole('ADMIN')")` for role-based access control.
+- Use method security for fine-grained authorization.
+- Check resource ownership in service layer, not just role membership.
+- Default deny: require explicit authorization for every endpoint.
+
+## XSS and CSRF
+- Spring auto-escapes Thymeleaf output. Do not use `th:utext` with user data.
+- Enable CSRF protection for session-based auth. Disable only for stateless JWT APIs.
+- Set `Content-Type` headers explicitly on responses.
+- Use CSP headers to restrict script sources.
+
+## Serialization
+- Do not deserialize untrusted data with `ObjectInputStream` (RCE risk).
+- Use Jackson with `@JsonIgnoreProperties(ignoreUnknown = true)`.
+- Disable default typing in Jackson: never use `enableDefaultTyping()`.
+- Validate deserialized objects with Bean Validation after parsing.
+
+## Dependencies
+- Run OWASP Dependency-Check in CI: `mvn verify -P owasp-check`.
+- Update Spring Boot regularly -- security patches are frequent.
+- Use `dependencyManagement` to control transitive dependency versions.
+- Audit `mvn dependency:tree` for unexpected transitive dependencies.
+
+## Secrets
+- Use Spring Cloud Config or Vault for secrets management.
+- Use `@Value("${secret}")` with env var placeholders, not hardcoded values.
+- Never log request headers containing `Authorization` or session tokens.
+- Use separate config profiles for dev/staging/prod with different secrets.
+
+## Logging Security
+- Use parameterized logging to prevent log injection.
+- Sanitize user input before logging: remove newlines and control characters.
+- Never log stack traces to API responses. Return generic error messages.
+
+# Java Testing
+
+## Framework
+- Use JUnit 5 (Jupiter) for all new tests. No JUnit 4.
+- Use AssertJ for fluent, readable assertions.
+- Use Mockito for mocking dependencies.
+- Use Testcontainers for integration tests with databases/services.
+
+## File Naming
+- Test classes: `FooTest.java` in `src/test/java/` mirroring source package.
+- Integration tests: `FooIT.java` or use `@Tag("integration")`.
+- Test utilities: `src/test/java/.../support/` or `TestUtils.java`.
+
+## Structure
+- Use `@Nested` classes to group related tests within a test class.
+- Use `@DisplayName` for human-readable test descriptions.
+- Use `@BeforeEach` for setup, `@AfterEach` for cleanup.
+- Use `@ParameterizedTest` with `@ValueSource`, `@CsvSource`, `@MethodSource`.
+
+## Assertions (AssertJ)
+- Use `assertThat(actual).isEqualTo(expected)` over JUnit assertions.
+- Use `assertThatThrownBy(() -> ...).isInstanceOf(FooException.class)`.
+- Use `assertThat(list).hasSize(3).extracting("name").contains("Ada")`.
+- Chain assertions for readable, self-documenting tests.
+
+## Mocking (Mockito)
+- Use `@Mock` + `@ExtendWith(MockitoExtension.class)` for injection.
+- Use `when().thenReturn()` for stubbing. `verify()` for interaction checking.
+- Use `@InjectMocks` to auto-inject mocks into the class under test.
+- Prefer constructor injection in production code for testability.
+- Use `ArgumentCaptor` to inspect complex arguments.
+
+## Integration Testing
+- Use Testcontainers for PostgreSQL, Redis, Kafka, etc.
+- Use `@SpringBootTest` sparingly -- it starts the full context. Prefer slices.
+- Use `@WebMvcTest` for controller tests, `@DataJpaTest` for repository tests.
+- Use `@TestConfiguration` for test-specific bean overrides.
+
+## Test Data
+- Use test builders or factory methods for creating test objects.
+- Use `@Sql` annotation to load test data from SQL files.
+- Keep test data minimal. Only set fields relevant to the behavior under test.
+- Use random UUIDs for IDs in tests to avoid collision.
+
+## Performance
+- Run tests in parallel: configure `junit.jupiter.execution.parallel.enabled=true`.
+- Use `@SpringBootTest` only when integration context is needed.
+- Mock external dependencies in unit tests for speed.
+- Keep the full test suite under 5 minutes.