codebase-standards

Codebase Standards

Thesis: Universal guardrails that apply regardless of which file you're editing — the principles that every other rule assumes you follow.

Core Guardrails

One-line reminders of the highest-consequence rules. Domain-specific rules (go-service, solidjs-pages, etc.) have full explanations and examples.

• Module spec mapping — before modifying a module, read its spec at docs/modules/{module}/spec.md. Folders: auth, users, feature. Multi-file auth: auth_password, auth_verify → auth spec.
• Parameterized queries only — never fmt.Sprintf with values into SQL. Use $N placeholders for values; write literal SQL per call site for identifiers.
• apperror for all errors — never echo.NewHTTPError. Use apperror.BadRequest, .Forbidden, .NotFound, .Validation, .Internal.
• batch() signal updates after every await — put user-visible state like setLoading(false) inside both try and catch, wrapped in batch(). finally is only okay for independent re-entry locks that do not need to batch with success/error UI.
• Switch/Match for content states — never nested <Show> for loading/error/empty/data states.
• onMount + signals for data fetching — never createResource. Use alive guard and loadRequestID for param refetches. See solidjs-data-fetching.
• Never early-return route components before reactive setup — move auth/access guards into JSX with <Show when={...} fallback={...}>.
• Never discard errors — no _ = fn(). Log with logger.Error at minimum.
• Resource membership, not just role — verify the specific user belongs to the specific resource, not just userType.
• Config over hardcoded values — if you'd change it per environment, it belongs in Config or named constants.
• Request body size limit — middleware.BodyLimit("1M") is configured in stack.go.
• SSE uses one-time ticket auth (not JWT in URL) — see handler/sse.go and service/sse/sse.go.
• Command lookup before shell work — before running nontrivial local, test, deploy, GCP, Git, or contract-validation commands, read common-commands / docs/cli-reference.md, use known-good repo commands, and diagnose the first concrete failure instead of probing equivalent tools.