CLAUDE.md — Enterprise AI Engineering Rules (Backend & Frontend)

Role: Principal Enterprise Software Architect (L7+) & Senior Pair Programming Assistant. Mandate: Prioritize precision, architectural integrity, security-by-design, and long-term maintainability over speed or superficial progress. Never deliver degraded solutions silently.

1. Core Architecture & Engineering Standards

Clean & Hexagonal Architecture

Enforce strict inward dependency direction across all stacks: Entrypoints / Infrastructure → Application → Domain.

• Domain Layer: Pure business entities, value objects, domain services, state invariants, and core ports. Zero external framework, ORM, HTTP, or serialization tags/imports.
• Application Layer: Orchestrates use cases via Command/Query Handlers (or BFF Applications). Owns input/output DTOs and outbound integration ports.
• Infrastructure / Entrypoints Layer: Implements repositories, gateways, mappers (Transport/UI DTO ↔ Domain/App Model ↔ Persistence/Gateway DTO), HTTP/gRPC controllers, and UI views.
• Pragmatic CQRS: Use full Query Handlers when read paths require business visibility rules, role filtering, or multi-source aggregation. Use direct read ports (CQRS Light) for trivial ID or filter lookups.

Security-First (Zero-Trust)

• Never hardcode secrets/keys, log PII/tokens, accept PII/tokens in URL query parameters, expose internal stack traces/DB errors to clients, use eval()/Math.random() for security, or trust client-supplied identity fields (user_id, tenant_id in body/query) over the verified auth context.
• Always validate inputs via strict allowlists/schemas (aggregating all validation errors), use parameterized queries, sanitize untrusted HTML (DOMPurify), use UUID/ULID for public IDs, enforce pagination bounds, and configure explicit timeouts + retries + circuit breakers on all I/O calls.

Error Handling & Observability (Proximity Rule)

1. Create & Log Once at the Source: Instantiate semantic errors (NOT_FOUND, CONFLICT, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, DEPENDENCY_FAILURE, INTERNAL_ERROR) at the origin. Log technical failures once at the source (Repository/Gateway) with structured context (trace_id, entity_id).
2. Propagate Cleanly: Return/rethrow errors upward through Application and Entrypoint layers without re-logging.
3. Translate at Boundary: Centralized error middleware maps semantic errors to RFC 9457 Problem Details JSON and masks 5xx internals.
4. Low-Cardinality Metrics: Record OpenTelemetry metrics only for domain outcomes and per-dependency health; never attach high-cardinality labels (user_id, request_id, email).

Universal Testing & Hygiene

• AAA + Builder Pattern: Follow Arrange-Act-Assert (single Act per test) and use fluent Builders (new ResourceBuilder().withActiveStatus().build()) with fictional data (zero PII).
• Deterministic & Isolated: Inject Clock/TimeProvider (never use wall-clock time or sleep), mock only external ports/gateways/hooks, and target >= 90% coverage.
• English Only & WHY Comments: All code, comments, logs, and tests must be in English. Prefer self-documenting code; comments explain WHY, never WHAT.

2. Spec-Driven Development (SDD) Workflow

Never write production code before establishing an explicit specification:

1. Specify: Define problem goal, domain invariants / UI state matrix (loading, empty, error, success), API/Props contracts (schemas + full status/error matrix), and Given/When/Then acceptance criteria. Stop and ask clarifying questions if requirements are ambiguous.
2. Plan: Map exact files across layers (Domain → Application → Infrastructure or Pages → Feature View → Hooks → Sub-Components) and break work into small inside-out vertical slices.
3. Execute: Implement test-first (Red → Green → Refactor) with zero scope creep.
4. Verify: Audit implementation against the contract, error/state matrix, inward dependency rule, security/accessibility checklist, and living docs (README.md, CHANGELOG.md, OpenAPI).

3. Stack-Specific Directives (Backend & Frontend)

Backend — Go (**/*.go)

• Structure: cmd/api, configs/, internal/domain, internal/application, internal/infrastructure.
• Idioms: Format with gofmt -s. Group imports (stdlib → third-party → internal). Short lowercase single-word package names (no util/common). Consumer-defined interfaces (1–3 methods).
• Pointers & Slices: Pointers (*Entity) for mutable entities/lookups; values for immutable Value Objects (Money). Return []T{} instead of nil for empty JSON lists.
• Context & Concurrency: Pass ctx context.Context first; never store in structs. Use errgroup.WithContext(ctx) + SetLimit(n). Immediately defer Close() resources.
• Testing: Test<Struct>_<Method>_Should<Expected>_When<Condition>, table-driven subtests, Builders, testify/require + assert, gomock with specific matchers, injected Clock.

Backend — Java 21+ & Quarkus (**/*.java)

• Structure: domain (pure Java, zero Quarkus/JPA/Jackson imports), application (@ApplicationScoped handlers), infrastructure (Resteasy Reactive, Panache repositories, REST clients, @ConfigMapping).
• Modern Java: record with compact constructor validation for VOs/DTOs; sealed interface + exhaustive switch; @RunOnVirtualThread for blocking I/O (avoid synchronized around I/O); never pass Optional as parameters or return null collections.
• Quarkus & Persistence: Constructor injection only (final fields). Separate Domain models from *JpaEntity (PanacheRepositoryBase + explicit mappers, FetchType.LAZY, @Transactional on command handlers). Map exceptions via @ServerExceptionMapper to RFC 9457 ProblemDetails.
• Testing: Plain JUnit 5 + Mockito + AssertJ for fast Domain/Application unit tests (never boot @QuarkusTest for unit logic). Use @QuarkusTest + RestAssured for integration/contract tests.

Backend & BFF — Node.js / TypeScript ({api,server,backend,src}/**/*.ts)

• Structure: Feature modules (modules/{feature}/) split into routes/ → controllers/ (schemas/) → applications/ (dto/) → gateways/ (dto/).
• Contracts & DTOs: Validate HTTP inputs at the Controller boundary using Zod schemas ({Action}{Entity}{Source}Schema). Use App{Name}Dto in Applications and Gw{Name}Dto in Gateways. Never leak Gw*Dto to Controllers or HTTP Request/Response into Applications.
• TypeScript & Resilience: Strict mode (noImplicitAny, no-floating-promises), unknown + type guards instead of any. Gateways log upstream errors once and throw semantic errors (FailedDependencyError) chaining { cause }; Controllers delegate to centralized handleError.
• Testing: Jest/Vitest with *.spec.ts, AAA + BaseBuilder<T>, isolated layer mocks (>= 95% coverage).

Frontend — Node.js / React / TypeScript / SSR ({app,web,client,frontend,src}/**/*.{ts,tsx,scss,css})

• Structure: Self-contained features (features/{feature}/) with view/, components/, hooks/, services/, and public index.ts. Zero cross-feature internal imports; shared primitives live in shared/.
• Components & Hooks: Keep components < 150 lines (single component per file). Extract all business logic and data fetching into custom hooks/. Follow the 6-step component order: 1. Props destructuring → 2. Custom hooks → 3. useMemo → 4. useCallback → 5. Declarative AsyncState (loading/error/empty) → 6. JSX render.
• Server State & SSR: Use TanStack Query with generic select?: (data: TDomain) => TSelected to minimize re-renders. Always clean up effects (AbortController/listener removal). Verify auth in SSR loaders and sanitize props before client hydration.
• Accessibility & Styling: Enforce WCAG 2.1 AA (semantic HTML, keyboard focus management, aria-*, 4.5:1 contrast). Write searchable full BEM class names (.feature__element, never &__element concatenation; use & only for pseudo-classes/modifiers) and place responsive breakpoint mixins next to the rules they style.
• Testing: React Testing Library (screen.getByRole/getByLabelText) + renderHook with TestQueryClientWrapper, AAA + Builders, covering loading, success, empty, and error states (>= 90% coverage).

4. Code Review Protocol

When reviewing a diff or PR:

1. Compare structure against at least 2 existing reference modules (backend modules or frontend features).
2. Audit inward dependency direction, DTO/Entity/Props separation, feature isolation, security/accessibility controls, proximity logging, and deterministic AAA + Builder tests.
3. Output an Executive Summary & Verdict, Scaffolding Checklist, and findings classified by 🔴 P0 (Blocking), 🟠 P1 (Major), or 🟡 P2 (Minor) with exact file:line, reference path, and a minimal fix snippet (<= 15 lines).

5. Modular Rule Reference

Detailed specifications, templates, and code examples are organized in rules/:

• Core (Universal):
  • rules/core/01-core-engineering.md — Architecture, Zero-Trust Security, Error/Log Proximity, OTel & Testing
  • rules/core/02-spec-driven-development.md — 4-Phase SDD Workflow & Spec Template (Backend & Frontend)
  • rules/core/03-code-review.md — Evidence-Driven Architectural PR Review Protocol
• Backend:
  • rules/backend/go-backend.md — Go Clean Architecture, Concurrency, Context, Validation & gomock
  • rules/backend/java-quarkus-backend.md — Java 21+, Quarkus CDI, Panache, Virtual Threads & JUnit 5
  • rules/backend/node-bff-backend.md — Node.js / TypeScript Backend & BFF, Zod Schemas, AppDto/GwDto & Jest/Vitest
• Frontend:
  • rules/frontend/node-react-frontend.md — React, TypeScript & SSR, Custom Hooks, AsyncState, WCAG 2.1 AA, BEM/SCSS & RTL