Vibe-Coding-Standards-and-Guidelines

Independent adversarial review that proves findings with failing exploit tests rather than prose — a reviewer who did NOT write the code writes tests designed to make it fail, the engineer fixes until they pass, and high-risk surfaces get multiple reviewers with distinct failure lenses. Use this when reviewing or merging a change, auditing a module, hardening auth/RBAC/money/migration/data-loss code, deciding whether one review pass is enough, writing a security or exploit test, mutation-testing a guard, or handling a non-blocking finding — on backend OR frontend, even if the user doesn't say "adversarial review."

When you change an architecture, migrate EVERY call site in the same change and delete the old path — no dual-path codebase, no "backward compat" bypass kwarg, no re-export shim. Use this when making a parameter required, ripping out a concept, promoting duplicated code to one shared copy, renaming a route or type, or choosing between a real migration and a clever in-place patch — for both backend and frontend, even if the user doesn't say "migration."

Forbids the UI from ever displaying something untrue — fabricated zeros for missing data, a failed fetch shown as an empty list, a raw identifier shown as a name, or a number coerced from garbage. Use this when building or reviewing any view that renders a value, money, count, rating, or status; when writing a number/money/percent formatter; when handling loading/empty/error states; when mapping a backend error to on-screen copy; or whenever an agent is about to render a plausible-looking value with no real data behind it — for both backend (what the API returns) and frontend (what the screen shows), even if the user doesn't say "honesty."

Treats the client as a cache of the server's truth — mutations reflect the server's returned result (never an assumed outcome), the cache is written from confirmed responses, and authority (permissions, prices, availability, membership) comes from the server, not client derivation. Use this when writing or reviewing an optimistic update, a mutation handler, a delete/remove-from-list flow, a refetch/invalidation, a double-submit guard, a replace-all editor, or any place the UI shows derived state — and when designing the endpoints that back them — for both backend and frontend, even if the user doesn't say "server-authoritative."

Insists that "it works" be proven through the actual request path, the deployed artifact, and the genuine UI — not inferred from green unit tests that mocked the exact seam that breaks. Use this when deciding whether a feature is done, reviewing a change that "passes all tests," wiring or trusting CI/CD, mocking the network or auth in a test, debugging a live bug that grep says shouldn't exist, or choosing what evidence counts as proof — for both backend and frontend, even if the user doesn't say "verify through the real path."

Structures multi-agent work into bounded tasks, tool-restricted roles, and an iterative review cycle that loops until reviewers report clean. Use this when dispatching agents to build or change code (frontend or backend), when an agent is about to both write and review its own work, when scoping a task like "implement the notification module" vs "improve the app", when two agents might write the same test file, when an agent builds a React feature and then needs an independent pass for accessibility or business-logic leak, or when deciding whether to commit after one review pass — even if the user doesn't name it explicitly.

Structure an AI-assisted codebase as a modular monolith with domain modules, structurally-enforced boundaries, predictable uniform layout, and day-one extractability. Use this when starting a new project or service, deciding where a new endpoint/feature/component should live, organizing backend domain modules or frontend feature slices, setting up import/lint boundary rules, picking between monolith and microservices, refactoring a "junk drawer" codebase, or whenever an agent is about to guess where code belongs — even if the user doesn't name architecture explicitly.

Enforces safe data-and-state handling — soft-delete user content by default with an audited legal hard-delete path, plus the recurring persistence pitfalls (savepoint wrapping, atomic counters, no DB transaction across external calls, deterministic order_by, ownership checks, ORM/migration parity). Use this when writing or reviewing any delete/erase feature, counter or balance increment, list/query endpoint, mutating repository method, ORM model or Alembic migration, payment/Stripe or other external-API flow, optimistic UI update, or idempotent mutation — on backend OR frontend — even if the user doesn't name it explicitly.

Enforce architecture and quality with structural guardrails (hooks, lint rules, CI gates) instead of prose guidelines, keep the main branch behind human-reviewed PRs, and turn every repeated review comment into an automated rule. Use this when setting up or reviewing pre-commit/pre-push/post-edit hooks, husky/lint-staged, ESLint import-boundary or a11y rules, tsc/CI gates, arch-import checks, ORM/migration parity, branch-protection or PR-merge policy, "# nocheck"/eslint-disable suppressions, or whenever the same issue shows up in code review twice and should become a check — on both frontend and backend, even if the user doesn't name it explicitly.

Defines module specs (a README that says what the module owns AND does NOT own) and typed contracts before any implementation, then drives the Spec -> Interface -> Tests -> Implementation loop. Use this when starting a new module, service, feature, component, or API client; when deciding "where does this logic live?"; when two pieces of code need a commission-rate / shared-value boundary; when writing or reviewing a module/feature README; or when defining backend service interfaces (Protocols, interfaces.py) or frontend contracts (component props/events, typed API clients) — even if the user never says "interface-first" or "contract."

Treats tests as the machine-readable definition of correct behavior and insists they run against production-equivalent infrastructure, not substitutes. Use this when writing or reviewing tests, choosing a test database (real engine vs in-memory SQLite), setting up test fixtures or CI, deciding what to mock, rendering components under test (Testing Library vs shallow render), wiring MSW or a network layer, or organizing/splitting test files — for both backend services and frontend components, even if the user doesn't say "tests as ground truth."