Forem: Olivia Craft

Cursor Rules for Vue 3 and Nuxt: AI Dev Guide 2026

Olivia Craft — Sun, 26 Apr 2026 10:00:08 +0000

Vue 3 with Nuxt is the framework that lets you ship a marketing landing page in a morning and a tangled mess of half-converted Options API components, prop mutations, and SSR hydration mismatches by the end of the quarter. The first regression is almost always a component that was started in Composition API with <script setup>, then "fixed" by someone pasting an Options API data() block underneath because that was the syntax they remembered — two reactivity systems in the same file, props read from this.foo in one method and from the props argument in another, lifecycle hooks split between mounted() and onMounted(), and a watch defined in both watch: and watchEffect() that fires twice on every change. The second is the developer who reaches into props.user.name = 'X' to "just update the display" — the parent's reactive object mutates silently, the child remounts later and the value snaps back, and the bug report says "the name keeps reverting." The third is a Nuxt 3 page that calls await fetch('/api/posts') inside <script setup> instead of useFetch — the request fires once on the server during SSR, the hydration payload doesn't include the result, then it fires again on the client, the user sees a flash of empty list, and DevTools shows duplicate network calls on every navigation.

Then you add an AI assistant.

Cursor and Claude Code were trained on Vue code that spans a decade — Vue 2 single-file components with export default { data() { return {...} }, methods: {...}, computed: {...} }, Vue.extend() factories, mixins that inject created() hooks into every consumer and produce name collisions silently, Vuex 3 modules with state / mutations / actions / getters and string-typed commit('SET_USER', payload) calls, this.$emit('input', value) from a child that the parent listens to as @input with no compile-time check that the event even exists, <template> blocks whose template-ref types resolve to any, untyped props: ['title', 'count'] declared as runtime arrays with no TypeScript inference, <nuxt-link to="/about"> from Nuxt 2 next to Nuxt 3's <NuxtLink>, ~/components/Foo.vue imports that broke when Nuxt 3 changed alias resolution, components without <script setup> that use defineComponent({ setup() { return {...} } }) with everything manually returned, watch: { foo: { handler, deep: true } } declared with deep because "the test passed only with deep: true" rather than because the data shape required it, two-way bindings via v-model plus :value plus @input written by hand instead of defineModel(), and the recurring habit of reaching for Object.assign(state, newState) to "force reactivity" because the AI saw that pattern in a 2019 Stack Overflow answer. Ask for "a profile page with a form to edit the user," and you get a defineComponent with data() { return { user: {} } }, an axios.get in mounted(), a methods: { save() { axios.put(...) } }, props declared as a string array, and a <template> that mutates this.user.name directly on input — Vue 3 syntax wrapped around Vue 2 thinking. It runs. It is not the Vue you should ship in 2026.

The fix is .cursorrules — one file in the repo that tells the AI what idiomatic modern Vue 3 + Nuxt 3 looks like. Eight rules below, each with the failure mode, the rule, and a before/after. Copy-paste .cursorrules at the end.

How Cursor Rules Work for Vue Projects

Cursor reads project rules from two locations: .cursorrules (a single file at the repo root, still supported) and .cursor/rules/*.mdc (modular files with frontmatter, recommended). For Vue 3 + Nuxt 3 I recommend modular rules so single-file-component conventions don't bleed into composable / store / server-route code, and so cross-cutting concerns like reactivity and SSR stay visible:

.cursor/rules/
  vue-components.mdc      # script setup, Composition API only
  vue-props-emits.mdc     # typed defineProps, defineEmits, defineModel
  vue-reactivity.mdc      # ref vs reactive, computed, watch, scope
  vue-pinia.mdc           # Pinia setup stores, storeToRefs, scoping
  vue-composables.mdc     # use*.ts, return refs, scope cleanup
  vue-nuxt-data.mdc       # useFetch / useAsyncData / useState / SSR
  vue-router.mdc          # typed routes, lazy load, definePageMeta
  vue-testing.mdc         # Vitest + Vue Testing Library + Playwright + MSW

Frontmatter controls activation: globs: ["**/*.vue", "composables/**/*.ts", "stores/**/*.ts", "server/**/*.ts", "nuxt.config.*"] with alwaysApply: false. Now the rules.

Rule 1: Composition API + `<script setup>` Only — No Options API, No Mixins, No `Vue.extend()`

Vue 3 supports both Options API and Composition API, and the Vue docs are deliberately neutral about which to pick. That neutrality is exactly why Cursor's training is split — half the examples in its corpus are export default { data, methods, computed }, half are <script setup> with ref and computed. Ask for a small component and you get whichever one the model happened to weight higher this prompt. Mixed Options/Composition in the same file is a maintenance nightmare: this means different things in different methods, lifecycle hooks fire in unpredictable orders, mixins inject names that collide silently with locally-defined refs. The rule: every component is <script setup lang="ts"> with the Composition API. No Options API. No mixins. Cross-component logic lives in composables/use*.ts.

The rule:

Every Vue component is a single-file component with `<script setup lang="ts">`.
There is no Options API in this codebase. The following are forbidden:
  - `export default { data() { return {...} } }` blocks.
  - `methods: {}`, `computed: {}`, `watch: {}` Options API blocks.
  - `mixins: [SomeMixin]` — replaced by composables.
  - `extends: Base` — replaced by composition + composables.
  - `Vue.extend({...})` — Vue 2 era, removed in modern code.
  - `defineComponent({ setup() { return {...} } })` with manual return —
    use `<script setup>` instead.

Every component file structure:
  <script setup lang="ts">
  // imports
  // defineProps / defineEmits / defineModel
  // composables (use*)
  // refs / computed / watch / lifecycle
  // local helpers
  </script>

  <template>
  <!-- template -->
  </template>

  <style scoped>
  /* style */
  </style>

`lang="ts"` is mandatory on every <script setup>. JS-only components are
not accepted.

Cross-component logic — anything that would have been a mixin in Vue 2 —
goes into `composables/use*.ts`. A composable returns refs, computeds,
and functions. Multiple components import and call the composable; each
gets its own reactive state instance.

Lifecycle hooks: `onMounted`, `onBeforeUnmount`, `onUpdated`, `onErrorCaptured`
imported from 'vue'. Never the Options API equivalents.

Template refs: `const root = useTemplateRef('root')` (Vue 3.5+) over the
older `const root = ref<HTMLElement | null>(null)` + `<div ref="root">`
pattern. The string identifier matches the template's `ref` attribute.

`<script setup>` exposes everything top-level to the template
automatically. Do NOT add a `defineExpose({...})` unless a parent needs
to call methods on this child via a template ref. When you do, defineExpose
is the explicit, narrow surface — never expose internals broadly.

Functional / render-function components only when JSX adds clarity (a
component that takes `as` prop and renders different elements). Default
is single-file component.

`useId()` (Vue 3.5+) for stable SSR-safe IDs. Never `Math.random()` or
incrementing counters for `for`/`id` attribute pairing.

Generic components: `<script setup lang="ts" generic="T extends {id: number}">`
to type a list-rendering component without losing inference.

Before — Options API + mixin, Vue 2 thinking in Vue 3 syntax:

<script lang="ts">
import Vue from 'vue';
import { LoggerMixin } from '@/mixins/logger';

export default Vue.extend({
  name: 'UserCard',
  mixins: [LoggerMixin],
  props: ['user', 'editable'],
  data() {
    return { editing: false, draft: { name: '' } };
  },
  computed: {
    displayName(): string { return this.draft.name || this.user.name; },
  },
  methods: {
    startEdit() { this.editing = true; this.draft.name = this.user.name; },
    save() { this.$emit('save', this.draft); this.editing = false; },
  },
  mounted() { this.log('mounted UserCard'); },
});
</script>

<template>
  <div>
    <p>{{ displayName }}</p>
    <button v-if="editable" @click="startEdit">Edit</button>
    <input v-if="editing" v-model="draft.name" />
    <button v-if="editing" @click="save">Save</button>
  </div>
</template>

Vue.extend is gone in Vue 3. Mixin injects log() invisibly. Props are untyped. $emit('save', ...) has no compile-time check.

After — <script setup>, typed everything, composable for logging:

<script setup lang="ts">
import { ref, computed } from 'vue';
import { useLogger } from '@/composables/useLogger';

interface User { id: number; name: string }

const props = defineProps<{ user: User; editable?: boolean }>();
const emit = defineEmits<{ save: [user: User] }>();

const { log } = useLogger('UserCard');

const editing = ref(false);
const draftName = ref('');

const displayName = computed(() => draftName.value || props.user.name);

function startEdit() {
  editing.value = true;
  draftName.value = props.user.name;
}

function save() {
  emit('save', { ...props.user, name: draftName.value });
  editing.value = false;
}

onMounted(() => log('mounted'));
</script>

<template>
  <div>
    <p>{{ displayName }}</p>
    <button v-if="editable" @click="startEdit">Edit</button>
    <input v-if="editing" v-model="draftName" />
    <button v-if="editing" @click="save">Save</button>
  </div>
</template>

Reactive intent is explicit. log is imported, not magic. save event is type-checked at call site. No prop mutation — draftName is a separate ref.

Rule 2: Typed `defineProps` + `defineEmits` + `defineModel` — Generics Syntax, Never Mutate Props

Vue's runtime props declaration (props: { title: { type: String, required: true } }) survives in Vue 3 but loses every advantage of TypeScript. Cursor will write defineProps(['title', 'count']) because that pattern compiles, then mutate props.count = props.count + 1 in a method because nothing told it not to. Vue 3.4+ added defineModel for two-way bindings — Cursor still emits the manual props.modelValue + emit('update:modelValue', x) boilerplate because that's what the older Vue 3 docs show. The rule: every prop and emit declaration uses the generics syntax for compile-time typing, defaults come from withDefaults, two-way bindings use defineModel, and props are immutable inside the child.

The rule:

Always use the generics syntax for defineProps and defineEmits:
  const props = defineProps<{ user: User; editable?: boolean }>();
  const emit = defineEmits<{
    save:   [user: User];
    cancel: [];
    delete: [id: number];
  }>();

Never the runtime arrays / objects:
  defineProps(['user', 'editable'])           // forbidden
  defineProps({ user: Object, editable: Boolean })  // forbidden

Defaults via withDefaults:
  const props = withDefaults(
    defineProps<{ size?: 'sm' | 'md' | 'lg'; disabled?: boolean }>(),
    { size: 'md', disabled: false }
  );

Required vs optional encoded in the type — `?` for optional. Don't repeat
required information at runtime.

Props are immutable. Inside the child, `props.foo = ...` is a bug.
  - Need a local mutable copy? `const draft = ref(structuredClone(props.foo))`.
  - Need to "edit" parent state? Emit an event the parent handles, OR
    use `defineModel()` for two-way binding (Vue 3.4+).
  - Need a derived value? `computed(() => transform(props.foo))`.

Two-way binding via defineModel (Vue 3.4+):
  // child
  const value = defineModel<string>({ required: true });
  // parent
  <ChildInput v-model="user.name" />

`defineModel` returns a writable ref. Reading it is `value.value`,
writing is `value.value = newValue`. The framework wires up the
emit. Multiple v-models: `defineModel<string>('first')`,
`defineModel<string>('last')`, used as `v-model:first` / `v-model:last`.

Emit signatures use the tuple form:
  defineEmits<{ change: [value: string, index: number] }>();
The function call signature `(e: 'change', value: string, index: number)
=> void` is also valid but more verbose. Tuple form preferred.

Slot props are typed via defineSlots (Vue 3.3+):
  defineSlots<{
    default(props: { user: User }): any;
    actions(props: { onSave: () => void }): any;
  }>();
Avoid `<template #default="{ user }">` with implicit any — defineSlots
gives the consumer compile-time inference.

Validators (runtime): only when type alone can't express the constraint
(an enum that the API also validates). Otherwise type narrowing in the
parent is the contract.

`v-model` on native inputs uses `defineModel`. Custom input components
expose `defineModel` for the parent to bind. NEVER manage modelValue via
props + emit by hand — defineModel is the only correct path post-Vue 3.4.

Before — array props, prop mutation, manual v-model emit:

<script setup>
const props = defineProps(['modelValue', 'maxLength']);
const emit = defineEmits(['update:modelValue']);

function onInput(e) {
  let v = e.target.value;
  if (v.length > props.maxLength) v = v.slice(0, props.maxLength);
  props.modelValue = v;                    // mutating prop, silently broken
  emit('update:modelValue', v);
}
</script>

<template>
  <input :value="modelValue" @input="onInput" />
</template>

Untyped. Mutates the prop. Manually wires up v-model. No lang="ts".

After — typed defineModel, immutable props, derived defaults:

<script setup lang="ts">
import { computed } from 'vue';

const props = withDefaults(
  defineProps<{ maxLength?: number }>(),
  { maxLength: 100 }
);

const value = defineModel<string>({ required: true });

function onInput(e: Event) {
  const v = (e.target as HTMLInputElement).value;
  value.value = v.slice(0, props.maxLength);
}

const remaining = computed(() => props.maxLength - value.value.length);
</script>

<template>
  <input :value="value" @input="onInput" />
  <small>{{ remaining }} characters remaining</small>
</template>

Compile-time typed. defineModel handles the v-model contract. props.maxLength is read-only, default applied via withDefaults. remaining derives instead of duplicating state.

Rule 3: Reactivity Discipline — `ref` By Default, `reactive` Rarely, `computed` For Derivations

Vue 3's reactivity primitives (ref, reactive, computed, watch, watchEffect, shallowRef, shallowReactive, toRefs, toRef, effectScope) are powerful and easily misused. Cursor's failure mode is consistent: it picks reactive({...}) for every object because it "looks cleaner" (no .value), then destructures it (const { count } = state), loses reactivity, and adds a watch(state, ..., { deep: true }) to compensate. Or it reaches for Object.assign(state, newState) because someone on Stack Overflow said that "forces reactivity." The rule: prefer ref for everything (primitives and objects), use reactive only for objects you mutate in place (and carefully), computed for derivations, watch only when a side effect needs to fire on a specific change, shallowRef / shallowReactive for large frozen data.

The rule:

Default to `ref` for every piece of state — primitives, objects, arrays.
  const count = ref(0);
  const user  = ref<User | null>(null);
  const items = ref<Item[]>([]);

Reading: `count.value`. Writing: `count.value = n` or
`items.value.push(...)`. The `.value` is annoying for ten minutes; the
clarity is forever.

`reactive` is reserved for cases where you genuinely want a mutable
object identity that's passed around:
  - A long-lived store-like object kept across function calls.
  - A form-state object passed to multiple sibling helpers.
For most components, `ref<T>(...)` is the right call.

Reactive objects lose reactivity when destructured:
  const state = reactive({ count: 0 });
  const { count } = state;   // count is now a NUMBER, not reactive
Use `toRefs(state)` to destructure as refs:
  const { count } = toRefs(state);

`computed` for any derived value. Two rules:
  1. A `computed` is read-only by default; if you need write, use the
     getter/setter form: `computed({ get, set })`.
  2. A `computed` does NOT have side effects. Anything async, anything
     that mutates, anything that calls fetch — that's `watch` or
     `watchEffect`, not `computed`.

`watch` is for explicit reactions to identified sources:
  watch(user, (newUser, oldUser) => { ... });
  watch([userId, filter], ([id, f]) => { ... });
  watch(() => props.user.id, (id) => { ... });   // getter form

`watchEffect` is for "run this effect, track whatever it reads":
  watchEffect(() => { fetchPosts(filter.value, page.value); });
Use `watch` when you need oldValue or want explicit deps. Use
`watchEffect` when deps would be tedious to enumerate.

`{ deep: true }` is a code smell. If you need deep, your data shape is
probably wrong. Acceptable cases: arrays of objects where you legitimately
care about mutation in any element. Bad cases: "the test only passed with
deep" — fix the data, not the watch.

`{ immediate: true }` runs the watcher once on setup. Use it; do not
duplicate the body in `onMounted`.

`shallowRef` / `shallowReactive` for large objects whose internals don't
need fine-grained tracking (a parsed AST, a chart dataset, a CodeMirror
instance). Reactivity only triggers on the top-level reference.

`toRef` / `toRefs` at composable boundaries — return refs from
composables so consumers can destructure without losing reactivity:
  function useUser() {
    const state = reactive({ name: '', age: 0 });
    return toRefs(state);
  }
  // consumer
  const { name, age } = useUser();   // both refs

Never: `Object.assign(state, newState)` to "force reactivity". If a ref
isn't updating, the cause is destructuring or aliasing — fix that.

Effect scope (effectScope, onScopeDispose) for composables that create
watchers and need to clean up when the consumer unmounts. The framework
handles this for component-scoped effects; manual scopes are for shared
composables (singletons used by multiple components).

`markRaw` for objects you explicitly DON'T want to be reactive (a Class
instance from a third-party SDK, a Map you're using as a cache).
Wrapping a Class in reactive is a perf trap — the proxy intercepts every
property access.

Before — reactive abuse, destructure breaks tracking, deep watch hammer:

<script setup>
import { reactive, watch } from 'vue';

const state = reactive({ count: 0, user: { name: 'A' } });
const { count, user } = state;          // both lose reactivity

watch(state, (newState) => {
  fetchSomething(newState.count);
}, { deep: true });                     // fires on every nested change
</script>

<template>
  <p>{{ count }} {{ user.name }}</p>     <!-- never updates -->
</template>

Destructure broke the link. Deep watch fires on every keystroke. Template renders stale values forever.

After — refs, computed for derivation, focused watch:

<script setup lang="ts">
import { ref, computed, watch } from 'vue';

const count = ref(0);
const user  = ref({ name: 'A' });

const greeting = computed(() => `Hi, ${user.value.name}! Count: ${count.value}`);

watch(count, (n) => fetchSomething(n));    // fires only when count changes

function increment() { count.value++; }
</script>

<template>
  <p>{{ greeting }}</p>
  <button @click="increment">+</button>
</template>

Reactivity is intact. The watch fires only on the dependency that matters. The derivation is explicit.

Rule 4: Pinia For State — Setup Stores, `storeToRefs`, Scoped Per Feature, Never Vuex

Pinia is the official Vue state-management library since 2022; Vuex is in maintenance. Cursor still emits Vuex 3 modules with state / mutations / actions / getters and string-typed commit('SET_USER', payload) calls because that's what most of the corpus contains. When it does pick Pinia, it defaults to the Options-style defineStore('id', { state, getters, actions }) because the Pinia docs show that first — losing the cleaner setup syntax and TypeScript inference. The rule: every store uses defineStore('id', () => { ... }) (setup syntax), one store per feature scope, getters via computed, actions are plain functions, consumers destructure with storeToRefs to preserve reactivity.

The rule:

State management uses Pinia. Vuex (any version) is forbidden in new
code; legacy Vuex modules are migrated on touch.

Every store uses the SETUP syntax:
  // stores/user.ts
  import { defineStore } from 'pinia';
  import { ref, computed } from 'vue';

  export const useUserStore = defineStore('user', () => {
    const user = ref<User | null>(null);
    const isLoggedIn = computed(() => user.value !== null);

    async function login(email: string, password: string) {
      user.value = await api.login(email, password);
    }
    function logout() { user.value = null; }

    return { user, isLoggedIn, login, logout };
  });

Reasons over the Options syntax:
  - Type inference is automatic — no need to type state shape twice.
  - State, getters, actions live next to each other, easy to reason about.
  - Composables can be called inside the store's setup function.

Store IDs are short, lowercase, kebab-case if multi-word: 'user',
'cart', 'product-search'. Match the file name (`stores/user.ts` →
'user').

Consumers destructure with storeToRefs to keep refs reactive:
  import { storeToRefs } from 'pinia';
  const userStore = useUserStore();
  const { user, isLoggedIn } = storeToRefs(userStore);   // refs
  const { login, logout }    = userStore;                // functions ok

NEVER `const { user } = userStore` — that loses reactivity for refs.

One store per FEATURE, not one mega-store. A 500-line store with 12
unrelated state slices is a sign you need to split:
  stores/user.ts          (auth, profile)
  stores/cart.ts          (cart items, totals)
  stores/products.ts      (product catalog cache)
  stores/notifications.ts (toast queue)

Stores can call each other — `useCartStore()` inside `useUserStore`'s
logout to clear the cart. Pinia handles ordering.

Mutations are direct: `user.value = newUser`. There is no Vuex-style
mutation/action distinction. If you need an audit trail, use Pinia's
`$subscribe` or a plugin.

Async work happens inside actions (regular async functions). Components
await the action and render based on the resulting state.

Persisted state: pinia-plugin-persistedstate for localStorage / cookie
persistence. Configure per-store, not globally.

SSR (Nuxt 3): `useState` for ad-hoc cross-component state, Pinia for
structured store state. Pinia auto-integrates with Nuxt 3 via @pinia/nuxt
module — state is serialized in the SSR payload and hydrated on the
client.

Testing: `createPinia()` per test, set as active via `setActivePinia`.
Stores are plain Composition API functions; they unit-test trivially.

Plugins for cross-cutting concerns (logging, persistence) — never
copy-paste the same logic into every store.

Before — Vuex-style options store, destructure loses reactivity:

// stores/cart.ts
import { defineStore } from 'pinia';

export const useCartStore = defineStore('cart', {
  state: () => ({ items: [] as CartItem[], coupon: null as string | null }),
  getters: { count: (s) => s.items.length },
  actions: {
    add(item: CartItem) { this.items.push(item); },
    SET_COUPON(c: string) { this.coupon = c; },
  },
});

<script setup>
const cart = useCartStore();
const { items, count } = cart;            // both lose reactivity
</script>

Mutation-like names (SET_COUPON) are Vuex residue. Consumer destructure breaks the bindings.

After — setup store, storeToRefs, scoped, typed:

// stores/cart.ts
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';

export interface CartItem { id: number; productId: number; qty: number; price: number }

export const useCartStore = defineStore('cart', () => {
  const items  = ref<CartItem[]>([]);
  const coupon = ref<string | null>(null);

  const count    = computed(() => items.value.length);
  const subtotal = computed(() => items.value.reduce((s, i) => s + i.price * i.qty, 0));

  function add(item: CartItem) { items.value.push(item); }
  function setCoupon(code: string | null) { coupon.value = code; }
  function clear() { items.value = []; coupon.value = null; }

  return { items, coupon, count, subtotal, add, setCoupon, clear };
});

<script setup lang="ts">
import { storeToRefs } from 'pinia';
import { useCartStore } from '@/stores/cart';

const cartStore = useCartStore();
const { items, count, subtotal } = storeToRefs(cartStore);
const { add, clear } = cartStore;
</script>

State, getters, actions co-located. Consumers preserve reactivity. No Vuex pretense.

Rule 5: Composables — Extract Reusable Logic Into `composables/use*.ts`, Return Refs, Cleanup With `onScopeDispose`

Composables are the Composition API's answer to mixins, render-props, and HOCs all at once. Cursor often inlines the same logic across three components instead of extracting (because that's the path of least resistance for the next-token predictor), or extracts it into a function that returns plain values instead of refs (losing reactivity at the consumer), or wires up an event listener inside onMounted and forgets the matching onBeforeUnmount. The rule: cross-component logic is a composable in composables/use*.ts, every composable returns refs / computeds, cleanup uses onScopeDispose / tryOnScopeDispose so it works inside both component and effect-scope contexts, and you reach for VueUse before hand-rolling browser APIs.

The rule:

Cross-component logic lives in `composables/use*.ts` (Nuxt 3 auto-imports
this directory). Naming: always `use<Thing>`, lowerCamelCase suffix.
  composables/useDebouncedRef.ts
  composables/useUserPreferences.ts
  composables/useAsyncTask.ts

A composable is a plain function that uses Composition API primitives
(ref, computed, watch, lifecycle hooks). It returns an object of refs
and functions. Each call creates fresh state — composables are
factories, not singletons.

Return refs, NOT plain values:
  // good
  export function useCounter(initial = 0) {
    const count = ref(initial);
    function increment() { count.value++; }
    return { count, increment };
  }
  // bad — caller can't watch count
  export function useCounter(initial = 0) {
    let count = initial;
    return { count, increment: () => count++ };
  }

If you need a singleton (one global instance across the app) — wrap in
an outer scope or use Pinia. Don't fake singleton-ness with
module-level refs unless you understand the SSR implications (cross-
request leakage). For SSR-safe shared state, use `useState` (Nuxt 3) or
a Pinia store.

Cleanup via onScopeDispose / tryOnScopeDispose, not just
onBeforeUnmount:
  import { onScopeDispose } from 'vue';
  export function useEventListener(target, event, handler) {
    target.addEventListener(event, handler);
    onScopeDispose(() => target.removeEventListener(event, handler));
  }

`tryOnScopeDispose` from VueUse is safer when the composable might be
called outside a setup context — it no-ops instead of throwing.

`effectScope()` for composables that manage a group of effects you may
need to dispose together (e.g. a long-lived shared composable used by
the app shell):
  const scope = effectScope();
  scope.run(() => { /* refs, watchers */ });
  // later
  scope.stop();

Prefer VueUse over hand-rolling browser APIs. `useEventListener`,
`useIntersectionObserver`, `useLocalStorage`, `useResizeObserver`,
`useDebouncedRef`, `useThrottle`, `useDark`, `useClipboard`, `useFetch`
(VueUse's, distinct from Nuxt's) — all already cleanup-correct, all
SSR-aware, all TypeScript-typed. Reach for them first.

Composables can call other composables. Inversion of control: a
composable that does API work should accept its dependencies (a
fetcher) rather than importing the global one — easier to test.

Async in composables: return `{ data, error, pending, refresh }` shape
matching Nuxt's useAsyncData / useFetch. Consumers know what to expect.

Don't over-extract. A 4-line piece of logic used in one component is
not a composable — it's a function. Extract on the second use, not the
first.

Before — inline logic, plain return, missing cleanup:

<script setup>
import { ref, onMounted } from 'vue';

const width = ref(window.innerWidth);
onMounted(() => {
  window.addEventListener('resize', () => { width.value = window.innerWidth; });
  // never removed — listener leaks across HMR + unmount
});
</script>

Each component duplicates this. The listener leaks. Crashes during SSR (no window on the server).

After — VueUse composable, SSR-safe, cleanup automatic:

<script setup lang="ts">
import { useWindowSize } from '@vueuse/core';

const { width, height } = useWindowSize();
</script>

<template>
  <p>{{ width }} × {{ height }}</p>
</template>

Or for a reusable pattern not in VueUse:

// composables/useOnlineStatus.ts
import { ref } from 'vue';
import { useEventListener } from '@vueuse/core';

export function useOnlineStatus() {
  const online = ref(typeof navigator !== 'undefined' ? navigator.onLine : true);
  useEventListener(window, 'online',  () => { online.value = true; });
  useEventListener(window, 'offline', () => { online.value = false; });
  return { online };
}

SSR-safe initial value. Listeners cleaned up automatically by VueUse. Reusable from any component or composable.

Rule 6: Nuxt 3 Data Fetching & SSR — `useFetch` / `useAsyncData` With Explicit Keys, `useState` For Shared State

Nuxt 3's data-fetching helpers (useFetch, useAsyncData, useLazyFetch, useLazyAsyncData, $fetch, useState) exist because plain fetch in <script setup> causes the most common Nuxt bug: the request fires on the server during SSR, the result isn't included in the hydration payload, and then it fires again on the client. Cursor reaches for plain fetch constantly — that's what its training corpus is full of. It also gets the auto-generated cache keys wrong (Nuxt derives a key from the file/component, but identical calls in different places without explicit keys collide), or omits transform / pick and ships the entire API payload through hydration just to render three fields. The rule: every server-side data read uses useFetch or useAsyncData with an explicit key, payload-shaping via transform and pick, $fetch only inside event handlers, useState for SSR-safe shared state.

The rule:

Server-side data fetching uses useFetch / useAsyncData. Every call has
an explicit `key`:
  const { data: posts } = await useFetch('/api/posts', { key: 'posts-list' });
  const { data: post  } = await useAsyncData(
    `post:${slug.value}`,
    () => $fetch(`/api/posts/${slug.value}`)
  );

Without an explicit key, Nuxt auto-derives one from the file location.
Two identical calls in the same file collide. Always pass `key`.

useFetch:
  - `useFetch(url, options)` — wraps $fetch with SSR awareness.
  - Returns `{ data, pending, error, refresh, status }` — refs.
  - Runs on server during SSR, hydrates result on client. No double-fetch.
  - Watches reactive sources in `url` or `options.query` automatically;
    refetches on change.

useAsyncData:
  - `useAsyncData(key, asyncFn, options)` — for any async work, not just
    HTTP.
  - Use when fetching from a JS SDK / direct DB call (in server routes)
    where useFetch doesn't apply.

Client-only fetches:
  - `useFetch(url, { server: false })` for data needed only after
    hydration (per-user dashboards where SSR doesn't help).
  - `useLazyFetch(url, options)` returns immediately with `pending=true`,
    UI shows skeleton, data populates when ready. Good for non-critical
    sections.

Plain `fetch(url)` and bare `$fetch(url)` in `<script setup>` are bugs.
They run twice (SSR + hydration) and the SSR result is discarded.
Allowed only:
  - Inside event handlers (`onClick`, `onSubmit`) — user-initiated calls.
  - Inside server routes (`server/api/*.ts`).
  - Inside Pinia actions / composables that are never called during
    initial render.

Payload shaping:
  - `transform: (data) => data.items` — strip wrapper objects.
  - `pick: ['id', 'title', 'slug']` — keep only fields used by the UI.
  - These run on the server BEFORE serialization; the wire payload
    shrinks proportionally.

Cache keys for invalidation:
  - `refresh()` re-runs the fetch.
  - `clearNuxtData('posts-list')` for explicit cache busting from
    elsewhere.

Server routes (server/api/*.ts):
  - One handler per route file: `export default defineEventHandler(...)`.
  - Validate input with Zod / valibot at the top.
  - Return typed responses; Nuxt infers them on the client.
  - For DB access, import from `~/server/utils/db.ts` — never expose
    client-side.

useState for SSR-safe shared state:
  - `const counter = useState('counter', () => 0);` — SSR-rendered,
    hydrated, shared across components.
  - Use for cross-component state that doesn't deserve a Pinia store.
  - Module-level `const state = ref(0)` is an SSR LEAK across requests.
  - Always provide an initializer function so SSR isolation works.

Error handling:
  - `useFetch` errors populate `error.value`; render an error UI when it's
    truthy.
  - For 4xx/5xx that should produce an error page, throw
    `createError({ statusCode: 404, statusMessage: 'Not found' })`.
  - Wrap critical server work in try/catch within the asyncFn, then
    surface a typed error.

`onMounted(() => fetchPosts())` is a Nuxt anti-pattern. It bypasses
SSR, causes layout shift, and breaks SEO. Move into `useFetch`
without `server: false` for SSR rendering.

Hydration mismatches:
  - Don't render `Date.now()` / `Math.random()` directly. Use `useId`
    for stable IDs; compute time-relative values inside `<ClientOnly>`.
  - `useNuxtApp().payload.serverRendered` for explicit server checks.

Before — plain fetch in script setup, no SSR, double-fetch, no key:

<script setup>
import { ref, onMounted } from 'vue';

const posts = ref([]);
onMounted(async () => {
  const r = await fetch('/api/posts');
  posts.value = await r.json();
});
</script>

<template>
  <ul><li v-for="p in posts" :key="p.id">{{ p.title }}</li></ul>
</template>

Empty list during SSR. Flashes empty on hydration. Refetches on every navigation. SEO crawlers see nothing.

After — useFetch with key, transform, error UI:

<script setup lang="ts">
interface Post { id: number; title: string; slug: string }

const { data: posts, error, pending, refresh } = await useFetch<Post[]>(
  '/api/posts',
  {
    key: 'posts-list',
    transform: (raw: { items: Post[] }) => raw.items,
    pick: ['id', 'title', 'slug'] as never,    // type assertion for pick
  }
);
</script>

<template>
  <p v-if="pending">Loading…</p>
  <p v-else-if="error" role="alert">
    Failed to load posts. <button @click="refresh">Retry</button>
  </p>
  <ul v-else>
    <li v-for="p in posts ?? []" :key="p.id">
      <NuxtLink :to="`/posts/${p.slug}`">{{ p.title }}</NuxtLink>
    </li>
  </ul>
</template>

Server-rendered first paint. No double-fetch. Wire payload shrunk via pick. Error/loading UIs explicit.

Rule 7: Vue Router 4 With Typed Routes — File-Based Or Unplugin-Vue-Router, `definePageMeta` In Nuxt

Vue Router 4 in raw form is string-typed: <RouterLink to="/users/42">, router.push({ name: 'user-detail', params: { id: '42' } }) where name and params are both string. Cursor will type-check the JSX wrapping and miss that the route name is a typo until the user clicks the link in production. unplugin-vue-router (and Nuxt 3's built-in equivalent) generates types from the file system so route names, params, and query parsing are compile-time checked. The rule: routes are file-based or registered via unplugin-vue-router for type safety, navigation uses the typed <RouterLink :to="{name: '...'}"> form, components are lazy-loaded via dynamic imports, route guards live in dedicated middleware files, definePageMeta configures layout/middleware/auth in Nuxt.

The rule:

Routes are FILE-BASED:
  - Nuxt 3: pages/ directory (built-in).
  - Vite + Vue: unplugin-vue-router with src/pages/.
  - Vue CLI legacy: migrate to Vite.

The plugin generates typed route names and params. Import from
'vue-router/auto-routes' (unplugin) or use Nuxt's typed
`navigateTo(...)`.

Navigation uses object form with named routes, not string paths:
  // good
  <RouterLink :to="{ name: 'user-detail', params: { id: user.id }}">…</RouterLink>
  router.push({ name: 'user-detail', params: { id: 42 }});
  navigateTo({ name: 'user-detail', params: { id: 42 }});  // Nuxt

  // bad — typos pass typecheck
  <RouterLink :to="`/users/${user.id}`">…</RouterLink>
  router.push(`/users/${id}`);

useRoute() / useRouter() in <script setup>; never `this.$route` /
`this.$router` (that's Options API).

Route params are typed once routes are typed:
  const route = useRoute('user-detail');
  const id = route.params.id;   // string, narrowed by route name

Query params are validated with Zod at the top of the page component
that uses them — coerce strings to the types you actually want.

Lazy-load route components with dynamic imports (file-based routing
does this for you). For manual route definitions:
  { path: '/admin', component: () => import('./pages/Admin.vue') }
This keeps the initial bundle small.

Route guards: GLOBAL guards in `router.beforeEach` registered in the
router setup (or `middleware/` in Nuxt). PER-ROUTE guards via
`beforeEnter` in route definitions. NEVER `beforeRouteEnter` /
`beforeRouteLeave` inline in a component — that's Options API and
breaks TypeScript inference in <script setup>.

Nuxt middleware: `middleware/auth.ts` registered globally or via
`definePageMeta({ middleware: 'auth' })`:
  // middleware/auth.ts
  export default defineNuxtRouteMiddleware((to) => {
    const user = useUserStore();
    if (!user.isLoggedIn) return navigateTo('/login');
  });

definePageMeta is the ONLY place to set per-page layout, middleware,
keepalive, transition, or pageTransition:
  definePageMeta({
    layout: 'admin',
    middleware: ['auth', 'admin'],
    pageTransition: { name: 'fade' },
  });

Programmatic navigation:
  await navigateTo({ name: 'user-detail', params: { id }});
  In Nuxt, `navigateTo` is preferred over `useRouter().push` because it
  also handles redirects in middleware.

External links: `navigateTo('https://...', { external: true })`. Without
`external: true`, Nuxt will treat external URLs as relative.

Scroll behavior: configured once in `app/router.options.ts` (Nuxt) or
the router setup. Never per-component.

Query-driven UI state (search, filters):
  - Read via `route.query.q`, parsed/validated.
  - Update via `router.replace({ query: { ...route.query, q: value }})`
    — `replace` not `push` to avoid bloating history.
  - Debounce the input handler that calls replace().

`<NuxtLink>` (Nuxt) and `<RouterLink>` (raw Vue Router) — never
`<a href="/internal">` for internal nav, that triggers a full reload
and skips prefetching.

Prefetching: `<NuxtLink>` prefetches by default in production. Disable
with `prefetch="false"` for very large rarely-visited pages.

Before — string paths, inline guard, no types, full reload links:

<script setup>
import { useRouter } from 'vue-router';
const router = useRouter();

function goToUser(id) {
  router.push(`/users/${id}`);          // typo passes
}

// Options-API guard mixed into setup component
onBeforeRouteEnter((to, from, next) => {
  if (!isAuthed()) next('/login');
  else next();
});
</script>

<template>
  <a href="/dashboard">Dashboard</a>     <!-- full page reload -->
</template>

String paths fragile. Inline guard breaks types. <a> does a full reload, killing performance.

After — typed routes, middleware file, NuxtLink, named navigation:

<script setup lang="ts">
definePageMeta({
  middleware: 'auth',
  layout: 'default',
});

const route = useRoute('users-id');
const id = computed(() => Number(route.params.id));

async function goToOrders() {
  await navigateTo({ name: 'users-id-orders', params: { id: id.value }});
}
</script>

<template>
  <NuxtLink :to="{ name: 'dashboard' }">Dashboard</NuxtLink>
  <button @click="goToOrders">View orders</button>
</template>

// middleware/auth.ts
export default defineNuxtRouteMiddleware(() => {
  const user = useUserStore();
  if (!user.isLoggedIn) return navigateTo('/login');
});

Route names checked at compile time. Middleware reusable. Navigation type-safe. Internal links use NuxtLink with prefetch.

Rule 8: Testing — Vitest For Units, `@vue/test-utils` + Vue Testing Library For Components, Playwright For E2E, MSW For Mocks

Vue's testing story consolidated around Vitest in 2023 — fast, ESM-native, Vite-integrated, Jest-compatible API. Component tests use @vue/test-utils for low-level mount control combined with Vue Testing Library for accessible assertions. End-to-end is Playwright (better than Cypress for SSR-driven Nuxt apps). API mocking is MSW so the same handlers cover unit tests (Node) and Playwright (browser). Cursor defaults to Jest + @vue/test-utils.shallowMount + class-name selectors — workable, but every refactor breaks the assertions. The rule: Vitest, full mount with role-based selectors, MSW for HTTP, Playwright for the user-facing flows, no shallow mount as the default.

The rule:

Unit / component tests: Vitest. Jest is legacy and migrated on touch.
  - jsdom environment for component tests, node for pure-logic tests.
  - vite.config.ts (or vitest.config.ts) configures the same Vue
    plugin, aliases, and CSS handling as production.
  - setupFiles include MSW handlers + Testing Library extends.

Component tests: prefer Vue Testing Library on top of @vue/test-utils.
  - `mount(Component, { props, slots, global: {...} })` from @vue/test-
    utils — not `shallowMount`. Shallow mounts hide integration bugs
    and force you to mock children that didn't need mocking.
  - User interactions via @testing-library/user-event (`await
    user.click(...)`, `await user.type(...)`). NEVER fireEvent for
    new tests.
  - Selectors by ROLE / accessible name:
      screen.getByRole('button', { name: /save/i })
      screen.getByLabelText('Email')
      screen.getByText(/welcome/i)
  - Avoid class selectors and data-testid except as last resort.

`flushPromises` from @vue/test-utils for awaiting reactive flushes
between user actions and assertions — Vitest's `await nextTick()` works
for one tick, but a chain of computed → watch → render needs
flushPromises.

Snapshot tests: sparingly, for stable presentational components
(empty states, icons). Snapshots of complex stateful components churn
on every refactor and add no signal.

Composables: tested as pure functions. No mount needed.
  import { useCounter } from '@/composables/useCounter';
  test('increments', () => {
    const { count, increment } = useCounter();
    increment();
    expect(count.value).toBe(1);
  });

For composables that use lifecycle hooks (`onMounted`), wrap in a
test component:
  import { mount } from '@vue/test-utils';
  const TestComponent = defineComponent({
    setup() { return useThing(); },
    template: '<div />',
  });

Pinia stores: `setActivePinia(createPinia())` in beforeEach. Then call
the store and assert directly. No mount required.

API mocks: MSW (msw) handlers shared between Vitest (node worker) and
Playwright (browser worker). Handlers live in `tests/mocks/handlers.ts`.

Server-side rendering tests: Nuxt provides `@nuxt/test-utils/e2e`. Use
`setup({ host, browser })` to spin up an isolated Nuxt app per test.
For unit-style tests, `mountSuspended` mounts Nuxt-aware components
(useFetch / useAsyncData / useState all work).

Playwright:
  - playwright.config.ts with projects for chromium / firefox / webkit.
  - baseURL pointed at http://localhost:3000.
  - webServer starts `nuxt dev` (or built `node .output/server/index`).
  - Role-based selectors from `page.getByRole`, `page.getByLabel`.
  - `expect(locator).toBeVisible()` over `toHaveCount(1)` — captures
    intent.
  - `page.waitForResponse(/api\/posts/)` when testing streaming /
    progressive enhancement.

Vue Router in tests: createRouter + createMemoryHistory; install via
`global.plugins`. Don't navigate via `router.push` and assert on
Document — use Playwright for routing flows.

Storybook 8 for visual catalogue + component-level interaction tests.
The Storybook test runner exports stories as Playwright tests; gives
you visual regression for free.

Coverage:
  - composables/, stores/, utils/: >90%.
  - components/: >70% combined (component + e2e).
  - Every store action: happy + error path test minimum.

CI:
  - Vitest on every PR (parallelized).
  - Playwright on every PR with sharding by test file.
  - Storybook test runner on every PR for changed stories.

Before — shallowMount, class selectors, fireEvent, no MSW:

import { shallowMount } from '@vue/test-utils';
import UserCard from '@/components/UserCard.vue';

test('renders name', () => {
  const wrapper = shallowMount(UserCard, {
    propsData: { user: { name: 'Ada' }},  // Vue 2 syntax
  });
  expect(wrapper.find('.name').text()).toBe('Ada');
  wrapper.find('.edit-btn').trigger('click');
  expect(wrapper.vm.editing).toBe(true);
});

Brittle CSS selector. Reaches into private vm.editing. Vue 2 propsData. Children stubbed and missing integration bugs.

After — Vitest + RTL + MSW + role-based assertions:

// tests/mocks/handlers.ts
import { http, HttpResponse } from 'msw';
export const handlers = [
  http.get('/api/users/:id', ({ params }) =>
    HttpResponse.json({ id: Number(params.id), name: 'Ada Lovelace' })
  ),
];

// vitest.setup.ts
import { setupServer } from 'msw/node';
import { handlers } from './tests/mocks/handlers';
import '@testing-library/jest-dom/vitest';

const server = setupServer(...handlers);
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

// components/UserCard.test.ts
import { render, screen } from '@testing-library/vue';
import userEvent from '@testing-library/user-event';
import UserCard from './UserCard.vue';

test('user can edit and save the name', async () => {
  const user = userEvent.setup();
  const onSave = vi.fn();

  render(UserCard, {
    props: { user: { id: 1, name: 'Ada' }, editable: true },
    attrs: { onSave },
  });

  expect(screen.getByText('Ada')).toBeInTheDocument();
  await user.click(screen.getByRole('button', { name: /edit/i }));

  const input = screen.getByRole('textbox');
  await user.clear(input);
  await user.type(input, 'Ada L.');
  await user.click(screen.getByRole('button', { name: /save/i }));

  expect(onSave).toHaveBeenCalledWith(expect.objectContaining({ name: 'Ada L.' }));
});

// e2e/profile.spec.ts
import { test, expect } from '@playwright/test';

test('profile edit flow', async ({ page }) => {
  await page.goto('/profile');
  await page.getByRole('button', { name: /edit/i }).click();
  await page.getByLabel('Name').fill('Ada Lovelace');
  await page.getByRole('button', { name: /save/i }).click();
  await expect(page.getByText('Profile saved')).toBeVisible();
});

Role-based selectors survive markup refactors. MSW handlers are shared. Component test exercises real interaction via user-event. Playwright covers the full SSR flow.

The Complete `.cursorrules` File

Drop this in the repo root. Cursor and Claude Code both pick it up.

# Vue 3 + Nuxt 3 — Production Patterns

## Components
- Every component is <script setup lang="ts"> Composition API.
- No Options API: no data()/methods/computed/watch blocks.
- No mixins, no Vue.extend(), no extends. Use composables.
- Lifecycle via onMounted/onBeforeUnmount/onUpdated imported from 'vue'.
- useTemplateRef() (3.5+) over manual ref + DOM ref attribute.
- defineExpose only when a parent must call child methods.
- useId() for stable SSR-safe IDs; never Math.random().
- Generic components via <script setup lang="ts" generic="T">.

## Props, Emits, Models
- Always defineProps<{...}>() generics syntax; never runtime arrays.
- withDefaults for optional defaults.
- defineEmits<{ event: [args] }>() tuple form.
- Props are immutable inside the child — never mutate props.foo.
- Two-way bindings via defineModel<T>() (Vue 3.4+); never manual
  modelValue/update:modelValue boilerplate.
- defineSlots<{...}>() for typed slot props.

## Reactivity
- ref by default for primitives, objects, arrays.
- reactive only for long-lived mutable objects passed around.
- toRefs / toRef at composable boundaries to keep destructured refs
  reactive.
- computed for derivations (read-only by default; getter/setter form
  for writable).
- watch for explicit reactions; watchEffect for "track whatever I read".
- { deep: true } is a code smell — fix the data shape.
- { immediate: true } over duplicating body in onMounted.
- shallowRef / shallowReactive for large frozen data.
- markRaw for class instances / non-reactive objects.
- Never Object.assign(state, ...) to "force reactivity" — fix
  destructuring instead.

## Pinia
- defineStore('id', () => { ... }) setup syntax only.
- One store per feature scope; no mega-stores.
- storeToRefs() when destructuring state/getters.
- Plain destructure for actions (functions stay reactive without).
- Stores can call other stores; Pinia handles ordering.
- pinia-plugin-persistedstate for selective persistence.
- @pinia/nuxt module for SSR-safe store hydration.
- Vuex (any version) is forbidden in new code.

## Composables
- composables/use*.ts (Nuxt auto-imports).
- Return refs / computeds / functions; never plain values.
- Cleanup via onScopeDispose / tryOnScopeDispose, not just
  onBeforeUnmount.
- effectScope() for shared composables that need group disposal.
- VueUse first; hand-roll only when not covered.
- Composables are factories (fresh state each call), not singletons.
- Singletons via Pinia or useState (Nuxt), never module-level refs
  (SSR leak).
- Async composables return { data, error, pending, refresh } shape.

## Nuxt 3 Data & SSR
- useFetch / useAsyncData with EXPLICIT key on every call.
- transform / pick to shrink the SSR payload.
- $fetch only inside event handlers and server routes.
- Plain fetch() in <script setup> is a bug (double-fetch).
- useState('key', () => initial) for SSR-safe shared state.
- Module-level refs leak across SSR requests — never.
- server: false for client-only fetches; useLazyFetch for non-critical.
- Validate input in server/api/*.ts with Zod / valibot.
- createError({ statusCode, statusMessage }) for error pages.
- Don't render Date.now()/Math.random() outside <ClientOnly>.

## Routing
- File-based: pages/ (Nuxt) or unplugin-vue-router (Vite).
- Navigation: object form with named routes, never string paths.
- useRoute('route-name') for typed params.
- Lazy-load route components via dynamic imports.
- Global guards in router.beforeEach or middleware/*.ts.
- definePageMeta for per-page layout / middleware / transition.
- navigateTo over useRouter().push in Nuxt (handles middleware
  redirects).
- <NuxtLink> / <RouterLink> for internal links, never <a href>.
- Query-driven UI state via router.replace + Zod-validated query.

## Testing
- Vitest for units / components.
- @vue/test-utils mount (NOT shallowMount) + Vue Testing Library.
- Role-based selectors; data-testid is a last resort.
- @testing-library/user-event over fireEvent.
- flushPromises for chained reactive updates.
- MSW handlers shared between Vitest (node) and Playwright (browser).
- Composables tested as pure functions; lifecycle ones via wrapper
  component.
- Pinia stores tested with createPinia + setActivePinia per test.
- @nuxt/test-utils mountSuspended for Nuxt-aware components.
- Playwright for e2e with chromium/firefox/webkit projects.
- Storybook 8 + test runner for visual regression.
- Snapshots only for stable presentational components.
- Coverage: >90% composables/stores/utils, >70% components.
- CI: Vitest + Playwright + Storybook test runner on every PR.

End-to-End Example: A Nuxt 3 Profile Page With Form, Composable, Pinia Store, And SSR Data

Without rules: Options-API-style defineComponent, plain fetch in setup, prop mutation in form, Vuex-style action names, no types, no SSR awareness.

<script>
import { defineComponent, ref, onMounted } from 'vue';
import { useUserStore } from '@/stores/user';

export default defineComponent({
  props: ['userId'],
  setup(props) {
    const user = ref(null);
    const userStore = useUserStore();

    onMounted(async () => {
      const r = await fetch(`/api/users/${props.userId}`);
      user.value = await r.json();
    });

    function save() {
      fetch(`/api/users/${props.userId}`, {
        method: 'PUT',
        body: JSON.stringify(user.value),
      });
      userStore.SET_USER(user.value);
    }

    return { user, save };
  },
});
</script>

<template>
  <form @submit.prevent="save" v-if="user">
    <input v-model="user.name" />
    <input v-model="user.email" />
    <button type="submit">Save</button>
  </form>
</template>

No SSR, fires on the client only. Untyped props. Direct mutation of user.value from v-model mixed with the prop concern. Vuex-style mutation name. No loading/error UI. No validation.

With rules: typed page, useFetch with key, defineModel form child, Pinia setup store, composable for save flow, server route with Zod, role-tested.

<!-- pages/profile/[id].vue -->
<script setup lang="ts">
import { storeToRefs } from 'pinia';
import { useUserStore } from '@/stores/user';
import { useUpdateUser } from '@/composables/useUpdateUser';

definePageMeta({ middleware: 'auth' });

const route = useRoute('profile-id');
const id = computed(() => Number(route.params.id));

interface User { id: number; name: string; email: string }

const { data: user, error, refresh } = await useFetch<User>(
  () => `/api/users/${id.value}`,
  { key: `user:${id.value}`, pick: ['id', 'name', 'email'] as never }
);

const userStore = useUserStore();
const { setUser } = userStore;
const { saving, fieldErrors, save } = useUpdateUser({ onSuccess: setUser });
</script>

<template>
  <p v-if="error" role="alert">
    Failed to load profile. <button @click="refresh">Retry</button>
  </p>
  <ProfileForm
    v-else-if="user"
    :user="user"
    :saving="saving"
    :field-errors="fieldErrors"
    @save="(draft) => save(id, draft)"
  />
</template>

<!-- components/ProfileForm.vue -->
<script setup lang="ts">
import { ref, watch } from 'vue';

interface User { id: number; name: string; email: string }

const props = defineProps<{
  user: User;
  saving: boolean;
  fieldErrors: Partial<Record<'name' | 'email', string>>;
}>();
const emit = defineEmits<{ save: [draft: Pick<User, 'name' | 'email'>] }>();

const draft = ref({ name: props.user.name, email: props.user.email });
watch(() => props.user, (u) => { draft.value = { name: u.name, email: u.email }; });

function onSubmit() { emit('save', draft.value); }
const nameId = useId();
const emailId = useId();
</script>

<template>
  <form @submit.prevent="onSubmit" novalidate>
    <label :for="nameId">Name</label>
    <input :id="nameId" v-model="draft.name" :aria-invalid="!!fieldErrors.name" />
    <p v-if="fieldErrors.name" role="alert">{{ fieldErrors.name }}</p>

    <label :for="emailId">Email</label>
    <input :id="emailId" v-model="draft.email" type="email"
           :aria-invalid="!!fieldErrors.email" />
    <p v-if="fieldErrors.email" role="alert">{{ fieldErrors.email }}</p>

    <button type="submit" :disabled="saving">
      {{ saving ? 'Saving…' : 'Save' }}
    </button>
  </form>
</template>

// composables/useUpdateUser.ts
import { ref } from 'vue';

interface User { id: number; name: string; email: string }
type FieldErrors = Partial<Record<'name' | 'email', string>>;

export function useUpdateUser(opts: { onSuccess?: (u: User) => void } = {}) {
  const saving = ref(false);
  const fieldErrors = ref<FieldErrors>({});

  async function save(id: number, draft: Pick<User, 'name' | 'email'>) {
    saving.value = true;
    fieldErrors.value = {};
    try {
      const updated = await $fetch<User>(`/api/users/${id}`, {
        method: 'PUT', body: draft,
      });
      opts.onSuccess?.(updated);
    } catch (err: any) {
      if (err?.data?.fieldErrors) fieldErrors.value = err.data.fieldErrors;
      else throw err;
    } finally {
      saving.value = false;
    }
  }
  return { saving, fieldErrors, save };
}

// stores/user.ts
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';

export interface User { id: number; name: string; email: string }

export const useUserStore = defineStore('user', () => {
  const user = ref<User | null>(null);
  const isLoggedIn = computed(() => user.value !== null);
  function setUser(u: User) { user.value = u; }
  function clear() { user.value = null; }
  return { user, isLoggedIn, setUser, clear };
});

// server/api/users/[id].put.ts
import { z } from 'zod';

const Schema = z.object({
  name: z.string().min(1).max(80),
  email: z.string().email(),
});

export default defineEventHandler(async (event) => {
  const id = Number(getRouterParam(event, 'id'));
  const body = await readBody(event);
  const parsed = Schema.safeParse(body);
  if (!parsed.success) {
    throw createError({
      statusCode: 422,
      statusMessage: 'Validation failed',
      data: { fieldErrors: parsed.error.flatten().fieldErrors },
    });
  }
  const updated = await db.user.update({ where: { id }, data: parsed.data });
  return updated;
});

// middleware/auth.ts
export default defineNuxtRouteMiddleware(() => {
  const { isLoggedIn } = useUserStore();
  if (!isLoggedIn) return navigateTo('/login');
});

Server-rendered profile, accessible form with useId-stable label associations, draft state isolated from props, composable encapsulates the save flow with typed field errors, Pinia store updated via a real action, server route validates with Zod and returns structured field errors that the UI surfaces — every layer typed, no double-fetches, no prop mutation.

Get the Full Pack

These eight rules cover the Vue 3 + Nuxt 3 patterns where AI assistants consistently reach for the wrong idiom. Drop them into .cursorrules and the next prompt you write will look different — Composition-API-default, prop-immutable, reactivity-disciplined, Pinia-scoped, useFetch-cached, route-typed, role-tested Vue, without having to re-prompt.

If you want the expanded pack — these eight plus rules for Nuxt 3 server routes with defineEventHandler + Zod + rate limiting, advanced useFetch / useAsyncData patterns (request dedupe, watch sources, transform pipelines), Pinia + Drizzle/Prisma integration with optimistic updates, VueUse mastery (createSharedComposable, useStorage typed schemas, useEventBus patterns), Vitest + @vue/test-utils deep dives (mounting Suspense, async components, teleport), Storybook 8 with Vue 3 generics + autodocs, internationalization with @nuxtjs/i18n (lazy locales, route prefixing, SEO), @nuxt/image configuration (provider setup, responsive sources, IPX for self-hosting), accessibility with vue-axe + Storybook a11y, animation patterns with <Transition> / <TransitionGroup> + @vueuse/motion, the Nitro server presets I use (Vercel Edge, Cloudflare Workers, Deno Deploy), and the Tailwind + Vue 3 patterns that don't fight <script setup> — it is bundled in Cursor Rules Pack v2 ($27, one payment, lifetime updates). Drop it in your repo, stop fighting your AI, ship Vue you would actually merge.

Cursor Rules for Ruby on Rails 8: AI Dev Guide 2026

Olivia Craft — Sun, 26 Apr 2026 09:59:33 +0000

Rails is the framework that lets you ship a working CRUD app in a morning and a 4,000-line OrdersController with 14 before_action filters by the end of the quarter. The first regression is almost always an N+1 in a view: @posts.each do |p| p.author.name end, no includes(:author) on the query, the request balloons from 12 ms to 2.4 s in production, and the only reason anybody notices is that NewRelic finally complains. The second is the callback that became the system: before_save :charge_credit_card on the Order model, which fires from the seeds, from the test factory, from a console update! you ran to fix a typo — and now the ops channel is full of duplicate Stripe charges nobody can explain. The third is the fat ActiveRecord model: User with 1,800 lines, 30 has_many associations, six concerns that all import each other, three class << self blocks competing for find_by_email, and a def self.process_signup_with_referral_and_invite_and_credit(email, ...) that nobody dares delete.

Then you add an AI assistant.

Cursor and Claude Code were trained on Rails code that spans nearly two decades — Rails 2 with RAILS_ROOT, Rails 3 with attr_accessible, Rails 4 with protected_attributes gem, Rails 5 with hand-rolled ActionCable controllers, Rails 6 with Webpacker, plus a long tail of legacy patterns: validates_presence_of :email instead of the modern validates :email, presence: true, before_filter instead of before_action, raw SQL string interpolation like Post.where("user_id = #{params[:id]}"), controllers with 200-line actions that build instance variables for six partials, render_to_string called inside model methods to email HTML, generic rescue Exception => e swallowing every error including Interrupt, business logic stuffed into after_create callbacks that fire from fixtures and break every test that touches the model, default_scope { where(deleted_at: nil) } invisibly altering every query in the app, jQuery sprinkled across app/assets/javascripts competing with Stimulus, Sprockets manifests fighting Propshaft, Spring boot caches that lie about which code is loaded, before_action chains six deep with :only and :except flags that shadow each other, params[:user] passed unfiltered to update!, User.find(params[:id]) with no authorization check, flash[:notice] = "Created" returned as the only signal of success, mailers called synchronously from controllers that block the response for 800 ms while SMTP negotiates. Ask for "an endpoint that creates an order and emails the user," and you get a 90-line OrdersController#create with five before_action filters, a mass_assignment of params[:order], an inline OrderMailer.confirmation(@order).deliver_now, a Stripe charge in an after_create, and zero tests. It runs. It is not the Rails you should ship in 2026.

The fix is .cursorrules — one file in the repo that tells the AI what idiomatic modern Rails 8 looks like. Eight rules below, each with the failure mode, the rule, and a before/after. Copy-paste .cursorrules at the end.

How Cursor Rules Work for Rails Projects

Cursor reads project rules from two locations: .cursorrules (a single file at the repo root, still supported) and .cursor/rules/*.mdc (modular files with frontmatter, recommended). For Rails 8 I recommend modular rules so controller conventions don't bleed into model code, model rules don't pollute job code, and cross-cutting concerns like authorization and testing stay visible across every layer:

.cursor/rules/
  rails-controllers.mdc      # skinny controllers, service objects, result types
  rails-models.mdc           # validates, scopes, enum, no callbacks-as-logic
  rails-queries.mdc          # includes/preload/eager_load, pluck, find_each
  rails-params.mdc           # strong params, form objects, never permit!
  rails-jobs.mdc             # ActiveJob + Solid Queue, idempotent, retry_on
  rails-hotwire.mdc          # Turbo Frames + Streams, Stimulus, importmap
  rails-authz.mdc            # Pundit policies, authorize, policy_scope
  rails-testing.mdc          # RSpec, FactoryBot, system specs with Cuprite

Frontmatter controls activation: globs: ["app/**/*.rb", "config/**/*.rb", "spec/**/*.rb", "test/**/*.rb"] with alwaysApply: false. Now the rules.

Rule 1: Skinny Controllers, Fat Service Objects — Business Logic In `app/services/*` POROs With Result Types

The single oldest Rails anti-pattern is the fat controller: an action that authenticates, authorizes, validates, charges a card, sends an email, writes an audit log, returns JSON, and re-renders a partial — all inline. Cursor's training set is full of this; ask for "create order endpoint" and you get 80 lines of controller. The fix is the service object pattern that the Rails community converged on a decade ago and that Rails 8 finally treats as a first-class citizen: controllers orchestrate (parse params, invoke a service, render a response); services own business logic; services return a Result object with success? and either value or error. Callbacks on ActiveRecord models are reserved for state housekeeping (touching timestamps, normalizing strings) — never for sending emails, charging cards, enqueuing jobs, or writing audit logs.

The rule:

Controllers do exactly four things:
  1. Authenticate (via concern / before_action :authenticate_user!).
  2. Authorize (Pundit; see Rule 7).
  3. Permit params (strong params; see Rule 4).
  4. Invoke a service object and render the result.

A controller action is at most ~10 lines. If it grows past that, the
business logic moves to a service in app/services/.

Service objects:
  - Live in app/services/<context>/<verb_noun>.rb (e.g.
    app/services/orders/create_order.rb, app/services/billing/refund.rb).
  - Are POROs (Plain Old Ruby Objects). No ApplicationService base class
    unless it provides shared behavior — usually it doesn't need to.
  - Expose ONE public method, `call`, instance or class. Pattern:
      result = Orders::CreateOrder.call(user:, params:)
      result = Orders::CreateOrder.new(user:, params:).call
  - Take dependencies via keyword arguments (no hidden global state).
  - Return a Result struct:
      Result = Data.define(:success, :value, :error)
      def self.success(value) = new(success: true, value:, error: nil)
      def self.failure(error) = new(success: false, value: nil, error:)
  - Never raise for expected failures (validation, business rule
    violation). Raise only for infrastructure errors (DB unreachable).

Controllers handle the result:
  case result = Orders::CreateOrder.call(user: current_user, params: order_params)
  in { success: true, value: order }
    redirect_to order, notice: "Order created"
  in { success: false, error: }
    flash.now[:alert] = error.message
    render :new, status: :unprocessable_entity
  end

ActiveRecord callbacks (`before_save`, `after_create`, etc.) are ONLY
for:
  - Normalizing fields (downcase email, strip whitespace, generate slug).
  - Setting derived columns (counter caches, denormalized totals).
  - Touching associated records.

NEVER in callbacks:
  - Charging payments / hitting third-party APIs.
  - Sending emails / SMS.
  - Enqueuing jobs that have side effects.
  - Writing audit logs.
  - Creating other top-level records.
All of those belong in the service object that initiated the change.

ApplicationController has only cross-cutting concerns: error rescuing
mapped to JSON/HTML responses, authentication, locale setting. NO
business helpers.

Concerns (app/controllers/concerns) extract shared controller behavior
ONLY when 2+ controllers genuinely share the behavior. Premature
concern extraction is worse than duplication.

Inline `respond_to do |format|` blocks are kept to 2 formats max.
Beyond that, split into separate controllers (Api::OrdersController,
OrdersController) so each format stays clear.

Before — fat controller with side effects, callback that charges:

class OrdersController < ApplicationController
  before_action :authenticate_user!
  before_action :load_cart, only: [:create]
  before_action :load_address, only: [:create]
  before_action :validate_inventory, only: [:create]

  def create
    @order = current_user.orders.build(params[:order])
    @order.shipping_address = @address
    @order.line_items_attributes = @cart.items.map(&:to_h)
    if @order.save
      Stripe::Charge.create(amount: @order.total_cents, source: params[:token])
      OrderMailer.confirmation(@order).deliver_now
      AuditLog.create(user: current_user, event: "order_created", payload: @order.attributes)
      Slack.notify("New order ##{@order.id}")
      redirect_to @order, notice: "Order placed"
    else
      render :new
    end
  rescue Stripe::CardError => e
    @order.destroy
    flash[:alert] = e.message
    render :new
  end
end

class Order < ApplicationRecord
  after_create :send_confirmation
  after_create :charge_card

  def charge_card
    Stripe::Charge.create(amount: total_cents, source: stripe_token)
  end
end

Mass assignment, synchronous Stripe call inside the request, mailer delivered inline, callback duplicates the controller's work, rescue resurrects an already-saved order, Slack notification blocks the response.

After — skinny controller, service object, Result, jobs for side effects:

class OrdersController < ApplicationController
  before_action :authenticate_user!

  def create
    authorize Order
    result = Orders::PlaceOrder.call(
      user: current_user,
      params: order_params,
      payment_token: params[:stripe_token]
    )
    case result
    in { success: true, value: order }
      redirect_to order, notice: "Order placed"
    in { success: false, error: }
      @order = error.order
      flash.now[:alert] = error.message
      render :new, status: :unprocessable_entity
    end
  end

  private

  def order_params
    params.require(:order).permit(:shipping_address_id, line_items_attributes: [:product_id, :quantity])
  end
end

# app/services/orders/place_order.rb
module Orders
  class PlaceOrder
    Result = Data.define(:success, :value, :error)
    Failure = Data.define(:message, :order)

    def self.call(**) = new(**).call

    def initialize(user:, params:, payment_token:)
      @user = user
      @params = params
      @payment_token = payment_token
    end

    def call
      order = @user.orders.build(@params)
      return Result.new(success: false, value: nil, error: Failure.new(order:, message: order.errors.full_messages.to_sentence)) unless order.valid?

      ApplicationRecord.transaction do
        order.save!
        Billing::ChargeCard.call!(order:, token: @payment_token)
      end

      OrderMailer.with(order:).confirmation.deliver_later
      AuditLogJob.perform_later(user_id: @user.id, event: "order_created", record: order)
      SlackNotifyJob.perform_later(channel: "#sales", text: "New order ##{order.id}")

      Result.new(success: true, value: order, error: nil)
    rescue Billing::CardError => e
      Result.new(success: false, value: nil, error: Failure.new(order:, message: e.message))
    end
  end
end

Controller is 12 lines. Side effects live in jobs (asynchronous, retryable). Stripe call is a service that raises a typed error the wrapping service translates to a Failure. Audit and Slack run after the response is sent. Order is never saved without payment because the transaction rolls back if the charge raises.

Rule 2: ActiveRecord Models — Modern `validates`, Scopes, Typed `enum`, No `default_scope`, No Business Callbacks

ActiveRecord is Rails' most powerful tool and its biggest footgun. Cursor will gladly emit validates_presence_of :email, validates_uniqueness_of :slug, validates_format_of :email, with: URI::MailTo::EMAIL_REGEXP — all of which work, all of which have been deprecated in favor of the unified validates :email, presence: true, uniqueness: true, format: { with: ... } style for over a decade. It will reach for default_scope to "soft delete" models and then spend three days debugging why Post.unscoped.where(...) doesn't behave like Post.with_deleted. It will write before_save :do_thing for anything resembling business logic. The rule constrains the model to data semantics: validations, associations, scopes, enums, normalizations.

The rule:

Validations use the unified `validates` API:
  validates :email, presence: true, uniqueness: { case_sensitive: false },
                    format: { with: URI::MailTo::EMAIL_REGEXP }
NEVER `validates_presence_of`, `validates_uniqueness_of`, etc. — those
are legacy. The modern form is one source of truth per attribute.

Custom validators (subclass ActiveModel::EachValidator) when the same
rule appears in 2+ models. One-off conditions inline via `validate
:method_name`.

`normalizes` (Rails 7.1+) for canonicalization:
  normalizes :email, with: ->(e) { e.strip.downcase }
NOT a `before_validation` callback that does the same thing.

Associations declare `inverse_of` explicitly when Rails can't infer it
(custom foreign keys, polymorphic, scoped associations). Bidirectional
inverse_of avoids duplicate query loads:
  belongs_to :author, class_name: "User", inverse_of: :posts
  has_many :posts, inverse_of: :author

`belongs_to` is required by default since Rails 5. Do NOT add
`optional: true` unless the column is genuinely nullable in the schema;
loosening it hides bugs.

`has_many :through` for join models with attributes; `has_and_belongs_to_many`
is reserved for pure many-to-many with no join model — almost never the
right answer in a real app. Default to `has_many :through`.

`enum` for typed states with the new hash form (Rails 7+):
  enum :status, { pending: 0, paid: 10, shipped: 20, refunded: 30 },
       default: :pending, prefix: true
The `prefix:` keeps generated method names unambiguous
(`order.status_paid?` vs `order.paid?` colliding with another model).

NEVER `default_scope`. It silently mutates every query in the app and
breaks `Model.unscoped` callers in non-obvious ways. Use explicit named
scopes the caller chooses to apply:
  scope :active, -> { where(deleted_at: nil) }
  scope :recent, -> { order(created_at: :desc) }
Soft-delete pattern: `discard` gem or column + `kept` scope, not
`default_scope`.

Scopes are class methods or named scopes. They return ActiveRecord
relations, never arrays. A scope that returns an array (calls `.to_a`,
`.map`, `.select` with a block) is a query method on the wrong layer —
move to a query object in app/queries/.

Callbacks are reserved for data-shape concerns:
  - `before_validation :downcase_email` (use `normalizes` if possible).
  - `before_save :update_search_vector` (denormalized column).
  - `after_destroy :touch_parent` (cache invalidation).
NEVER for sending mail, charging cards, enqueuing side-effect jobs,
calling third-party APIs. Those go in services (Rule 1).

Concerns in app/models/concerns extract behavior shared by 2+ models
(Slugged, SoftDeletable, AuditLogged). One concern per file. NEVER
extract a concern just to "make the model smaller" — that's a code
smell, not a refactor.

`attribute` declarations for non-column virtual attributes (Rails
typed attributes API):
  attribute :unconfirmed_email, :string
  attribute :referral_count, :integer, default: 0

Counter caches via `counter_cache: true` on the belongs_to side, with
the matching column on the parent. NOT hand-rolled `after_create
:increment_counter`.

`touch: true` on belongs_to to bump parent's `updated_at` for cache
invalidation, not a custom `after_save`.

ActiveRecord transaction blocks (`ApplicationRecord.transaction do
... end`) for multi-record atomic operations. NESTED transactions need
`requires_new: true` to actually nest (otherwise they are no-ops in
the inner block).

Composite primary keys (Rails 7.1+) when the schema needs them; do not
add a redundant `id` column to a junction table.

Before — legacy validators, default_scope, callback-as-logic:

class User < ApplicationRecord
  default_scope { where(deleted_at: nil) }

  validates_presence_of :email
  validates_uniqueness_of :email
  validates_format_of :email, with: /\A[^@]+@[^@]+\z/

  has_many :posts

  before_validation :downcase_email
  after_create :send_welcome_email
  after_create :enqueue_referral_credit
  after_create :notify_slack

  STATUSES = %w[pending active suspended].freeze

  def downcase_email
    self.email = email.downcase if email
  end

  def send_welcome_email
    UserMailer.welcome(self).deliver_now
  end

  def enqueue_referral_credit
    Referral.where(referred_email: email).each(&:apply_credit!)
  end

  def notify_slack
    Slack.post("New user #{email}")
  end

  def self.active
    where(status: "active")
  end
end

Legacy validators, default_scope hides deleted users from every query forever, three callbacks fire from every test factory, status is a string with no type safety, mail delivered inline.

After — unified validates, normalizes, enum, scopes, no business callbacks:

class User < ApplicationRecord
  has_many :posts, inverse_of: :author, dependent: :restrict_with_error

  normalizes :email, with: ->(e) { e.strip.downcase }

  validates :email,
            presence: true,
            uniqueness: { case_sensitive: false },
            format: { with: URI::MailTo::EMAIL_REGEXP }

  enum :status, { pending: 0, active: 10, suspended: 20 }, default: :pending, prefix: true

  scope :kept,   -> { where(deleted_at: nil) }
  scope :recent, -> { order(created_at: :desc) }
  scope :search, ->(q) { where("email ILIKE ?", "%#{sanitize_sql_like(q)}%") }

  attribute :referral_token, :string
end

Service Users::Register calls User.create!(...), then enqueues WelcomeEmailJob, ApplyReferralCreditJob, SlackNotifyJob. Tests construct users via factories without firing side effects. Soft-delete is opt-in via User.kept. Status is a typed enum with prefixed predicate methods (user.status_active?).

Rule 3: N+1 Prevention And Query Discipline — `includes` / `preload` / `eager_load`, `pluck`, `find_each`, No String Interpolation

Every Rails app eventually has an N+1 in a view. Cursor will write @posts = Post.all in the controller and <%= post.author.name %> in the view, and never think about includes(:author). It will write User.where("created_at > '#{params[:date]}'") because string interpolation in where is concise — and now you have SQL injection. It will iterate User.all.each over a 50 million row table and OOM the box. The rule sets the discipline: every association used in a view is eager-loaded with the right method, large iterations use find_each, ID-only queries use pluck, all parameterized queries use the ? / hash form, never string interpolation.

The rule:

Every controller action that loads records and renders associations
calls `includes(...)` (or `preload`/`eager_load` when specifically
needed). The bullet gem is in the development Gemfile group:
  gem "bullet", group: :development
  Bullet.alert = true; Bullet.bullet_logger = true; Bullet.console = true
N+1 detected in dev = bug = fix before commit.

Pick the right loader:
  - `includes(:assoc)` — Rails picks preload OR eager_load; defaults
    to preload (separate query). Preferred for most cases.
  - `preload(:assoc)` — always two queries (one for parent, one for
    child via WHERE IN).
  - `eager_load(:assoc)` — single LEFT OUTER JOIN. Required when you
    need to filter / order by the association in the same query.
  - `joins(:assoc)` — INNER JOIN, no eager loading; for filtering when
    you don't need the data.

`includes(:author).references(:authors)` when filtering by an included
association in a where clause; otherwise Rails may issue an unwanted
LEFT OUTER JOIN at execution time.

Nested eager loads:
  Post.includes(comments: :author, tags: [])
The empty array form preempts auto-eager-load on a tag-less post.

`select` to limit columns when you only render a few:
  User.select(:id, :email, :created_at)
Especially important on tables with `text` / `jsonb` blobs.

`pluck` for ID lists or single-column extractions:
  user_ids = User.where(active: true).pluck(:id)
NOT `User.where(active: true).map(&:id)` — that loads full models then
discards them.

`find_each` / `find_in_batches` / `in_batches` for any iteration over
> 1,000 rows:
  User.find_each(batch_size: 500) do |user|
    # ...
  end
NEVER `User.all.each` over a large table — loads the full result set
into memory.

`exists?` over `present?` / `any?` for existence checks:
  User.where(email:).exists?  # SELECT 1 ... LIMIT 1
NOT `User.where(email:).any?` (loads records then checks) or
`.count > 0` (full COUNT scan).

Every `where` uses parameterized form:
  User.where("email ILIKE ?", "%#{sanitize_sql_like(q)}%")
  User.where(email: emails)
  User.where(created_at: start..end)
NEVER string interpolation:
  User.where("email = '#{params[:email]}'")  # SQL INJECTION

`order` with a column reference, never a string of unsanitized input:
  Post.order(column => direction)
  # where column/direction came from a whitelist hash, NOT params.

Counter-cache columns over `count` queries that hit the DB on every
view render. `posts_count` on User, with `counter_cache: true` on
Post.belongs_to.

Aggregates use SQL, not Ruby:
  Order.group(:status).sum(:total_cents)
NOT `Order.all.group_by(&:status).transform_values { |os| os.sum(&:total_cents) }`.

EXPLAIN every query that touches a hot path. Add indexes for any
WHERE / ORDER BY column that hits production traffic. Composite indexes
ordered most-selective column first.

`distinct` after a JOIN that may duplicate parent rows. Use `merge` to
combine scopes from another model.

JSON serialization uses Jbuilder or `as_json(only: [...], include: ...)`
with explicit attribute lists. NEVER `to_json` on a full model with
secrets in the schema.

Pagination via Pagy (preferred) or Kaminari. Never `Model.limit(20)
.offset(params[:page] * 20)` hand-rolled.

Before — N+1, string interpolation, all.each:

class PostsController < ApplicationController
  def index
    @posts = Post.where("created_at > '#{params[:since]}'").order("created_at desc")
  end
end

<% @posts.each do |post| %>
  <h2><%= post.author.name %></h2>
  <p><%= post.comments.count %> comments</p>
  <% post.tags.each do |tag| %>
    <span><%= tag.name %></span>
  <% end %>
<% end %>

SQL injection via params[:since]. N+1 on author (one query per post). N+1 on tags. Comment count hits DB per post with no counter cache.

After — eager load, parameterized, counter cache, pagy:

class PostsController < ApplicationController
  def index
    posts = Post
              .where(created_at: parsed_since..)
              .includes(:author, :tags)
              .order(created_at: :desc)
    @pagy, @posts = pagy(posts, items: 20)
  end

  private

  def parsed_since
    Time.iso8601(params[:since]) rescue 24.hours.ago
  end
end

<% @posts.each do |post| %>
  <h2><%= post.author.name %></h2>
  <p><%= post.comments_count %> comments</p>
  <% post.tags.each do |tag| %>
    <span><%= tag.name %></span>
  <% end %>
<% end %>
<%== pagy_nav(@pagy) %>

Two queries total (posts + authors + tags). Comment count served from comments_count counter cache column. Pagination wraps the relation. Input is parsed safely.

Rule 4: Strong Parameters And Form Objects — Per-Action Param Shape, Multi-Model Forms In `app/forms/*`

Mass assignment was the original Rails security disaster (the Github commit-as-anyone bug, 2012). Strong Parameters was the fix, and it works — when you use it precisely. Cursor will write params.require(:user).permit! because it's shorter, or worse, params.require(:user).permit(:email, :name, :role) exposing role to public form posts. It will build single-action params hashes that get reused across create and update even when the two have different valid attribute sets. And when the form spans multiple models it will reach for accepts_nested_attributes_for, which works but gets ugly fast — better to extract a Form Object that owns the validation, the persistence, and the error surface for the whole form.

The rule:

Strong params live in a private method per controller action OR per
resource if create/update truly accept the same shape:
  def create
    @user = User.new(user_params(:create))
  end

  def update
    @user.update(user_params(:update))
  end

  private

  def user_params(action)
    permitted = case action
                when :create then [:email, :password, :name]
                when :update then [:name, :avatar]
                end
    params.require(:user).permit(*permitted)
  end

NEVER `params.require(:x).permit!` — that's mass assignment by
another name. The whitelist is the security boundary.

NEVER include attributes a normal user shouldn't be able to set
(`role`, `admin`, `email_confirmed`, `stripe_customer_id`) in a
publicly-reachable controller's permit list. Admin updates go through
a separate Admin::UsersController with its own params method.

Nested attributes (accepts_nested_attributes_for) are acceptable for
SIMPLE one-level cases (an Order with line_items_attributes). When the
form has 2+ levels, conditional fields, or cross-model validations,
extract a Form Object.

Form Objects:
  - Live in app/forms/<context>/<form_name>.rb
    (e.g. app/forms/users/registration_form.rb).
  - Include ActiveModel::Model (or Attributes for typed attrs).
  - Declare attributes with types via `attribute`.
  - Validate at the form level (not the underlying models).
  - Expose `save` that wraps the multi-model persistence in a
    transaction.
  - Surface errors via `errors` (ActiveModel-compatible so form helpers
    work).

Example:
  class Users::RegistrationForm
    include ActiveModel::Model
    include ActiveModel::Attributes

    attribute :email,    :string
    attribute :name,     :string
    attribute :password, :string
    attribute :company,  :string
    attribute :accept_terms, :boolean, default: false

    validates :email, :name, :password, presence: true
    validates :accept_terms, acceptance: true

    def save
      return false unless valid?
      ApplicationRecord.transaction do
        @user = User.create!(email:, name:, password:)
        @company = Company.create!(name: company, owner: @user)
      end
      true
    end

    attr_reader :user, :company
  end

Controllers use form objects identically to ActiveRecord:
  @form = Users::RegistrationForm.new(form_params)
  if @form.save
    sign_in @form.user
    redirect_to dashboard_path
  else
    render :new, status: :unprocessable_entity
  end

Views render form errors via `form.object.errors` — works because
ActiveModel::Model adds the API.

For API endpoints, use a serializer (Jbuilder, alba, or oj-based).
NEVER `render json: @user` without an explicit attribute list.

JSON request bodies parsed by Rails into params automatically. Keys
are still subject to strong params. Validate request shape with the
same `params.require(...).permit(...)` chain.

`params.expect(...)` (Rails 8 shortcut) for the common pattern of
`require(:user).permit(:email, :name)`:
  params.expect(user: [:email, :name])
Returns nil-safely if structure wrong; preferred over the older form.

Before — permit!, mass-assignment of role, nested attrs everywhere:

class UsersController < ApplicationController
  def create
    @user = User.new(params.require(:user).permit!)
    if @user.save
      sign_in @user
      redirect_to root_path
    else
      render :new
    end
  end

  def update
    @user = User.find(params[:id])
    @user.update(params[:user])  # raw mass assignment
    redirect_to @user
  end
end

Anyone can post user[role]=admin and become an admin. Update bypasses strong params entirely. No transaction, no error rendering on update.

After — per-action permit, form object for multi-model, params.expect:

class RegistrationsController < ApplicationController
  def new
    @form = Users::RegistrationForm.new
  end

  def create
    @form = Users::RegistrationForm.new(registration_params)
    if @form.save
      sign_in @form.user
      redirect_to dashboard_path, notice: "Welcome"
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  def registration_params
    params.expect(registration_form: [:email, :name, :password, :company, :accept_terms])
  end
end

class Admin::UsersController < AdminController
  def update
    @user = User.find(params[:id])
    if @user.update(admin_user_params)
      redirect_to admin_user_path(@user), notice: "Updated"
    else
      render :edit, status: :unprocessable_entity
    end
  end

  private

  def admin_user_params
    params.expect(user: [:email, :name, :role, :status])
  end
end

Public form goes through a Form Object with explicit fields. role exists only on the Admin controller's whitelist. params.expect is structure-validating. Transaction wraps the multi-record persistence inside the form.

Rule 5: ActiveJob With Solid Queue / Sidekiq — Idempotent, `retry_on` / `discard_on`, Always `perform_later`, Never Synchronous Side Effects In Controllers

Rails 8 ships Solid Queue as the default backend (DB-backed, no Redis required for new apps). Sidekiq is still the production choice for high-throughput apps. Either way, ActiveJob is the API: every side effect that isn't strictly part of the request goes through it. Cursor's defaults are bad here — it will call Mailer.deliver_now from a controller (blocking the response), define jobs with no retry policy (one transient failure = silent loss), and write jobs that aren't idempotent (retry = duplicate Stripe charge). The rule is strict: emails, SMS, third-party API calls, audit logs, push notifications, slack pings — all perform_later, all idempotent, all with explicit retry/discard rules.

The rule:

Every job inherits from ApplicationJob. ApplicationJob declares
defaults:
  class ApplicationJob < ActiveJob::Base
    retry_on ActiveRecord::Deadlocked, wait: :polynomially_longer, attempts: 5
    retry_on Net::OpenTimeout, Net::ReadTimeout, wait: 5.seconds, attempts: 3
    discard_on ActiveJob::DeserializationError
  end

Per-job overrides:
  class ChargeCardJob < ApplicationJob
    queue_as :payments
    retry_on Stripe::APIConnectionError, wait: :polynomially_longer, attempts: 4
    discard_on Stripe::CardError  # don't retry a declined card
  end

Every job's `perform` is IDEMPOTENT. It can run twice for the same
input without double-charging, double-emailing, double-anything:
  - Check for an existing Stripe charge by idempotency key BEFORE
    creating a new one (`Stripe::Charge.create({...}, {idempotency_key: ...})`).
  - SELECT-then-INSERT inside a transaction with a unique constraint
    on the natural key.
  - Use `find_or_create_by!` or `upsert_all` for record creation.
  - Mail jobs check a sent_at flag or a separate Notification record
    before delivering.

Pass IDs, not records:
  ChargeCardJob.perform_later(order_id: order.id)
NOT `ChargeCardJob.perform_later(order)` — serializing/deserializing
the full record across runs is fragile (record mutated between enqueue
and run, GlobalID lookup fails if record deleted).

Inside the job, refetch:
  def perform(order_id:)
    order = Order.find(order_id)
    # ...
  end

Queue priority lanes:
  - `default` — most jobs.
  - `mailers` — outgoing email (separate so a backed-up mail queue
    doesn't block business logic).
  - `payments` — billing-related, highest priority + dedicated worker
    pool.
  - `low` — analytics, audit logs, search reindex.

Configure worker concurrency per lane (Solid Queue config/queue.yml,
Sidekiq sidekiq.yml).

Mailers ALWAYS via `deliver_later`:
  OrderMailer.with(order:).confirmation.deliver_later
NEVER `deliver_now` from a controller.
`deliver_now` is acceptable in:
  - Rake tasks where you want synchronous send.
  - Tests that explicitly assert delivery behavior.
  - Cron jobs where the cron IS the queue.

Recurring jobs: Solid Queue `config/recurring.yml` (Rails 8) declares
schedules. NOT a custom `Clockwork`/`whenever` cron config layered on
top.

Solid Queue worker process:
  bin/jobs    # in development
  In production: separate process via Procfile / Kamal service.

Sidekiq Pro / Enterprise patterns when on Sidekiq:
  - `unique_for: 1.hour` (sidekiq-unique-jobs) on jobs that should not
    queue duplicates.
  - `sidekiq_throttle` for rate-limited third-party APIs.
  - Batches for fan-out + collect patterns.

Job arguments are JSON-serializable: primitives, hashes/arrays of
primitives, ActiveRecord objects via GlobalID (but prefer IDs). NEVER
pass procs, large payloads, or objects with non-trivial serialization.

Long-running jobs (> 30s) split into smaller jobs that enqueue the
next chunk. Workers should not block on a single piece of work for
minutes.

Errors raised inside a job that aren't matched by retry_on/discard_on
go to ActiveJob's default handling — Solid Queue persists the failure;
Sidekiq retries with exponential backoff up to 25 attempts. Configure
a dead job handler that ships to Sentry / Honeybadger.

Background job UI: Mission Control – Jobs (Rails 8 default for Solid
Queue) at /jobs, mounted in routes.rb behind authentication.

Before — synchronous mail, no retry, non-idempotent charge:

class OrdersController < ApplicationController
  def create
    @order = current_user.orders.create!(order_params)
    Stripe::Charge.create(amount: @order.total_cents, source: params[:token])
    OrderMailer.confirmation(@order).deliver_now
    redirect_to @order
  end
end

class WelcomeEmailJob < ApplicationJob
  def perform(user)
    UserMailer.welcome(user).deliver_now
  end
end

Stripe call blocks the response. No retry, no idempotency key — a network blip = duplicate charge. Mailer blocks the response. Job takes a record (GlobalID hazards), no retry config, no idempotency.

After — async charge with idempotency key, perform_later mail, retry:

class ChargeCardJob < ApplicationJob
  queue_as :payments
  retry_on Stripe::APIConnectionError, Net::OpenTimeout, wait: :polynomially_longer, attempts: 4
  discard_on Stripe::CardError, Stripe::InvalidRequestError

  def perform(order_id:)
    order = Order.find(order_id)
    return if order.charged?

    charge = Stripe::Charge.create(
      { amount: order.total_cents, currency: "usd", source: order.stripe_token },
      { idempotency_key: "order-#{order.id}-charge" }
    )
    order.update!(stripe_charge_id: charge.id, charged_at: Time.current)
    OrderConfirmationMailer.with(order:).receipt.deliver_later
  end
end

class OrdersController < ApplicationController
  def create
    result = Orders::PlaceOrder.call(user: current_user, params: order_params, payment_token: params[:stripe_token])
    case result
    in { success: true, value: order }
      ChargeCardJob.perform_later(order_id: order.id)
      redirect_to order, notice: "Order placed; processing payment"
    in { success: false, error: }
      flash.now[:alert] = error.message
      render :new, status: :unprocessable_entity
    end
  end
end

Controller returns immediately. Charge job is idempotent (returns early if already charged), uses a Stripe idempotency key, retries on transient network errors, discards on hard card errors. Mail is enqueued from inside the charge job after success.

Rule 6: Hotwire Over JavaScript SPAs — Turbo Frames, Turbo Streams, Stimulus For Sprinkles, Importmap

Rails 7 made Hotwire the default frontend stack and Rails 8 doubles down. Cursor's training data still skews toward 2018-era jQuery sprinkled across app/assets/javascripts, full Vue/React SPAs that double the build complexity, and format.js { render js: "..." } returning raw JavaScript strings (an XSS magnet). The modern stack: Turbo Drive intercepts navigation; Turbo Frames scope partial updates; Turbo Streams broadcast or respond with surgical DOM operations; Stimulus controllers add behavior to specific elements; importmap-rails serves ES modules without a Node build for most apps. JavaScript bundling (jsbundling-rails / esbuild) is reserved for apps that genuinely need a bundler.

The rule:

Default frontend stack: Turbo + Stimulus + importmap-rails. No
jsbundling-rails / esbuild / Webpack unless the app has a specific
need (TypeScript, JSX, large vendored dep that doesn't ship as ESM).

NO jQuery. Stimulus replaces it for DOM behavior. No `format.js`
templates returning raw JS. Use Turbo Streams (`format.turbo_stream`)
instead.

Turbo Drive is on by default. Per-link / per-form opt-out:
  link_to "Download", url, data: { turbo: false }
For full-page reloads (legacy pages, third-party form widgets).

Turbo Frames scope partial updates:
  <%= turbo_frame_tag "comments" do %>
    <%= render @comments %>
    <%= link_to "New comment", new_comment_path %>
  <% end %>
A link clicked inside the frame loads the response's matching frame
into place. The rest of the page is untouched.

Turbo Streams from controller actions for surgical updates:
  respond_to do |format|
    format.turbo_stream { render turbo_stream: turbo_stream.append("messages", partial: "messages/message", locals: { message: @message }) }
    format.html { redirect_to messages_path }
  end

Common Turbo Stream actions: append, prepend, replace, update,
remove, before, after. Each targets a DOM ID.

Server-broadcast Turbo Streams via Action Cable / Solid Cable:
  class Message < ApplicationRecord
    broadcasts_to ->(message) { [message.room, "messages"] }
  end
The model auto-broadcasts to a stream every subscriber listens on.
View subscribes via:
  <%= turbo_stream_from @room, "messages" %>

Stimulus controllers in app/javascript/controllers/<name>_controller.js:
  - One controller per concern (dropdown, autocomplete, modal).
  - Targets declared, never querySelector.
  - Actions declared, never addEventListener.
  - Values typed, never raw data attributes parsed manually.

  // app/javascript/controllers/dropdown_controller.js
  import { Controller } from "@hotwired/stimulus"
  export default class extends Controller {
    static targets = ["menu"]
    static values = { open: Boolean }
    toggle() { this.openValue = !this.openValue }
    openValueChanged() { this.menuTarget.classList.toggle("hidden", !this.openValue) }
  }

ViewComponent for component-style view extraction. Renders faster
than partials, has its own test class, accepts typed attrs:
  class ButtonComponent < ViewComponent::Base
    def initialize(label:, variant: :primary)
      @label, @variant = label, variant
    end
  end

Phlex as an alternative when teams prefer Ruby DSL over ERB.

Forms: `form_with` (the modern helper), Turbo-enabled by default. On
validation failure, render :new with status: :unprocessable_entity —
Turbo replaces the form with the error-decorated version automatically.

Importmap pinning in config/importmap.rb:
  pin "@hotwired/turbo-rails", to: "turbo.min.js"
  pin "@hotwired/stimulus", to: "stimulus.min.js"
  pin_all_from "app/javascript/controllers", under: "controllers"

CSS: Propshaft (Rails 8 default) serves CSS. Tailwind via
tailwindcss-rails (preferred) or cssbundling-rails. NO Sprockets in
new Rails 8 apps.

Avoid:
  - render_to_string in controllers (use partial rendering).
  - `<%= raw user_input %>` (XSS — use `sanitize` with whitelist).
  - `<%= render "shared/menu", user: current_user %>` shotgunned in
    every layout (one place, app/views/layouts).
  - `field_with_errors` div wrapping that breaks CSS layouts —
    config.action_view.field_error_proc to a no-wrap variant.

Real-time updates without Action Cable when polling suffices:
  <%= turbo_frame_tag "status", src: status_order_path(@order),
                                 loading: :lazy,
                                 refresh: "morph",
                                 data: { turbo_refresh: "5s" } %>
Server returns the updated frame; Turbo morphs it in place.

Before — jQuery, format.js, full SPA temptation:

<div id="comments">
  <%= render @comments %>
</div>

<%= form_with url: comments_path, remote: true do |f| %>
  <%= f.text_area :body %>
  <%= f.submit %>
<% end %>

<script>
  $(document).on("ajax:success", "form", function(e) {
    var data = e.detail[0];
    $("#comments").append(data);
    $("form")[0].reset();
  });
</script>

def create
  @comment = @post.comments.create!(comment_params)
  respond_to do |format|
    format.js { render js: "$('#comments').append('#{render_to_string(@comment)}')" }
  end
end

jQuery, manual ajax wiring, raw JS string with interpolation (XSS), no progressive enhancement, no real-time broadcast.

After — Turbo Frame, Turbo Stream, broadcast, Stimulus reset:

class Post < ApplicationRecord
  has_many :comments, dependent: :destroy
end

class Comment < ApplicationRecord
  belongs_to :post
  broadcasts_to ->(c) { [c.post, "comments"] }, inserts_by: :append
end

<%= turbo_stream_from @post, "comments" %>

<%= turbo_frame_tag "comments" do %>
  <%= render @post.comments %>
<% end %>

<%= turbo_frame_tag "new_comment" do %>
  <%= form_with model: [@post, Comment.new], data: { controller: "reset-form", action: "turbo:submit-end->reset-form#reset" } do |f| %>
    <%= f.text_area :body %>
    <%= f.submit %>
  <% end %>
<% end %>

class CommentsController < ApplicationController
  def create
    @comment = @post.comments.create!(comment_params)
    respond_to do |format|
      format.turbo_stream  # auto-renders create.turbo_stream.erb
      format.html { redirect_to @post }
    end
  end
end

// app/javascript/controllers/reset_form_controller.js
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
  reset(event) { if (event.detail.success) this.element.reset() }
}

Comment broadcasts to every subscriber via Solid Cable. Form posts via Turbo, resets via Stimulus only on success. No jQuery, no XSS surface, real-time across all open tabs.

Rule 7: Authorization — Pundit Policies For Every Resource, `authorize` In Controllers, `policy_scope` For Index Queries

Rails has authentication built in (Rails 8 generators ship a session-based Authentication concern). Authorization is your job. Cursor will scatter if current_user.admin? through views, controllers, and helpers; it will rely on current_user.posts.find(params[:id]) to "authorize" by scoping (which fails the moment a polymorphic relationship breaks the assumption); it will write a controller that returns 200 with empty data instead of 403 when permission is denied. The Pundit pattern is unambiguous: every resource has a Policy class; every controller action calls authorize (which raises if denied); every index query calls policy_scope (which returns the authorized subset). current_user is a controller-and-mailer concept — not a view helper accessed via <% if current_user.admin? %>.

The rule:

Pundit is the default authorization library (gem "pundit"). One
policy per resource at app/policies/<resource>_policy.rb.

Every controller action calls `authorize`:
  def show
    @post = Post.find(params[:id])
    authorize @post
  end

  def create
    @post = current_user.posts.build(post_params)
    authorize @post  # checks PostPolicy#create?
    @post.save
    redirect_to @post
  end

`authorize` raises Pundit::NotAuthorizedError when denied. Rescue once
in ApplicationController:
  rescue_from Pundit::NotAuthorizedError, with: :forbidden
  def forbidden
    respond_to do |format|
      format.html { redirect_to root_path, alert: "Not authorized" }
      format.json { head :forbidden }
    end
  end

`verify_authorized` and `verify_policy_scoped` after_action filters
in ApplicationController catch missed authorize calls in test/dev:
  after_action :verify_authorized, except: [:index]
  after_action :verify_policy_scoped, only: [:index]

Index actions use `policy_scope`:
  def index
    @posts = policy_scope(Post).includes(:author).page(params[:page])
  end

PostPolicy::Scope returns the relation the current user is allowed
to see:
  class PostPolicy < ApplicationPolicy
    class Scope < ApplicationPolicy::Scope
      def resolve
        return scope.all if user.admin?
        scope.where(author: user).or(scope.where(published: true))
      end
    end

    def show?    = record.published? || record.author == user || user.admin?
    def create?  = user.present?
    def update?  = record.author == user || user.admin?
    def destroy? = update?
  end

Permitted attributes via `permitted_attributes`:
  class PostPolicy < ApplicationPolicy
    def permitted_attributes
      base = [:title, :body]
      base << :featured if user.admin?
      base
    end
  end
  # in controller:
  @post.update(permitted_attributes(@post))

NEVER `current_user.admin?` checks in views. Instead:
  <% if policy(@post).update? %>
    <%= link_to "Edit", edit_post_path(@post) %>
  <% end %>

NEVER scope-by-relationship as the ONLY auth check:
  current_user.posts.find(params[:id])  # works, but...
  # if @post is a Comment polymorphic across Post/User, scoping breaks.
Pair it with `authorize`:
  @comment = Comment.find(params[:id])
  authorize @comment

Multi-tenant apps: tenant resolution in middleware / a current_tenant
concern. EVERY query in the request is tenant-scoped via
ActsAsTenant or row-level security. Pundit policies layer on top.

Roles: Rolify gem for many-to-many user-role mappings; OR a simple
enum on User for fixed role lists. Whichever is used, ALL policy
checks go through Pundit, never direct `user.has_role?(...)`
sprinkled in views.

API tokens: a separate Authentication concern verifies a Bearer
token; sets `current_user` for the request; policies behave the same
in API and HTML controllers.

Audit log: app/services/auditing.rb writes immutable records of who
did what. Every authorize? call that returns true on a sensitive
action (delete, refund, role change) calls Auditing.record(...) from
the service object, NOT from the policy.

Authentication itself: Rails 8 `bin/rails generate authentication`
or Devise (mature, more features). Not hand-rolled.

Before — admin checks in views, no central policy, scoping by relationship only:

class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])
    if @post.author != current_user && !@post.published? && !current_user&.admin?
      redirect_to root_path, alert: "Not authorized" and return
    end
  end

  def update
    @post = Post.find(params[:id])
    if @post.author != current_user && !current_user.admin?
      head :forbidden and return
    end
    @post.update(params.require(:post).permit(:title, :body, :featured))
    redirect_to @post
  end
end

<% if current_user&.admin? || @post.author == current_user %>
  <%= link_to "Edit", edit_post_path(@post) %>
<% end %>

Authorization logic duplicated in every action and view. :featured is permittable by anyone. Easy to forget on a new action.

After — Pundit policy, authorize, policy_scope, permitted_attributes:

class PostsController < ApplicationController
  def index
    @posts = policy_scope(Post).includes(:author).page(params[:page])
  end

  def show
    @post = Post.find(params[:id])
    authorize @post
  end

  def update
    @post = Post.find(params[:id])
    authorize @post
    @post.update(permitted_attributes(@post))
    redirect_to @post
  end
end

class PostPolicy < ApplicationPolicy
  class Scope < ApplicationPolicy::Scope
    def resolve
      return scope.all if user&.admin?
      base = scope.where(published: true)
      user ? base.or(scope.where(author: user)) : base
    end
  end

  def show?    = record.published? || record.author == user || user&.admin?
  def update?  = record.author == user || user&.admin?
  def destroy? = update?

  def permitted_attributes
    base = [:title, :body]
    base << :featured if user&.admin?
    base
  end
end

<% if policy(@post).update? %>
  <%= link_to "Edit", edit_post_path(@post) %>
<% end %>

Authorization logic in ONE place. Index returns the right subset. Featured flag protected from public posts. Views ask the policy.

Rule 8: Testing — RSpec, FactoryBot, System Specs With Cuprite, Request Specs Over Controller Specs, VCR For HTTP

Rails 8 ships Minitest by default; RSpec remains the dominant choice in production codebases for its fixture-free factories, expressive matchers, and structured describe/context/it organization. Cursor's defaults are dated: it generates controller specs (deprecated since Rails 5), uses fixtures (the test/fixtures/*.yml files that share state across every test), reaches for Selenium WebDriver (slow, flaky, requires Chromedriver pinning), and writes let! for everything (defeating lazy evaluation). The modern stack: RSpec for specs; FactoryBot for test data; system specs with Capybara + Cuprite (Chrome DevTools Protocol, no Selenium); request specs for HTTP-level integration; VCR or webmock for third-party HTTP; RuboCop + standardrb for style.

The rule:

RSpec is the test framework. Spec files at spec/<type>/<name>_spec.rb.
Per layer:
  spec/models/         — model unit specs (validations, scopes, callbacks).
  spec/services/       — service object specs (call → result assertions).
  spec/jobs/           — job specs (perform with stubbed externals).
  spec/policies/       — Pundit policy specs (one matcher per action).
  spec/requests/       — controller-level integration via real HTTP.
  spec/system/         — end-to-end browser specs via Cuprite.
  spec/components/     — ViewComponent specs.
  spec/forms/          — Form Object specs.

NEVER write controller specs (`spec/controllers/`). Rails 5
deprecated their utility; request specs cover the same surface with
better integration semantics.

FactoryBot factories at spec/factories/<plural>.rb:
  FactoryBot.define do
    factory :user do
      sequence(:email) { |n| "user#{n}@example.com" }
      name { "Test User" }
      password { "secret123" }
    end

    factory :post do
      association :author, factory: :user
      title { "Hello" }
      body { "World" }
      published { false }

      trait :published do
        published { true }
        published_at { 1.day.ago }
      end
    end
  end

NO fixtures (test/fixtures/*.yml). Factories are explicit per-test
data; fixtures are shared global state that breaks tests on edits.

`let` is lazy; `let!` is eager. Default to `let`. `let!` only when
the side-effect of setup is what's being tested:
  let!(:other_post) { create(:post, :published) }
  it "doesn't include other users' drafts" do
    sign_in user
    get posts_path
    expect(response.body).to include(other_post.title)
  end

`subject` for the system under test, named when there's more than one
implicit subject:
  subject(:service) { described_class.new(user:, params:) }

System specs config (spec/rails_helper.rb):
  Capybara.register_driver(:cuprite) do |app|
    Capybara::Cuprite::Driver.new(app, window_size: [1400, 900], js_errors: true, headless: true)
  end
  Capybara.javascript_driver = :cuprite
  RSpec.configure do |config|
    config.before(:each, type: :system) { driven_by :cuprite }
  end

Cuprite advantages: faster than Selenium, no Chromedriver pinning,
real Chrome via DevTools Protocol, easy debugging via headless: false.

System specs:
  - User-flow level. ONE flow per file.
  - Use semantic Capybara matchers (`have_button`, `have_link`,
    `have_field`).
  - Avoid `find('.css-class')` — brittle. Prefer accessible queries.
  - Wait for content (`expect(page).to have_content('Saved')`), don't
    sleep.
  - Screenshots on failure: capybara-screenshot-diff for visual
    regression.

Request specs:
  describe "POST /posts" do
    it "creates a post when authorized" do
      sign_in user
      post posts_path, params: { post: { title: "Hi", body: "yo" } }
      expect(response).to have_http_status(:found)
      expect(Post.last.title).to eq("Hi")
    end
  end

External HTTP:
  - VCR for recording real responses (one cassette per spec; cassettes
    in fixtures/vcr_cassettes/).
  - WebMock for explicit stub-and-assert when the request shape is
    what you're testing.
  - NEVER hit a real third-party API in CI.

ActiveJob testing:
  config.active_job.queue_adapter = :test
  expect { ChargeCardJob.perform_later(order_id: o.id) }
    .to have_enqueued_job(ChargeCardJob).with(order_id: o.id).on_queue("payments")

Mailer testing: ActionMailer::TestCase patterns; ActionMailer::Base
.deliveries cleared between specs; assert delivery via
`ActionMailer::Base.deliveries.last`.

Time control: `freeze_time { ... }` (ActiveSupport::Testing::TimeHelpers,
included by default in Rails 5.2+). NEVER `Timecop` in new code.

Database cleaning: transactional fixtures by default. For specs that
spin up multiple connections (system specs that run JS) use
`DatabaseCleaner` with `:truncation` strategy on those examples.

Coverage:
  - Models, services, policies: aim 100% line, ~90% branch.
  - Controllers (request specs): every action with happy + error path.
  - System specs: critical user flows (signup, checkout, primary CRUD).
  - Don't chase coverage on view templates.

Linting: RuboCop with rubocop-rails + rubocop-rspec OR Standard.
Pre-commit hook + CI step. Style violations block merge.

CI: every PR runs `bundle exec rspec` + `bundle exec rubocop` +
`bin/brakeman` (security scanner) in parallel.

Before — controller spec, fixtures, Selenium, sleep, jest pattern:

# test/controllers/posts_controller_test.rb
require "test_helper"

class PostsControllerTest < ActionDispatch::IntegrationTest
  fixtures :users, :posts

  test "creates a post" do
    post posts_url, params: { post: { title: "X", body: "Y" } }
    assert_redirected_to post_url(Post.last)
  end
end

# spec/system/orders_spec.rb
RSpec.describe "Orders" do
  before(:each) { Capybara.javascript_driver = :selenium_chrome_headless }

  it "creates" do
    visit "/orders/new"
    fill_in "Address", with: "123"
    click_on "Submit"
    sleep 2
    expect(page).to have_text("created")
  end
end

Fixtures shared across tests, no auth check, Selenium pinning, sleep instead of wait, text instead of content.

After — RSpec, FactoryBot, Cuprite, request + system + service specs:

# spec/factories/users.rb
FactoryBot.define do
  factory :user do
    sequence(:email) { |n| "user#{n}@example.com" }
    name { "Test User" }
    password { "secret123" }
  end
end

# spec/services/orders/place_order_spec.rb
require "rails_helper"

RSpec.describe Orders::PlaceOrder do
  subject(:service) { described_class.new(user:, params:, payment_token: "tok_visa") }

  let(:user) { create(:user) }
  let(:params) { { shipping_address_id: create(:address, user:).id, line_items_attributes: [{ product_id: create(:product).id, quantity: 1 }] } }

  context "with valid input and successful charge" do
    before { allow(Billing::ChargeCard).to receive(:call!).and_return(true) }

    it "creates the order, enqueues mail, returns success" do
      result = nil
      expect { result = service.call }.to change(Order, :count).by(1)
        .and have_enqueued_mail(OrderMailer, :confirmation)
      expect(result.success).to be true
      expect(result.value).to be_persisted
    end
  end

  context "when card is declined" do
    before { allow(Billing::ChargeCard).to receive(:call!).and_raise(Billing::CardError, "declined") }

    it "rolls back and returns failure with the message" do
      expect { service.call }.not_to change(Order, :count)
      result = service.call
      expect(result.success).to be false
      expect(result.error.message).to eq("declined")
    end
  end
end

# spec/requests/orders_spec.rb
require "rails_helper"

RSpec.describe "Orders" do
  describe "POST /orders" do
    let(:user) { create(:user) }

    it "redirects to the order on success" do
      sign_in user
      post orders_path, params: { order: { shipping_address_id: create(:address, user:).id, line_items_attributes: [{ product_id: create(:product).id, quantity: 1 }] }, stripe_token: "tok_visa" }
      expect(response).to have_http_status(:found)
      expect(response).to redirect_to(Order.last)
    end

    it "renders new with errors on validation failure" do
      sign_in user
      post orders_path, params: { order: { shipping_address_id: nil, line_items_attributes: [] } }
      expect(response).to have_http_status(:unprocessable_entity)
      expect(response.body).to include("Shipping address")
    end
  end
end

# spec/system/checkout_spec.rb
require "rails_helper"

RSpec.describe "Checkout", type: :system do
  let(:user) { create(:user) }
  let!(:product) { create(:product, name: "Widget", price_cents: 1000) }

  before do
    sign_in user
    visit new_order_path
  end

  it "completes a successful checkout" do
    select "Default address", from: "Shipping address"
    select "Widget", from: "Products"
    click_on "Place order"
    expect(page).to have_content("Order placed")
    expect(page).to have_current_path(%r{/orders/\d+})
  end
end

Service spec covers happy and failure paths. Request spec exercises the controller surface end-to-end. System spec walks the user flow in a real browser via Cuprite. Factories build precisely the data each test needs. Mail is asserted via have_enqueued_mail, jobs via have_enqueued_job.

The Complete `.cursorrules` File

Drop this in the repo root. Cursor and Claude Code both pick it up.

# Ruby on Rails 8 — Production Patterns

## Controllers & services
- Controllers do four things: authenticate, authorize (Pundit), permit
  params, invoke a service.
- Action body ~10 lines max; longer = extract a service.
- Services in app/services/<context>/<verb_noun>.rb; PORO with `call`.
- Services return Result struct: success/value or success:false/error.
- Pattern-match the result in the controller.
- ApplicationController: only error rescuing, auth, locale.
- Concerns extracted only when 2+ controllers genuinely share behavior.
- ActiveRecord callbacks ONLY for normalization / derived columns /
  touching parents. Never for mail, payments, jobs, audits.

## Models
- `validates :attr, presence: true, ...` — never `validates_presence_of`.
- `normalizes :email, with: ->(e) { e.strip.downcase }` for canonicalization.
- `enum :status, { ... }, default:, prefix:` for typed states.
- Associations declare `inverse_of` when needed; counter_cache via
  belongs_to option, not callbacks.
- NEVER `default_scope`. Use named scopes the caller opts into.
- Scopes return relations, not arrays. Array-returning queries → query
  objects in app/queries/.
- Concerns in app/models/concerns only when 2+ models share behavior.

## Queries
- Every association used in a view → `includes(...)`.
- bullet gem in development; N+1 = bug.
- `includes` default; `preload` to force two queries; `eager_load` for
  filter-by-association; `joins` for filtering without loading.
- `select` to limit columns; `pluck` for ID lists; `find_each` for
  > 1000 row iterations.
- `exists?` over `any?` / `count > 0` for existence checks.
- Parameterized where: `User.where("col ILIKE ?", "%#{sanitize_sql_like(q)}%")`,
  never string interpolation.
- Aggregates in SQL (group/sum), not Ruby.
- Pagy for pagination.

## Strong params & forms
- `params.expect(resource: [:a, :b])` (Rails 8) over `permit(...)`.
- NEVER `permit!`. Per-action whitelists.
- Admin attributes (role, status) only on Admin::*Controller params.
- Multi-model forms via Form Objects in app/forms/<context>/<name>.rb;
  ActiveModel::Model + ActiveModel::Attributes; `save` wraps in a
  transaction.
- Serializers (Jbuilder/alba) for JSON responses; never `render json: model`.

## Background jobs
- Solid Queue (Rails 8 default) or Sidekiq.
- ApplicationJob declares default retry_on/discard_on; per-job overrides.
- Every job idempotent (Stripe idempotency_key, find_or_create_by!,
  upsert_all, sent_at flags).
- Pass IDs not records. Refetch in `perform`.
- Queue lanes: default, mailers, payments, low — with prioritized
  worker pools.
- Mailers ALWAYS `.deliver_later` from controllers.
- Recurring schedules in config/recurring.yml (Solid Queue).
- Mission Control – Jobs UI mounted behind auth.

## Hotwire (Turbo + Stimulus)
- Default stack: Turbo + Stimulus + importmap-rails. No jQuery, no
  Webpacker, no jsbundling unless specifically needed.
- Turbo Drive on by default; opt out via data-turbo="false" per element.
- Turbo Frames scope partial updates with `<turbo-frame id="...">`.
- Turbo Streams from controllers (`format.turbo_stream`) for surgical
  DOM ops.
- `broadcasts_to` on models for Action Cable / Solid Cable broadcast.
- Stimulus controllers in app/javascript/controllers/; static targets,
  values, actions; never querySelector / addEventListener.
- ViewComponent (or Phlex) for typed view extraction.
- Propshaft + tailwindcss-rails (Rails 8 defaults).
- `form_with` (Turbo-enabled), render :new on validation fail with
  status: :unprocessable_entity.

## Authorization
- Pundit. One policy per resource at app/policies/<resource>_policy.rb.
- Every action calls `authorize`; index calls `policy_scope`.
- after_action :verify_authorized + :verify_policy_scoped in
  ApplicationController.
- `permitted_attributes` in policy; controller calls
  `@x.update(permitted_attributes(@x))`.
- `policy(record).action?` in views — never raw `current_user.admin?`.
- Multi-tenant: ActsAsTenant or RLS at DB level; Pundit layered on top.
- Roles via Rolify or User enum; ALL checks routed through Pundit.

## Testing
- RSpec; spec/<type>/<name>_spec.rb; types: models, services, jobs,
  policies, requests, system, components, forms.
- FactoryBot factories with sequences and traits; NO fixtures.
- `let` lazy by default; `let!` only when setup side effect is the
  test.
- System specs via Cuprite (CDP), not Selenium; semantic matchers
  (have_button/have_link/have_field/have_content).
- Request specs over controller specs.
- VCR for recorded HTTP; WebMock for stubbed assertions; never real
  third-party in CI.
- ActiveJob test adapter; `have_enqueued_job` / `have_enqueued_mail`.
- `freeze_time { ... }`; never Timecop.
- RuboCop / Standard + Brakeman in CI.

End-to-End Example: A Comments Feature With Background Email, Authorization, And Hotwire

Without rules: Fat controller, mass assignment, synchronous mail, no Pundit, no Turbo, controller spec.

class CommentsController < ApplicationController
  def create
    @comment = Comment.new(params[:comment])
    @comment.user_id = session[:user_id]
    @comment.post_id = params[:post_id]
    if @comment.save
      CommentMailer.notify(@comment.post.author, @comment).deliver_now
      AuditLog.create(user_id: session[:user_id], action: "comment_create")
      redirect_to "/posts/#{params[:post_id]}", notice: "Created"
    else
      redirect_to "/posts/#{params[:post_id]}", alert: "Failed"
    end
  end
end

With rules: RSpec'd service object, idempotent job, Pundit, Turbo Stream broadcast, system spec.

# app/controllers/comments_controller.rb
class CommentsController < ApplicationController
  before_action :authenticate_user!
  before_action :set_post

  def create
    authorize Comment.new(post: @post)
    result = Comments::CreateComment.call(user: current_user, post: @post, params: comment_params)
    case result
    in { success: true, value: comment }
      respond_to do |format|
        format.turbo_stream
        format.html { redirect_to @post, notice: "Comment posted" }
      end
    in { success: false, error: }
      flash.now[:alert] = error.message
      render "posts/show", status: :unprocessable_entity
    end
  end

  private

  def set_post
    @post = Post.find(params[:post_id])
  end

  def comment_params
    params.expect(comment: [:body])
  end
end

# app/services/comments/create_comment.rb
module Comments
  class CreateComment
    Result = Data.define(:success, :value, :error)
    Failure = Data.define(:message)

    def self.call(**) = new(**).call

    def initialize(user:, post:, params:)
      @user, @post, @params = user, post, params
    end

    def call
      comment = @post.comments.build(@params.merge(author: @user))
      if comment.save
        NotifyCommentJob.perform_later(comment_id: comment.id)
        Result.new(success: true, value: comment, error: nil)
      else
        Result.new(success: false, value: nil, error: Failure.new(message: comment.errors.full_messages.to_sentence))
      end
    end
  end
end

# app/models/comment.rb
class Comment < ApplicationRecord
  belongs_to :post, counter_cache: true, touch: true
  belongs_to :author, class_name: "User", inverse_of: :comments

  validates :body, presence: true, length: { minimum: 2, maximum: 5_000 }

  broadcasts_to ->(c) { [c.post, "comments"] }, inserts_by: :append
end

# app/policies/comment_policy.rb
class CommentPolicy < ApplicationPolicy
  def create?  = user.present? && record.post.published?
  def update?  = record.author == user
  def destroy? = update? || record.post.author == user || user&.admin?
end

# app/jobs/notify_comment_job.rb
class NotifyCommentJob < ApplicationJob
  queue_as :mailers
  retry_on Net::OpenTimeout, Net::ReadTimeout, wait: 10.seconds, attempts: 3
  discard_on ActiveRecord::RecordNotFound

  def perform(comment_id:)
    comment = Comment.find(comment_id)
    return if comment.notified_at?

    CommentMailer.with(comment:).new_comment.deliver_later
    AuditLogJob.perform_later(user_id: comment.author_id, event: "comment_create", record: comment)
    comment.update_column(:notified_at, Time.current)
  end
end

# app/views/posts/show.html.erb
<%= turbo_stream_from @post, "comments" %>
<%= turbo_frame_tag "comments" do %>
  <%= render @post.comments.includes(:author).order(:created_at) %>
<% end %>

<% if policy(Comment.new(post: @post)).create? %>
  <%= turbo_frame_tag "new_comment" do %>
    <%= form_with model: [@post, Comment.new] do |f| %>
      <%= f.text_area :body %>
      <%= f.submit "Post comment" %>
    <% end %>
  <% end %>
<% end %>

# app/views/comments/create.turbo_stream.erb
<%= turbo_stream.append "comments", partial: "comments/comment", locals: { comment: @comment } %>
<%= turbo_stream.replace "new_comment" do %>
  <%= turbo_frame_tag "new_comment" do %>
    <%= form_with model: [@post, Comment.new] do |f| %>
      <%= f.text_area :body %>
      <%= f.submit "Post comment" %>
    <% end %>
  <% end %>
<% end %>

# spec/services/comments/create_comment_spec.rb
require "rails_helper"

RSpec.describe Comments::CreateComment do
  let(:user) { create(:user) }
  let(:post_record) { create(:post, :published) }
  subject(:service) { described_class.new(user:, post: post_record, params: { body: "Looks good" }) }

  it "creates the comment and enqueues notification" do
    expect { service.call }
      .to change(Comment, :count).by(1)
      .and have_enqueued_job(NotifyCommentJob)
  end

  it "returns failure with empty body" do
    failing = described_class.new(user:, post: post_record, params: { body: "" })
    expect(failing.call.success).to be false
  end
end

# spec/system/commenting_spec.rb
require "rails_helper"

RSpec.describe "Commenting", type: :system do
  let(:user) { create(:user) }
  let!(:post_record) { create(:post, :published) }

  before { sign_in user; visit post_path(post_record) }

  it "posts a comment and shows it via Turbo Stream" do
    fill_in "Body", with: "Great post"
    click_on "Post comment"
    expect(page).to have_content("Great post")
  end
end

Skinny controller, service object, Pundit policy, idempotent job, Turbo Stream broadcast for real-time, request and system specs covering the flow.

Get the Full Pack

These eight rules cover the Rails 8 patterns where AI assistants consistently reach for the wrong idiom. Drop them into .cursorrules and the next prompt you write will look different — skinny controllers with service objects, modern ActiveRecord without callback-as-business-logic, N+1-free queries, strong params with form objects, idempotent ActiveJob, Hotwire over SPAs, Pundit on every action, RSpec + Cuprite test suites, without having to re-prompt.

If you want the expanded pack — these eight plus rules for Sidekiq tuning (concurrency, throttling, dead-job handling), Action Cable / Solid Cable patterns for high-fan-out broadcasts, Solid Queue and Solid Cache configuration for production scale, Kamal 2 deployment recipes (Docker, accessory services, zero-downtime deploys, secrets), Stimulus controllers for the dozen patterns every app needs (modal, dropdown, autocomplete, sortable, infinite scroll), ViewComponent + Lookbook for component-driven view layers, multi-tenant Rails with Postgres row-level security and ActsAsTenant, Phlex as a Ruby DSL alternative to ERB, Pagy tuning for huge datasets, Brakeman + bundler-audit + dependabot for security CI, and the deploy patterns I use for Rails 8 on Hetzner + Kamal + Cloudflare — it is bundled in Cursor Rules Pack v2 ($27, one payment, lifetime updates). Drop it in your repo, stop fighting your AI, ship Rails you would actually merge.

Cursor Rules for PHP and Laravel: AI Dev Guide 2026

Olivia Craft — Sun, 26 Apr 2026 09:58:58 +0000

Laravel is the framework that lets you ship a working CRUD app over a long morning and a tangled mess of fat controllers, mass-assignment vulnerabilities, and N+1 queries by the end of the quarter. The first regression is almost always a query log explosion: a Blade view iterates over $users and renders $user->company->name inside the loop, every row triggers a separate select * from companies where id = ?, the homepage now fires four hundred queries on every request, and the database starts queuing connections under load. The second is mass assignment that became mass exploitation: a developer copy-pasted protected $guarded = [] from a Stack Overflow answer in 2018, the User model now accepts whatever the request payload contains, and a curl request with is_admin=1 in the body just escalated a regular user to root. The third is the synchronous mailer in a registration controller: the SMTP server hiccups, the request hangs for 30 seconds, the user double-clicks the submit button, and now there are two accounts with the same email and a half-sent welcome message in the queue.

Then you add an AI assistant.

Cursor and Claude Code were trained on Laravel code that spans a decade and a half — Laravel 4 IoC bindings in start/global.php, Laravel 5 callable strings in routes (Route::get('/x', 'XController@show')), protected $guarded = [] everywhere because "we'll get to it later," DB::raw("WHERE name LIKE '%" . $search . "%'") with string concatenation that is one form field away from a SQL injection postmortem, controllers that do everything inline (validate, query, transform, mail, respond) in 200 lines per action, jobs dispatched as dispatch(new SendEmail(...)) from inside a controller and awaited synchronously, API endpoints that return raw Eloquent models with password_hash, remember_token, and stripe_secret exposed to the client because nobody wrote a JsonResource, authorization via if (auth()->user()->is_admin) scattered through every controller, tests that use the real Mailgun API in CI because nobody called Mail::fake(), boot() methods on models with twenty static event hooks that nobody can find when they break, and accessors written as getFooAttribute() because the AI never learned the Attribute::make() syntax that has been the idiom since Laravel 9. Ask for "an endpoint that creates an order and emails the customer," and you get a 180-line invocable controller that validates inline, persists with Order::create($request->all()), fires Mail::to($order->user)->send(new OrderConfirmation($order)) synchronously, returns the bare model as JSON, and has zero tests. It runs. It is not the Laravel you should ship in 2026.

The fix is .cursorrules — one file in the repo that tells the AI what idiomatic modern Laravel looks like. Eight rules below, each with the failure mode, the rule, and a before/after. Copy-paste .cursorrules at the end.

How Cursor Rules Work for Laravel Projects

Cursor reads project rules from two locations: .cursorrules (a single file at the repo root, still supported) and .cursor/rules/*.mdc (modular files with frontmatter, recommended). For a Laravel app I recommend modular rules so concerns stay separable — the model rules apply to app/Models/**, the test rules apply to tests/**, and the queue rules apply to app/Jobs/** and app/Listeners/** without bleeding into HTTP code:

.cursor/rules/
  laravel-models.mdc         # fillable, casts, observers, Attribute::make
  laravel-controllers.mdc    # invokable controllers + Action classes
  laravel-validation.mdc     # FormRequest, custom rules, authorize()
  laravel-queries.mdc        # eager loading, scopes, chunk/lazy
  laravel-jobs.mdc           # ShouldQueue, retries, uniqueness, fakes
  laravel-resources.mdc      # JsonResource, conditional fields, OpenAPI
  laravel-authorization.mdc  # Policies, Gates, $this->authorize()
  laravel-testing.mdc        # Pest, factories, RefreshDatabase, fakes

Frontmatter controls activation: globs: ["app/**/*.php", "routes/**/*.php", "tests/**/*.php"] with alwaysApply: false. Now the rules.

Rule 1: Eloquent Models — Explicit `$fillable`, Typed `$casts`, Observers Over `boot()`, `Attribute::make()` Accessors

Cursor's training is heavy on Laravel 5–7 model patterns: protected $guarded = [] to "save time," accessors written as getFullNameAttribute(), mutators in the same file scattered between scopes and relationships, static::created(function ($model) { ... }) blocks inside boot() that grow until nobody can find which side effect ran on save. The rule: every model declares an explicit $fillable allowlist, every column with a non-string type declares a $casts entry (including PHP 8.1+ enums), the modern Attribute::make() API is the only accessor/mutator syntax, and all model events live in dedicated Observer classes registered in AppServiceProvider.

The rule:

Every Eloquent model in app/Models/* has:

  - `protected $fillable = [...]` listing exactly the columns that may
    be mass-assigned through `Model::create()` or `$model->fill()`.
  - `protected $guarded = []` is FORBIDDEN. PRs containing it are
    rejected.
  - `protected $casts = [...]` for every non-string column. Required
    cast types:
      - 'integer', 'boolean', 'float', 'decimal:2'
      - 'datetime', 'immutable_datetime', 'date'
      - 'array', 'collection', 'object', 'AsArrayObject::class'
      - Enum classes: 'status' => OrderStatus::class
      - Custom value objects via 'AsCustomCast::class'

  - `protected $hidden = [...]` for any sensitive column that must
    never serialize (password, remember_token, two_factor_secret,
    api_token, stripe_*).

  - `protected $appends = [...]` ONLY for accessors that the API
    explicitly needs serialized — never as a convenience for Blade.

Accessors and mutators use `Attribute::make()` (Laravel 9+ syntax).
The `getFooAttribute()` / `setFooAttribute()` magic-method form is
forbidden in new code:

  use Illuminate\Database\Eloquent\Casts\Attribute;

  protected function fullName(): Attribute {
      return Attribute::make(
          get: fn () => trim("{$this->first_name} {$this->last_name}"),
          set: fn (string $value) => [
              'first_name' => Str::before($value, ' '),
              'last_name'  => Str::after($value, ' '),
          ],
      );
  }

Model events (creating/created/updating/updated/deleting/deleted/
restoring/restored) live in dedicated Observer classes in
app/Observers/*Observer.php. The model's `boot()` method is reserved
for global scopes only (rare). Observers are registered in
AppServiceProvider::boot() via `Order::observe(OrderObserver::class)`.

Relationships have explicit return types so static analysis catches
mistakes:

  public function company(): BelongsTo {
      return $this->belongsTo(Company::class);
  }

Use enum-backed constants for any column with a fixed set of values.
The migration uses `$table->string('status')->default('pending')` and
the model casts to the enum:

  protected $casts = ['status' => OrderStatus::class];

Soft deletes via `use SoftDeletes;` ONLY when the business explicitly
needs an "undelete" or "audit-trail" affordance. Soft deletes change
every query and trip up junior devs — they are not a default.

Timestamps: rely on `created_at` / `updated_at` (Laravel default).
For models that don't need them set `public $timestamps = false;`
explicitly — silent absence is a bug.

`Model::preventLazyLoading()`, `Model::preventSilentlyDiscardingAttributes()`,
and `Model::preventAccessingMissingAttributes()` are called in
AppServiceProvider::boot() inside `if (! $this->app->isProduction())`
so dev/test environments crash on N+1 lazy loads, silent attribute
drops, and missing attribute reads.

Before — guarded empty, magic accessor, event in boot():

class Order extends Model
{
    protected $guarded = [];

    public function getFormattedTotalAttribute(): string
    {
        return '$' . number_format($this->total / 100, 2);
    }

    protected static function boot()
    {
        parent::boot();
        static::created(function ($order) {
            Mail::to($order->user)->send(new OrderConfirmation($order));
            Log::info("Order {$order->id} created");
            $order->user->increment('lifetime_value', $order->total);
        });
    }
}

Mass-assignable everything. Magic accessor invisible to static analysis. Side effects buried in boot() that fire on every test and every seeder.

After — explicit fillable, typed casts, observer, modern accessor:

namespace App\Models;

use App\Enums\OrderStatus;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\HasMany;

class Order extends Model
{
    protected $fillable = [
        'user_id', 'shipping_address_id', 'subtotal_cents',
        'tax_cents', 'total_cents', 'currency', 'status', 'placed_at',
    ];

    protected $casts = [
        'subtotal_cents' => 'integer',
        'tax_cents'      => 'integer',
        'total_cents'    => 'integer',
        'status'         => OrderStatus::class,
        'placed_at'      => 'immutable_datetime',
    ];

    protected $hidden = ['stripe_payment_intent_id'];

    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    public function items(): HasMany
    {
        return $this->hasMany(OrderItem::class);
    }

    protected function formattedTotal(): Attribute
    {
        return Attribute::make(
            get: fn () => Money::cents($this->total_cents, $this->currency)->format(),
        )->shouldCache();
    }
}

// app/Observers/OrderObserver.php
namespace App\Observers;

use App\Jobs\SendOrderConfirmation;
use App\Models\Order;

class OrderObserver
{
    public function created(Order $order): void
    {
        SendOrderConfirmation::dispatch($order);
    }
}

// app/Providers/AppServiceProvider.php
public function boot(): void
{
    Order::observe(OrderObserver::class);
    Model::preventLazyLoading(! $this->app->isProduction());
    Model::preventSilentlyDiscardingAttributes(! $this->app->isProduction());
}

Mass assignment is allowlisted. Status is a real enum with a single source of truth. Side effects live in an observer that tests can swap out. Lazy loads crash dev immediately.

Rule 2: Skinny Controllers, Single-Action Invokable Controllers, Service/Action Classes For Business Logic

Cursor's default for "build me an endpoint" is a resource controller with seven methods, each ranging from 30 to 200 lines, mixing validation, persistence, third-party calls, mailers, and response shaping in one file. The rule: HTTP controllers are thin — they receive a typed Form Request, dispatch a single Action class, and return a JsonResource or a redirect. All business logic lives in app/Actions/* invokable classes that are pure functions of their dependencies, easy to test in isolation, and reusable from controllers, console commands, and queue jobs.

The rule:

Controllers in app/Http/Controllers/* are SINGLE-ACTION INVOKABLE
classes by default for any non-trivial endpoint:

  class CreateOrderController {
      public function __invoke(CreateOrderRequest $request, CreateOrder $action) {
          $order = $action($request->validatedDto());
          return new OrderResource($order);
      }
  }

A controller method body has at most these statements:
  1. Resolve dependencies (constructor / method injection).
  2. Pull validated data via the Form Request (see Rule 3).
  3. Call exactly ONE Action class (or a small composition of two).
  4. Return a JsonResource, RedirectResponse, View, or
     ResourceCollection.

Forbidden in controllers:
  - Database queries (Eloquent or DB facade) — those go in the Action
    or a Repository/Query class.
  - Business rules (`if ($order->total > 1000) { ... }`) — those go in
    the Action or the Domain layer.
  - Mailer calls (`Mail::to(...)->send(...)`) — those go in queued
    jobs dispatched by the Action.
  - Third-party HTTP calls — those go in dedicated Service classes
    injected into the Action.
  - More than ~15 lines of code total.

Resourceful controllers (`Route::resource`) are still acceptable for
straight CRUD where each method is 1-3 lines. The moment a method
exceeds that, split it into an invokable controller + Action.

Action classes live in app/Actions/<Domain>/<Verb><Noun>.php and are
invokable:

  namespace App\Actions\Orders;

  use App\DataObjects\OrderInput;
  use App\Models\Order;

  final class CreateOrder
  {
      public function __construct(
          private readonly OrderRepository $repository,
          private readonly InventoryService $inventory,
          private readonly Dispatcher $events,
      ) {}

      public function __invoke(OrderInput $input): Order {
          $this->inventory->reserve($input->productIds);
          $order = $this->repository->create($input);
          $this->events->dispatch(new OrderPlaced($order));
          return $order;
      }
  }

Actions accept typed input objects (DataObjects / spatie/laravel-data
objects) — never raw arrays, never the Request itself. The Request
lives only in the controller; conversion to a DTO happens in the
Form Request's `validatedDto()` helper.

Actions are `final` classes and use `readonly` properties for
dependencies (PHP 8.1+).

Actions return domain models or DTOs — never HTTP responses or
JsonResources. Response shaping is the controller's concern.

Routes in routes/api.php and routes/web.php use the `[Controller::class,
'method']` array syntax for resource controllers, or `Controller::class`
alone for invokable controllers. The string callable `'X@y'` form
(Laravel 5 era) is forbidden.

Route model binding does the lookup; controllers receive the resolved
model:

  Route::get('/orders/{order}', ShowOrderController::class);

  class ShowOrderController {
      public function __invoke(Order $order): OrderResource {
          $this->authorize('view', $order);
          return new OrderResource($order);
      }
  }

Before — fat controller with everything inline:

class OrderController extends Controller
{
    public function store(Request $request)
    {
        $request->validate([
            'product_ids'   => 'required|array',
            'product_ids.*' => 'integer|exists:products,id',
            'address_id'    => 'required|integer|exists:addresses,id',
        ]);

        $products = Product::whereIn('id', $request->product_ids)->get();
        $total = 0;
        foreach ($products as $p) {
            if ($p->stock < 1) {
                return response()->json(['error' => "Out of stock: {$p->name}"], 422);
            }
            $total += $p->price_cents;
            $p->decrement('stock');
        }

        $order = Order::create([
            'user_id'    => auth()->id(),
            'address_id' => $request->address_id,
            'total'      => $total,
            'status'     => 'pending',
        ]);

        foreach ($products as $p) {
            $order->items()->create(['product_id' => $p->id, 'price' => $p->price_cents]);
        }

        Mail::to(auth()->user())->send(new OrderConfirmation($order));

        return response()->json($order);
    }
}

Validation, query, business rules, persistence, mailer, and response shaping in one method. Untestable without spinning up the world. Returns the bare model.

After — invokable controller, Form Request, Action class, Resource:

// app/Http/Controllers/Orders/CreateOrderController.php
namespace App\Http\Controllers\Orders;

use App\Actions\Orders\CreateOrder;
use App\Http\Requests\Orders\CreateOrderRequest;
use App\Http\Resources\OrderResource;

final class CreateOrderController
{
    public function __invoke(
        CreateOrderRequest $request,
        CreateOrder $action,
    ): OrderResource {
        $order = $action($request->toDto());
        return new OrderResource($order);
    }
}

// app/Actions/Orders/CreateOrder.php
namespace App\Actions\Orders;

use App\DataObjects\OrderInput;
use App\Events\OrderPlaced;
use App\Exceptions\OutOfStockException;
use App\Models\Order;
use App\Services\InventoryService;
use Illuminate\Contracts\Events\Dispatcher;
use Illuminate\Support\Facades\DB;

final readonly class CreateOrder
{
    public function __construct(
        private InventoryService $inventory,
        private Dispatcher $events,
    ) {}

    public function __invoke(OrderInput $input): Order
    {
        return DB::transaction(function () use ($input) {
            $reserved = $this->inventory->reserve($input->productIds);
            $order = Order::create([
                'user_id'             => $input->userId,
                'shipping_address_id' => $input->shippingAddressId,
                'subtotal_cents'      => $reserved->subtotalCents,
                'tax_cents'           => $reserved->taxCents,
                'total_cents'         => $reserved->totalCents,
                'currency'            => $reserved->currency,
                'status'              => OrderStatus::Pending,
            ]);
            $order->items()->createMany($reserved->items);
            $this->events->dispatch(new OrderPlaced($order));
            return $order;
        });
    }
}

// routes/api.php
Route::middleware('auth:sanctum')
    ->post('/orders', CreateOrderController::class)
    ->name('orders.store');

Controller is six lines. Action is testable in isolation with a fake InventoryService. The mailer is dispatched by an event listener (Rule 5), not the controller.

Rule 3: Form Requests For Validation — Authorization, Custom Rule Objects, DTO Conversion

$request->validate([...]) inline at the top of every controller is the Laravel anti-pattern that survived three major versions because it works and the docs show it. Cursor reproduces it everywhere. The rule: every endpoint that accepts input has a dedicated FormRequest in app/Http/Requests/*, the rules array lives there, the authorize() method does the policy check, custom rules are objects in app/Rules/*, and the request exposes a typed toDto() method that the controller and action consume.

The rule:

Every controller method that accepts user input takes a Form Request,
not the bare Request. Form Requests live in
app/Http/Requests/<Domain>/<Verb><Noun>Request.php:

  php artisan make:request Orders/CreateOrderRequest

Generated. Never inline `$request->validate([...])` in a controller.

Form Request structure:

  class CreateOrderRequest extends FormRequest
  {
      public function authorize(): bool
      {
          return $this->user()->can('create', Order::class);
      }

      public function rules(): array
      {
          return [
              'product_ids'        => ['required', 'array', 'min:1', 'max:50'],
              'product_ids.*'      => ['integer', 'exists:products,id', new ProductInStock()],
              'shipping_address_id'=> [
                  'required', 'integer',
                  Rule::exists('addresses', 'id')->where('user_id', $this->user()->id),
              ],
              'currency'           => ['required', 'string', new Enum(Currency::class)],
              'notes'              => ['nullable', 'string', 'max:500'],
          ];
      }

      public function messages(): array
      {
          return [
              'product_ids.required' => 'Pick at least one product.',
              'product_ids.max'      => 'You can order up to 50 items at once.',
          ];
      }

      public function toDto(): OrderInput
      {
          $v = $this->validated();
          return new OrderInput(
              userId:            $this->user()->id,
              productIds:        $v['product_ids'],
              shippingAddressId: $v['shipping_address_id'],
              currency:          Currency::from($v['currency']),
              notes:             $v['notes'] ?? null,
          );
      }
  }

Rules use the array form (`['required', 'string']`), never the
pipe-string form (`'required|string'`). The pipe form breaks when a
rule needs a `|` (regex patterns) and is harder to compose.

Custom validation rules are invokable Rule objects in app/Rules/*:

  namespace App\Rules;

  use Closure;
  use Illuminate\Contracts\Validation\ValidationRule;
  use App\Models\Product;

  class ProductInStock implements ValidationRule
  {
      public function validate(string $attribute, mixed $value, Closure $fail): void
      {
          if (! Product::where('id', $value)->where('stock', '>', 0)->exists()) {
              $fail('The :attribute is out of stock.');
          }
      }
  }

For complex validation that hits the DB hard, use `prepareForValidation`
to normalize input (trim, lowercase emails, strip currency formatting)
and `withValidator` for cross-field rules.

`authorize()` returns a boolean. For policy checks against a route-bound
model use `$this->user()->can('update', $this->route('order'))`. Never
do `return true;` to "deal with auth later."

Request rules referencing the authenticated user (e.g., a unique-email
rule that excludes the current user) take that user from `$this->user()`,
not `auth()->user()` inside the rules array.

Validated data accessed via `$this->validated()` (returns only validated
keys) or `$this->safe()->only([...])`. Never `$this->all()` or
`$this->input(...)` after validation — bypasses the contract.

Form Request -> DTO via `toDto()` is the canonical pattern. Actions
accept the DTO; they never see the FormRequest or Request.

For API endpoints: failing validation auto-returns 422 with the
ValidationException JSON shape. For web forms: redirects back with
`->withErrors()` and `->withInput()` automatically.

Rate limiting per route via the `throttle:` middleware, configured
in app/Providers/RouteServiceProvider.php; per-action limits inside
Form Requests via `RateLimiter::for(...)` named limiters.

Before — inline validate, no authorization, no DTO:

public function store(Request $request)
{
    $data = $request->validate([
        'product_ids' => 'required|array',
        'address_id'  => 'required|integer',
    ]);

    return Order::create($data + ['user_id' => auth()->id()]);
}

Authorization absent. No DTO. Mass-assigns directly from request.

After — Form Request with authorize, custom rule, typed DTO:

// app/Http/Requests/Orders/CreateOrderRequest.php
namespace App\Http\Requests\Orders;

use App\DataObjects\OrderInput;
use App\Enums\Currency;
use App\Models\Order;
use App\Rules\ProductInStock;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
use Illuminate\Validation\Rules\Enum;

final class CreateOrderRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()?->can('create', Order::class) ?? false;
    }

    public function rules(): array
    {
        return [
            'product_ids'         => ['required', 'array', 'min:1', 'max:50'],
            'product_ids.*'       => ['integer', 'distinct', 'exists:products,id', new ProductInStock()],
            'shipping_address_id' => [
                'required', 'integer',
                Rule::exists('addresses', 'id')->where('user_id', $this->user()->id),
            ],
            'currency'            => ['required', new Enum(Currency::class)],
            'notes'               => ['nullable', 'string', 'max:500'],
        ];
    }

    public function toDto(): OrderInput
    {
        $v = $this->validated();
        return new OrderInput(
            userId:            $this->user()->id,
            productIds:        $v['product_ids'],
            shippingAddressId: $v['shipping_address_id'],
            currency:          Currency::from($v['currency']),
            notes:             $v['notes'] ?? null,
        );
    }
}

// app/DataObjects/OrderInput.php
namespace App\DataObjects;

use App\Enums\Currency;

final readonly class OrderInput
{
    public function __construct(
        public int $userId,
        /** @var array<int, int> */
        public array $productIds,
        public int $shippingAddressId,
        public Currency $currency,
        public ?string $notes,
    ) {}
}

Authorization happens before the controller body. Validation rules are typed and reusable. The Action receives a typed DTO it can confidently destructure.

Rule 4: Database Queries & N+1 Prevention — Eager Loading, Scopes, `select()` Only Needed Columns, `chunk()`/`lazy()` For Large Sets

The N+1 query is Laravel's most common production incident. Cursor will write User::all() followed by a Blade @foreach that touches $user->company->name, and the request that should hit the DB twice fires four hundred queries. The rule: every query that will be iterated declares its eager loads via with(), only selects the columns it needs, uses query scopes for any pattern repeated more than twice, and processes large result sets via chunk() or lazy(). DB::raw with string concatenation is a hard ban; parameterized binds or DB::raw('lower(?)', [$value]) are the only acceptable form.

The rule:

N+1 prevention is enforced. In dev/test, AppServiceProvider::boot()
calls `Model::preventLazyLoading()` so any unintended lazy load throws
`LazyLoadingViolationException`. Every PR that opts out (with
`Model::preventLazyLoading(false)`) requires a code-review justification.

Eager loading rules:
  - Every query whose results will be iterated declares `with([...])`.
  - Polymorphic and morph-many relations use `morphWith` for nested
    eager loads of polymorphic children.
  - Constrained eager loads via closure:
      `with(['orders' => fn ($q) => $q->where('status', 'paid')->limit(10)])`
  - `withCount(['comments'])` instead of `count($post->comments)` in
    a loop.
  - `withExists(['subscription'])` for boolean "does it exist" checks
    instead of `$user->subscription !== null`.
  - `loadMissing(...)` only when the parent query already executed
    (e.g., a single model passed into a method). For lists, use `with`
    at the query.

`select()` non-trivially. The default `select *` is wasteful for wide
tables. Specify columns whenever the consumer (resource, view) uses
fewer than half the columns. Always include the primary key and any
foreign keys needed for relationships:
  User::select('id', 'name', 'email')->with('orders:id,user_id,total_cents')->get();

Query scopes for any filter/order pattern reused >=2 times.
Local scopes:
  public function scopeActive(Builder $q): Builder {
      return $q->where('status', UserStatus::Active);
  }
Global scopes for tenancy / soft-delete-like behavior, registered in
the model's `booted()` method via `static::addGlobalScope(...)`.

DB::raw is forbidden with string concatenation. The only acceptable
forms are:
  - DB::raw('lower(name)') — literal, no user input.
  - DB::raw('count(*) as total') — literal aggregate alias.
  - For parameterized raw expressions, use whereRaw with bindings:
      ->whereRaw('lower(name) like ?', ["%{$search}%"])
    BUT the surrounding column name and operator are still literals;
    the user input is bound.
  - For full-text search: use the dedicated FullText index + Scout
    (Algolia/Meilisearch/Typesense), not LIKE concatenation.

Pagination: `paginate($perPage)` for offset pagination on small
datasets; `cursorPaginate()` for large datasets where deep offsets
would be expensive. `simplePaginate()` when the total count is unused.

Large datasets:
  - `chunk(1000, fn ($rows) => ...)` for batch processing where order
    is unimportant.
  - `chunkById(1000, fn ($rows) => ...)` when iterating while writing
    to the same table — avoids reprocessing.
  - `lazy(1000)` returns a LazyCollection — same memory profile as
    chunk but composes with collection methods.
  - `cursor()` returns a generator — single forward pass, smallest
    memory, but holds an open DB cursor. Avoid for jobs that may be
    long-running or interleave with other queries.

Indexes. Migrations declare indexes for any column used in a WHERE,
ORDER BY, or JOIN. Composite indexes for compound conditions; column
order matches selectivity (most selective first).

Transactions. Multi-write operations wrap in `DB::transaction(fn () =>
...)`. Never manual `DB::beginTransaction()` / `commit()` / `rollBack()`
— the closure form handles deadlock retries automatically.

Read replicas (database.connections with `read`/`write` arrays):
specify the connection on read-heavy reports via `->on('reporting')`
or rely on default routing.

Before — N+1, DB::raw concat, no scope:

$users = User::all();
foreach ($users as $user) {
    echo $user->name . ' (' . $user->company->name . ') - ' . count($user->orders);
}

$results = DB::select(
    "SELECT * FROM products WHERE name LIKE '%" . $request->q . "%' ORDER BY created_at DESC"
);

One query for users, one for each user's company, one for each user's orders. SQL injection in the second snippet.

After — eager loaded, scoped, parameterized:

// app/Models/User.php
public function scopeActive(Builder $q): Builder
{
    return $q->where('status', UserStatus::Active);
}

// Action / Query class
$users = User::query()
    ->active()
    ->select('id', 'name', 'email', 'company_id')
    ->with([
        'company:id,name',
    ])
    ->withCount('orders')
    ->orderByDesc('created_at')
    ->cursorPaginate(50);

foreach ($users as $user) {
    echo "{$user->name} ({$user->company->name}) - {$user->orders_count}";
}

// Search via parameterized whereRaw + Scout for production
$products = Product::search($request->validated('q'))
    ->where('available', true)
    ->paginate(20);

Two queries total regardless of result size. Counts come from the DB, not PHP. Search goes through Scout's typed search engine, not LIKE concatenation.

Rule 5: Queues & Background Jobs — `ShouldQueue`, Idempotent `handle()`, `WithoutOverlapping`, Redis In Production, Never Sync Mailers

A synchronous mailer in a controller is a five-second user-facing latency on a good day and a 30-second timeout on a bad one. Cursor will dispatch jobs synchronously, omit retry strategies, and write handle() methods that crash halfway through with no idempotency guard, leaving the system in an inconsistent state. The rule: every side effect (mail, webhook, third-party API call, image processing) is queued, jobs implement ShouldQueue with explicit tries, backoff, timeout, and a unique-job constraint where appropriate, and handle() is written so the second attempt produces the same outcome as the first.

The rule:

Side effects that are not part of the request's correctness contract
are queued. This includes:
  - Mailers (welcome emails, receipts, notifications).
  - Push notifications, SMS.
  - Webhook deliveries to third parties.
  - Image/video transcoding.
  - PDF generation.
  - Search index updates (Scout already does this if QUEUE_CONNECTION
    is set).
  - Bulk imports / exports.
  - Cache warming.

Synchronous in-request:
  - Reading from cache to render the response.
  - Writing the primary domain model (the order, the post, the comment).
  - Authorization checks.
  - Validation.

Every queued job in app/Jobs/* implements `ShouldQueue` and uses these
traits:
  use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

And declares:
  public int $tries = 5;
  public int $backoff = 30; // or a method returning [10, 30, 60, 300]
  public int $timeout = 120;
  public int $maxExceptions = 3;
  public bool $deleteWhenMissingModels = true;

`uniqueId()` and `ShouldBeUnique` for jobs that must not run twice
simultaneously (sending a welcome email, processing a payment):

  class SendWelcomeEmail implements ShouldQueue, ShouldBeUnique
  {
      public int $uniqueFor = 3600;
      public function uniqueId(): string {
          return "welcome-email:{$this->user->id}";
      }
  }

WithoutOverlapping middleware for jobs that touch shared state
(updating a counter, syncing a single integration):

  public function middleware(): array {
      return [(new WithoutOverlapping($this->order->id))->expireAfter(180)];
  }

`handle()` MUST be idempotent. Patterns:
  - Check current state at the top: `if ($this->order->status->isPaid()) return;`
  - Use `firstOrCreate` / `updateOrCreate` for persistence.
  - Use idempotency keys when calling third-party APIs.
  - Wrap in a DB transaction so partial writes don't survive crashes.

`failed(Throwable $e)` method on every job that has business
implications when it fails — sends a Slack alert, marks a related
record as failed, releases a reservation.

Queue connection: `redis` in production (single-host Redis, or
Horizon-managed). `database` only in dev / for low-volume cron-like
work. `sync` only in tests with `Bus::fake()` / `Queue::fake()`.

Horizon for production: workers, balancing strategy ("auto"), per-queue
process counts, memory limits, retry policies all in
config/horizon.php. Slack notifications on long-waiting queues.

Job batching for fan-out work (process 10K rows): `Bus::batch([...])
->then(fn ($batch) => ...)->dispatch()`. Track progress, send a
notification on completion.

Scheduled jobs in app/Console/Kernel.php with explicit overlap
prevention:
  $schedule->command('reports:nightly')
      ->dailyAt('02:00')
      ->onOneServer()
      ->withoutOverlapping(60)
      ->runInBackground()
      ->emailOutputOnFailure(config('app.ops_email'));

`onQueue('emails')` for routing — high-priority queues processed by
dedicated worker pools.

Encryption of sensitive payloads via `ShouldBeEncrypted` interface for
jobs that serialize tokens / PII into the queue payload.

Never `Mail::to(...)->send(...)` (synchronous). Always
`Mail::to(...)->queue(...)` or implement Mailable as `ShouldQueue`.

Before — sync mail, no retries, no idempotency:

class OrderController
{
    public function store(Request $request)
    {
        $order = Order::create($request->all());
        Mail::to(auth()->user())->send(new OrderConfirmation($order));
        SendToWarehouse::dispatch($order);
        return $order;
    }
}

class SendToWarehouse implements ShouldQueue
{
    public function __construct(public Order $order) {}

    public function handle(WarehouseClient $client): void
    {
        $client->createShipment($this->order->id, $this->order->items);
    }
}

Mail blocks the request. Job has no tries, no timeout, no idempotency — a retry duplicates the warehouse shipment.

After — queued mail, retries with backoff, idempotent handle, unique guard:

// app/Jobs/SendOrderConfirmation.php
namespace App\Jobs;

use App\Mail\OrderConfirmationMail;
use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Mail;

final class SendOrderConfirmation implements ShouldQueue, ShouldBeUnique
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 5;
    public int $timeout = 60;
    public int $maxExceptions = 3;
    public bool $deleteWhenMissingModels = true;
    public int $uniqueFor = 3600;

    public function __construct(public readonly Order $order) {}

    public function uniqueId(): string
    {
        return "order-confirmation:{$this->order->id}";
    }

    public function backoff(): array
    {
        return [10, 30, 60, 300];
    }

    public function handle(): void
    {
        $this->order->refresh();

        if ($this->order->confirmation_sent_at !== null) {
            return; // idempotent
        }

        Mail::to($this->order->user->email)
            ->queue(new OrderConfirmationMail($this->order));

        $this->order->forceFill(['confirmation_sent_at' => now()])->save();
    }

    public function failed(\Throwable $e): void
    {
        report($e);
        $this->order->forceFill(['confirmation_failed_at' => now()])->save();
    }
}

// app/Jobs/SyncToWarehouse.php
final class SyncToWarehouse implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 8;

    public function middleware(): array
    {
        return [(new WithoutOverlapping($this->order->id))->expireAfter(300)];
    }

    public function __construct(public readonly Order $order) {}

    public function handle(WarehouseClient $client): void
    {
        $idempotencyKey = "warehouse:order:{$this->order->id}";
        $client->createShipment($this->order, idempotencyKey: $idempotencyKey);
    }
}

Jobs survive transient warehouse outages. Retries don't double-send the email or duplicate the shipment. The request returns the moment the order is persisted.

Rule 6: API Resources & Typed Responses — `JsonResource` For Every Endpoint, Conditional Fields, OpenAPI Generation

Returning a raw Eloquent model from an API is how your password_hash, remember_token, two_factor_secret, and stripe_customer_id end up in the public response and on a security researcher's blog post. Cursor does this routinely — return $user; is shorter than writing a Resource and the AI optimizes for fewer files. The rule: every API response goes through a JsonResource (or ResourceCollection), the resource controls exactly which fields ship, conditional includes use when() / whenLoaded(), and the OpenAPI spec is generated from typed annotations or scrambled from method signatures.

The rule:

Every JSON API response is wrapped in a JsonResource. Returning a bare
Eloquent model or collection is forbidden:

  // BAD
  return User::find($id);

  // GOOD
  return new UserResource(User::findOrFail($id));

Resources live in app/Http/Resources/<Domain>/<Noun>Resource.php and
extend either:
  - JsonResource — for a single model.
  - ResourceCollection — for a custom collection wrapper.
  - AnonymousResourceCollection (returned by `Resource::collection(...)`)
    — for a list of models with the default wrapper.

Resource shape rules:
  - Whitelist fields. Only declare keys that the API contract documents.
  - Cast types match the cast types on the model. The Resource is the
    contract; the model schema may evolve underneath.
  - Money fields ship as `{ amount_cents: int, currency: string,
    formatted: string }`, never as floats.
  - Datetimes ship as ISO-8601 strings via `->toIso8601String()`.
  - Enums ship as their `->value`, not as objects.

Conditional fields:
  - `whenLoaded('relation')` — include the relation only if eager-loaded.
    Prevents accidental N+1 from a lazy-load inside the resource.
  - `whenCounted('relation')` — include the count only if `withCount`
    was called.
  - `when($condition, fn () => ...)` — include the field only when
    a condition is true (e.g., admin-only fields).
  - `mergeWhen($condition, [...])` — merge a sub-array conditionally.

Resource collections for paginated responses retain the meta envelope:
  return new OrderCollection($orders);

  class OrderCollection extends ResourceCollection {
      public $collects = OrderResource::class;
      public function with($request): array {
          return ['meta' => ['version' => 'v2']];
      }
  }

The default wrapping key is "data". For non-wrapped responses set
`JsonResource::withoutWrapping()` in AppServiceProvider; otherwise
keep the wrap.

Polymorphic relations: dispatch to the right resource via
`MorphResource::make($model)` that returns the appropriate resource
based on the model class.

OpenAPI documentation: either
  - L5-Swagger with annotations on controllers + resources, or
  - Scribe (knuckleswtf/scribe) with reflection + docblocks, or
  - Spectator + handcrafted OpenAPI YAML.
The CI build runs `php artisan scribe:generate` (or equivalent) and
fails if the spec drifts from the routes/controllers.

Versioning: API versions in route prefixes (`/api/v1`, `/api/v2`),
each with its own resources directory (`Resources/V1/`, `Resources/V2/`).
Never version inside a single resource via conditional logic.

Error responses: a single shape across the API.
  { "message": string, "errors"?: { "field": [string, ...] } }
ValidationException auto-renders this; for other exceptions register
custom renderers in app/Exceptions/Handler.php.

HTTP status codes are explicit:
  - 200 GET success
  - 201 POST creating a resource
  - 202 async / queued
  - 204 DELETE / no content
  - 400 client-side malformed
  - 401 unauthenticated
  - 403 unauthorized (use the Policy, see Rule 7)
  - 404 not found (route model binding handles this)
  - 409 conflict (business rule violation, e.g., already-paid order)
  - 422 validation
  - 429 rate limited

Streaming / large downloads: `Response::streamDownload(...)` for CSVs
and reports. Never assemble large strings in memory.

Before — bare model, secrets in the wire format:

public function show(User $user)
{
    return $user->load('orders');
}

password_hash, remember_token, two_factor_secret ship to the client. Lazy-loaded relations on every render.

After — JsonResource with whitelist, conditional includes, typed money:

// app/Http/Resources/V1/UserResource.php
namespace App\Http\Resources\V1;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

final class UserResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'         => $this->id,
            'name'       => $this->name,
            'email'      => $this->email,
            'role'       => $this->role->value,
            'created_at' => $this->created_at->toIso8601String(),
            'orders'     => OrderResource::collection($this->whenLoaded('orders')),
            'orders_count' => $this->whenCounted('orders'),
            'admin_notes'  => $this->when(
                $request->user()?->can('viewAdminNotes', $this->resource),
                fn () => $this->admin_notes,
            ),
        ];
    }
}

// app/Http/Resources/V1/OrderResource.php
final class OrderResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'         => $this->id,
            'status'     => $this->status->value,
            'total'      => [
                'amount_cents' => $this->total_cents,
                'currency'     => $this->currency,
                'formatted'    => Money::cents($this->total_cents, $this->currency)->format(),
            ],
            'placed_at'  => $this->placed_at?->toIso8601String(),
            'items'      => OrderItemResource::collection($this->whenLoaded('items')),
        ];
    }
}

// app/Http/Controllers/Users/ShowUserController.php
final class ShowUserController
{
    public function __invoke(Request $request, User $user): UserResource
    {
        $request->user()->can('view', $user) ?: abort(403);
        return new UserResource(
            $user->loadMissing(['orders'])->loadCount('orders')
        );
    }
}

The wire format is a contract, not a leak. Conditional fields hide admin-only data without a separate endpoint.

Rule 7: Authorization — Policies For Every Model, Gates For Non-Model Checks, `$this->authorize()` Everywhere, Never `if ($user->is_admin)`

Authorization scattered through controllers as if (auth()->user()->is_admin || auth()->user()->id === $order->user_id) is the pattern that survives until one developer forgets it on one endpoint and a regular user starts deleting other users' orders. Cursor produces this every time. The rule: every model has a Policy, every controller calls $this->authorize() (or the Form Request's authorize() method does), non-model permissions live in Gates registered in AppServiceProvider, and route-level guards use middleware (->middleware('can:update,order')).

The rule:

Every Eloquent model that has any access control has a Policy in
app/Policies/<Model>Policy.php, registered in AuthServiceProvider's
$policies array. Policies use the standard ability names:
  - viewAny(User $user): bool
  - view(User $user, Model $model): bool
  - create(User $user): bool
  - update(User $user, Model $model): bool
  - delete(User $user, Model $model): bool
  - restore(User $user, Model $model): bool
  - forceDelete(User $user, Model $model): bool

Plus custom abilities for domain-specific actions:
  - cancel(User $user, Order $order): bool
  - refund(User $user, Order $order): bool

Policy methods return `bool` or `Response` (for denial messages):
  return Response::deny('This order is older than 30 days.');

The `before()` method on a Policy short-circuits for super-admins:
  public function before(User $user, string $ability): ?bool {
      return $user->isPlatformAdmin() ? true : null;
  }
Returning `null` lets the per-method check run.

Authorization in controllers:
  - `$this->authorize('update', $order);` — throws 403 on denial.
  - `$user->can('update', $order)` — boolean, used in conditionals
    and `when()`-conditional resources.
  - `Gate::authorize('update', $order)` — facade form, same behavior.

Authorization in Form Requests' `authorize()` method:
  return $this->user()?->can('create', Order::class) ?? false;

Route-level middleware for whole-resource gates:
  Route::middleware('can:viewAny,App\Models\Order')
      ->get('/orders', IndexOrdersController::class);
  Route::middleware('can:update,order')
      ->patch('/orders/{order}', UpdateOrderController::class);

Non-model abilities (admin dashboard, feature toggles) are Gates
registered in AppServiceProvider::boot():
  Gate::define('access-admin-panel', fn (User $u) => $u->is_admin);
  Gate::define('manage-billing', fn (User $u) => $u->hasRole('billing'));

Forbidden patterns:
  - `if ($user->is_admin)` in controllers — use Gates.
  - `if ($user->id === $model->user_id)` in controllers — use Policies.
  - `auth()->user()->role === 'admin'` — use enum comparison + Gate.
  - Authorization "by hiding the URL" — not authorization.

Multi-tenant authorization: every Policy checks tenant scoping first:
  public function view(User $user, Order $order): bool {
      if ($order->tenant_id !== $user->current_tenant_id) return false;
      return $user->id === $order->user_id || $user->isTenantAdmin();
  }

Or use a global tenant scope on the model so cross-tenant queries
return zero rows; the Policy then only checks per-tenant role.

Roles & permissions: spatie/laravel-permission for any non-trivial
RBAC. Roles assigned via `$user->assignRole('editor')`. Permissions
checked via Gates that delegate to `$user->hasPermissionTo('publish posts')`.

Sanctum / Passport tokens have abilities (scopes); check via
`$request->user()->tokenCan('orders:write')` inside Policies for
machine-to-machine flows.

Audit: every authorization failure logs the user, ability, and target
to a dedicated channel (config/logging.php) so abuse patterns are
visible.

Before — scattered conditionals, no Policy:

public function update(Request $request, Order $order)
{
    if (auth()->user()->id !== $order->user_id && !auth()->user()->is_admin) {
        return response()->json(['error' => 'Forbidden'], 403);
    }
    $order->update($request->all());
    return $order;
}

Authorization repeated everywhere. Mass assigned. Easy to forget on the next endpoint.

After — Policy + authorize() + middleware + Form Request:

// app/Policies/OrderPolicy.php
namespace App\Policies;

use App\Models\Order;
use App\Models\User;
use Illuminate\Auth\Access\Response;

final class OrderPolicy
{
    public function before(User $user, string $ability): ?bool
    {
        return $user->isPlatformAdmin() ? true : null;
    }

    public function view(User $user, Order $order): bool
    {
        return $user->id === $order->user_id;
    }

    public function update(User $user, Order $order): Response
    {
        if ($user->id !== $order->user_id) {
            return Response::deny('Not your order.');
        }
        if ($order->status->isShipped()) {
            return Response::deny('Cannot modify a shipped order.');
        }
        return Response::allow();
    }

    public function cancel(User $user, Order $order): Response
    {
        return $this->update($user, $order)
            ->merge($order->placed_at->diffInHours() < 24
                ? Response::allow()
                : Response::deny('Cancellation window has closed.'));
    }
}

// app/Providers/AuthServiceProvider.php
protected $policies = [
    Order::class => OrderPolicy::class,
];

// routes/api.php
Route::middleware(['auth:sanctum', 'can:update,order'])
    ->patch('/orders/{order}', UpdateOrderController::class);

// app/Http/Controllers/Orders/UpdateOrderController.php
final class UpdateOrderController
{
    public function __invoke(
        UpdateOrderRequest $request,
        Order $order,
        UpdateOrder $action,
    ): OrderResource {
        // can:update middleware already ran; defense-in-depth:
        $this->authorize('update', $order);
        $order = $action($order, $request->toDto());
        return new OrderResource($order);
    }
}

One source of truth for authorization. Reusable across HTTP, console, and event listeners. Denial reasons surface to the client.

Rule 8: Testing — Pest By Default, `RefreshDatabase`, Factories With States, `Bus::fake()` / `Queue::fake()` / `Mail::fake()`, Parallel Testing

Cursor will write PHPUnit-style tests with setUp() boilerplate, real Mailgun calls in CI, and assertions against the entire JSON response with assertJsonStructure brittle to any field addition. The rule: Pest is the default for new tests, every test extends a base TestCase with RefreshDatabase, factories define the canonical model shape with named states for variations, every test that dispatches jobs / events / mail uses the appropriate fake() and asserts against it, and the suite runs in parallel via php artisan test --parallel.

The rule:

Pest is the default test framework for new code (pestphp/pest +
pestphp/pest-plugin-laravel). PHPUnit tests are migrated on touch.

Test directory structure:
  tests/Unit/           — pure PHP unit tests, no Laravel app.
  tests/Feature/        — full HTTP / app boot, DB enabled.
  tests/Browser/        — Dusk (only when needed).
  tests/Pest.php        — global hooks (uses() registrations).

Pest.php registers global traits:
  uses(Tests\TestCase::class, Illuminate\Foundation\Testing\RefreshDatabase::class)
      ->in('Feature');

Feature tests use `RefreshDatabase` for transactional isolation. The
SQLite in-memory connection in CI:
  - DB_CONNECTION=sqlite, DB_DATABASE=:memory:
  - or a dedicated test Postgres for tests that depend on Postgres-only
    features (JSON ops, full-text, cursor pagination over composite
    keys).

Model factories in database/factories/* define the canonical shape and
named states for variations:

  class OrderFactory extends Factory {
      public function definition(): array {
          return [
              'user_id'     => User::factory(),
              'total_cents' => $this->faker->numberBetween(1000, 50000),
              'currency'    => 'USD',
              'status'      => OrderStatus::Pending,
              'placed_at'   => $this->faker->dateTimeBetween('-30 days'),
          ];
      }
      public function paid(): static {
          return $this->state(['status' => OrderStatus::Paid, 'paid_at' => now()]);
      }
      public function shipped(): static {
          return $this->state(['status' => OrderStatus::Shipped, 'shipped_at' => now()]);
      }
  }

Tests construct fixtures through factories, never raw `Model::create([...])`
inside a test:
  Order::factory()->paid()->for($user)->has(Item::factory()->count(3))->create();

HTTP tests via the Pest fluent API:
  it('creates an order', function () {
      $user = User::factory()->create();
      Bus::fake();

      $response = $this->actingAs($user)->postJson('/api/orders', [
          'product_ids' => [1, 2],
          'shipping_address_id' => 5,
          'currency' => 'USD',
      ]);

      $response->assertCreated()->assertJsonPath('data.status', 'pending');
      $this->assertDatabaseHas('orders', ['user_id' => $user->id, 'status' => 'pending']);
      Bus::assertDispatched(SyncToWarehouse::class, fn ($job) => $job->order->user_id === $user->id);
  });

Side-effect fakes are mandatory:
  - `Bus::fake()` before any code that dispatches jobs; assert via
    `Bus::assertDispatched(JobClass::class, $callback)`.
  - `Queue::fake()` for direct queue pushes.
  - `Mail::fake()` then `Mail::assertQueued(MailableClass::class, $callback)`.
  - `Notification::fake()` then `Notification::assertSentTo($user, ...)`.
  - `Event::fake([OrderPlaced::class])` to selectively fake only some
    events while others continue firing.
  - `Http::fake([...])` for outbound HTTP — never let tests hit real
    third parties.
  - `Storage::fake('s3')` for file uploads.

Database assertions:
  - `assertDatabaseHas('table', [...])` / `assertDatabaseMissing(...)`.
  - `assertDatabaseCount('table', n)`.
  - `assertModelExists($model)` / `assertModelMissing($model)`.
  - `assertSoftDeleted($model)`.

JSON response assertions:
  - `assertJsonPath('data.id', 5)` for pinpoint asserts.
  - `assertJsonStructure([...])` for shape.
  - `assertExactJson([...])` only for tiny responses; brittle for
    larger ones.
  - For complex shapes use a snapshot (spatie/pest-plugin-snapshots).

Authentication: `actingAs($user)` for session; `actingAs($user,
'sanctum')` for token-scoped tests; `Sanctum::actingAs($user, ['orders:write'])`
for ability-scoped tests.

Architecture tests via Pest's `arch()`:
  arch('controllers are thin')
      ->expect('App\Http\Controllers')
      ->toUseStrictTypes()
      ->and('App\Http\Controllers')
      ->classes()
      ->toHaveMethod('__invoke')
      ->ignoring(['App\Http\Controllers\Controller']);

Datasets for parameterized tests:
  it('rejects invalid currency', function (string $bad) {
      // ...
  })->with(['XYZ', '', 'us', '12345']);

Parallel testing: `php artisan test --parallel` with paratest. Tests
must be isolation-safe — no shared state, no order dependencies, no
hardcoded IDs.

CI: GitHub Actions matrix on PHP 8.3 / 8.4, Postgres + Redis services,
artisan test --parallel --coverage with a 80% threshold on app/.
Larastan level 8 in the same workflow.

Coverage targets:
  - Actions / Services: >90% line coverage.
  - Form Requests: every rule has a passing + failing case.
  - Policies: every method has an allowed + denied case.
  - Resources: at least one shape test (snapshot acceptable).
  - Controllers: covered transitively by Feature tests.

Before — PHPUnit boilerplate, real mail, brittle assertions:

class OrderControllerTest extends TestCase
{
    public function test_creates_order()
    {
        $user = factory(User::class)->create();
        $this->actingAs($user);
        $response = $this->postJson('/api/orders', [
            'product_ids' => [1, 2], 'address_id' => 1,
        ]);
        $response->assertStatus(200);
        $this->assertEquals(1, Order::count());
    }
}

Real mail fires. No transaction wrap. Brittle assertion on count.

After — Pest, fakes, factories with states, structured asserts:

// tests/Feature/Orders/CreateOrderTest.php
use App\Jobs\SyncToWarehouse;
use App\Mail\OrderConfirmationMail;
use App\Models\Address;
use App\Models\Product;
use App\Models\User;
use Illuminate\Support\Facades\Bus;
use Illuminate\Support\Facades\Mail;

beforeEach(function () {
    Bus::fake();
    Mail::fake();
});

it('creates an order for the authenticated user', function () {
    $user = User::factory()->create();
    $address = Address::factory()->for($user)->create();
    $products = Product::factory()->count(3)->inStock()->create();

    $response = $this->actingAs($user)->postJson('/api/orders', [
        'product_ids'         => $products->pluck('id')->all(),
        'shipping_address_id' => $address->id,
        'currency'            => 'USD',
    ]);

    $response
        ->assertCreated()
        ->assertJsonPath('data.status', 'pending')
        ->assertJsonStructure(['data' => ['id', 'status', 'total' => ['amount_cents', 'currency', 'formatted']]]);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
        'status'  => 'pending',
    ]);
    $this->assertDatabaseCount('order_items', 3);

    Bus::assertDispatched(SyncToWarehouse::class, fn ($j) => $j->order->user_id === $user->id);
    Mail::assertNothingQueued(); // confirmation queued by job, not request
});

it('forbids creating an order with another user\'s address', function () {
    $user  = User::factory()->create();
    $other = User::factory()->create();
    $alien = Address::factory()->for($other)->create();
    $product = Product::factory()->inStock()->create();

    $response = $this->actingAs($user)->postJson('/api/orders', [
        'product_ids'         => [$product->id],
        'shipping_address_id' => $alien->id,
        'currency'            => 'USD',
    ]);

    $response->assertUnprocessable()->assertJsonValidationErrorFor('shipping_address_id');
});

it('rejects unauthenticated requests', function () {
    $this->postJson('/api/orders', [])->assertUnauthorized();
});

// tests/Unit/Actions/CreateOrderTest.php — pure logic, no HTTP
it('creates the order inside a transaction', function () {
    $action = app(CreateOrder::class);
    $user = User::factory()->create();
    $address = Address::factory()->for($user)->create();
    $products = Product::factory()->count(2)->inStock()->create();

    $order = $action(new OrderInput(
        userId: $user->id,
        productIds: $products->pluck('id')->all(),
        shippingAddressId: $address->id,
        currency: Currency::USD,
        notes: null,
    ));

    expect($order)->toBeInstanceOf(Order::class)
        ->status->toBe(OrderStatus::Pending)
        ->items->toHaveCount(2);
});

Tests are fast, deterministic, parallelizable. Side effects are asserted, not executed. Factory states make intent clear.

The Complete `.cursorrules` File

Drop this in the repo root. Cursor and Claude Code both pick it up.

# Laravel 11/12 — Production Patterns

## Models
- Explicit $fillable; $guarded = [] is forbidden.
- $casts for every non-string column, including enums.
- $hidden for secrets (password, remember_token, api_token, stripe_*).
- Accessors/mutators via Attribute::make() — never getFooAttribute().
- Model events in app/Observers/*Observer.php, registered in
  AppServiceProvider; boot() reserved for global scopes.
- Relationships have explicit return types (BelongsTo, HasMany, ...).
- Enum-backed columns via PHP 8.1+ enums.
- preventLazyLoading + preventSilentlyDiscardingAttributes +
  preventAccessingMissingAttributes in dev/test.
- Soft deletes only when business explicitly needs undelete.

## Controllers & Actions
- Single-action invokable controllers for non-trivial endpoints.
- Controller body: <=15 lines, no DB, no business logic, no mailers.
- Business logic in app/Actions/<Domain>/<Verb><Noun>.php — final
  readonly classes, accept typed DTOs, return models/DTOs.
- Resourceful controllers acceptable for 1-3 line CRUD methods.
- Routes use [Controller::class, 'method'] or Controller::class.
- String 'X@y' callables are forbidden.
- Route model binding for lookups.

## Validation
- Every input endpoint has a FormRequest in app/Http/Requests/...
- Inline $request->validate([...]) is forbidden.
- authorize() does the policy check; never `return true;`.
- Rules in array form ['required','string'] — never pipe strings.
- Custom rules as ValidationRule objects in app/Rules/*.
- toDto() converts validated input to a typed DTO; controller passes
  DTO to Action.
- Cross-field rules in withValidator(); normalization in
  prepareForValidation().

## Queries
- preventLazyLoading enforced in dev; opt-out requires justification.
- with([...]) on every query whose results are iterated.
- Constrained eager loads via closure; withCount/withExists for counts
  and existence checks.
- select() specific columns when consumer uses <half the row.
- Query scopes for any pattern reused >=2 times; global scopes for
  tenancy.
- DB::raw with string concatenation is forbidden; whereRaw with
  bindings only.
- Full-text via Scout, never LIKE concat.
- Pagination: paginate / cursorPaginate / simplePaginate by use case.
- Large sets: chunk / chunkById / lazy / cursor by tradeoff.
- Migrations declare indexes for WHERE/ORDER BY/JOIN columns.
- Multi-write ops in DB::transaction(fn () => ...).

## Queues & Jobs
- Side effects (mail, webhooks, third-party APIs, transcoding,
  search index, bulk imports) are queued.
- Mailers: ->queue(...), or Mailable implements ShouldQueue. Never
  ->send(...) for transactional mail.
- Every job: ShouldQueue + tries + backoff (array for tiered) +
  timeout + maxExceptions + deleteWhenMissingModels.
- ShouldBeUnique + uniqueId() for jobs that must not run twice.
- WithoutOverlapping middleware for shared-state jobs.
- handle() is idempotent: state-check at top, firstOrCreate /
  updateOrCreate, idempotency keys for third parties.
- failed(Throwable) on jobs with business consequences.
- Production queue: redis (Horizon-managed). database only in dev /
  low volume. sync only with Bus::fake/Queue::fake.
- onQueue('emails') for per-queue routing; dedicated worker pools.
- Bus::batch for fan-out work with progress.
- Scheduled tasks: onOneServer + withoutOverlapping + runInBackground.

## API Resources
- Every API response is a JsonResource / ResourceCollection. Bare
  models forbidden.
- Resources whitelist fields; types match model casts.
- Money: { amount_cents, currency, formatted }. Datetimes: ISO-8601.
  Enums: ->value.
- Conditional includes: whenLoaded / whenCounted / when / mergeWhen.
- Polymorphic via MorphResource that dispatches to the right resource.
- API versioned via route prefixes and Resources/V1 / Resources/V2
  directories.
- Error response shape: { message, errors? }; consistent across all
  endpoints.
- Status codes explicit and correct (200/201/202/204/400/401/403/404/
  409/422/429).
- OpenAPI spec generated by Scribe / L5-Swagger; CI fails on drift.
- Streaming downloads via Response::streamDownload.

## Authorization
- Every model with access control has a Policy in app/Policies/...
- Standard ability names + custom abilities (cancel, refund, ...).
- Policies return bool or Response (with deny messages).
- before() short-circuits for platform admins.
- $this->authorize() in controllers; can:ability,model middleware on
  routes; FormRequest::authorize() for early rejection.
- Non-model abilities as Gates registered in AppServiceProvider.
- Scattered if-conditionals (is_admin, user_id checks) forbidden.
- Multi-tenant: Policy or global scope checks tenant_id first.
- Spatie/laravel-permission for any non-trivial RBAC.
- Sanctum/Passport token abilities checked via tokenCan() inside
  Policies.

## Testing
- Pest is the default for new tests; PHPUnit migrated on touch.
- Feature tests use RefreshDatabase; SQLite :memory: or dedicated
  Postgres for Postgres-only features.
- Factories define canonical shape; named states for variations.
- Bus::fake / Queue::fake / Mail::fake / Notification::fake /
  Event::fake / Http::fake / Storage::fake mandatory before code
  that dispatches.
- assertDatabaseHas / assertModelExists / assertSoftDeleted for DB
  state.
- assertJsonPath for pinpoint; assertJsonStructure for shape;
  snapshots for large bodies.
- Sanctum::actingAs for token + abilities.
- Architecture tests via arch() (controllers thin, actions invokable,
  no facades in Domain).
- Datasets for parameterized cases.
- php artisan test --parallel; tests isolation-safe.
- CI: matrix on PHP 8.3/8.4, Postgres+Redis services, --parallel
  --coverage 80% min, Larastan level 8.

End-to-End Example: Posting a Comment On A Blog Post

Without rules: fat controller, mass-assigned, sync mail, raw model in response, no test.

class CommentController extends Controller
{
    public function store(Request $request, $postId)
    {
        $request->validate(['body' => 'required|string']);
        $post = Post::findOrFail($postId);
        if (!auth()->check()) abort(401);
        $comment = Comment::create([
            'post_id' => $post->id,
            'user_id' => auth()->id(),
            'body'    => $request->body,
        ]);
        Mail::to($post->author->email)->send(new NewCommentMail($comment));
        return response()->json($comment->load('user'));
    }
}

With rules: invokable controller, Form Request, Action, queued mail, Resource, Policy, Pest tests.

// routes/api.php
Route::middleware(['auth:sanctum', 'can:comment,post'])
    ->post('/posts/{post}/comments', PostCommentController::class)
    ->name('posts.comments.store');

// app/Http/Controllers/Comments/PostCommentController.php
namespace App\Http\Controllers\Comments;

use App\Actions\Comments\PostComment;
use App\Http\Requests\Comments\PostCommentRequest;
use App\Http\Resources\V1\CommentResource;
use App\Models\Post;

final class PostCommentController
{
    public function __invoke(
        PostCommentRequest $request,
        Post $post,
        PostComment $action,
    ): CommentResource {
        $comment = $action($post, $request->toDto());
        return new CommentResource($comment);
    }
}

// app/Http/Requests/Comments/PostCommentRequest.php
namespace App\Http\Requests\Comments;

use App\DataObjects\CommentInput;
use App\Models\Post;
use Illuminate\Foundation\Http\FormRequest;

final class PostCommentRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()?->can('comment', $this->route('post')) ?? false;
    }

    public function rules(): array
    {
        return [
            'body'      => ['required', 'string', 'min:2', 'max:2000'],
            'parent_id' => ['nullable', 'integer', 'exists:comments,id'],
        ];
    }

    public function toDto(): CommentInput
    {
        $v = $this->validated();
        return new CommentInput(
            userId:   $this->user()->id,
            body:     trim($v['body']),
            parentId: $v['parent_id'] ?? null,
        );
    }
}

// app/DataObjects/CommentInput.php
namespace App\DataObjects;

final readonly class CommentInput
{
    public function __construct(
        public int $userId,
        public string $body,
        public ?int $parentId,
    ) {}
}

// app/Actions/Comments/PostComment.php
namespace App\Actions\Comments;

use App\DataObjects\CommentInput;
use App\Events\CommentPosted;
use App\Models\Comment;
use App\Models\Post;
use Illuminate\Contracts\Events\Dispatcher;
use Illuminate\Support\Facades\DB;

final readonly class PostComment
{
    public function __construct(private Dispatcher $events) {}

    public function __invoke(Post $post, CommentInput $input): Comment
    {
        return DB::transaction(function () use ($post, $input) {
            $comment = $post->comments()->create([
                'user_id'   => $input->userId,
                'body'      => $input->body,
                'parent_id' => $input->parentId,
            ]);
            $this->events->dispatch(new CommentPosted($comment));
            return $comment->load('user:id,name');
        });
    }
}

// app/Listeners/NotifyAuthorOfNewComment.php
namespace App\Listeners;

use App\Events\CommentPosted;
use App\Jobs\SendNewCommentEmail;

final class NotifyAuthorOfNewComment
{
    public function handle(CommentPosted $event): void
    {
        if ($event->comment->user_id === $event->comment->post->user_id) {
            return; // don't notify the author of their own comment
        }
        SendNewCommentEmail::dispatch($event->comment);
    }
}

// app/Jobs/SendNewCommentEmail.php
namespace App\Jobs;

use App\Mail\NewCommentMail;
use App\Models\Comment;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Mail;

final class SendNewCommentEmail implements ShouldQueue, ShouldBeUnique
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 5;
    public int $timeout = 30;
    public int $uniqueFor = 600;

    public function __construct(public readonly Comment $comment) {}

    public function uniqueId(): string
    {
        return "new-comment-mail:{$this->comment->id}";
    }

    public function backoff(): array
    {
        return [10, 30, 60, 120, 300];
    }

    public function handle(): void
    {
        $this->comment->loadMissing('post.author');

        Mail::to($this->comment->post->author->email)
            ->queue(new NewCommentMail($this->comment));
    }
}

// app/Policies/PostPolicy.php
final class PostPolicy
{
    public function comment(User $user, Post $post): Response
    {
        if ($post->comments_locked) return Response::deny('Comments are closed.');
        if ($user->is_banned) return Response::deny('Your account is suspended.');
        return Response::allow();
    }
}

// app/Http/Resources/V1/CommentResource.php
final class CommentResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'         => $this->id,
            'body'       => $this->body,
            'parent_id'  => $this->parent_id,
            'created_at' => $this->created_at->toIso8601String(),
            'author'     => [
                'id'   => $this->user->id,
                'name' => $this->user->name,
            ],
        ];
    }
}

// tests/Feature/Comments/PostCommentTest.php
use App\Jobs\SendNewCommentEmail;
use App\Models\Post;
use App\Models\User;
use Illuminate\Support\Facades\Bus;

beforeEach(fn () => Bus::fake());

it('lets an authenticated user post a comment on an open post', function () {
    $user = User::factory()->create();
    $post = Post::factory()->create();

    $response = $this->actingAs($user)->postJson("/api/posts/{$post->id}/comments", [
        'body' => 'Great post!',
    ]);

    $response->assertCreated()->assertJsonPath('data.body', 'Great post!');
    $this->assertDatabaseHas('comments', ['post_id' => $post->id, 'user_id' => $user->id]);
    Bus::assertDispatched(SendNewCommentEmail::class);
});

it('rejects comments on locked posts', function () {
    $user = User::factory()->create();
    $post = Post::factory()->create(['comments_locked' => true]);

    $this->actingAs($user)
        ->postJson("/api/posts/{$post->id}/comments", ['body' => 'Hi'])
        ->assertForbidden();

    Bus::assertNotDispatched(SendNewCommentEmail::class);
});

it('does not notify the author of their own comment', function () {
    $author = User::factory()->create();
    $post   = Post::factory()->for($author, 'author')->create();

    $this->actingAs($author)
        ->postJson("/api/posts/{$post->id}/comments", ['body' => 'self'])
        ->assertCreated();

    // Listener returns early; no job dispatched
    Bus::assertNotDispatched(SendNewCommentEmail::class);
});

Thin controller, typed DTO, single Action, queued mailer with retries, policy-gated, resource-shaped response, Pest tests asserting both the success path and the locked-post / self-comment edge cases.

Get the Full Pack

These eight rules cover the Laravel patterns where AI assistants consistently reach for the wrong idiom. Drop them into .cursorrules and the next prompt you write will look different — fillable-explicit, action-driven, FormRequest-validated, eager-loaded, queue-disciplined, resource-wrapped, policy-gated, Pest-tested Laravel, without having to re-prompt.

If you want the expanded pack — these eight plus rules for Livewire 3 component architecture (full-page components, computed properties, event dispatch, lifecycle hooks), Filament 3 admin panels (Resource definitions, Form/Table builders, custom actions, RelationManagers), Inertia.js with Vue/React adapters (typed page props, shared data, partial reloads), advanced Pest patterns (architecture tests, datasets, custom expectations, parallel-safe seeding), Octane deployment (Swoole/RoadRunner state hygiene, container singletons, request lifecycle pitfalls), broadcasting with Reverb (channel auth, presence channels, private channel scoping), queue tuning (Horizon balancing, supervisor configs, memory limits, --max-jobs rotation), multi-tenancy (Tenancy for Laravel, single- vs multi-database, tenant-scoped Policies, queue isolation), Sanctum & Passport token strategies, Eloquent performance (chunkById vs cursor vs lazy benchmarks, raw query escape hatches with parameter binding), Volt single-file components, FluxUI / Alpine integrations, the deploy patterns I use for Laravel on Forge + Vapor, and the Larastan + Rector + Pint configuration that catches AI mistakes before code review — it is bundled in Cursor Rules Pack v2 ($27, one payment, lifetime updates). Drop it in your repo, stop fighting your AI, ship Laravel you would actually merge.

Cursor Rules for Kubernetes: AI-Assisted K8s Guide 2026

Olivia Craft — Sun, 26 Apr 2026 09:57:11 +0000

Kubernetes is the platform where a single missing line in a YAML file can take down every pod in a namespace, silently OOM-kill a service for three weeks before anyone notices the spike in 5xxs, or expose the production Postgres password in a ConfigMap that ships to every region. The manifest renders. kubectl apply returns deployment.apps/api configured. The pods go Running. Six hours later the node runs out of memory because nothing set a limit, the readiness probe passes immediately because someone copied a httpGet: / from a tutorial and / returns 200 even when the downstream database is on fire, and the rollout that was supposed to be zero-downtime dumps every in-flight request because there's no PodDisruptionBudget and the cluster autoscaler drained the node during peak traffic.

Then you add an AI assistant.

Cursor and Claude Code were trained on a decade of Kubernetes YAML, most of it blog-post snippets that predate best practices — image: nginx:latest with no digest, Deployment manifests with no resources: block, Service objects that expose type: LoadBalancer to the open internet, Secret data inlined in the repo as base64 (which is not encryption), kubectl apply -f . from a developer laptop instead of a GitOps pipeline, securityContext missing entirely so containers run as root with every Linux capability, livenessProbe and readinessProbe configured identically so a flap in one restarts the pod instead of pulling it out of the service, and namespaces with no NetworkPolicy so every pod can talk to every other pod in the cluster. Ask for "a Deployment for my Node API," and you get a manifest that works on minikube and detonates in production the first time a node reboots.

The fix is .cursorrules — one file in the repo that tells the AI what idiomatic, production-grade Kubernetes looks like. Eight rules below, each with the failure mode, the rule that prevents it, and a before/after. Copy-paste .cursorrules at the end. Examples target modern Kubernetes (1.28+) with standard tooling (kubectl, Helm, Kustomize, Argo CD), but the rules apply equally to EKS, GKE, AKS, and self-managed clusters.

How Cursor Rules Work for Kubernetes Projects

Cursor reads project rules from two locations: .cursorrules (a single file at the repo root, still supported) and .cursor/rules/*.mdc (modular files with frontmatter, recommended for any non-trivial cluster repo). For Kubernetes I recommend modular rules so that platform-level conventions (RBAC, NetworkPolicy) don't bleed into application-level manifests, and so Helm chart authoring rules don't fire when you're editing raw YAML:

.cursor/rules/
  k8s-manifests.mdc      # Deployment, Service, Ingress conventions
  k8s-resources.mdc      # requests, limits, QoS, HPA, VPA
  k8s-probes.mdc         # liveness, readiness, startup probe discipline
  k8s-security.mdc       # securityContext, PSA, NetworkPolicy, RBAC
  k8s-secrets.mdc        # external secret managers, sealed secrets
  k8s-rollout.mdc        # strategy, PDB, surge, unavailable, maxReplicas
  k8s-observability.mdc  # labels, logs, metrics, namespaces
  k8s-gitops.mdc         # no kubectl apply in prod, Argo/Flux patterns

Frontmatter controls activation: globs: ["**/*.yaml", "**/*.yml", "**/Chart.yaml", "**/kustomization.yaml"] with alwaysApply: false. Now the rules.

Rule 1: Declarative GitOps — Never kubectl apply Against Production

The single most common AI failure in Kubernetes is "here's the kubectl command to deploy it." Cursor cheerfully emits kubectl apply -f deployment.yaml or kubectl edit deploy api and calls that a deployment strategy. It is not. It is an imperative change that leaves no audit trail, drifts from the repo within hours, and means the cluster state is whatever the last sleepy human typed at 3am. Production Kubernetes runs one way: the git repo is the source of truth, a controller (Argo CD, Flux) reconciles the cluster to the repo, and humans never touch the cluster directly except to observe it.

The rule:

Every resource in a non-dev cluster has a manifest in git, reconciled
by a GitOps controller (Argo CD, Flux). Drift is auto-healed or alerted.

Forbidden in production: kubectl apply / create / edit / patch / scale /
delete, and helm install/upgrade from a developer laptop.
Allowed: kubectl get / describe / logs / top / exec / rollout status /
port-forward — all read-only.

Every manifest includes the six recommended labels
(app.kubernetes.io/{name,instance,version,component,part-of,managed-by})
and omits server-populated fields (status, clusterIP, nodeName).

CI runs kubeconform, kube-linter, and a dry-run diff on every PR.

Bad — imperative commands, no audit trail, drift from repo:

kubectl create deployment api --image=myregistry/api:latest
kubectl scale deployment api --replicas=5
# Two weeks later
kubectl edit deployment api              # bumps memory — never recorded
kubectl set image deployment/api api=myregistry/api:v1.4.3

Six months later, nobody knows what's in the cluster. The repo's deployment.yaml still says replicas: 3 and image: myregistry/api:v1.2.0.

Good — declarative manifest committed to the repo, synced by Argo CD:

# argocd/applications/api.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: api-production
  namespace: argocd
spec:
  project: payments
  source:
    repoURL: https://github.com/acme/infra
    targetRevision: main
    path: apps/api/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: payments
  syncPolicy:
    automated: { prune: true, selfHeal: true }
    syncOptions: [ServerSideApply=true]

The image bump from 1.4.3 to 1.4.4 is a PR. The replica increase from 5 to 8 is a PR. The rollback is git revert. The cluster matches the repo at every moment, and the history of every change is in git log.

Rule 2: Resource Requests and Limits — On Every Container, No Exceptions

A Deployment with no resources: block is a loaded gun pointed at your cluster. Without requests, the scheduler places the pod on any node that fits physically, with no room for the workload — so three pods pile onto one node, all thrash for CPU, and latency triples. Without limits, a single misbehaving pod allocates until the kernel OOM-killer fires, and the killer rarely picks the process you'd prefer. AI models skip resources entirely because half of their training data is "hello world" manifests and the other half is copy-pasted from the same tutorial where somebody set memory: 2Gi and never revisited it.

The rule:

Every container (including init and sidecar) in every Deployment,
StatefulSet, DaemonSet, Job, or CronJob MUST set:
  resources.requests.cpu
  resources.requests.memory
  resources.limits.memory

resources.limits.cpu is optional on latency-sensitive services
(CPU throttling hurts p99 tail latency). Set it for batch/offline
workloads that shouldn't disturb neighbors.

Choosing values:
  - Start from p99 under load + 20% headroom.
  - Memory request == memory limit (Guaranteed QoS): the pod is not
    evicted first under node pressure.
  - CPU request matches steady-state, not peak.

Forbidden: omitting resources, burstable memory (request < limit on
latency-sensitive services), or "looked fine on my laptop" guesses.

Every namespace has a LimitRange (defaults) and a ResourceQuota (cap).

Bad — no resources, scheduler and kernel decide the outcome:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: api
          image: myregistry/api:v1.4.3
          ports:
            - containerPort: 8080

Best Effort QoS. First to be evicted under any node pressure. Nothing stops a memory leak from eating the whole node.

Good — explicit requests and limits, Guaranteed QoS on memory:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: payments
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: api
          image: myregistry/api@sha256:c2f7b8a9...
          resources:
            requests:
              cpu: "500m"
              memory: "512Mi"
            limits:
              memory: "512Mi"  # == request for Guaranteed memory QoS
              # no cpu limit — CPU throttling hurts tail latency
          ports:
            - containerPort: 8080

# namespaces/payments/limitrange.yaml — enforces defaults cluster-wide
apiVersion: v1
kind: LimitRange
metadata:
  name: default-limits
  namespace: payments
spec:
  limits:
    - type: Container
      default:
        memory: "256Mi"
      defaultRequest:
        cpu: "100m"
        memory: "256Mi"
      max:
        cpu: "4"
        memory: "8Gi"

Now a manifest without resources: inherits sensible defaults, and one that tries to request 32 cores is rejected at the API server.

Rule 3: Probes — Liveness, Readiness, and Startup, Each Tuned for Its Job

livenessProbe and readinessProbe do different things, and AI-generated manifests almost always configure them identically (or both to httpGet: /). This is actively harmful. The liveness probe decides "restart this container"; the readiness probe decides "pull this pod out of the Service." If they check the same endpoint with the same thresholds, a downstream database blip restarts a pod that would have recovered in five seconds, and a slow-booting pod gets traffic before it's ready. Startup probes (added in 1.16) solve the "my JVM takes 45 seconds to warm up" problem that otherwise forces you to set a useless initialDelaySeconds: 60 on liveness.

The rule:

Every traffic-serving container has THREE probes with THREE jobs:
  - readinessProbe /readyz — "should this pod receive traffic?"
      May check downstream deps (DB, cache) with short timeouts.
      Failure removes the pod from Service endpoints.
  - livenessProbe /livez — "should this container be restarted?"
      In-process check only. NEVER checks downstream deps —
      a DB blip must not restart every pod in a loop.
  - startupProbe — "has the app booted?" Liveness and readiness
      don't evaluate until startup succeeds. Prefer this over
      livenessProbe.initialDelaySeconds for slow boots.

Tuning: readiness fast (period 5-10s, threshold 2-3); liveness slow
(period 10-30s, threshold 3-5); startup's period * threshold covers
expected max boot time. timeoutSeconds 1-2 for cheap checks.

Never: same endpoint for liveness and readiness; exec probes that fork
a shell; omitting probes because "the process exits on failure"
(containers hang more often than they exit cleanly).

Bad — liveness and readiness identical, checks database, no startup probe:

containers:
  - name: api
    image: myregistry/api@sha256:...
    livenessProbe:
      httpGet:
        path: /
        port: 8080
      initialDelaySeconds: 60  # hacky — masks slow boot
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /
        port: 8080
      initialDelaySeconds: 60
      periodSeconds: 10

/ probably returns 200 even when the app is broken. The 60-second delay hides slow boots. A database glitch restarts every pod in a loop.

Good — three probes, each doing one job:

containers:
  - name: api
    image: myregistry/api@sha256:...
    startupProbe:
      httpGet:
        path: /livez
        port: 8080
      periodSeconds: 5
      failureThreshold: 12  # up to 60s to start
    livenessProbe:
      httpGet:
        path: /livez
        port: 8080
      periodSeconds: 20
      timeoutSeconds: 2
      failureThreshold: 3   # ~60s to declare unhealthy
    readinessProbe:
      httpGet:
        path: /readyz        # checks DB + cache reachability
        port: 8080
      periodSeconds: 5
      timeoutSeconds: 2
      failureThreshold: 2

// /livez — in-process only. Cheap. Doesn't depend on anything external.
http.HandleFunc("/livez", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
})

// /readyz — actually verify we can serve a request.
http.HandleFunc("/readyz", func(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 500*time.Millisecond)
    defer cancel()
    if err := db.PingContext(ctx); err != nil {
        http.Error(w, "db unavailable", http.StatusServiceUnavailable)
        return
    }
    if err := cache.PingContext(ctx); err != nil {
        http.Error(w, "cache unavailable", http.StatusServiceUnavailable)
        return
    }
    w.WriteHeader(http.StatusOK)
})

Now a DB outage removes the pod from the Service (readiness fails) but doesn't restart it in a loop (liveness still passes). Startup is bounded at ~60s without hacky delays.

Rule 4: Image Pinning — By Digest, Not Tag, Never :latest

image: myregistry/api:latest is the most common way AI-generated manifests ship a broken pod at 2am. The tag is mutable — whoever pushed last wins, and the pod that restarts at 2am runs a different binary than the pod that started at 4pm. imagePullPolicy: Always makes it worse by pulling on every restart. Even semantic tags (:v1.4.3) can be retagged at the registry. The only way to know what's running is to pin by digest (@sha256:...), which is what OCI guarantees is immutable.

The rule:

Production manifests pin images BY DIGEST:
  image: myregistry/api@sha256:c2f7b8a9d...

Semantic tags are acceptable in dev overlays; production overlays
resolve to a digest. :latest and no-tag references are forbidden
outside developer sandboxes.

imagePullPolicy: IfNotPresent when digest-pinned (immutable content
means no reason to re-pull). `Always` with a mutable tag re-pulls
on every restart and may fetch a different binary.

Supply chain: all production images come from a private registry,
are scanned (Trivy, Grype) and signed (Cosign). Kyverno or Gatekeeper
rejects unsigned images at admission. Use renovate + a digest resolver
to bump tag and digest in lockstep on PRs.

Prefer workload identity (IRSA on EKS, Workload Identity on GKE) to
imagePullSecrets for private-registry auth.

Bad — mutable tag, pulls every restart, no supply-chain check:

spec:
  containers:
    - name: api
      image: myregistry/api:latest
      imagePullPolicy: Always

Good — digest-pinned, supply-chain gated:

spec:
  containers:
    - name: api
      # Source image: myregistry/api:v1.4.3
      # Digest resolved at release time; updated via renovate PR.
      image: myregistry/api@sha256:c2f7b8a9d4e1f5a2b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b
      imagePullPolicy: IfNotPresent

A Kyverno ClusterPolicy with verifyImages matching myregistry/* and your Cosign public key rejects any unsigned image at admission. Now you know exactly which bytes are running, and the cluster refuses to run anything that wasn't signed by your release pipeline.

Rule 5: Security Context — Non-Root, Read-Only Root Filesystem, Drop Capabilities

A Kubernetes pod with no securityContext runs as root with every Linux capability, writable root filesystem, and no seccomp profile. That's the default because Kubernetes values backwards compatibility; it is not the setting you want in production. AI models happily generate manifests without a security context because most tutorials skip it. The pod runs fine — until the first CVE in a base image turns a read vulnerability into a container escape.

The rule:

Every Pod has a restrictive pod-level securityContext; every container
tightens it further. Baseline (Pod Security Admission "restricted"):

Pod:       runAsNonRoot: true
           runAsUser, runAsGroup, fsGroup: non-zero
           seccompProfile.type: RuntimeDefault
Container: allowPrivilegeEscalation: false
           privileged: false
           readOnlyRootFilesystem: true
           capabilities.drop: [ALL]

Writable dirs (/tmp, /var/cache) use emptyDir volumes.

Every namespace has the PSA label:
  pod-security.kubernetes.io/enforce: restricted

Forbidden: hostNetwork/hostPID/hostIPC, hostPath volumes (rare CSI
exceptions), privileged: true anywhere, adding NET_ADMIN / SYS_ADMIN
without a code-comment justification.

Every namespace has a default-deny NetworkPolicy + explicit allow rules.

Bad — root container, writable fs, every capability:

spec:
  containers:
    - name: api
      image: myregistry/api@sha256:...
      # no securityContext — runs as root with ALL caps, writable root fs
      ports:
        - containerPort: 8080

Good — hardened, least-privilege:

spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 10001
    runAsGroup: 10001
    fsGroup: 10001
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: api
      image: myregistry/api@sha256:...
      securityContext:
        allowPrivilegeEscalation: false
        privileged: false
        readOnlyRootFilesystem: true
        capabilities:
          drop: ["ALL"]
      volumeMounts:
        - name: tmp
          mountPath: /tmp
        - name: cache
          mountPath: /var/cache/app
      ports:
        - containerPort: 8080
  volumes:
    - name: tmp
      emptyDir: {}
    - name: cache
      emptyDir: {}

# namespaces/payments/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: payments
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/enforce-version: latest
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/warn: restricted

# namespaces/payments/default-deny.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-all
  namespace: payments
spec:
  podSelector: {}
  policyTypes: [Ingress, Egress]

Now the pod cannot write to its root filesystem, cannot escalate, cannot add capabilities, and cannot talk to any pod outside the explicit allow rules.

Rule 6: Secrets — External Managers and Ephemeral Mounts, Never Inline

Base64 is not encryption. kind: Secret with data: {password: cGFzc3dvcmQ=} committed to a git repo is a plaintext password visible to anyone with read access. AI-generated manifests do this constantly because the Secret API is named "Secret" and the tutorials say "use Secrets." The production pattern is: secrets live in a dedicated manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager), an operator (External Secrets Operator, Vault agent injector, Secrets Store CSI Driver) projects them into the pod at runtime, and the git repo references them by name — never by value.

The rule:

Secret MATERIAL (passwords, keys, certs) never appears in YAML,
Helm values, Kustomize secretGenerator literals, or inline env vars.

Secrets live in an external manager (AWS Secrets Manager, GCP Secret
Manager, Azure Key Vault, Vault). The cluster pulls them via:
  - External Secrets Operator (ExternalSecret → Secret)
  - Secrets Store CSI Driver (files at runtime)
  - Vault agent injector (sidecar writes to the pod fs)

Sealed Secrets or SOPS-encrypted secrets are acceptable for pure
GitOps when external managers aren't available.

Consumption: prefer mounted files over env vars (env vars leak via
process listings, crash dumps, /proc/<pid>/environ). If env vars
are unavoidable, use valueFrom.secretKeyRef — never a literal value.

RBAC scopes secrets:get/list/watch to specific service accounts.
No human has secrets:list in production; break-glass access is
audited and time-boxed.

Every secret has a rotation cadence. ExternalSecret.refreshInterval
is set (e.g., 1h). Pods pick up new values via sidecar refresh or
a rolling restart triggered by a secret-checksum annotation.

Bad — password in git as base64:

apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
  namespace: payments
type: Opaque
data:
  username: cG9zdGdyZXM=           # "postgres"
  password: c3VwZXJzZWNyZXQxMjM=   # "supersecret123"
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: api
          env:
            - name: DB_PASSWORD
              value: "supersecret123"  # and also inline. twice.

Good — External Secrets Operator pulls from AWS Secrets Manager:

# apps/api/externalsecret.yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: api-db
  namespace: payments
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: aws-secrets
    kind: ClusterSecretStore
  target:
    name: api-db
    creationPolicy: Owner
  data:
    - secretKey: username
      remoteRef: { key: payments/api/db, property: username }
    - secretKey: password
      remoteRef: { key: payments/api/db, property: password }

# Deployment consumption — reference, never literal
env:
  - name: DB_USER
    valueFrom: { secretKeyRef: { name: api-db, key: username } }
  - name: DB_PASSWORD
    valueFrom: { secretKeyRef: { name: api-db, key: password } }

The git repo has the reference, not the value. Rotating the password is a change in AWS Secrets Manager; the next refresh pulls it. Prefer a CSI mount at /var/run/secrets/db over env vars when the app can be taught to read files — env vars leak through /proc/<pid>/environ.

Rule 7: Rollouts — Strategy, PodDisruptionBudget, HPA, and Graceful Shutdown

A Kubernetes rollout that looks safe can still drop traffic: the default RollingUpdate with maxUnavailable: 25% combined with a cluster autoscaler event can remove every pod on a draining node simultaneously. The Deployment.spec.strategy is only half the story — you also need a PodDisruptionBudget so voluntary disruptions respect your availability target, an HPA so replica count scales with load, and a container that respects SIGTERM so in-flight requests drain instead of getting dropped.

The rule:

Every user-facing Deployment MUST have all four of:
  - spec.strategy.rollingUpdate with EXPLICIT maxSurge and
    maxUnavailable (critical services: maxUnavailable: 0).
  - A sibling PodDisruptionBudget sized to survive a node drain.
  - A HorizontalPodAutoscaler with explicit min/max and a metric target.
  - terminationGracePeriodSeconds set to the app's real drain time.

Graceful shutdown: on SIGTERM, fail readiness first, let the Service
remove the pod, finish in-flight work, then exit. A preStop `sleep 5-10`
covers kube-proxy iptables propagation.

Strategy: RollingUpdate for stateless services; Recreate only when
two versions cannot run simultaneously; Argo Rollouts / Flagger for
canary or blue-green on high-stakes paths.

Production replicas >= 2. Singletons must carry a comment justifying
why. Never terminationGracePeriodSeconds: 0, never skip the PDB
("we have many replicas" doesn't help when a single drained node
takes out the only pods on that node).

Bad — default rolling update, no PDB, no HPA, no graceful shutdown:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  # no strategy specified — defaults to maxSurge/maxUnavailable: 25%
  template:
    spec:
      containers:
        - name: api
          image: myregistry/api@sha256:...

Good — explicit strategy, PDB, HPA, graceful shutdown:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: payments
spec:
  replicas: 3  # HPA overrides, but this is the floor the controller uses
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: api
          image: myregistry/api@sha256:...
          lifecycle:
            preStop:
              exec:
                command: ["/bin/sh", "-c", "sleep 10"]
          # SIGTERM handler in the app drains connections over up to 50s
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: api-pdb
  namespace: payments
spec:
  minAvailable: 2   # we need at least 2 pods at all times
  selector:
    matchLabels:
      app.kubernetes.io/name: api
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api
  namespace: payments
spec:
  scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: api }
  minReplicas: 3
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target: { type: Utilization, averageUtilization: 70 }

The app handles SIGTERM: flip readiness to failing, wait ~5s for kube-proxy to propagate, then srv.Shutdown(ctx) with a timeout matching the drain window. Node drains, deploys, and autoscaler downscales all keep serving.

Rule 8: Observability — Structured Labels, Logs, Metrics, and Namespace Hygiene

A Kubernetes workload you can't observe is a workload you can't debug at 3am. AI-generated manifests routinely omit the standard labels, ship logs in a random format (or to files inside the container that nobody collects), and expose no metrics endpoint — which means kubectl logs is the only troubleshooting tool and incidents blow past SLO before anyone understands what's wrong.

The rule:

Every resource carries the six recommended labels:
  app.kubernetes.io/{name, instance, version, component, part-of, managed-by}

Every Pod:
  - Logs to stdout/stderr in STRUCTURED JSON with ts, level, msg,
    trace_id, span_id, request_id. Never log to files inside the container.
  - Exposes /metrics in Prometheus format on a dedicated port
    (9090/9102), scraped by a ServiceMonitor or PodMonitor.
  - Propagates OpenTelemetry trace_id/span_id and includes them
    in every log line.

Namespaces: one per (team, environment) — payments-production and
payments-staging are separate namespaces, never the same. Each has
a ResourceQuota, a LimitRange, a default-deny NetworkPolicy, and
a dedicated ServiceAccount per workload (never `default`).

Services: stable meaningful names (api, db, cache). Internal services
use ClusterIP; external traffic goes through Ingress or a Gateway.
Never type: LoadBalancer on an internal service.

Forbidden: shipping without labels, "line soup" unstructured logs,
skipping metrics ("the LB knows" — it doesn't know queue depth,
GC pauses, or anything inside your process), deploying to `default`.

Bad — no structured labels, no metrics, logs to a file:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  labels:
    app: api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: myregistry/api@sha256:...
          volumeMounts:
            - name: logs
              mountPath: /var/log/api
      volumes:
        - name: logs
          emptyDir: {}

app: api is not enough — queries like "all payments components in production" fail. /var/log/api is invisible to the cluster log pipeline.

Good — full labels, stdout JSON logs, Prometheus metrics:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: payments
  labels:
    app.kubernetes.io/name: api
    app.kubernetes.io/instance: api-production
    app.kubernetes.io/version: "1.4.3"
    app.kubernetes.io/component: backend
    app.kubernetes.io/part-of: payments
    app.kubernetes.io/managed-by: argocd
spec:
  replicas: 3
  selector:
    matchLabels:
      app.kubernetes.io/name: api
      app.kubernetes.io/instance: api-production
  template:
    metadata:
      labels:
        app.kubernetes.io/name: api
        app.kubernetes.io/instance: api-production
        app.kubernetes.io/version: "1.4.3"
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "9090"
        prometheus.io/path: "/metrics"
    spec:
      serviceAccountName: api
      containers:
        - name: api
          image: myregistry/api@sha256:...
          ports:
            - name: http
              containerPort: 8080
            - name: metrics
              containerPort: 9090
          env:
            - name: LOG_FORMAT
              value: json
---
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: api
  namespace: payments
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: api
  podMetricsEndpoints:
    - port: metrics
      interval: 30s

// Structured, stdout, one event per line.
log.Info("request",
    "method", r.Method,
    "path", r.URL.Path,
    "status", status,
    "duration_ms", dur.Milliseconds(),
    "trace_id", trace.SpanContextFromContext(r.Context()).TraceID().String(),
)

Now the log aggregator indexes by trace_id, Prometheus scrapes /metrics without extra configuration, and "show me all components of payments running version 1.4.3" is a one-line Kubernetes label selector.

The Complete `.cursorrules` File for Kubernetes

Drop this into your repo root as .cursorrules, or split into .cursor/rules/*.mdc files. It's the consolidated version of every rule above plus the tooling defaults that go with them.

# Kubernetes Cursor Rules

## GitOps
- Production cluster state is reconciled from a git repo by Argo CD or Flux.
- Never emit kubectl apply / kubectl edit / kubectl patch / kubectl scale /
  helm install / helm upgrade instructions for production.
- Every resource has a committed manifest. Drift is auto-healed or alerted.
- CI runs kubeconform, kube-linter, and a dry-run diff on every PR.

## Resources
- Every container sets resources.requests.cpu, resources.requests.memory,
  and resources.limits.memory.
- Memory request == memory limit for latency-sensitive services (Guaranteed QoS).
- Do NOT set CPU limits on latency-sensitive services (throttling hurts p99).
- Every namespace has a LimitRange (defaults) and a ResourceQuota (cap).
- Sidecars and init containers also declare resources.

## Probes
- livenessProbe checks "should this container be restarted" — in-process only.
- readinessProbe checks "should this pod receive traffic" — may verify
  downstream dependencies with short timeouts.
- startupProbe bounds slow boots; never use initialDelaySeconds as a workaround.
- Different endpoints for liveness vs readiness. /livez and /readyz.
- Never use exec probes that spawn a shell in the hot loop.

## Images
- Production manifests pin images by digest (image: repo@sha256:...).
- Tag-only or :latest images are rejected in any non-dev overlay.
- imagePullPolicy: IfNotPresent when digest-pinned.
- All production images come from a private registry, scanned, and signed.
- Image signatures enforced by Kyverno / Gatekeeper / connaisseur at admission.

## Security
- Every pod sets runAsNonRoot, runAsUser, runAsGroup, fsGroup, seccompProfile.
- Every container sets allowPrivilegeEscalation: false, privileged: false,
  readOnlyRootFilesystem: true, capabilities.drop: [ALL].
- Writable dirs use emptyDir volumes mounted at known paths (/tmp, /var/cache).
- hostNetwork, hostPID, hostIPC, hostPath volumes are forbidden with rare
  documented exceptions.
- Every namespace has the Pod Security Admission label at `restricted`.
- Every namespace has a default-deny NetworkPolicy + explicit allow rules.

## Secrets
- Secret MATERIAL never lives in the git repo in plaintext OR base64.
- Secrets come from an external manager (AWS/GCP/Azure/Vault) via the
  External Secrets Operator or Secrets Store CSI Driver.
- Sealed Secrets or SOPS-encrypted are acceptable for GitOps when external
  managers are unavailable.
- Prefer mounted files over env vars for secret consumption.
- RBAC scopes `secrets:get/list/watch` to specific service accounts only.

## Rollouts
- Every Deployment sets strategy.rollingUpdate.maxSurge and maxUnavailable
  explicitly. Critical services use maxUnavailable: 0.
- Every user-facing workload has a PodDisruptionBudget.
- Every user-facing workload has a HorizontalPodAutoscaler with min/max
  replicas and a metric target.
- terminationGracePeriodSeconds is set to the app's real drain time.
- Containers handle SIGTERM: fail readiness, drain, exit cleanly.
- preStop hook with a sleep covers kube-proxy propagation.
- production replicas >= 2. Singletons require a comment justifying them.

## Observability
- Every resource has the six recommended labels (name, instance, version,
  component, part-of, managed-by).
- Logs are structured JSON on stdout/stderr. Never log to files.
- /metrics endpoint exposed on a dedicated port, scraped by a PodMonitor
  or ServiceMonitor.
- Trace propagation via OpenTelemetry; trace_id present in every log line.
- One namespace per (team, environment). Never mix prod and staging.
- Every workload has its own ServiceAccount; never use `default`.
- External traffic via Ingress / Gateway, not type: LoadBalancer on
  internal Services.

## Tooling
- kubeconform --strict on every YAML.
- kube-linter run against every chart / kustomization.
- Polaris or Datree for policy checks in CI.
- Helm charts use helm template | kubeconform; no chart-only validation.
- Kustomize overlays have a base/ and overlays/{dev,staging,production}.
- All manifests live on a branch protected with required reviews.

Real Examples: AI-Generated Manifests Before and After Rules

Here's what changes in practice when the rules above are loaded into Cursor.

Example 1: "Give me a Deployment and Service for my Node API."

Without rules — typical AI output:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: mycompany/api:latest
          ports:
            - containerPort: 3000
          env:
            - name: DB_PASSWORD
              value: "supersecret"
---
apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  type: LoadBalancer
  selector:
    app: api
  ports:
    - port: 80
      targetPort: 3000

Sin count: :latest, no resources, no probes, no securityContext, password inline, default namespace, type: LoadBalancer on an internal service, only the app label.

With rules in .cursorrules — same prompt, production-grade output:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: payments
  labels: &labels
    app.kubernetes.io/name: api
    app.kubernetes.io/instance: api-production
    app.kubernetes.io/version: "1.4.3"
    app.kubernetes.io/component: backend
    app.kubernetes.io/part-of: payments
    app.kubernetes.io/managed-by: argocd
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate: { maxSurge: 1, maxUnavailable: 0 }
  selector:
    matchLabels:
      app.kubernetes.io/name: api
      app.kubernetes.io/instance: api-production
  template:
    metadata:
      labels: *labels
    spec:
      serviceAccountName: api
      terminationGracePeriodSeconds: 60
      securityContext:
        runAsNonRoot: true
        runAsUser: 10001
        fsGroup: 10001
        seccompProfile: { type: RuntimeDefault }
      containers:
        - name: api
          image: mycompany/api@sha256:c2f7b8a9d...
          ports:
            - { name: http,    containerPort: 3000 }
            - { name: metrics, containerPort: 9090 }
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities: { drop: ["ALL"] }
          resources:
            requests: { cpu: "200m", memory: "256Mi" }
            limits:   { memory: "256Mi" }
          env:
            - name: DB_PASSWORD
              valueFrom: { secretKeyRef: { name: api-db, key: password } }
          volumeMounts:
            - { name: tmp, mountPath: /tmp }
          lifecycle:
            preStop: { exec: { command: ["/bin/sh", "-c", "sleep 10"] } }
          startupProbe:    { httpGet: { path: /livez, port: http }, periodSeconds: 5,  failureThreshold: 12 }
          livenessProbe:   { httpGet: { path: /livez, port: http }, periodSeconds: 20, failureThreshold: 3 }
          readinessProbe:  { httpGet: { path: /readyz, port: http }, periodSeconds: 5, failureThreshold: 2 }
      volumes:
        - { name: tmp, emptyDir: {} }
---
apiVersion: v1
kind: Service
metadata: { name: api, namespace: payments, labels: *labels }
spec:
  type: ClusterIP
  selector:
    app.kubernetes.io/name: api
    app.kubernetes.io/instance: api-production
  ports:
    - { name: http, port: 80, targetPort: http }
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata: { name: api, namespace: payments }
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: api
      app.kubernetes.io/instance: api-production

Labels. Digest pin. Probes for each job. PDB. Hardened security context. Secrets via reference. Metrics port. No type: LoadBalancer on an internal service.

The same prompt for "a CronJob that runs a nightly sync" produces a manifest with concurrencyPolicy: Forbid, backoffLimit, ttlSecondsAfterFinished, startingDeadlineSeconds, the same hardened securityContext, and resource limits — instead of a bare schedule + image: sync:latest.

Get the Full Pack

These eight rules cover the highest-leverage Kubernetes patterns where AI assistants consistently fail — the ones that turn into incidents, audit findings, and 3am pages. Drop them into .cursorrules and you'll see the difference on the very next prompt.

If you want the same depth for Terraform, Docker, Go, Java, Rust, TypeScript, Python, React, Next.js, and more — all the rules I've packaged from a year of refining Cursor configs across production clusters — they're all at:

oliviacraft.lat

One pack. Twenty-plus languages and frameworks. Battle-tested rules with before/after examples for each. Stop fighting your AI assistant and start shipping production-grade manifests on the first try.

Cursor Rules for Elixir: AI-Assisted Dev Guide 2026

Olivia Craft — Sun, 26 Apr 2026 09:56:37 +0000

Elixir is the language where the right code looks almost boring — a function head, three tiny pattern-matched clauses, a with chain for the happy path, a supervisor that restarts anything that breaks, and a @spec that Dialyzer actually checks. The wrong code looks like someone translated a Ruby service class and a Node.js controller into BEAM syntax: cond blocks five levels deep, a try/rescue around every DB call because exceptions scare the author, GenServers used as global mutable dictionaries, Task.async/1 spawned bare into the void, Ecto queries scattered across controllers, and String.to_atom/1 called on user input so the VM's atom table fills and the node dies three weeks later during Black Friday.

Then you add an AI assistant.

Cursor and Claude Code were trained on a decade of BEAM code that includes some excellent OTP work but also a mountain of blog-post snippets — Phoenix controllers that talk to Ecto directly, GenServer.call/3 used as a database, defensive rescue clauses that catch Ecto.NoResultsError and return nil, processes spawned without a supervisor so they die silently when the node restarts, @spec omitted entirely because "the pattern match documents the types," Task.await/2 with no timeout, and Phoenix contexts that are thin wrappers over schemas with no business logic. Ask for "a function that fetches a user and charges their card," and you get a flat function with three case expressions, a try around the Stripe call, and a Repo.get!/2 that will raise a 500 when the ID is wrong. The code runs on the happy path. It does not survive production.

The fix is .cursorrules — one file in the repo that tells the AI what idiomatic, production-grade Elixir and OTP look like. Eight rules below, each with the failure mode, the rule that prevents it, and a before/after. Copy-paste .cursorrules at the end. Examples target modern Elixir (1.16+) with Phoenix 1.7, Ecto 3, and standard OTP primitives.

How Cursor Rules Work for Elixir Projects

Cursor reads project rules from two locations: .cursorrules (a single file at the repo root, still supported) and .cursor/rules/*.mdc (modular files with frontmatter, recommended for any non-trivial Elixir app). For Elixir I recommend modular rules so the Phoenix web-layer conventions don't bleed into pure-OTP libraries in an umbrella and so Ecto patterns only fire near database code:

.cursor/rules/
  ex-core.mdc         # pattern matching, with, tagged tuples, @spec
  ex-otp.mdc          # GenServer, Supervisor, let-it-crash, restart strategies
  ex-ecto.mdc         # queries in contexts, Multi, changesets, migrations
  ex-phoenix.mdc      # controllers, contexts boundary, LiveView discipline
  ex-concurrency.mdc  # Task.Supervisor, async_stream, timeouts
  ex-testing.mdc      # ExUnit, async, Mox, property tests

Frontmatter controls activation: globs: ["**/*.ex", "**/*.exs", "**/mix.exs"] with alwaysApply: false. Now the rules.

Rule 1: Pattern Match Over Conditionals — Function Heads First, `with` for Chains

The single most common AI failure in Elixir is "a big flat function with if/case/cond at every branch." That pattern works in every language Cursor was trained on, but in Elixir the idiom is to push branching into function heads — which turns control flow into a table of patterns, makes missing cases a compile-time warning, and dialyzes cleanly. When you genuinely do have a sequence of fallible steps, with replaces the tower-of-case.

The rule:

Prefer pattern matching over conditionals:
  - Multiple function clauses with different heads BEAT case/cond/if
    inside a single function body.
  - Let the compiler tell you about missing patterns via exhaustiveness
    warnings (use @dialyzer :no_match or :no_return sparingly).
  - Prefer `case` over `cond` when the value is a single expression.
  - Prefer `cond` over nested `if` when you have multiple independent
    boolean branches.
  - Use `with` to chain operations that each return {:ok, _} | {:error, _}.
    An `else` clause catches specific error shapes.

Destructure in function heads where possible. Fall through to a generic
clause only when you want a runtime pattern guard.

Never write a 6-clause cond. That's always three functions in disguise.

Bad — control flow in a conditional tower:

def process_payment(user_id, amount) do
  user = Accounts.get_user(user_id)
  if user == nil do
    {:error, :not_found}
  else
    if user.status == :active do
      if amount > 0 do
        case Stripe.charge(user.customer_id, amount) do
          {:ok, charge} -> {:ok, charge}
          {:error, e} -> {:error, e}
        end
      else
        {:error, :invalid_amount}
      end
    else
      {:error, :inactive}
    end
  end
end

Good — function heads + with:

def process_payment(user_id, amount) when amount > 0 do
  with {:ok, user} <- fetch_active_user(user_id),
       {:ok, charge} <- Stripe.charge(user.customer_id, amount) do
    {:ok, charge}
  end
end

def process_payment(_user_id, _amount), do: {:error, :invalid_amount}

defp fetch_active_user(user_id) do
  case Accounts.get_user(user_id) do
    %User{status: :active} = user -> {:ok, user}
    %User{} -> {:error, :inactive}
    nil -> {:error, :not_found}
  end
end

Each clause does one thing. The happy path is a straight line. Missing a case is a compiler warning. The AI can't talk you into a sixth if branch because the structure rejects it.

Rule 2: Tagged Tuples Are the Error Protocol — `{:ok, value}` / `{:error, reason}`

In Elixir, functions that can fail return {:ok, value} or {:error, reason}. Functions that cannot fail return the value directly. A bang version (function!/n) raises on error. AI assistants mix these idioms freely — they'll return {:ok, nil} when the row isn't found, false to mean "error," raise inside a function whose caller expects a tuple, or return {:error, "not found"} as a string instead of an atom. Every mismatch turns callers into a blob of defensive code.

The rule:

Error protocol:
  - Fallible functions return {:ok, value} | {:error, reason}.
  - `reason` is an atom (:not_found, :unauthorized) or a struct
    (Ecto.Changeset, a custom error struct). Never a bare string.
  - Infallible functions return the raw value.
  - The bang version (`get_user!/1`) raises an exception on failure.
    Use it only where the caller is okay being killed by the supervisor.

NEVER:
  - Return {:ok, nil} to mean "not found" — use {:error, :not_found}.
  - Return `false` to mean "error" — it's indistinguishable from a valid
    boolean result.
  - Raise from a function that has a non-bang name.
  - Use strings as error reasons — they can't be matched on.
  - Mix {:ok, _} returns with bare-value returns in the same function
    (different return shapes per branch). Callers can't handle it.

@spec every public function. Dialyzer catches return-shape bugs at
compile time, and the spec IS the contract.

Bad — inconsistent return shapes, string reasons, bang on a non-bang name:

def find_user(email) do
  case Repo.get_by(User, email: email) do
    nil -> {:ok, nil}                 # should be :error
    user -> user                       # should be {:ok, user}
  end
end

def authorize(user, action) do
  if can?(user, action), do: true, else: {:error, "nope"}
end

Good — tagged tuples everywhere, atom reasons, specs:

@spec find_user(String.t()) :: {:ok, User.t()} | {:error, :not_found}
def find_user(email) do
  case Repo.get_by(User, email: email) do
    nil -> {:error, :not_found}
    %User{} = user -> {:ok, user}
  end
end

@spec authorize(User.t(), atom()) :: :ok | {:error, :forbidden}
def authorize(%User{} = user, action) when is_atom(action) do
  if can?(user, action), do: :ok, else: {:error, :forbidden}
end

Callers can now write with {:ok, user} <- find_user(email), :ok <- authorize(user, :pay) do ... end. Dialyzer checks every call site against the spec.

Rule 3: Let It Crash — Use Supervisors, Not try/rescue

The Elixir idiom that confuses every non-BEAM-trained AI is "let it crash." In most languages, you catch exceptions at every layer because the alternative is a process that dies and takes the program with it. In Elixir, processes are cheap and supervised — so catching Postgrex.Error inside your function and returning nil isn't defensive, it's actively harmful. You've swallowed the crash the supervisor was designed to respond to, turned a transient error into silent data loss, and hidden the failure from your monitoring.

The rule:

Let processes crash. A crashed process is restarted by its supervisor;
a silent error is a bug that festers.

try/rescue is acceptable only:
  - At the boundary with a non-Elixir system (Port, NIF, external lib
    with known exception contracts).
  - In a top-level request handler (Plug, Phoenix endpoint) that must
    translate an unexpected exception into a 500 response for the user.
  - When you genuinely need to do cleanup and RE-RAISE — in which case
    use try/after, not try/rescue.

NEVER:
  - Wrap Repo calls in try/rescue to return nil/[] on error.
  - Catch Ecto.NoResultsError — use Repo.get (not Repo.get!) if you
    want {:ok, _} | {:error, _}.
  - rescue _ or rescue Exception — this catches process EXITs that
    should propagate (:shutdown, :timeout, :killed).
  - Use try/rescue to implement control flow. If you find yourself
    raising an exception to signal "not found," you wrote the wrong code.

Every long-running process (GenServer, Task, Agent) lives under a
supervisor with an explicit restart strategy (:one_for_one, :rest_for_one).
Bare `spawn`/`Task.async` without supervision is forbidden except in
one-off scripts.

Bad — rescue as control flow, swallowed crash:

def get_balance(user_id) do
  try do
    user = Repo.get!(User, user_id)
    Accounts.calculate_balance(user)
  rescue
    _ -> 0
  end
end

A deleted user now has a balance of zero. A DB outage returns zero. A bug in calculate_balance/1 returns zero. You'll never know.

Good — crash on unexpected failure, return tagged tuple for known outcomes:

@spec get_balance(pos_integer()) :: {:ok, Money.t()} | {:error, :not_found}
def get_balance(user_id) do
  case Repo.get(User, user_id) do
    nil -> {:error, :not_found}
    %User{} = user -> {:ok, Accounts.calculate_balance(user)}
  end
end

A deleted user returns {:error, :not_found}. A DB outage crashes, the supervisor restarts, telemetry fires, monitoring pages. A bug in calculate_balance/1 crashes immediately — you get a stack trace instead of a silent zero.

Rule 4: GenServer Discipline — State Per Process, Not a Global Dictionary

GenServer is OTP's general-purpose stateful process. AI assistants wildly overuse it — as a global key-value store, as a cache, as a mutex around pure computation, as a wrapper for every module that has internal state. The result: a single GenServer serializing every call in the system, a message queue that grows unboundedly under load, and an architecture that's impossible to scale because one process is the bottleneck.

The rule:

Reach for GenServer when you need:
  - Long-lived state that outlives any single call.
  - Serialized access to a resource (a specific external handle,
    a bounded connection pool).
  - A process with a well-defined message protocol.

DO NOT use GenServer for:
  - Pure stateless computation (use a plain module).
  - Caching — use :ets, :persistent_term, or Cachex (which wraps them).
  - "Singleton" patterns imported from OOP — usually wrong in BEAM.
  - Storing configuration — use Application.get_env or a struct.

GenServer rules:
  - init/1 is for SETUP, not WORK. Move slow work into a {:continue, _}
    step or a handle_info(:init_complete, ...) after init.
  - handle_call is for replies you need synchronously. Long-running work
    in a call blocks every caller — use handle_cast or GenServer.reply/2
    from a spawned task.
  - Every call takes a timeout. The default 5_000 is rarely what you want.
  - The state shape is a typed struct: `defstruct` + `@type t :: %__MODULE__{...}`.
  - A GenServer that just wraps an Agent probably wants to be an Agent
    (or neither — a plain module with :ets behind it).
  - Supervise every GenServer. Its child_spec is explicit; its
    restart: strategy is chosen (default :permanent is rarely right
    for workers doing one job).

Bad — GenServer as a global dictionary that serializes every write:

defmodule Counters do
  use GenServer

  def start_link(_), do: GenServer.start_link(__MODULE__, %{}, name: __MODULE__)
  def init(state), do: {:ok, state}
  def bump(key), do: GenServer.call(__MODULE__, {:bump, key})

  def handle_call({:bump, key}, _from, state) do
    state = Map.update(state, key, 1, &(&1 + 1))
    {:reply, :ok, state}
  end
end

Every Counters.bump/1 in every request is a GenServer.call blocking on a single process. A 5ms call becomes 5s of tail latency under load.

Good — :counters or :ets for shared counters, no GenServer at all:

defmodule Counters do
  @table :counters

  def setup, do: :ets.new(@table, [:public, :named_table, :set, write_concurrency: true])

  @spec bump(term()) :: :ok
  def bump(key) do
    :ets.update_counter(@table, key, {2, 1}, {key, 0})
    :ok
  end

  @spec get(term()) :: non_neg_integer()
  def get(key) do
    case :ets.lookup(@table, key) do
      [{^key, n}] -> n
      [] -> 0
    end
  end
end

Concurrent writes. No serialization. No message queue. No process to supervise for what is fundamentally shared memory.

Rule 5: Ecto in Contexts — Queries Live in the Domain, Transactions Use `Multi`

Phoenix's context boundary exists precisely so the web layer doesn't know about Ecto. AI-generated code breaks that boundary immediately: controllers import Ecto.Query and build queries inline, schemas embed business logic in before_insert hooks, and multi-step writes are a tower of Repo.transaction(fn -> ... end) with manual rollback. The result is a web layer that can't be tested without a database and a schema that can't be understood without reading three controllers.

The rule:

Context boundary:
  - All Ecto queries live in context modules (Accounts, Billing, Catalog).
  - Controllers, LiveViews, and channels call context functions only.
  - Schemas hold types + changesets. NO database calls, NO business
    rules beyond validation.

Changesets:
  - Every write goes through a changeset that validates, casts, and
    constrains. cast_assoc / put_assoc for associations.
  - Never call Repo.insert with a raw map/struct.

Transactions:
  - Multi-step writes use `Ecto.Multi`. Each step is named; each
    takes the accumulator of prior steps; a step failure rolls back
    cleanly and returns {:error, step_name, changeset, changes_so_far}.
  - Never nest Repo.transaction/2 manually with multiple inserts.
  - Never use Repo.transaction/2 with a function that doesn't return
    {:ok, _} | {:error, _} — the rollback behavior is subtle.

Query rules:
  - Prefer named/reusable query functions (by_user(query, user_id))
    over inline Ecto.Query in controllers.
  - `Repo.preload` at context boundaries, not scattered across views.
  - N+1: if a list query is followed by an attribute access that hits
    the DB, add preload.
  - Never call `|> Repo.all() |> Enum.filter(...)` when a WHERE clause works.

Forbidden: Repo in a LiveView mount; `import Ecto.Query` in a view or
controller; `Repo.get!` in a controller (let the context return
{:error, :not_found}).

Bad — controller queries directly, manual transaction:

def create(conn, %{"order" => params}) do
  Repo.transaction(fn ->
    order = Repo.insert!(%Order{params})
    _ = Repo.insert!(%OrderLine{order_id: order.id, ...})
    _ = Repo.update!(Ecto.Changeset.change(%Inventory{id: params["item"]}, stock: ...))
    order
  end)
  |> case do
    {:ok, order} -> render(conn, "show.json", order: order)
    {:error, _} -> send_resp(conn, 500, "")
  end
end

Good — context with Ecto.Multi, controller stays thin:

defmodule Shop.Orders do
  alias Ecto.Multi
  alias Shop.Repo
  alias Shop.Orders.{Order, OrderLine, Inventory}

  @spec create_order(map()) ::
          {:ok, Order.t()} | {:error, :insufficient_stock | Ecto.Changeset.t()}
  def create_order(attrs) do
    Multi.new()
    |> Multi.insert(:order, Order.changeset(%Order{}, attrs))
    |> Multi.insert(:line, fn %{order: o} -> OrderLine.changeset(%OrderLine{}, o, attrs) end)
    |> Multi.run(:stock, fn repo, %{line: line} ->
      Inventory.decrement(repo, line.item_id, line.quantity)
    end)
    |> Repo.transaction()
    |> case do
      {:ok, %{order: order}} -> {:ok, order}
      {:error, :stock, :insufficient, _} -> {:error, :insufficient_stock}
      {:error, _step, changeset, _changes} -> {:error, changeset}
    end
  end
end

def create(conn, %{"order" => params}) do
  case Shop.Orders.create_order(params) do
    {:ok, order} -> render(conn, "show.json", order: order)
    {:error, :insufficient_stock} -> send_resp(conn, 409, "out of stock")
    {:error, %Ecto.Changeset{} = cs} -> render(conn, "error.json", changeset: cs)
  end
end

The controller is five lines and tests without a database. The transaction rolls back cleanly on stock failure. The Multi pipeline reads like a recipe.

Rule 6: Structured Concurrency — `Task.Supervisor`, Timeouts, Linked Tasks

Bare Task.async/1 followed by Task.await/1 works in tutorials. In production it leaks tasks on crash, blocks forever on default timeouts, and leaves no way for a supervisor to clean up. AI assistants love Task.async because it looks like JavaScript promises. It isn't — every spawned task is a linked process, and a crash in the task takes down the caller unless you remember to use Task.yield or a Task.Supervisor.

The rule:

Concurrency primitives:
  - Task.Supervisor.async_stream/3 (or .async_stream_nolink/3) for
    bounded parallelism over a collection. Always pass max_concurrency.
  - Task.Supervisor.async_nolink/1 for fire-and-forget with the ability
    to observe failure via handle_info({:DOWN, _, _, _, reason}).
  - GenServer.call/3 for request/reply to a named process.
  - Task.await/2 ONLY with an explicit timeout and an understanding
    that a timeout means the task is still running (or has crashed).

Rules:
  - Every external I/O call has an explicit timeout. Never rely on :infinity
    or library defaults for network calls.
  - Every Task.Supervisor.async_stream has max_concurrency and on_timeout
    (:kill_task by default) chosen explicitly.
  - Never Task.async_stream WITHOUT a supervisor in library code —
    a crash would kill the caller.
  - Never Task.async inside a GenServer.handle_call — you've now linked
    the task to the GenServer; a task crash crashes the server.
  - Use Task.async_stream_nolink when the caller should survive a task
    crash (reports errors via Stream output).

NEVER:
  - spawn/1 in library or service code. It's unlinked, unsupervised,
    unmonitored — a silent ghost process.
  - Task.await without a timeout. The default is :infinity.
  - Receive a :DOWN message without demonitoring the reference.

Bad — unbounded parallelism, no supervisor, crash takes down the caller:

def fetch_all(urls) do
  urls
  |> Enum.map(&Task.async(fn -> HTTPoison.get!(&1) end))
  |> Enum.map(&Task.await/1)  # :infinity timeout
end

1000 URLs spawn 1000 linked tasks that all blast the network. The first failure crashes the parent process. Every await waits forever on the default timeout.

Good — supervised, bounded, timeouts explicit:

@spec fetch_all([String.t()]) :: [{:ok, Response.t()} | {:error, term()}]
def fetch_all(urls) do
  Task.Supervisor.async_stream_nolink(
    MyApp.TaskSup,
    urls,
    &fetch_one/1,
    max_concurrency: 8,
    timeout: 5_000,
    on_timeout: :kill_task
  )
  |> Enum.map(fn
    {:ok, result} -> result
    {:exit, reason} -> {:error, reason}
  end)
end

defp fetch_one(url) do
  case Finch.build(:get, url) |> Finch.request(MyApp.Finch, receive_timeout: 4_000) do
    {:ok, %Finch.Response{status: s}} when s in 200..299 = resp -> {:ok, resp}
    {:ok, %Finch.Response{status: s}} -> {:error, {:http, s}}
    {:error, reason} -> {:error, reason}
  end
end

Concurrency bounded at 8. Task crashes don't kill the caller. Every HTTP call has a timeout shorter than the task timeout. Timeouts produce a normal error return.

Rule 7: @spec and Dialyzer on Every Public API

Dialyzer is the single most underused tool in the Elixir ecosystem. Run it once and it will find calls that can't possibly succeed, case clauses that are unreachable, functions that always return the error branch, and nil leaking into places that don't handle it. AI-generated code ships without specs because "the pattern match is the documentation," which is fine until someone calls your function with the wrong shape and gets a generic FunctionClauseError at runtime.

The rule:

Every PUBLIC function has a @spec. Private helpers are encouraged but
not required.

Spec conventions:
  - Use the most precise types available. t() for struct types,
    String.t() for strings, pos_integer() / non_neg_integer() when
    appropriate.
  - Return types reflect every branch. {:ok, User.t()} | {:error, :not_found}.
  - Never `any()` / `term()` unless truly unknown (JSON decoding, reflection).
  - Opaque types for domain values: @opaque Money.t(); users interact
    via module functions, not struct internals.

Dialyzer:
  - Every release includes a Dialyzer run in CI. No new warnings pass.
  - Use `mix dialyzer --plt` to populate the PLT once; commit the PLT
    files for faster CI (optional — or cache in GitHub Actions).
  - @dialyzer {:nowarn_function, ...} is acceptable ONLY with a comment
    explaining why (usually a library returning too-broad a spec).

@doc and @moduledoc accompany every public function/module. At minimum
one line. Examples in @doc that are also @spec-checked with `iex>` are
doctests — ExUnit runs them.

Bad — no spec, implicit contract, dialyzer cannot help:

def charge(user, amount) do
  Stripe.create_charge(%{customer: user.customer_id, amount: amount})
end

Does it return {:ok, _} or the charge directly? Does it raise? What happens if amount is a float? What if user.customer_id is nil? Nobody knows without reading the implementation and chasing Stripe.

Good — specs, doc, clear contract:

@typedoc "An amount in the smallest currency unit (cents for USD)."
@type cents :: pos_integer()

@doc """
Charges the user's card for the given amount.

Returns `{:ok, charge}` on success, `{:error, reason}` on failure.
"""
@spec charge(User.t(), cents()) ::
        {:ok, Stripe.Charge.t()} | {:error, :no_card | Stripe.Error.t()}
def charge(%User{customer_id: nil}, _amount), do: {:error, :no_card}

def charge(%User{customer_id: cid}, amount) when is_integer(amount) and amount > 0 do
  case Stripe.create_charge(%{customer: cid, amount: amount}) do
    {:ok, %Stripe.Charge{} = charge} -> {:ok, charge}
    {:error, %Stripe.Error{} = e} -> {:error, e}
  end
end

Dialyzer catches charge(user, "10.00") at compile time. The :no_card branch is handled in one clause, not a nil inside the function body. The spec IS the contract the AI should write to.

Rule 8: Phoenix Contexts Are the Domain — Web Layer Stays Thin

Phoenix 1.3 introduced contexts because "everything in the controller" didn't scale. AI assistants, trained on Phoenix 1.0-era tutorials, still treat the controller as the place where business logic lives. The fix is brutal and simple: the controller does three things — parse input, call a context function, render output — and nothing else. Everything else lives in the context (or a LiveView's handle_event / handle_info for reactive flows).

The rule:

Controllers (and LiveView handle_* callbacks) do ONLY:
  1. Parse and validate the shape of input (Plug / cast_assoc at the edge).
  2. Call ONE context function.
  3. Render the result (JSON, HTML, or reply to a LiveView client).

Controllers must NOT:
  - Import Ecto.Query.
  - Call Repo.
  - Contain conditional logic beyond the pattern match of the context's
    return value.
  - Call a second context function "to enrich" — add a function to the
    context that does both.
  - Reach across contexts (Users calling Billing directly). Contexts are
    coupling boundaries; cross-context work lives in an orchestrator
    module.

LiveView discipline:
  - mount/3 loads initial data via context calls. Use async_result /
    start_async for slow loads.
  - Events flow through handle_event to a context function.
  - Pub/sub subscriptions receive via handle_info and update assigns.
  - No Ecto in the LiveView. Period.

Routing:
  - Route naming follows Phoenix conventions (resources, nested scopes).
  - Plug pipelines are composed, not copied.
  - `action_fallback` handles {:error, _} uniformly.

Forbidden: business rules in templates; Repo calls in HEEx components;
Plug.Conn assigns leaking into contexts.

Bad — controller with logic, direct DB access, no context in sight:

def update(conn, %{"id" => id, "user" => params}) do
  user = Repo.get!(User, id)
  if user.id == conn.assigns.current_user.id or conn.assigns.current_user.admin do
    changeset = User.changeset(user, params)
    case Repo.update(changeset) do
      {:ok, user} ->
        Logger.info("updated user #{user.id}")
        render(conn, "show.json", user: user)
      {:error, cs} ->
        conn |> put_status(422) |> render("error.json", changeset: cs)
    end
  else
    send_resp(conn, 403, "")
  end
end

Good — controller stays thin, context owns the work:

defmodule MyApp.Accounts do
  @spec update_user(actor :: User.t(), user_id :: pos_integer(), attrs :: map()) ::
          {:ok, User.t()} | {:error, :not_found | :forbidden | Ecto.Changeset.t()}
  def update_user(%User{} = actor, user_id, attrs) do
    with {:ok, user} <- fetch_user(user_id),
         :ok <- authorize(actor, user),
         {:ok, user} <- do_update(user, attrs) do
      :telemetry.execute([:accounts, :user, :updated], %{count: 1}, %{user_id: user.id})
      {:ok, user}
    end
  end

  defp fetch_user(id), do: Repo.get(User, id) |> ok_or(:not_found)
  defp authorize(%User{admin: true}, _), do: :ok
  defp authorize(%User{id: id}, %User{id: id}), do: :ok
  defp authorize(_, _), do: {:error, :forbidden}
  defp do_update(user, attrs), do: user |> User.changeset(attrs) |> Repo.update()
  defp ok_or(nil, tag), do: {:error, tag}
  defp ok_or(value, _), do: {:ok, value}
end

# fallback_controller.ex handles every {:error, _} shape in one place.
def update(conn, %{"id" => id, "user" => params}) do
  with {:ok, user} <- Accounts.update_user(conn.assigns.current_user, id, params) do
    render(conn, "show.json", user: user)
  end
end

The controller is two lines. The context can be unit-tested without a web connection. Authorization is a separate clause that composes. Telemetry fires from the domain, where the event has meaning.

The Complete `.cursorrules` File for Elixir

Drop this into your repo root as .cursorrules, or split into .cursor/rules/*.mdc files. It's the consolidated version of every rule above plus the tooling defaults.

# Elixir Cursor Rules

## Pattern Matching
- Prefer multi-clause function heads with pattern matching over if/case/cond.
- Use `with` for chained {:ok, _} | {:error, _} operations.
- Destructure in function heads where possible.
- No 6-clause cond — that's three functions in disguise.

## Error Protocol
- Fallible functions return {:ok, value} | {:error, reason}.
- `reason` is an atom or struct — never a bare string.
- Infallible functions return raw values; bang versions raise.
- Never return {:ok, nil} to mean "not found" — use {:error, :not_found}.
- Every public function has a @spec.

## Let It Crash
- Crash on unexpected failure; the supervisor restarts the process.
- try/rescue is for boundaries (Ports, NIFs, top-level handlers) and
  re-raised cleanup only.
- Never `rescue _` or `rescue Exception` — swallows :shutdown, :timeout.
- Every long-running process lives under a supervisor.
- No bare spawn/Task.async outside one-off scripts.

## GenServer
- GenServer is for long-lived state or serialized resource access.
- Not for pure computation, not for caching, not as a global dictionary.
- init/1 is for SETUP. Slow work moves to {:continue, _} or handle_info.
- Every call has an explicit timeout. State is a typed struct.
- Every GenServer is supervised; child_spec and restart strategy are explicit.

## Ecto and Contexts
- Ecto queries live in context modules, not controllers.
- Schemas hold types + changesets — no DB calls, no business logic.
- Multi-step writes use Ecto.Multi; never nest Repo.transaction manually.
- Preload at context boundaries; name reusable query functions.
- No `import Ecto.Query` in views, controllers, or LiveViews.

## Concurrency
- Use Task.Supervisor.async_stream_nolink with explicit max_concurrency
  and timeout.
- Every external I/O call has an explicit timeout — never rely on :infinity.
- No Task.async inside GenServer.handle_call.
- No spawn/1 in library or service code.

## Specs and Dialyzer
- @spec on every public function, using the most precise types.
- CI runs mix dialyzer; no new warnings allowed.
- @doc + @moduledoc on every public function/module.
- Doctests where the @spec is checkable via iex> examples.

## Phoenix
- Controllers do three things: parse, call context, render. Nothing else.
- No Repo in controllers, views, LiveViews, or HEEx components.
- action_fallback handles {:error, _} uniformly.
- LiveView mount/3 loads via context; handle_event routes to context;
  handle_info updates assigns from pub/sub.
- Cross-context work lives in an orchestrator module.

## Tooling
- `mix format` on every file; formatter config committed.
- `mix credo --strict` in CI.
- `mix dialyzer` in CI; PLT cached.
- Every public module has @moduledoc.
- Tests run `async: true` where state allows.

Real Examples: AI-Generated Code Before and After Rules

Here's what changes in practice when the rules above are loaded into Cursor.

Example 1: "Write a function that creates an order and charges the customer."

Without rules — typical AI output:

def place_order(user_id, params) do
  user = Repo.get!(User, user_id)
  try do
    order = Repo.insert!(%Order{user_id: user.id, total: params["total"]})
    case Stripe.charge(user.stripe_id, order.total) do
      {:ok, charge} ->
        Repo.update!(Ecto.Changeset.change(order, paid: true, charge_id: charge.id))
        {:ok, order}
      {:error, err} ->
        Repo.delete!(order)
        {:error, err}
    end
  rescue
    e -> {:error, e}
  end
end

Sin count: Repo.get! raises on missing user, manual compensation instead of transaction, rescue e swallows every error including shutdown, no spec, direct Ecto in the domain function without a changeset, no timeout on Stripe, no Multi, bang functions used for control flow.

With rules in .cursorrules — same prompt, idiomatic output:

alias Ecto.Multi
alias MyApp.{Repo, Payments.Stripe}

@spec place_order(pos_integer(), map()) ::
        {:ok, Order.t()}
        | {:error, :not_found | :charge_failed | Ecto.Changeset.t()}
def place_order(user_id, params) do
  with {:ok, user} <- Accounts.fetch_user(user_id),
       {:ok, %{order: order}} <- insert_and_charge(user, params) do
    {:ok, order}
  end
end

defp insert_and_charge(user, params) do
  Multi.new()
  |> Multi.insert(:order, Order.changeset(%Order{}, Map.put(params, "user_id", user.id)))
  |> Multi.run(:charge, fn _repo, %{order: order} ->
    case Stripe.charge(user.stripe_id, order.total, timeout: 5_000) do
      {:ok, %Stripe.Charge{} = charge} -> {:ok, charge}
      {:error, _} = err -> err
    end
  end)
  |> Multi.update(:paid, fn %{order: o, charge: c} ->
    Order.mark_paid_changeset(o, c.id)
  end)
  |> Repo.transaction()
  |> case do
    {:ok, _} = ok -> ok
    {:error, :charge, _reason, _} -> {:error, :charge_failed}
    {:error, _step, changeset, _} -> {:error, changeset}
  end
end

Transaction rolls back on any failure. Every branch has a tagged-tuple return. Repo.get! is gone. The spec documents every outcome. No try/rescue. Stripe has a timeout.

Example 2: "Fetch 100 product records from 3 upstream APIs in parallel."

With rules:

@spec fetch_catalog([product_id()]) :: [{product_id(), {:ok, Product.t()} | {:error, term()}}]
def fetch_catalog(product_ids) do
  [A, B, C]
  |> Enum.flat_map(&Enum.zip(product_ids, List.duplicate(&1, length(product_ids))))
  |> Task.Supervisor.async_stream_nolink(
    MyApp.TaskSup,
    fn {id, source} -> fetch_one(source, id) end,
    max_concurrency: 12,
    timeout: 4_000,
    on_timeout: :kill_task
  )
  |> Enum.map(fn
    {:ok, {id, result}} -> {id, result}
    {:exit, reason} -> {:error, reason}
  end)
end

Bounded concurrency, linked to the app's Task.Supervisor, per-request timeout shorter than the surrounding call, crashes isolated from the caller.

Get the Full Pack

These eight rules cover the highest-leverage Elixir patterns where AI assistants consistently fail — the ones that turn into silent data loss, unbounded message queues, and 3am pages. Drop them into .cursorrules and you'll see the difference on the very next prompt.

If you want the same depth for Rust, Go, Java, TypeScript, Python, React, Next.js, Phoenix LiveView, and more — all the rules I've packaged from a year of refining Cursor configs across production BEAM codebases — they're all at:

oliviacraft.lat

One pack. Twenty-plus languages and frameworks. Battle-tested rules with before/after examples for each. Stop fighting your AI assistant and start shipping idiomatic OTP code on the first try.

Cursor Rules for Scala: AI-Assisted Dev Guide 2026

Olivia Craft — Sun, 26 Apr 2026 09:56:04 +0000

Scala is the language where two developers on the same team write genuinely different dialects. One writes pure functional code with cats-effect IO, typeclass-derived instances, and Either[AppError, A] at every boundary. The other writes what looks like Java with better syntax — null returns, throw new RuntimeException, var counters, ArrayBuffer mutated in a for loop, Future chains with swallowed exceptions, and a deep class hierarchy rooted in an abstract BaseService. Both compile. Both pass tests. Only one of them survives contact with concurrency, error handling, and the production JVM.

Then you add an AI assistant.

Cursor and Claude Code were trained on fifteen years of Scala code that spans Scala 2.8 Java-in-Scala through modern Scala 3 with ZIO 2 and Cats-Effect 3. Ask for "a function that reads a user and returns their orders," and the AI picks a random slice of that history — you might get def getUser(id: Long): User that throws NotFoundException, or def getUser(id: Long): Future[Option[User]] with an implicit ExecutionContext leaking in from five files over, or def getUser(id: Long): IO[Either[AppError, User]] if you're lucky. It compiles either way. It tells you nothing about idiom, and it drags whatever patterns are dominant in your repo further from consistency with every prompt.

The fix is .cursorrules — one file in the repo that tells the AI what idiomatic Scala looks like in your codebase. Eight rules below, each with the failure mode, the rule that prevents it, and a before/after. Copy-paste .cursorrules at the end. Examples use Scala 3 syntax (given / using / enum) with a brief note where Scala 2 differs, Cats-Effect for effects, and standard immutable collections.

How Cursor Rules Work for Scala Projects

Cursor reads project rules from two locations: .cursorrules (a single file at the repo root, still supported) and .cursor/rules/*.mdc (modular files with frontmatter, recommended for any non-trivial Scala project). For Scala I recommend modular rules so that effect-system conventions (IO vs Future) don't interfere with pure-library code and so the type-class conventions only fire on files that actually define instances:

.cursor/rules/
  scala-core.mdc        # immutability, Option/Either, for-comp, ADTs
  scala-types.mdc       # sealed trait + case class, enum, opaque types
  scala-effects.mdc     # cats-effect IO (or ZIO), no blocking in IO
  scala-collections.mdc # immutable.List/Vector/Map, no java.util, no var
  scala-typeclasses.mdc # given/using, no inheritance hierarchies for polymorphism
  scala-sbt.mdc         # -Werror, -Xfatal-warnings, scalafmt, scalafix

Frontmatter controls activation: globs: ["**/*.scala", "**/*.sbt", "**/build.sbt", "**/project/*.scala"] with alwaysApply: false. Now the rules.

Rule 1: Immutability First — `val` Over `var`, Immutable Collections, No `null`

The single most common AI failure in Scala is "Java habits in Scala syntax." var count = 0 in a loop, ArrayBuffer mutated across function calls, null returned from a lookup, a mutable.Map passed between threads with no synchronization. Every one of these is a bug in a language whose whole point is that values don't change.

The rule:

Immutability is the default. Every value is a `val` unless there is a
specific, localized reason for `var` (tight-loop performance, or a
mutable cell inside a single function).

Collections default to scala.collection.immutable: List, Vector, Map,
Set. `mutable.*` is acceptable only inside a function body and never
crosses a method boundary.

Never return null. Never accept null as a valid input (use Option on
the type). When interop with Java returns nullable values, wrap at
the boundary: Option(javaCall()).

Transformations use map / flatMap / fold / foldLeft / collect — not
a while loop mutating a var. A `return` statement is a smell; rewrite
using a recursive helper, fold, or expression-oriented matching.

Prefer case class over class; prefer def over var; prefer val over def
when the computation is pure and cheap.

Forbidden at the API boundary:
  - Any type that is nullable in practice (java.util.Optional is
    tolerable only at the Java interop boundary).
  - Mutable collections as method parameters or return types.
  - Methods that take a function and mutate a captured variable.

Bad — vars, null, mutable collection, Java-style loop:

class OrderService {
  def totalFor(userId: Long): Double = {
    val orders = repo.findByUser(userId) // returns null if none
    if (orders == null) return 0.0
    var total = 0.0
    val i = orders.iterator()
    while (i.hasNext) {
      total += i.next().total
    }
    total
  }
}

Good — immutable values, Option at the boundary, expression-oriented:

final class OrderService(repo: OrderRepo):
  def totalFor(userId: UserId): Money =
    repo
      .findByUser(userId)      // returns List[Order] — empty means none
      .map(_.total)
      .foldLeft(Money.zero)(_ + _)

No null. No var. The computation is a single expression. Money.zero makes the empty case obvious; foldLeft eliminates the loop.

Rule 2: `Option`, `Either`, `Try` — Not `null` and Not Thrown Exceptions

The second-biggest AI Scala failure is "exceptions as control flow." throw new IllegalArgumentException("not found") inside a business function, try/catch wrapping the caller to translate it back into a return value, null returned from a lookup, and a completely different dialect being used by the next file over. The JVM will happily execute it; the type system tells you nothing about which functions can fail; and "find everywhere this error can surface" becomes a stack-trace-grepping exercise.

The rule:

Failure is data. Fallible operations return:
  - Option[A]          — value may be absent, no reason needed.
  - Either[E, A]       — value may be absent with a reason; E is your
                          error ADT, never a String or Throwable.
  - Try[A]             — used at the boundary with code that throws
                          (parsers, reflection, unsafe Java libs). Converted
                          to Either[E, A] at the earliest opportunity.
  - IO[A] / ZIO[R, E, A] — for effectful computations (see Rule 6).

Errors are a SEALED TRAIT (or Scala 3 `enum`) specific to the domain:

  enum OrderError:
    case InsufficientStock(itemId: ItemId)
    case PaymentDeclined(reason: String)
    case NotFound
    case Validation(field: String, message: String)

NEVER:
  - throw an exception from a business function. Exceptions are for
    bugs, boundary failures, and fatal JVM errors only.
  - Return Either[String, A] or Either[Throwable, A] — lose the type
    info and the pattern matcher can't help you.
  - Return null / Option[Null] / Option[Option[A]].
  - Swallow exceptions in a broad `catch NonFatal(_) =>`. If you catch,
    you translate to a typed error and return it.

.get on Option and .right.get on Either are forbidden in production
code. Use pattern matching, getOrElse, fold, or orElse.

Bad — thrown exception, String error, no typed ADT:

def authorize(user: User, action: String): Boolean = {
  if (user == null) throw new IllegalArgumentException("no user")
  if (user.banned) throw new RuntimeException("banned")
  user.permissions.contains(action)
}

Good — typed errors, composable returns, no exceptions:

enum AuthError:
  case Banned
  case Missing(permission: String)

def authorize(user: User, action: Permission): Either[AuthError, Unit] =
  if user.banned then Left(AuthError.Banned)
  else if user.permissions.contains(action) then Right(())
  else Left(AuthError.Missing(action.name))

Callers match on AuthError exhaustively. The compiler catches the day somebody adds a new case and forgets a branch.

Rule 3: For-Comprehensions for Monadic Composition

Scala's for is sugar for flatMap / map / withFilter. AI-generated code often builds nested flatMap callbacks instead — which works but becomes illegible once you chain three steps. For-comprehensions turn the same computation into a straight line that reads like imperative code but composes across Option, Either, IO, Future, and any other monad.

The rule:

When composing two or more monadic operations of the SAME effect,
use a for-comprehension — not nested flatMap or nested case matching.

Structure:
  for
    a <- monadA
    b <- monadB(a)
    c <- monadC(b)
  yield build(a, b, c)

The generators (a, b, c) can be:
  - val bindings for pure values (a = expr, no <-).
  - `if` filters (works for Option/List; does NOT work for Either — use
    a helper that lifts a Boolean into Either[E, Unit]).

Mixing effects:
  - Do NOT mix Future and Option in one for-comprehension — they're
    different monads. Use a monad transformer (OptionT, EitherT) or
    lift early.
  - For Either[E, A] with short-circuit, all steps must yield
    Either[E, _] with the SAME E. Adjust with .left.map or flatMap
    as needed.

For IO / ZIO chains, the for-comprehension is the standard idiom.
Desugared flatMap is acceptable for 1-2 steps but reach for `for` at 3+.

Bad — flatMap tower, one operation per arrow, hard to read:

def placeOrder(userId: UserId, items: List[ItemId]): Either[AppError, Order] =
  users.find(userId).flatMap { user =>
    inventory.reserve(items).flatMap { reservation =>
      payments.charge(user, reservation.total).flatMap { charge =>
        orders.insert(user, reservation, charge).map { order =>
          order
        }
      }
    }
  }

Good — straight-line for-comprehension:

def placeOrder(userId: UserId, items: List[ItemId]): Either[AppError, Order] =
  for
    user        <- users.find(userId).toRight(AppError.NotFound)
    reservation <- inventory.reserve(items)
    charge      <- payments.charge(user, reservation.total)
    order       <- orders.insert(user, reservation, charge)
  yield order

Same computation. Half the indentation. The error type is AppError throughout; any step returning a different error uses .leftMap(AppError.from) at its arrow.

Rule 4: Algebraic Data Types — Sealed Traits + Case Classes (or Scala 3 `enum`)

Scala's killer feature is algebraic data types: express a value as "one of these variants," and the compiler checks that every match handles every case. AI assistants often reach for class hierarchies with abstract class, virtual methods, and instanceof checks instead — which is Java-shaped code that loses the entire advantage. The ADT + pattern match is the single biggest leverage point in Scala codebases.

The rule:

Model variants as SEALED hierarchies + case classes/objects, or (Scala 3)
as `enum`. Match exhaustively.

Scala 3:
  enum PaymentMethod:
    case Card(last4: String, brand: CardBrand)
    case BankTransfer(iban: String)
    case Wallet(provider: WalletProvider)

Scala 2:
  sealed trait PaymentMethod
  object PaymentMethod:
    final case class Card(last4: String, brand: CardBrand) extends PaymentMethod
    final case class BankTransfer(iban: String) extends PaymentMethod
    final case class Wallet(provider: WalletProvider) extends PaymentMethod

Pattern match on the ADT; the compiler warns on missing cases. Turn
that warning into an error with -Wunused -Wnonexhaustive and
-Xfatal-warnings.

Guidelines:
  - All concrete ADT cases are `final` (to stop further inheritance).
  - The trait / base enum is `sealed` (so the compiler can see all cases).
  - Behavior that depends on the variant is a pattern match in a
    module, NOT virtual methods on each case — this keeps cases
    focused on data and lets new behaviors be added without changing
    the data definitions (expression problem; we're picking "easy to
    add operations" over "easy to add variants").
  - Prefer `enum` over `sealed trait` + case objects in Scala 3.
  - Use `opaque type` for domain wrappers (UserId, Money) to get
    type-safety without runtime boxing.

Forbidden:
  - `abstract class` with concrete methods that variant subclasses override
    — that's a virtual-dispatch hierarchy, not an ADT.
  - `if x.isInstanceOf[...]` — pattern match instead.
  - Partial matches (missing a case) in production code without a
    compiler warning acknowledgement.

Bad — class hierarchy with virtual dispatch and instanceof:

abstract class PaymentMethod {
  def describe: String
  def last4: String = ""
}
class Card(val number: String) extends PaymentMethod {
  override def describe = s"Card ending ${number.takeRight(4)}"
  override def last4 = number.takeRight(4)
}
class BankTransfer(val iban: String) extends PaymentMethod {
  override def describe = s"Bank: $iban"
}

def processorFor(pm: PaymentMethod): Processor = {
  if (pm.isInstanceOf[Card]) CardProcessor
  else if (pm.isInstanceOf[BankTransfer]) BankProcessor
  else throw new RuntimeException("unknown")
}

Good — enum, exhaustive pattern match, opaque types:

opaque type Iban   = String
opaque type Last4  = String

enum PaymentMethod:
  case Card(last4: Last4, brand: CardBrand)
  case BankTransfer(iban: Iban)
  case Wallet(provider: WalletProvider)

def describe(pm: PaymentMethod): String = pm match
  case PaymentMethod.Card(last4, brand)  => s"$brand ending ${last4: String}"
  case PaymentMethod.BankTransfer(iban)  => s"Bank: ${iban: String}"
  case PaymentMethod.Wallet(p)           => s"Wallet: $p"

def processorFor(pm: PaymentMethod): Processor = pm match
  case _: PaymentMethod.Card         => CardProcessor
  case _: PaymentMethod.BankTransfer => BankProcessor
  case _: PaymentMethod.Wallet       => WalletProcessor

Add a fourth payment method and the compiler lists every match that needs updating. No instanceof. No "unknown" branch that will someday fire at runtime.

Rule 5: Type Classes Over Inheritance for Polymorphism

When you need "the same operation, different types," the Java reflex is a base class or an interface. The Scala idiom is a type class — a trait parameterized by the type, with instances (given in Scala 3, implicit in Scala 2) that the compiler resolves. AI-generated code rarely uses type classes because the default training data is full of interface-heavy OOP. The result is a rigid hierarchy where adding a new type means editing a base class; a type class lets you add instances without touching the hierarchy at all.

The rule:

For polymorphism over types you don't control (stdlib types, Java
types, library types), use a TYPE CLASS rather than inheritance.

Scala 3:
  trait Show[A]:
    def show(a: A): String

  object Show:
    given Show[Int] with
      def show(a: Int) = a.toString

    given [A: Show]: Show[List[A]] with
      def show(xs: List[A]) = xs.map(summon[Show[A]].show).mkString("[", ",", "]")

  def display[A: Show](a: A): String = summon[Show[A]].show(a)

Scala 2:
  trait Show[A] { def show(a: A): String }
  object Show {
    implicit val intShow: Show[Int] = (a: Int) => a.toString
    implicit def listShow[A](implicit s: Show[A]): Show[List[A]] =
      xs => xs.map(s.show).mkString("[", ",", "]")
  }

Guidelines:
  - Instances go in the companion of the type class OR the companion
    of the data type — nowhere else. Keep implicit scope tight.
  - Derive instances when possible (Scala 3 `derives Show`; Shapeless
    in Scala 2) rather than hand-writing boilerplate.
  - Use Cats / Typelevel's existing type classes (Eq, Show, Functor,
    Monad) over rolling your own. Don't reinvent Semigroup.

Forbidden:
  - `implicit` imports at the call site to inject behavior — instances
    belong in canonical scope.
  - `abstract class` hierarchies used to simulate type classes — you've
    lost the open-for-extension benefit.
  - Global `implicit` vals with broad types (implicit ec: ExecutionContext
    at a global scope is the classic trap — inject it explicitly).

Bad — inheritance hierarchy for a rendering capability:

abstract class Renderable {
  def render: String
}
class IntWrapper(i: Int) extends Renderable {
  override def render = i.toString
}
class OrderWrapper(o: Order) extends Renderable {
  override def render = s"Order(${o.id})"
}
def display(r: Renderable): String = r.render

Any type that renders needs to be wrapped. Primitives can't be renderable. Third-party types need adapters.

Good — type class, instances in companions, no wrappers:

trait Render[A]:
  def render(a: A): String

object Render:
  given Render[Int] with
    def render(a: Int) = a.toString

  given Render[Order] with
    def render(o: Order) = s"Order(${o.id})"

  given [A: Render]: Render[List[A]] with
    def render(xs: List[A]) = xs.map(summon[Render[A]].render).mkString("[", ",", "]")

def display[A](a: A)(using r: Render[A]): String = r.render(a)

display(42), display(order), display(List(order1, order2)) all work. Adding a Render[User] doesn't require editing anything except the Render companion or User's companion.

Rule 6: Effect Types — `IO` / `ZIO` Over Raw `Future`, No Blocking on the Main Pool

Future was Scala's effect type for a decade, and the AI's training data is full of it. But Future has structural problems: it's eager (starts as soon as it's created), it captures its ExecutionContext from implicit scope (which makes "what runs where" invisible), and it can't be cancelled. Modern production Scala uses Cats-Effect's IO or ZIO's ZIO[R, E, A]: referentially transparent, cancellable, with explicit scheduling.

The rule:

For new code, effect composition uses IO (cats-effect) or ZIO.
Future is acceptable at the boundary with libraries that return it
(akka-http, slick) and is converted to IO immediately (IO.fromFuture).

Rules with IO/ZIO:
  - No hidden implicit ExecutionContext. The effect runtime carries
    its own scheduler.
  - Blocking operations use IO.blocking { ... } (cats-effect) or
    ZIO.attemptBlocking. Never block on the compute pool.
  - Errors are typed: IO raises Throwable (wrap to Either[E, A] for
    domain errors); ZIO[R, E, A] makes E first-class.
  - Concurrency uses parMapN, parTraverse, Stream, Fiber — all with
    bounded parallelism.
  - Shutdown semantics are defined: Resource (cats-effect) or Scope
    (ZIO) for anything that needs cleanup.

Future-specific rules (if you must use it):
  - Every Future is created inside an enclosing function that takes
    ExecutionContext explicitly (using) — never as a global implicit.
  - Never Await.result in production code. Run at the edge of the
    world only.
  - Use Future.traverse with an explicit parallelism bound, not bare
    flat Map-over-list.
  - Never swallow failures in .recover { case _ => default } without
    at least logging.

Forbidden everywhere:
  - Thread.sleep in business logic. Use IO.sleep (which doesn't block).
  - scala.concurrent.blocking {} wrapping network calls — it's a hint
    to the default pool, not a separate pool. Use a dedicated EC or
    IO.blocking.
  - Bare Thread / new Runnable / ExecutorService in code. Use the
    effect library's scheduling.

Bad — raw Future, global implicit EC, Await at the edge, swallowed failure:

import scala.concurrent.ExecutionContext.Implicits.global

def topCustomers(): Future[List[Customer]] = {
  customers.listAll().map { all =>
    all.filter(_.spend > 10000)
       .sortBy(-_.spend)
       .take(10)
  }.recover { case _ => Nil }
}

val result = Await.result(topCustomers(), 10.seconds) // blocks the caller

Good — IO, explicit resource, typed error, bounded concurrency:

import cats.effect.*
import cats.syntax.all.*

def topCustomers(repo: CustomerRepo): IO[Either[AppError, List[Customer]]] =
  repo.listAll.attempt.map:
    case Right(all)   => Right(all.filter(_.spend > 10_000).sortBy(-_.spend).take(10))
    case Left(e: DbError) => Left(AppError.Persistence(e))
    case Left(e)      => Left(AppError.Unexpected(e.getMessage))

// At the edge of the world (main / HTTP handler):
object Main extends IOApp.Simple:
  def run: IO[Unit] =
    CustomerRepo.resource.use: repo =>
      topCustomers(repo).flatMap:
        case Right(customers) => IO.println(customers.mkString("\n"))
        case Left(err)        => IO.println(s"failed: $err").as(ExitCode.Error).void

No global ExecutionContext. No blocking. The effect is lazy — you can compose topCustomers with retries, timeouts, or parMapN without evaluating anything.

Rule 7: Collections — Immutable by Default, Lazy with Care, No `java.util`

Scala has three collection hierarchies: scala.collection.immutable, scala.collection.mutable, and views/streams. AI-generated code picks at random from all three plus java.util (because Java interop is easy and the training data includes mixed codebases). The consequence is subtle correctness bugs — a mutable.Map passed to two threads, a LazyList held at head causing memory retention, a java.util.ArrayList in a public API that callers have to defensively copy.

The rule:

Collection choices:
  - Use scala.collection.immutable.{List, Vector, Map, Set} by default.
  - Use Vector for random access or large collections; List for head-heavy
    linked-list access.
  - Use LazyList for infinite or expensive streams, but NEVER hold a
    reference to the head — iterate and drop, or use fs2.Stream / ZStream.
  - Use mutable.* ONLY inside a function body and convert to immutable
    before returning.
  - Use Array only for JVM interop or numeric hot loops.
  - Do NOT expose java.util.{List, Map, Set} in public APIs. Wrap or
    convert at the boundary: javaList.asScala.toList.

Common pitfalls:
  - `.view` is lazy; materialize with `.toList` / `.toVector` before
    returning or storing.
  - `.par` (parallel collections) is deprecated in Scala 3 / moved to a
    library; prefer IO.parTraverse, ZIO.foreachPar, or fs2.Stream.
  - `.iterator` can be consumed only once — don't return one from a public
    method, return a `View` or a fresh-each-time function.

Performance: `List` prepends are O(1); appends are O(n). Use
`List#::` / `Vector#:+` appropriately, or build with `ListBuffer`
inside a function and convert at the end.

Equality: use `==` (structural) for value types. For primitive-heavy
code, use `java.util.Arrays.equals`. `.eq` (reference equality) is
rarely what you want.

Bad — mutable buffer returned, view held, java.util leaking:

def topScorers(rounds: java.util.List[Round]): mutable.Buffer[Player] = {
  val buf = mutable.Buffer[Player]()
  val it = rounds.iterator()
  while (it.hasNext) {
    val r = it.next()
    if (r.score > 100) buf += r.player
  }
  buf
}

val lazy = players.view.filter(_.active) // never materialized — surprises later

Good — immutable API, no java interop leakage, materialized before return:

def topScorers(rounds: List[Round]): List[Player] =
  rounds.collect { case Round(p, score) if score > 100 => p }

// Interop at the boundary
def fromJava(rounds: java.util.List[Round]): List[Round] =
  rounds.asScala.toList

// Active players, materialized once
val active: Vector[Player] = players.iterator.filter(_.active).toVector

Callers can safely share the returned List. No hidden mutation. No accidentally-retained view.

Rule 8: Strict sbt — `-Werror`, Fatal Warnings, scalafmt, scalafix

A Scala compiler run that produces warnings is a Scala compiler run that's hiding bugs. Unused imports, missing exhaustive matches, deprecated APIs, implicit conversions that lose type information — every one of these is a warning until you treat it as an error. AI-generated code frequently introduces all of them because the compiler didn't stop the build. A strict sbt config makes the compiler an ally instead of a doorman.

The rule:

build.sbt baseline for every module:

  scalaVersion := "3.3.3"  // latest LTS
  scalacOptions ++= Seq(
    "-deprecation",
    "-feature",
    "-unchecked",
    "-Werror",                 // warnings are errors
    "-Wunused:all",
    "-Wvalue-discard",
    "-Ysafe-init",
    "-explain",
    "-source:future"           // opt into future-compat warnings
  )

For Scala 2 use equivalent flags plus the compiler plugin:
  - "-Xfatal-warnings"
  - "-Ywarn-unused"
  - "-Xlint:_"
  - wartremover plugin for deeper checks (Any, Null, Var).

Tooling in CI:
  - scalafmt   — formatting, config committed, check in CI.
  - scalafix   — semantic rewrites (OrganizeImports, ExplicitResultTypes).
  - sbt +test  — all cross-compilations green.
  - mdoc       — documentation examples are compiled and tested.

Library hygiene:
  - Pin Scala version (scalaVersion := "3.3.3", not latest).
  - Prefer libraryDependencySchemes := strict to catch minor-version
    incompatibilities.
  - Use sbt-dependency-check or sbt-snyk in CI.
  - Favor typelevel stack (cats, cats-effect, fs2, http4s, skunk,
    doobie) for effect-typed apps; play / akka for frameworks.

Project layout:
  - Business logic in `core/` with zero web/http dependencies.
  - Web adapter in `http/`, database adapter in `db/`.
  - Main module wires them together. Each module is independently
    testable.

Bad — permissive scalac, no warnings enforced, Any-leaking API:

// build.sbt
scalaVersion := "3.3.0"
scalacOptions ++= Seq("-deprecation")

// elsewhere
def handle(input: Any): Any = input match
  case s: String => s.length
  case i: Int    => i * 2
  case _         => null   // null returned, Any accepted, Any returned

Good — strict flags, no Any at the boundary, exhaustive match:

// build.sbt
scalaVersion := "3.3.3"
scalacOptions ++= Seq(
  "-deprecation", "-feature", "-unchecked",
  "-Werror", "-Wunused:all", "-Wvalue-discard",
  "-Ysafe-init", "-explain", "-source:future"
)

enum Input:
  case Text(s: String)
  case Number(i: Int)

def handle(in: Input): Int = in match
  case Input.Text(s)   => s.length
  case Input.Number(i) => i * 2

Add Input.Bool(b: Boolean) and the build fails at every unexhaustive match. No Any. No null. No silent regressions.

The Complete `.cursorrules` File for Scala

Drop this into your repo root as .cursorrules, or split into .cursor/rules/*.mdc files. It's the consolidated version of every rule above plus the tooling defaults.

# Scala Cursor Rules

## Immutability
- Default to `val`; `var` only inside a function body for localized performance.
- scala.collection.immutable by default (List, Vector, Map, Set).
- Never return null; never accept null. Wrap Java interop with Option(...).
- mutable.* never crosses a method boundary.
- Prefer case class over class; prefer def over var.

## Errors
- Fallible operations return Option[A], Either[E, A], or IO/ZIO with typed errors.
- E is a sealed trait / enum specific to the domain — never String, never Throwable.
- Never throw from a business function.
- Never `catch NonFatal(_)` without translating to a typed error.
- .get on Option and .right.get on Either are forbidden in production.

## For-Comprehensions
- Use for { ... } for 2+ monadic steps over the same effect.
- Mix effects via OptionT / EitherT, not ad-hoc conversions in the middle.
- Adjust error types with `.leftMap` so all generators share an E.

## ADTs
- Model variants with sealed trait + case class or Scala 3 enum.
- All concrete cases are final; the trait/base is sealed.
- Behavior depending on variant is a pattern match in a module — not
  virtual methods per case.
- Use opaque type for domain wrappers (UserId, Money).
- No `x.isInstanceOf[...]`.

## Type Classes
- Polymorphism over external/stdlib types uses a type class, not inheritance.
- Instances live in the companion of the type class OR the data type — tight scope.
- Prefer Cats' Eq/Show/Functor/Monad over hand-rolled.
- No global implicit ExecutionContext; inject explicitly.
- Derive instances (derives Show, Codec) when possible.

## Effects
- New code uses IO (cats-effect) or ZIO for effect composition.
- Future is a boundary type only; convert to IO with IO.fromFuture.
- IO.blocking for blocking ops — never block the compute pool.
- parTraverse / parMapN with explicit concurrency bounds.
- Resource / Scope for anything needing cleanup.
- No Thread.sleep in business logic; use IO.sleep.

## Collections
- scala.collection.immutable by default.
- Vector for random access; List for head-heavy.
- LazyList: never hold the head.
- mutable.* only inside a function; convert before return.
- Do not expose java.util.* in public APIs; convert at the boundary.

## sbt and Tooling
- scalaVersion pinned (latest LTS).
- scalacOptions: -Werror, -Wunused:all, -Wvalue-discard, -Ysafe-init, -explain.
- scalafmt config committed; scalafmtCheckAll in CI.
- scalafix rules: OrganizeImports, ExplicitResultTypes, NoAutoTupling.
- mdoc for documentation that's compiled.
- libraryDependencySchemes := strict; CI dependency checks.

## Testing
- MUnit or ScalaTest with async: true where state allows.
- Property tests via ScalaCheck for data transformations.
- Effect tests with cats-effect-testing or zio-test.
- No shared mutable state in tests.

Real Examples: AI-Generated Code Before and After Rules

Here's what changes in practice when the rules above are loaded into Cursor.

Example 1: "Write a function that loads a user, fetches their orders, and computes total spend."

Without rules — typical AI output:

import scala.concurrent.ExecutionContext.Implicits.global

def totalSpend(userId: Long): Future[Double] = {
  userRepo.find(userId).flatMap { userOpt =>
    userOpt match {
      case Some(user) =>
        orderRepo.byUser(user.id).map { orders =>
          var total = 0.0
          for (o <- orders) total += o.amount
          total
        }
      case None => Future.failed(new RuntimeException("not found"))
    }
  }.recover { case _ => 0.0 }
}

Sin count: global implicit EC, Future.failed with a String wrapped in an exception, var accumulator, imperative for-loop, swallowed failure in .recover, no typed error, no return type on orderRepo.byUser, uses Double for money.

With rules in .cursorrules — same prompt, idiomatic output:

enum AppError:
  case UserNotFound
  case Persistence(cause: Throwable)

def totalSpend(userId: UserId)(using users: UserRepo, orders: OrderRepo)
    : IO[Either[AppError, Money]] =
  (for
    user   <- EitherT(users.find(userId).attempt.map {
                case Right(Some(u)) => Right(u)
                case Right(None)    => Left(AppError.UserNotFound)
                case Left(e)        => Left(AppError.Persistence(e))
              })
    orders <- EitherT(orders.byUser(user.id).attempt.map {
                case Right(os) => Right(os)
                case Left(e)   => Left(AppError.Persistence(e))
              })
  yield orders.map(_.amount).foldLeft(Money.zero)(_ + _)).value

Typed error ADT. Money instead of Double. for over EitherT composes errors cleanly. No global EC; dependencies via using. No var, no imperative loop, no swallowed failure.

Example 2: "Process 1000 items in parallel, bounded to 8 at a time."

Without rules:

val futures = items.map(i => Future(process(i)))
val all = Future.sequence(futures)       // unbounded parallelism
val results = Await.result(all, Inf)     // blocks forever if any hangs

With rules:

def processAll(items: List[Item]): IO[List[Result]] =
  items.parTraverseN(8)(item => IO.blocking(process(item)))

Bounded at 8 concurrent. Blocking process runs on the blocking pool, not the compute pool. The whole thing is lazy — compose with timeouts or retries before running.

Get the Full Pack

These eight rules cover the highest-leverage Scala patterns where AI assistants consistently fail — the ones that turn pure functional code into Java-in-Scala and quiet bugs into production incidents. Drop them into .cursorrules and you'll see the difference on the very next prompt.

If you want the same depth for Rust, Go, Java, Kotlin, TypeScript, Python, React, Next.js, Elixir, and more — all the rules I've packaged from a year of refining Cursor configs across production JVM codebases — they're all at:

oliviacraft.lat

One pack. Twenty-plus languages and frameworks. Battle-tested rules with before/after examples for each. Stop fighting your AI assistant and start shipping idiomatic Scala on the first try.

8 Cursor Rules for Go Developers — 2026 Edition

Olivia Craft — Sun, 26 Apr 2026 09:55:03 +0000

Go prizes one obvious way. Then an AI assistant trained on a planet of Java and Python writes code that compiles but reads like a C# port: swallowed errors, fat interfaces, goroutines nobody owns, and init() doing database calls on import. The fix isn't endless re-prompting — it's a .cursorrules file that tells Cursor and Claude Code what idiomatic Go actually looks like in your repo. Eight rules, each with a before and after. Drop them in and ship.

Rule 1: Errors are values — handle them, never discard

Never write `_ = someCall()` to ignore an error.
Check every returned error and return with context via fmt.Errorf("%w", err).
Sentinel errors use errors.Is; typed errors use errors.As.

Before

f, _ := os.Open(path)
defer f.Close()
data, _ := io.ReadAll(f)

After

f, err := os.Open(path)
if err != nil {
    return nil, fmt.Errorf("open %s: %w", path, err)
}
defer f.Close()
data, err := io.ReadAll(f)
if err != nil {
    return nil, fmt.Errorf("read %s: %w", path, err)
}

Errors wrap with %w so callers can errors.Is them. No silent data loss.

Rule 2: Accept interfaces, return concrete types

Function parameters take the smallest interface the function actually uses.
Return concrete struct pointers, not interfaces.
Interfaces are defined at the consumer, not the producer.

Before

type UserService interface { /* 14 methods */ }
func NewUserService() UserService { return &userService{} }
func Send(s UserService, id string) error { return s.SendEmail(id) }

After

type emailSender interface {
    SendEmail(id string) error
}

func Send(s emailSender, id string) error { return s.SendEmail(id) }

type UserService struct{ /* ... */ }
func NewUserService() *UserService { return &UserService{} }

Tests pass a two-line fake. The producer stays flexible.

Rule 3: `context.Context` is the first argument, always

Every function that does I/O, crosses a goroutine boundary, or may block
takes ctx context.Context as its first parameter.
Never store ctx in a struct. Never pass context.TODO() in production code.

Before

func (r *Repo) FindUser(id string) (*User, error) {
    return r.db.QueryRow("SELECT ... WHERE id=$1", id).Scan(...)
}

After

func (r *Repo) FindUser(ctx context.Context, id string) (*User, error) {
    return r.db.QueryRowContext(ctx, "SELECT ... WHERE id=$1", id).Scan(...)
}

Now a cancelled HTTP request actually cancels the query. Timeouts propagate.

Rule 4: Every goroutine has an owner and a stop signal

Goroutines are spawned from a parent that knows how to stop them.
Use errgroup.Group, sync.WaitGroup, or context cancellation.
Never `go f()` at the top level of a handler without an owner.

Before

func handle(w http.ResponseWriter, r *http.Request) {
    go processAsync(r.Body) // leaked if server shuts down mid-request
    w.WriteHeader(http.StatusAccepted)
}

After

func handle(w http.ResponseWriter, r *http.Request) {
    g, ctx := errgroup.WithContext(r.Context())
    g.Go(func() error { return processAsync(ctx, r.Body) })
    if err := g.Wait(); err != nil {
        http.Error(w, err.Error(), 500); return
    }
    w.WriteHeader(http.StatusAccepted)
}

When the request ends, so does the goroutine. No leaks on shutdown.

Rule 5: Channels have a direction — declare it

Function parameters use directional channel types: `<-chan T` for receive,
`chan<- T` for send. Only the owner may close a channel.
Never close a channel on the sender side from multiple goroutines.

Before

func producer(c chan int) { for i := 0; i < 10; i++ { c <- i } }
func consumer(c chan int) { for v := range c { fmt.Println(v) } }

After

func producer(out chan<- int) {
    defer close(out)
    for i := 0; i < 10; i++ { out <- i }
}

func consumer(in <-chan int) {
    for v := range in { fmt.Println(v) }
}

The compiler enforces the contract. Closing twice is a compile error.

Rule 6: `init()` is for registration, not business logic

init() may register drivers, parse embedded templates, or set up lookup tables.
init() may NOT open DB connections, read env vars, or spawn goroutines.
Configuration happens in main(). Everything is dependency-injected from there.

Before

var db *sql.DB

func init() {
    db, _ = sql.Open("postgres", os.Getenv("DATABASE_URL"))
}

After

func NewApp(cfg Config) (*App, error) {
    db, err := sql.Open("postgres", cfg.DatabaseURL)
    if err != nil {
        return nil, fmt.Errorf("open db: %w", err)
    }
    return &App{DB: db}, nil
}

Tests build an App with a test DB. Production reads env in main(). No import-time surprises.

Rule 7: Tests are table-driven with `t.Run` subtests

Tests use `tests := []struct { name string; ... }{}` plus `for _, tc := range tests`
and `t.Run(tc.name, func(t *testing.T) { ... })`.
Use t.Parallel() on independent subtests. Use t.Cleanup for teardown.

Before

func TestAdd(t *testing.T) {
    if Add(1, 2) != 3 { t.Fatal("1+2") }
    if Add(0, 0) != 0 { t.Fatal("0+0") }
    if Add(-1, 1) != 0 { t.Fatal("-1+1") }
}

After

func TestAdd(t *testing.T) {
    tests := []struct {
        name string
        a, b, want int
    }{
        {"positives", 1, 2, 3},
        {"zeros", 0, 0, 0},
        {"mixed_signs", -1, 1, 0},
    }
    for _, tc := range tests {
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()
            if got := Add(tc.a, tc.b); got != tc.want {
                t.Fatalf("Add(%d,%d)=%d want %d", tc.a, tc.b, got, tc.want)
            }
        })
    }
}

Adding a case is one line. Failure output names the failing case. -run TestAdd/zeros targets one.

Rule 8: `gofmt`, `go vet`, `golangci-lint` — clean or it doesn't ship

Every commit passes: gofmt -s -d, go vet, golangci-lint run.
Enable: errcheck, govet, ineffassign, staticcheck, unused, gosec, revive.
No `//nolint` without a reason comment and an issue link.

Before: developer hand-runs some of these, reviewers eyeball the rest.

After: a Makefile target plus pre-commit hook:

.PHONY: check
check:
    gofmt -s -l . | tee /dev/stderr | (! read)
    go vet ./...
    golangci-lint run ./...

Commits that fail never land on main. Lint findings stop being PR-review filler and become compile-time errors for humans.

Drop them in and stop re-prompting

These eight rules cover where AI-written Go gets unidiomatic: error handling, interfaces, context, goroutines, channels, init, tests, and tooling. Paste them into .cursorrules at the repo root and the next function Cursor generates will already look like Go a Gopher would merge.

If you want the expanded set — these eight plus rules for generics, sync.Pool, HTTP middleware, database/sql patterns, slog structured logging, embed, and testcontainers-based integration tests — grab Cursor Rules Pack v2 ($27, one payment, lifetime updates). Drop it in your repo, stop fighting your AI, ship Go you'd merge.

size-test

Olivia Craft — Sat, 25 Apr 2026 20:56:37 +0000

hello

world

rl-probe

Olivia Craft — Fri, 24 Apr 2026 12:02:15 +0000

test

hello world

Cursor Rules for Svelte: The Complete Guide to AI-Assisted Svelte Development

Olivia Craft — Fri, 24 Apr 2026 11:55:51 +0000

Cursor Rules for Svelte: The Complete Guide to AI-Assisted Svelte Development

Svelte is the framework where the compiler does so much for you that the bugs are almost always shape bugs, not behavior bugs. The component renders. The reactive statement runs. The store updates. And nothing in npm run dev warns you that the $: block you wrote depends on a value the compiler can't statically see, that the onMount callback you marked async is going to set state on an unmounted component when the user navigates mid-fetch, that the global store you import in seven components is leaking subscriptions because you never called the unsubscribe function the subscribe call returned, that the +page.svelte you wrote with a top-level fetch runs on the client first and re-runs after hydration, double-firing the request and shifting layout, or that the transition:fade you sprinkled on every list item makes a 200-row table take three full seconds to mount on a mid-tier Android. The app feels fast in development. It ships. Real users on real connections see jank, double-fetches, stale store values after navigation, and a memory profile that climbs every time someone opens and closes a modal.

Then you add an AI assistant.

Cursor and Claude Code were trained on a decade of Svelte content. Most of it is Svelte 3 syntax with <slot> everywhere, components that prop-drill state through five levels because the tutorial author hadn't introduced stores yet, $: doubled = count * 2 examples that hide the ten different things you should never put in a $: block, onMount(async () => { data = await fetch(...) }) with no abort signal and no unmount guard, <script lang="ts"> with export let user; and no type annotation at all, and +page.svelte files that call fetch from the markup as if SvelteKit's load function didn't exist. Ask for "a Svelte page that lists users," and you get prop-drilled props, a reactive block that fires on every keystroke even when nothing relevant changed, a fetch in onMount that races itself on navigation, and a transition on every <li>.

The fix is .cursorrules — one file in the repo that tells the AI what idiomatic modern Svelte (and SvelteKit) actually looks like. Eight rules below, each with the failure mode, the rule, and a before/after. Copy-paste .cursorrules at the end.

How Cursor Rules Work for Svelte Projects

Cursor reads project rules from two locations: .cursorrules (a single file at the repo root, still supported) and .cursor/rules/*.mdc (modular files with frontmatter, recommended for anything bigger than a single app). For Svelte/SvelteKit I recommend modular rules so a marketing site's transition conventions don't bleed into a dashboard's data-loading constraints:

.cursor/rules/
  svelte-core.mdc        # stores, reactivity, lifecycle
  svelte-props.mdc       # typed props, generics, slot/snippet
  svelte-kit-load.mdc    # load functions, server vs universal
  svelte-kit-forms.mdc   # form actions, progressive enhancement
  svelte-motion.mdc      # transitions, animations, performance

Frontmatter controls activation: globs: ["**/*.{svelte,ts}"] with alwaysApply: false. Now the rules.

Rule 1: Stores Over Prop Drilling — `writable`, `readable`, `derived`

The most common Svelte mistake is prop-drilling state through five layers because the AI was trained on small example components. Cursor writes <UserList user={user} /> then <UserRow user={user} /> then <UserAvatar user={user} /> and now any change to the User shape rewrites four files. The fix is the store: writable<User>(initial) lives in one module, every component that needs the value imports it and reads with $user, every component that needs to update calls user.set(...) or user.update(fn). derived composes stores into computed values. readable wraps external sources (a WebSocket, the system clock, the page visibility API) so subscribers get start/stop notifications for free.

The rule:

State that more than two components read or write goes in a store, not
in props. Define stores in `src/lib/stores/<name>.ts`, export the store
itself plus narrow read/write helpers when the API is non-trivial.

writable<T>(initial) for plain mutable state. update(fn) over set(value)
when the new value depends on the old. Never mutate the value in place
(`$user.name = 'x'`) — Svelte sees no change. Always call set/update.

derived([a, b], ([$a, $b]) => ...) for computed values. Never compute
in markup with `$:` when the same computation is used in multiple
components — derive once, subscribe everywhere.

readable<T>(initial, (set) => { ...; return () => cleanup(); }) for
external sources. The teardown function fires when the last subscriber
unsubscribes — wire WebSockets, intervals, event listeners through this.

Auto-subscription with `$store` only inside .svelte files. In .ts files
use `get(store)` for one-shot reads or `store.subscribe(fn)` and capture
the unsubscribe. Never let a manual subscribe leak.

Never put non-serializable values (DOM nodes, class instances with
methods) in stores that cross route boundaries — SvelteKit serializes
them and you lose identity.

Before — prop-drilled state, mutated in place, no single source of truth:

<!-- App.svelte -->
<script>
  let user = { name: 'Ada', plan: 'free' };
</script>
<Layout {user}>
  <Sidebar {user} />
  <Main {user} on:upgrade={() => user.plan = 'pro'} />
</Layout>

<!-- Main.svelte -->
<script>
  export let user;
  function upgrade() {
    user.plan = 'pro'; // mutation — no re-render in Sidebar
  }
</script>
<button on:click={upgrade}>Upgrade</button>

user.plan = 'pro' mutates the object in place. The parent's reference doesn't change, so Svelte's $:-backed reactivity in Sidebar never fires. Every layer takes a user prop just to forward it.

After — store, derived value, auto-subscription, no mutation:

<!-- src/lib/stores/user.ts -->
<script context="module" lang="ts">
  import { writable, derived } from 'svelte/store';
  export const user = writable<{ name: string; plan: 'free' | 'pro' }>(
    { name: 'Ada', plan: 'free' }
  );
  export const isPaid = derived(user, ($u) => $u.plan === 'pro');
</script>

<!-- Main.svelte -->
<script lang="ts">
  import { user } from '$lib/stores/user';
  function upgrade() {
    user.update((u) => ({ ...u, plan: 'pro' }));
  }
</script>
<button on:click={upgrade}>Upgrade</button>

<!-- Sidebar.svelte -->
<script lang="ts">
  import { user, isPaid } from '$lib/stores/user';
</script>
<p>{$user.name} {#if $isPaid}★{/if}</p>

update returns a new object — every subscriber re-renders. Sidebar and Main import directly; no prop-forwarding through Layout. derived computes isPaid once.

Rule 2: Reactive Declarations With `$:` — Pure, Statically Analyzable, No Side Effects

Svelte's $: is its most powerful and most misused feature. It runs whenever any referenced reactive variable changes — but the compiler only tracks what it can statically see in the dependency graph. Cursor writes $: result = compute(items) where compute reads from a closure variable the compiler can't see, and the block silently never re-runs. Worse, Cursor uses $: for side effects: $: console.log(count), $: localStorage.setItem('x', value), $: fetch(url). The block fires on every render of every dependency, including ones you didn't realize were dependencies — you get triple writes to localStorage, three fetches per keystroke, and a console flood that hides the actual bug.

The rule:

`$:` is for derived values that are pure functions of their declared
dependencies. `$: doubled = count * 2`. `$: filtered = items.filter(matches)`.
The right-hand side must be a pure expression — no fetch, no localStorage,
no logging, no setState-style writes to other reactive variables.

For side effects on change, use the explicit pattern:
`$: { if (value !== prev) { sideEffect(value); prev = value; } }` — and
even better, lift the side effect into an effect/store subscription
outside the component, or into onMount/afterUpdate with explicit guards.

Never do destructive work in `$:` (`$: items.push(x)`). The block runs
multiple times on the same input — you'll duplicate effects. Compute,
don't mutate.

Multi-statement reactive blocks (`$: { ... }`) declare ALL their
dependencies in the first executed line. If the first branch returns
early, dependencies in the unreached branch are not tracked. Read the
inputs at the top, then branch.

For Svelte 5 projects, prefer `$state`/`$derived`/`$effect` runes
over `$:` — they have explicit dependency tracking and clearer side-
effect semantics.

Before — side effect in $:, hidden dependency, triple-firing:

<script>
  export let userId;
  let user = null;
  let count = 0;

  $: fetchUser(userId); // fires on every count change too — count is a closure dep
  $: console.log('user changed', user); // logs on render, not on user change
  $: items.push({ userId, count }); // mutates on every reactive tick

  async function fetchUser(id) {
    const r = await fetch(`/api/users/${id}`);
    user = await r.json();
    count++; // re-triggers $: fetchUser → infinite loop
  }
</script>

fetchUser mutates count, which is a dependency of the same $: block, which re-fires the fetch. items.push runs on every render. The console "log on change" actually logs on every render, including ones where user didn't change.

After — $: for pure derivation, side effects in onMount + reactive guard:

<script lang="ts">
  import { onMount } from 'svelte';
  export let userId: string;
  let user: User | null = null;
  let prevUserId = '';

  $: greeting = user ? `Hello ${user.name}` : 'Loading…'; // pure derivation

  $: if (userId !== prevUserId) {
    prevUserId = userId;
    void loadUser(userId); // explicit, guarded, single fire per change
  }

  async function loadUser(id: string) {
    const r = await fetch(`/api/users/${id}`);
    if (!r.ok) return;
    user = await r.json();
  }
</script>

<p>{greeting}</p>

$: greeting = ... is pure — recomputes when user changes, never fires a network call. The side effect lives behind an explicit if (changed) guard so it fires once per real change, not once per reactive tick.

Rule 3: Lifecycle Discipline — `onMount` Async Safety, `onDestroy` Cleanup

onMount(async () => { data = await fetch(...) }) looks innocent and is the source of most "state set on unmounted component" bugs in Svelte. The component mounts, the fetch starts, the user navigates away, the component unmounts, the fetch resolves, the assignment runs against a destroyed instance. In dev you see a stale render; in prod you see memory pressure as event listeners and intervals never get cleaned up. Cursor doesn't write onDestroy cleanup unless explicitly asked because the training examples are toy components that never unmount. Same problem with setInterval, addEventListener, IntersectionObserver, WebSocket subscriptions — start in onMount, forget in onDestroy, leak forever.

The rule:

`onMount` MUST NOT be marked `async`. The Svelte runtime treats the
return value as a cleanup function — an async onMount returns a
Promise, which it can't use as cleanup. Define an inner async function
and call it: `onMount(() => { void load(); })`.

Async work started in onMount uses an AbortController. Store the
controller, pass `signal` to fetch, abort in onDestroy / the cleanup
return. Race-protected: `if (controller.signal.aborted) return;`
before any state assignment.

Every onMount that allocates a resource (interval, listener, observer,
subscription, websocket) RETURNS a cleanup function. The return-from-
onMount form is preferred over a separate onDestroy because it keeps
allocate and free side-by-side.

Manual store subscriptions (`store.subscribe(fn)`) outside .svelte files
ALWAYS capture the unsubscribe and call it. Inside .svelte files use
`$store` autosubscribe — never manual subscribe.

`beforeUpdate` / `afterUpdate` are escape hatches. Reach for them only
when DOM measurement requires it (focus management, scroll position
preservation). Never for "setState on data change" — that is `$:`.

For Svelte 5: prefer `$effect` with its automatic cleanup return — it
subsumes onMount + onDestroy for most cases.

Before — async onMount, no abort, no cleanup, leaked interval:

<script>
  import { onMount } from 'svelte';
  export let userId;
  let user = null;

  onMount(async () => {
    const r = await fetch(`/api/users/${userId}`);
    user = await r.json(); // fires even if the user navigated away

    setInterval(() => poll(userId), 5000); // never cleared
    window.addEventListener('focus', () => poll(userId)); // never removed
  });
</script>

If the route changes during await, the assignment runs on an unmounted component and React-style warnings flood the console. The interval and listener accumulate every time the user visits this route.

After — sync onMount, AbortController, cleanup return:

<script lang="ts">
  import { onMount } from 'svelte';
  export let userId: string;
  let user: User | null = null;

  onMount(() => {
    const controller = new AbortController();

    (async () => {
      try {
        const r = await fetch(`/api/users/${userId}`, { signal: controller.signal });
        if (controller.signal.aborted) return;
        user = await r.json();
      } catch (err) {
        if ((err as Error).name === 'AbortError') return;
        throw err;
      }
    })();

    const interval = setInterval(() => poll(userId), 5000);
    const onFocus = () => poll(userId);
    window.addEventListener('focus', onFocus);

    return () => {
      controller.abort();
      clearInterval(interval);
      window.removeEventListener('focus', onFocus);
    };
  });
</script>

Mount-time allocation and unmount-time cleanup live in the same block. The fetch aborts on navigation. The interval and listener are released. No "set state on unmounted component" warnings.

Rule 4: Typed Props With TypeScript Generics — `export let` Without `: T` Is a Bug

export let user; ships an any prop. The component compiles, the parent passes whatever, and the bug is the third nested field access at runtime. Cursor writes untyped exports because the Svelte 3 documentation samples don't include types. The fix is export let user: User, plus generics for components that work over arbitrary item types (a <List items={users} let:item>{item.name}</List> should be generic in the item type so the slot prop is typed). Svelte supports generics via <script lang="ts" generics="T"> — most AI assistants don't reach for it because it's a relatively recent addition, so they fall back to any-typed slot props.

The rule:

Every `export let prop` has a TypeScript type annotation. Optional
props use `export let prop: T | undefined = undefined` (not bare
`export let prop`). Default values use `export let prop: T = default`
and the type must include the default's type.

Required vs optional is encoded in the type, not in JSDoc. Svelte's
type-checker emits errors for missing required props at the call site.

Components that work over arbitrary item types use the `generics`
attribute: `<script lang="ts" generics="T extends { id: string }">`.
Slot props are then typed via `let:item` on the consumer side without
casts.

Event payloads are typed via `createEventDispatcher<{ select: User;
delete: { id: string } }>()`. No untyped `dispatch('select', user)`.

`$$Props`, `$$Events`, `$$Slots` interfaces declare the component's
public surface when the inferred surface is wrong (rare — prefer
inference). Used at the top of the .svelte file.

No `export let` without type. ESLint or `svelte-check --fail-on-warnings`
in CI catches it.

Before — untyped props, untyped slot, untyped event:

<!-- List.svelte -->
<script>
  import { createEventDispatcher } from 'svelte';
  export let items;
  const dispatch = createEventDispatcher();
</script>

<ul>
  {#each items as item}
    <li on:click={() => dispatch('select', item)}>
      <slot {item} />
    </li>
  {/each}
</ul>

<!-- Parent.svelte -->
<List items={users} on:select={(e) => loadUser(e.detail.id)} let:item>
  {item.name} <!-- item is `any` — no autocomplete, no error if you typo .nmae -->
</List>

items is any[]. e.detail is any. item in the slot is any. Any rename of User.name doesn't surface as a type error.

After — generics, typed dispatch, typed slot:

<!-- List.svelte -->
<script lang="ts" generics="T extends { id: string }">
  import { createEventDispatcher } from 'svelte';
  export let items: T[];
  export let emptyLabel: string = 'No items';
  const dispatch = createEventDispatcher<{ select: T; delete: { id: string } }>();
</script>

{#if items.length === 0}
  <p>{emptyLabel}</p>
{:else}
  <ul>
    {#each items as item (item.id)}
      <li>
        <button on:click={() => dispatch('select', item)}>
          <slot {item} />
        </button>
      </li>
    {/each}
  </ul>
{/if}

<!-- Parent.svelte -->
<script lang="ts">
  import type { User } from '$lib/types';
  let users: User[] = [];
  function onSelect(e: CustomEvent<User>) { /* e.detail is User */ }
</script>

<List items={users} on:select={onSelect} let:item>
  {item.name} <!-- item is User; `item.nmae` is a compile error -->
</List>

generics="T extends { id: string }" makes the component reusable and the slot prop strongly typed at the call site. Renaming User.name errors at every consumer. e.detail is User, not any.

Rule 5: SvelteKit Load Functions — Server vs Universal, Never Fetch in Components

SvelteKit gives you +page.ts (universal — runs on server during SSR, then on client during navigation) and +page.server.ts (server-only — always runs on the server, can read databases, secrets, files). Cursor reaches for +page.svelte with a top-level <script> fetch, which is the worst of all worlds: it doesn't run during SSR (so no SEO, no fast first paint), it runs on every client navigation re-mount (so duplicate requests), and it can't access secrets without exposing them. The fix is mechanical: data loading lives in a load function. Server-only data lives in +page.server.ts. Public data that benefits from CDN caching lives in +page.ts. Components receive data via the data prop.

The rule:

Data loading happens in `load()` functions, never in `+page.svelte`
component bodies. No top-level `fetch` in component scripts. No
`onMount(() => fetch(...))` for data the page needs to render.

`+page.server.ts` for: anything that touches the database, anything
using a secret/env var, anything that calls an internal-only API,
anything that needs cookies/headers. Never `import` server-only modules
from `+page.ts` — the build will leak them to the client.

`+page.ts` for: public APIs, data safe to cache at the edge, data the
client can re-fetch on subsequent navigations without a server round-trip.

`load` functions use the supplied `fetch` argument, NOT the global
fetch. The supplied fetch handles SSR cookies, internal routing, and
relative URLs correctly.

Streaming: return promises in nested fields of the load object for
non-critical data. The page renders with the critical data; nested
promises stream in via `{#await}`.

Errors in load throw `error(404, 'Not found')` from `@sveltejs/kit` —
never `return { error: ... }`. Redirects throw `redirect(303, '/login')`.

`depends('app:users')` + `invalidate('app:users')` for client-side
re-fetches. Never re-implement caching in components.

Before — fetch in component, runs on client only, double-fires on nav:

<!-- src/routes/users/[id]/+page.svelte -->
<script>
  import { page } from '$app/stores';
  import { onMount } from 'svelte';
  let user = null;
  onMount(async () => {
    const r = await fetch(`/api/users/${$page.params.id}`);
    user = await r.json();
  });
</script>

{#if user}<h1>{user.name}</h1>{:else}Loading…{/if}

No SSR data — search engines see "Loading…". Every client navigation re-mounts the component and re-fetches. If the API requires a session cookie, the fetch may not include it correctly during transitions.

After — +page.server.ts, typed data prop, error helper:

// src/routes/users/[id]/+page.server.ts
import type { PageServerLoad } from './$types';
import { error } from '@sveltejs/kit';
import { db } from '$lib/server/db';

export const load: PageServerLoad = async ({ params, depends }) => {
  depends('app:user');
  const user = await db.users.findById(params.id);
  if (!user) throw error(404, 'User not found');
  return {
    user,
    recentOrders: db.orders.findRecent(params.id), // streamed — non-critical
  };
};

<!-- src/routes/users/[id]/+page.svelte -->
<script lang="ts">
  import type { PageData } from './$types';
  export let data: PageData;
</script>

<h1>{data.user.name}</h1>

{#await data.recentOrders}
  <p>Loading orders…</p>
{:then orders}
  <ul>{#each orders as o (o.id)}<li>{o.total}</li>{/each}</ul>
{/await}

data.user is server-rendered — search engines see the name. recentOrders streams in. The 404 is a real HTTP 404. No double-fetch on navigation.

Rule 6: Form Actions Over Client-Side Fetch — Progressive Enhancement Built-In

The default Cursor pattern for "submit a form" is <form on:submit|preventDefault={handle}> with a fetch inside handle. It works when JS is loaded, breaks completely when it isn't (mobile network failures, ad blockers, the brief window before hydration), and re-implements every part of form handling — CSRF, validation errors, redirects, optimistic updates — by hand. SvelteKit form actions solve this. A +page.server.ts exports an actions object. A <form method="POST" action="?/createUser" use:enhance> posts to that action. With JS, use:enhance intercepts and updates the UI without reload. Without JS, the browser does a full POST and the page re-renders. One source of truth, two delivery mechanisms.

The rule:

For mutations triggered by a form, use SvelteKit form actions:
`export const actions: Actions = { default: async ({ request }) => {...} }`
in `+page.server.ts`. The form is `<form method="POST" use:enhance>`.

Validation lives in the action. Failures return `fail(400, { errors,
values })` — the form re-renders with the errors and the previously
entered values via `form` prop on the page.

Redirects after successful mutation use `throw redirect(303, '/path')`
from the action — never client-side `goto()` after a fetch.

`use:enhance` is the default. Its callback receives `({ formData,
formElement, cancel })` for optimistic UI; the returned function
receives `({ result, update })` for post-submit handling. `update()`
re-runs `load`. Reach for `applyAction` only when the page should
refresh from the action's return value.

Multiple actions on one page use named actions:
`actions: { create: ..., delete: ... }` and
`<button formaction="?/delete">`.

For non-form mutations (drag-drop, in-place edit), prefer a `+server.ts`
endpoint over an unrelated form. Don't shoehorn JSON APIs into form
actions; don't shoehorn forms into bespoke fetch handlers.

CSRF is handled by SvelteKit's origin check for form actions — do
not disable. Custom JSON endpoints need their own CSRF strategy.

Before — hand-rolled fetch, no validation surface, no progressive enhancement:

<script>
  let email = '', error = '';
  async function submit() {
    const r = await fetch('/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    });
    if (!r.ok) {
      error = (await r.json()).message;
      return;
    }
    location.href = '/welcome';
  }
</script>

<form on:submit|preventDefault={submit}>
  <input bind:value={email} />
  {#if error}<p>{error}</p>{/if}
  <button>Sign up</button>
</form>

If JS hasn't loaded, clicking the button does nothing. CSRF, redirect handling, error mapping — all hand-rolled. email is lost on validation error if the user reloads.

After — form action, use:enhance, progressive enhancement, fail() for validation:

// +page.server.ts
import type { Actions } from './$types';
import { fail, redirect } from '@sveltejs/kit';
import { z } from 'zod';

const SignupSchema = z.object({ email: z.string().email() });

export const actions: Actions = {
  default: async ({ request }) => {
    const data = Object.fromEntries(await request.formData());
    const parsed = SignupSchema.safeParse(data);
    if (!parsed.success) {
      return fail(400, { values: data, errors: parsed.error.flatten().fieldErrors });
    }
    await db.users.create(parsed.data);
    throw redirect(303, '/welcome');
  },
};

<!-- +page.svelte -->
<script lang="ts">
  import { enhance } from '$app/forms';
  import type { ActionData } from './$types';
  export let form: ActionData;
</script>

<form method="POST" use:enhance>
  <input name="email" value={form?.values?.email ?? ''} />
  {#if form?.errors?.email}<p>{form.errors.email[0]}</p>{/if}
  <button>Sign up</button>
</form>

Works without JS (full POST → server validates → re-renders with errors). Works with JS (use:enhance intercepts, no reload, same code path). Validation in one place. Redirect handled by SvelteKit. CSRF protected.

Rule 7: Slot/Snippet Composition Over God Components

Cursor likes a single <UserCard> that takes 12 props — showAvatar, showBadge, compact, interactive, onSelect, onDelete, selectionMode, theme. Six months later it has 22 props, three of them mutually exclusive, and every consumer either passes the wrong combination or copy-pastes the entire component into a new one. The Svelte answer is composition: a small core component that exposes named slots (Svelte 4) or snippet props (Svelte 5), and the consumer wires together the variant they want. <UserCard let:user><Avatar {user} /><Name {user} /></UserCard> is more code at the call site but it's all explicit, all type-checked, and there are no boolean prop combinations to test.

The rule:

A component with more than ~5 props that mainly toggles structural
variants is a smell. Refactor to slots/snippets that the parent fills.

Named slots over boolean props for layout: `<slot name="header">`,
`<slot name="footer">` instead of `<Card showHeader showFooter>`.

Slot props (`<slot {item}>`) propagate data to the consumer — used
when the parent needs to render derived data. Type-check via the
`generics` attribute (Rule 4).

Default slot for the primary content. Reserve named slots for
peripheral structure — every named slot is a place the parent has
to learn about.

Svelte 5: prefer `Snippet` props over slots. Snippets are first-class
typed values: `import type { Snippet } from 'svelte'; export let row:
Snippet<[item: User]>`. Render with `{@render row(item)}`. Slot fallback
content becomes the snippet's default.

A "God component" controlled by a `mode` enum (`mode="compact" |
"detailed" | "kanban"`) is two or three components in disguise. Split
them. Share a layout primitive if needed; do not share an
overloaded one.

Before — boolean explosion, mutually exclusive flags, untestable matrix:

<!-- UserCard.svelte -->
<script>
  export let user;
  export let showAvatar = true;
  export let showBadge = false;
  export let compact = false;
  export let interactive = false;
  export let theme = 'light';
  export let onSelect = null;
  // ...nine more
</script>

<div class="card {compact ? 'compact' : ''} {theme}">
  {#if showAvatar}<img src={user.avatar} />{/if}
  <h2>{user.name}</h2>
  {#if showBadge}<span class="badge">{user.plan}</span>{/if}
  {#if interactive}<button on:click={() => onSelect?.(user)}>Select</button>{/if}
</div>

The matrix of { showAvatar, showBadge, compact, interactive, theme } is 32 combinations. Each new requirement adds a flag and another two-power doubling.

After — small primitive, slots for structure, composition at the call site:

<!-- UserCard.svelte -->
<script lang="ts">
  import type { User } from '$lib/types';
  export let user: User;
</script>

<article class="card">
  <slot name="media" {user} />
  <div class="body">
    <slot {user}>
      <h2>{user.name}</h2>
    </slot>
  </div>
  <slot name="actions" {user} />
</article>

<!-- Consumer: sidebar (compact, no actions) -->
<UserCard {user} let:user>
  <strong>{user.name}</strong>
</UserCard>

<!-- Consumer: admin list (avatar + plan badge + actions) -->
<UserCard {user} let:user>
  <svelte:fragment slot="media"><Avatar {user} /></svelte:fragment>
  <h2>{user.name} <PlanBadge plan={user.plan} /></h2>
  <svelte:fragment slot="actions">
    <button on:click={() => select(user)}>Select</button>
    <button on:click={() => remove(user)}>Delete</button>
  </svelte:fragment>
</UserCard>

UserCard has one prop. Variants are expressed by what the consumer passes into the slots — typed, explicit, composable. No mode enum, no flag matrix.

Rule 8: Transition and Animation Discipline — Not on Every Element

Svelte's transitions are gorgeous and ergonomic — transition:fade on any element, done. Cursor sprinkles them everywhere because the docs make them look free. They aren't. Every transition allocates a JS-driven animation that runs on the main thread per element. A list of 200 items with transition:fade on each <li> mounts with 200 simultaneous animations, blocks the main thread, and your time-to-interactive on a mid-tier Android collapses. The animate:flip directive on a sortable list does the right thing but only when the keyed {#each (item.id)} is correct — without the key, every item re-mounts and the animation is meaningless.

The rule:

Transitions are for individually-meaningful UI changes — modal open,
toast appear, route segment swap. NOT for "every item in this list
fades in on first render."

For lists, use `animate:flip` on items inside a `{#each items as item
(item.id)}` (the key is mandatory). flip animates moves between sorts/
filters; it does NOT fade items in/out. Combine with a single parent
`transition:fade` if the whole list should appear together.

`local` modifier (`transition:fade|local`) when the transition should
only fire on local block changes, not on parent route transitions. Most
list-item transitions should be local — otherwise they re-fire on every
navigation.

Custom transitions return `{ duration, css?, tick? }`. Prefer `css`
(GPU-composited) over `tick` (main-thread JS per frame). Reach for
`tick` only for non-CSS-animatable properties (canvas, scrollTop).

Reduced motion: respect `prefers-reduced-motion`. Either gate
transitions behind a media query check (use `@sveltejs/kit`'s no-helper
pattern with a store) or set `duration: 0` when the media query matches.
Never ship a UI that ignores the OS setting.

For long lists (>50 items), virtualize (svelte-virtual-list,
@tanstack/svelte-virtual) — transitions on a virtualized list animate
only the visible window, which is what you wanted anyway.

Before — transition on every list item, no key, no reduced-motion check:

<script>
  import { fade } from 'svelte/transition';
  export let users; // 500 items
</script>

<ul>
  {#each users as user}
    <li transition:fade={{ duration: 300 }}>{user.name}</li>
  {/each}
</ul>

500 simultaneous fades on mount. Without (user.id) key, any sort change re-mounts every item — 500 more fades. Users with reduced-motion enabled get the full animation.

After — flip for moves, single parent fade, local + reduced-motion:

<script lang="ts">
  import { fade } from 'svelte/transition';
  import { flip } from 'svelte/animate';
  import { reducedMotion } from '$lib/stores/motion';
  export let users: User[];

  $: duration = $reducedMotion ? 0 : 200;
</script>

<ul transition:fade|local={{ duration }}>
  {#each users as user (user.id)}
    <li animate:flip={{ duration }}>{user.name}</li>
  {/each}
</ul>

// src/lib/stores/motion.ts
import { readable } from 'svelte/store';
import { browser } from '$app/environment';

export const reducedMotion = readable(false, (set) => {
  if (!browser) return;
  const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
  set(mq.matches);
  const onChange = (e: MediaQueryListEvent) => set(e.matches);
  mq.addEventListener('change', onChange);
  return () => mq.removeEventListener('change', onChange);
});

One transition on the container, not 500. animate:flip handles re-orderings smoothly with a stable key. prefers-reduced-motion is honored.

The Complete `.cursorrules` File

Drop this in the repo root. Cursor and Claude Code both pick it up.

# Svelte / SvelteKit — Production Patterns

## Stores Over Prop Drilling
- State read/written by more than two components lives in a store
  (`src/lib/stores/<name>.ts`), not in props.
- writable(initial) for plain mutable state. update(fn) over set when
  the new value depends on the old. Never mutate in place.
- derived([a, b], ...) for computed values used in multiple places.
- readable(initial, (set) => {...; return cleanup}) for external sources
  (WebSocket, interval, media query). Cleanup fires on last unsubscribe.
- `$store` autosubscribe inside .svelte. In .ts use get(store) for one-
  shot reads; manual subscribe MUST capture and call the unsubscribe.
- No non-serializable values in stores that cross route boundaries.

## Reactive Declarations With $:
- `$:` is for pure derivations of declared dependencies. No fetch, no
  localStorage, no logging, no setState-style writes.
- For side effects on change: explicit `if (value !== prev) {...; prev =
  value }` guard, OR lift to onMount / store subscription.
- Multi-statement reactive blocks read all dependencies at the top —
  early returns hide deps from the compiler.
- Svelte 5: prefer $state / $derived / $effect runes over $:.

## Lifecycle Discipline
- onMount is NOT async. Define inner async function; call it.
- Async work in onMount uses AbortController; signal to fetch; abort in
  cleanup. Guard with `if (signal.aborted) return;` before state writes.
- onMount that allocates (interval, listener, observer, subscription)
  RETURNS a cleanup function — keep allocate and free side-by-side.
- Manual store.subscribe outside .svelte ALWAYS captures unsubscribe.
- beforeUpdate/afterUpdate only for DOM measurement (focus, scroll).
  Never for "react to data change" — that is $: or $effect.
- Svelte 5: prefer $effect with its automatic cleanup return.

## Typed Props With Generics
- Every `export let prop` has a type annotation. Optional: `T |
  undefined = undefined`. Default: `T = default` with matching type.
- Components over arbitrary item types use
  `<script lang="ts" generics="T extends ...">`.
- Event payloads typed via createEventDispatcher<{ event: T }>().
- $$Props/$$Events/$$Slots only when inferred surface is wrong.
- svelte-check --fail-on-warnings in CI catches untyped props.

## SvelteKit Load Functions
- Data loading lives in load(). No top-level fetch in component scripts.
  No onMount(() => fetch(...)) for page-render data.
- +page.server.ts for DB, secrets, internal APIs, cookies/headers.
  Never import server-only modules from +page.ts.
- +page.ts for public/CDN-cacheable data.
- Use the supplied `fetch` argument, never global fetch.
- Stream non-critical data via promises in nested fields + {#await}.
- Errors: `throw error(404, 'msg')`. Redirects: `throw redirect(303, '/path')`.
- depends('app:x') + invalidate('app:x') for client re-fetch.

## Form Actions Over Client-Side Fetch
- Form mutations: actions in +page.server.ts + <form method="POST"
  use:enhance>. Works without JS, enhanced with JS.
- Validation in the action; failures `return fail(400, { errors, values })`.
- Successful mutation: `throw redirect(303, '/path')` from the action.
- Multiple actions: named actions + `formaction="?/name"`.
- Non-form mutations: +server.ts endpoints. Don't shoehorn.
- CSRF handled by SvelteKit's origin check; do not disable.

## Slot/Snippet Composition
- Components with >5 mostly-structural props are a smell — refactor
  to slots/snippets the parent fills.
- Named slots over boolean props for layout: <slot name="header" />
  not <Card showHeader />.
- Slot props (let:item) propagate data; type via `generics` attribute.
- Svelte 5: prefer Snippet<[T]> props over slots — first-class typed.
- A `mode` enum component is N components pretending to be one. Split.

## Transition / Animation Discipline
- Transitions for individually-meaningful changes (modal, toast, route
  swap). NOT for "every list item fades in on mount."
- Lists: `animate:flip` inside `{#each items as item (item.id)}` — key
  is mandatory. Single parent transition for the whole list.
- `|local` modifier prevents re-firing on parent route transitions.
- Custom transitions: prefer `css` (GPU) over `tick` (main thread JS).
- Respect prefers-reduced-motion — gate via store, set duration: 0
  when matched.
- Lists >50 items: virtualize (svelte-virtual-list, tanstack-svelte-virtual).

End-to-End Example: A SvelteKit User Profile Page

Without rules: untyped props, fetch in onMount, prop drilling, transition on every row, hand-rolled form.

<!-- +page.svelte -->
<script>
  import { onMount } from 'svelte';
  import { page } from '$app/stores';
  import { fade } from 'svelte/transition';
  let user = null, orders = [];
  onMount(async () => {
    user = await (await fetch(`/api/users/${$page.params.id}`)).json();
    orders = await (await fetch(`/api/users/${$page.params.id}/orders`)).json();
  });
  async function rename() {
    await fetch(`/api/users/${$page.params.id}`, {
      method: 'PATCH', body: JSON.stringify({ name: user.name }),
    });
  }
</script>

{#if user}
  <h1>{user.name}</h1>
  <input bind:value={user.name} />
  <button on:click={rename}>Save</button>
  <ul>
    {#each orders as o}<li transition:fade>{o.total}</li>{/each}
  </ul>
{/if}

With rules: server load, typed data prop, form action, single transition, keyed list with flip.

// src/routes/users/[id]/+page.server.ts
import type { Actions, PageServerLoad } from './$types';
import { error, fail, redirect } from '@sveltejs/kit';
import { z } from 'zod';
import { db } from '$lib/server/db';

const RenameSchema = z.object({ name: z.string().min(1).max(80) });

export const load: PageServerLoad = async ({ params, depends }) => {
  depends('app:user');
  const user = await db.users.findById(params.id);
  if (!user) throw error(404, 'User not found');
  return { user, orders: db.orders.findRecent(params.id) };
};

export const actions: Actions = {
  rename: async ({ request, params }) => {
    const parsed = RenameSchema.safeParse(
      Object.fromEntries(await request.formData()),
    );
    if (!parsed.success) {
      return fail(400, { errors: parsed.error.flatten().fieldErrors });
    }
    await db.users.update(params.id, parsed.data);
    throw redirect(303, `/users/${params.id}`);
  },
};

<!-- src/routes/users/[id]/+page.svelte -->
<script lang="ts">
  import { enhance } from '$app/forms';
  import { fade } from 'svelte/transition';
  import { flip } from 'svelte/animate';
  import { reducedMotion } from '$lib/stores/motion';
  import type { ActionData, PageData } from './$types';
  export let data: PageData;
  export let form: ActionData;

  $: duration = $reducedMotion ? 0 : 200;
</script>

<h1>{data.user.name}</h1>

<form method="POST" action="?/rename" use:enhance>
  <input name="name" value={data.user.name} />
  {#if form?.errors?.name}<p>{form.errors.name[0]}</p>{/if}
  <button>Save</button>
</form>

{#await data.orders}
  <p>Loading orders…</p>
{:then orders}
  <ul transition:fade|local={{ duration }}>
    {#each orders as o (o.id)}
      <li animate:flip={{ duration }}>{o.total}</li>
    {/each}
  </ul>
{/await}

User data is server-rendered (SEO, fast first paint). Orders stream in. The form works without JS, enhances with it. Validation errors round-trip with the previous values. The list has one transition, not N. Reduced-motion is honored. data and form are fully typed.

Get the Full Pack

These eight rules cover the Svelte and SvelteKit patterns where AI assistants consistently reach for the wrong idiom. Drop them into .cursorrules and the next prompt you write will look different — store-backed, typed, server-loaded, action-mutated, composition-first, motion-disciplined Svelte, without having to re-prompt.

If you want the expanded pack — these eight plus rules for SvelteKit hooks (handle, handleFetch, server hooks for auth), endpoint conventions for +server.ts, runed Svelte 5 patterns, Tailwind + Svelte component organization, Playwright component tests, accessibility patterns specific to Svelte (focus management, ARIA in transitions, keyboard nav in custom widgets), Vitest + svelte-testing-library conventions, and the deployment patterns I use on production SvelteKit services — it is bundled in Cursor Rules Pack v2 ($27, one payment, lifetime updates). Drop it in your repo, stop fighting your AI, ship Svelte you would actually merge.

Cursor Rules for Java — Production Patterns That Actually Ship

Olivia Craft — Fri, 24 Apr 2026 11:55:48 +0000

Cursor Rules for Java — Production Patterns That Actually Ship

Cursor with Java is a different beast than Cursor with Python or TypeScript. Java projects have deep type hierarchies, annotation-driven frameworks, XML build files, and a ceremony level that trips up AI assistants constantly. But when you configure it right, Cursor becomes an enterprise Java power tool — IntelliSense-grade completions, class navigation that understands your Spring context, and refactoring that respects your architecture.

The gap between "AI that writes Java" and "AI that writes Java I'd merge" comes down to rules. Without rules, Cursor generates tutorial-grade code: controllers that do business logic, services with no error handling, tests that mock everything into meaninglessness. With the right rules, it generates code that passes your team's review on the first try.

Here are 8 production-tested Cursor rules for Java covering Spring Boot, Maven, error handling, async patterns, testing, documentation, refactoring, and performance. Each one includes concrete examples so you can see exactly what changes.

1. Spring Boot Scaffolding — Controllers, Services, Repositories

Without rules, AI generates fat controllers that call repositories directly, services that return entities to the API layer, and repositories with custom query methods that belong in the service. The layers blur into mud.

The rule:

Spring Boot layer separation:
- Controllers handle HTTP concerns only: request validation, response mapping, status codes.
  Controllers never contain business logic. Return DTOs, never entities.
- Services contain all business logic. Accept and return domain objects or DTOs.
  Services are the transaction boundary (@Transactional).
- Repositories are Spring Data interfaces. Custom queries use @Query with JPQL.
  Never put business logic in default repository methods.
- Use record DTOs for request/response. Map between entities and DTOs in the service layer.

Bad — fat controller with business logic:

@RestController
@RequestMapping("/api/orders")
public class OrderController {
    @Autowired
    private OrderRepository orderRepository;
    @Autowired
    private UserRepository userRepository;

    @PostMapping
    public Order createOrder(@RequestBody Map<String, Object> body) {
        Long userId = Long.valueOf(body.get("userId").toString());
        User user = userRepository.findById(userId).orElse(null);
        if (user == null) throw new RuntimeException("User not found");

        Order order = new Order();
        order.setUser(user);
        order.setTotal(new BigDecimal(body.get("total").toString()));
        order.setStatus("PENDING");
        order.setCreatedAt(LocalDateTime.now());

        return orderRepository.save(order);
    }
}

Good — layered with DTOs:

// Controller — HTTP concerns only
@RestController
@RequestMapping("/api/orders")
@RequiredArgsConstructor
public class OrderController {
    private final OrderService orderService;

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public OrderResponse createOrder(@Valid @RequestBody CreateOrderRequest request) {
        return orderService.createOrder(request);
    }
}

// Service — business logic and transactions
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository;
    private final UserRepository userRepository;

    @Transactional
    public OrderResponse createOrder(CreateOrderRequest request) {
        User user = userRepository.findById(request.userId())
                .orElseThrow(() -> new UserNotFoundException(request.userId()));

        Order order = Order.builder()
                .user(user)
                .total(request.total())
                .status(OrderStatus.PENDING)
                .build();

        Order saved = orderRepository.save(order);
        return OrderResponse.from(saved);
    }
}

// DTOs — records, immutable
public record CreateOrderRequest(
        @NotNull Long userId,
        @NotNull @Positive BigDecimal total,
        @NotEmpty List<Long> itemIds
) {}

public record OrderResponse(Long id, BigDecimal total, String status, LocalDateTime createdAt) {
    public static OrderResponse from(Order order) {
        return new OrderResponse(order.getId(), order.getTotal(),
                order.getStatus().name(), order.getCreatedAt());
    }
}

The controller is five lines. The service owns the transaction. DTOs protect your entities from leaking to the API. Each layer has exactly one responsibility.

2. Maven Workflow — Dependency Management and Plugin Patterns

AI adds dependencies with version numbers inline, skips the BOM, and never configures plugins beyond defaults. Your pom.xml becomes a version conflict minefield.

The rule:

Maven dependency management:
- Use spring-boot-starter-parent or a BOM for version management. Never hardcode
  dependency versions that are managed by the BOM.
- Group dependencies: starters first, then domain libraries, then test dependencies.
- Always use <dependencyManagement> in multi-module projects for version consistency.
- Configure maven-compiler-plugin to target Java 21. Set encoding to UTF-8.
- Use maven-surefire-plugin for unit tests, maven-failsafe-plugin for integration tests.
- Never add dependencies without specifying the <scope> for test/provided dependencies.

Bad — unmanaged versions, no structure:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>3.3.1</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.17.0</version>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.10.2</version>
    </dependency>
</dependencies>

Good — BOM-managed, properly scoped:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.1</version>
</parent>

<properties>
    <java.version>21</java.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
    <!-- Starters -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>

    <!-- Test -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

No version numbers on managed dependencies. Scopes are explicit. The BOM handles compatibility so you don't have to.

3. Error Handling — Checked Exceptions and Custom Wrappers

AI catches Exception, wraps everything in RuntimeException, or silently swallows errors. Your production logs become useless and your API returns 500 for every failure.

The rule:

Error handling patterns:
- Define a base domain exception extending RuntimeException.
  All domain exceptions extend from it.
- Each exception includes context: entity ID, operation, and a machine-readable error code.
- Use @RestControllerAdvice for global exception mapping to RFC 7807 ProblemDetail.
- Map domain exceptions to appropriate HTTP status codes. Never expose stack traces in responses.
- Checked exceptions from libraries must be caught at the boundary and wrapped
  in a domain exception — never let them propagate up the stack.

Bad — generic exceptions leak everywhere:

public PaymentResult processPayment(Long orderId) {
    try {
        Order order = orderRepository.findById(orderId).orElseThrow();
        return paymentGateway.charge(order.getTotal());
    } catch (Exception e) {
        throw new RuntimeException("Payment failed", e);
    }
}

Good — domain exceptions with context and RFC 7807 responses:

// Base domain exception
public abstract class DomainException extends RuntimeException {
    private final String errorCode;

    protected DomainException(String message, String errorCode) {
        super(message);
        this.errorCode = errorCode;
    }

    public String getErrorCode() { return errorCode; }
}

// Specific exception with context
public class PaymentFailedException extends DomainException {
    private final Long orderId;
    private final String gatewayResponse;

    public PaymentFailedException(Long orderId, String gatewayResponse) {
        super("Payment failed for order " + orderId + ": " + gatewayResponse,
              "PAYMENT_FAILED");
        this.orderId = orderId;
        this.gatewayResponse = gatewayResponse;
    }
}

// Service — catches checked exceptions at the boundary
public PaymentResult processPayment(Long orderId) {
    Order order = orderRepository.findById(orderId)
            .orElseThrow(() -> new OrderNotFoundException(orderId));
    try {
        return paymentGateway.charge(order.getTotal());
    } catch (GatewayTimeoutException e) {
        throw new PaymentFailedException(orderId, "Gateway timeout: " + e.getMessage());
    }
}

// Global handler — RFC 7807
@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(PaymentFailedException.class)
    public ProblemDetail handlePaymentFailed(PaymentFailedException ex) {
        ProblemDetail detail = ProblemDetail.forStatusAndDetail(
                HttpStatus.PAYMENT_REQUIRED, ex.getMessage());
        detail.setProperty("errorCode", ex.getErrorCode());
        return detail;
    }
}

Every exception has context for debugging. The API returns structured errors. Checked exceptions die at the service boundary.

4. Async and Reactive Patterns — CompletableFuture and Project Reactor

Without rules, AI blocks threads, ignores error propagation in async chains, and mixes reactive and imperative styles randomly. Your application handles 50 concurrent requests when it should handle 5000.

The rule:

Async and reactive patterns:
- Use CompletableFuture for async operations that are naturally imperative.
  Always provide a custom executor — never use the common ForkJoinPool for I/O.
- Chain with thenApply/thenCompose — never call .get() or .join() in request threads.
- Use @Async with a configured ThreadPoolTaskExecutor, not the default SimpleAsyncTaskExecutor.
- For reactive: use Mono/Flux consistently. Never call .block() outside of tests.
- Handle errors in async chains with exceptionally() or onErrorResume() — never let
  exceptions silently disappear.

Bad — blocking calls, no error handling in async chain:

public OrderSummary getOrderSummary(Long orderId) {
    CompletableFuture<Order> orderFuture = CompletableFuture.supplyAsync(
            () -> orderRepository.findById(orderId).orElseThrow());
    CompletableFuture<List<Payment>> paymentFuture = CompletableFuture.supplyAsync(
            () -> paymentRepository.findByOrderId(orderId));

    Order order = orderFuture.join();       // blocks request thread
    List<Payment> payments = paymentFuture.join(); // blocks again
    return new OrderSummary(order, payments);
}

Good — non-blocking with custom executor and error handling:

@Configuration
public class AsyncConfig {
    @Bean("ioExecutor")
    public Executor ioExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(10);
        executor.setMaxPoolSize(50);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("io-");
        executor.initialize();
        return executor;
    }
}

@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository;
    private final PaymentRepository paymentRepository;
    @Qualifier("ioExecutor") private final Executor ioExecutor;

    public CompletableFuture<OrderSummary> getOrderSummary(Long orderId) {
        CompletableFuture<Order> orderFuture = CompletableFuture
                .supplyAsync(() -> orderRepository.findById(orderId)
                        .orElseThrow(() -> new OrderNotFoundException(orderId)), ioExecutor);

        CompletableFuture<List<Payment>> paymentFuture = CompletableFuture
                .supplyAsync(() -> paymentRepository.findByOrderId(orderId), ioExecutor);

        return orderFuture.thenCombine(paymentFuture, OrderSummary::new)
                .exceptionally(ex -> {
                    throw new OrderSummaryException(orderId, ex);
                });
    }
}

Both queries run in parallel on a dedicated I/O pool. No thread blocking. Errors propagate through the chain instead of disappearing silently.

5. Test Structure — JUnit 5, Mocking, and Fixtures

AI generates tests that test nothing — mocking every dependency, verifying mock calls instead of behavior, and using random magic values that obscure intent.

The rule:

Testing patterns (JUnit 5 + Mockito):
- Name tests: methodName_givenCondition_expectedResult.
- Use @ExtendWith(MockitoExtension.class), not @SpringBootTest, for unit tests.
  Reserve @SpringBootTest for integration tests only.
- Mock external boundaries (repositories, clients). Never mock the class under test.
- Use test fixtures with builder methods for creating test data — no random inline values.
- Assert behavior and return values, not mock interactions.
  Verify mock calls only when side effects are the point of the test.
- Integration tests use @SpringBootTest + Testcontainers for real databases.

Bad — testing mock interactions, not behavior:

@Test
void testCreateOrder() {
    when(userRepository.findById(1L)).thenReturn(Optional.of(new User()));
    when(orderRepository.save(any())).thenReturn(new Order());

    orderService.createOrder(new CreateOrderRequest(1L, BigDecimal.TEN, List.of(1L)));

    verify(userRepository).findById(1L);
    verify(orderRepository).save(any());
}

Good — testing behavior with meaningful assertions:

@ExtendWith(MockitoExtension.class)
class OrderServiceTest {
    @Mock private OrderRepository orderRepository;
    @Mock private UserRepository userRepository;
    @InjectMocks private OrderService orderService;

    @Test
    void createOrder_givenValidRequest_returnsOrderWithPendingStatus() {
        User user = TestFixtures.activeUser();
        CreateOrderRequest request = new CreateOrderRequest(user.getId(), new BigDecimal("99.99"), List.of(1L));
        when(userRepository.findById(user.getId())).thenReturn(Optional.of(user));
        when(orderRepository.save(any(Order.class))).thenAnswer(inv -> {
            Order order = inv.getArgument(0);
            order.setId(1L);
            return order;
        });

        OrderResponse result = orderService.createOrder(request);

        assertThat(result.status()).isEqualTo("PENDING");
        assertThat(result.total()).isEqualByComparingTo("99.99");
    }

    @Test
    void createOrder_givenUnknownUser_throwsUserNotFoundException() {
        when(userRepository.findById(999L)).thenReturn(Optional.empty());

        assertThatThrownBy(() -> orderService.createOrder(
                new CreateOrderRequest(999L, BigDecimal.TEN, List.of(1L))))
                .isInstanceOf(UserNotFoundException.class);
    }
}

// Shared test fixtures
public final class TestFixtures {
    public static User activeUser() {
        return User.builder().id(1L).name("Ada Lovelace").email("ada@test.com")
                .status(UserStatus.ACTIVE).build();
    }
}

Tests describe behavior in their names. Fixtures create consistent, readable test data. Assertions verify outcomes, not implementation details.

6. Documentation — Javadoc and Inline Comments

AI either generates zero documentation or generates noise: /** Gets the user. */ public User getUser(). Neither helps your team.

The rule:

Documentation patterns:
- Write Javadoc on all public classes and methods. Focus on WHY and WHEN, not WHAT
  (the signature already tells you what).
- Include @param, @return, and @throws tags. Document what exceptions mean for the caller.
- For complex business logic, add inline comments explaining the business rule — not the code.
- Never write comments that repeat the code: "// get user" above getUser() is noise.
- Use @see to link related classes. Document thread-safety for shared state.

Bad — useless Javadoc that adds nothing:

/**
 * Order service.
 */
public class OrderService {
    /**
     * Creates an order.
     * @param request the request
     * @return the order
     */
    public OrderResponse createOrder(CreateOrderRequest request) { ... }
}

Good — Javadoc explains WHY and documents contracts:

/**
 * Handles order lifecycle from creation through fulfillment.
 * All methods are transactional — partial order creation is not possible.
 *
 * @see PaymentService for payment processing after order creation
 * @see InventoryService for stock reservation during order creation
 */
public class OrderService {

    /**
     * Creates a new order and reserves inventory for all items.
     * The order starts in PENDING status and must be confirmed via
     * {@link #confirmOrder(Long)} within 30 minutes or it auto-cancels.
     *
     * @param request validated order details including user ID and item list
     * @return the created order with generated ID and current status
     * @throws UserNotFoundException if the user ID does not exist
     * @throws InsufficientStockException if any item cannot be reserved
     */
    @Transactional
    public OrderResponse createOrder(CreateOrderRequest request) {
        // Business rule: orders over $10,000 require manager approval
        // and start in REVIEW status instead of PENDING
        if (request.total().compareTo(REVIEW_THRESHOLD) > 0) {
            return createOrderForReview(request);
        }
        ...
    }
}

The class-level doc tells you what this service covers and where to look for related logic. The method doc explains the 30-minute auto-cancel — information you can't get from reading the method signature. The inline comment explains a business rule, not a code mechanic.

7. Refactoring Patterns — Rename, Extract, and Generics

When AI generates code, it often creates long methods, duplicated logic, and concrete types where generics belong. Without refactoring rules, asking Cursor to "clean this up" produces cosmetic changes that don't improve the design.

The rule:

Refactoring patterns:
- Extract methods when a block has a distinct purpose — name the method after the purpose,
  not the implementation.
- Use generics to eliminate duplicated logic across types. Prefer bounded wildcards
  (? extends T) in method parameters.
- When renaming, update all references including test classes and documentation.
- Replace type-switching (instanceof chains) with polymorphism.
- Extract shared behavior into abstract base classes or interfaces with default methods
  only when 3+ classes share it — not for 2 classes.

Bad — long method with duplicated notification logic:

public void processOrder(Order order) {
    order.setStatus(OrderStatus.PROCESSING);
    orderRepository.save(order);

    String message = "Order " + order.getId() + " is being processed";
    if (order.getUser().getNotificationPreference() == NotificationPreference.EMAIL) {
        emailService.send(order.getUser().getEmail(), "Order Update", message);
    } else if (order.getUser().getNotificationPreference() == NotificationPreference.SMS) {
        smsService.send(order.getUser().getPhone(), message);
    }

    // 50 more lines of fulfillment logic...
}

Good — extracted methods, polymorphic notifications:

public void processOrder(Order order) {
    updateStatus(order, OrderStatus.PROCESSING);
    notifyUser(order.getUser(), buildOrderUpdateMessage(order));
    fulfillOrder(order);
}

private void notifyUser(User user, String message) {
    notificationStrategy.forPreference(user.getNotificationPreference())
            .send(user, message);
}

// Generic repository base for common operations
public interface CrudOperations<T, ID> {
    T findOrThrow(ID id);
    T saveAndFlush(T entity);
}

public abstract class BaseRepository<T, ID> implements CrudOperations<T, ID> {
    @Override
    public T findOrThrow(ID id) {
        return findById(id).orElseThrow(() ->
                new EntityNotFoundException(getEntityName(), id));
    }
}

The method reads like a business process description. Notification logic is polymorphic — adding a new channel doesn't touch existing code. The generic base eliminates repeated findById().orElseThrow() patterns across repositories.

8. Performance — Caching, Lazy Loading, and Streams

AI generates code that works in development and dies under load. N+1 queries, uncached repeated lookups, eager loading of entire object graphs, and streams that materialize collections multiple times.

The rule:

Performance patterns:
- Use @Cacheable for read-heavy, rarely-changing data. Define cache names and TTL explicitly.
  Always implement @CacheEvict on mutation methods.
- Use @EntityGraph or JOIN FETCH for relationships needed in the query — prevent N+1.
  Default all @OneToMany and @ManyToMany to FetchType.LAZY.
- Use Stream API for transformations but never for side effects. Prefer
  toList() over collect(Collectors.toList()). Use parallelStream() only for
  CPU-bound work with 10,000+ elements — never for I/O.
- For pagination, always use Pageable with reasonable defaults. Never load unbounded
  collections.

Bad — N+1 queries, no caching, eager loading everything:

@Entity
public class Order {
    @OneToMany(fetch = FetchType.EAGER)  // loads ALL items on every query
    private List<OrderItem> items;
}

public List<OrderSummary> getRecentOrders() {
    List<Order> orders = orderRepository.findAll(); // unbounded, loads all items eagerly
    return orders.stream()
            .map(order -> new OrderSummary(
                    order.getId(),
                    order.getItems().size(),  // N+1 if lazy, wasteful if eager
                    order.getTotal()))
            .collect(Collectors.toList());
}

Good — lazy loading, JOIN FETCH, caching, pagination:

@Entity
public class Order {
    @OneToMany(fetch = FetchType.LAZY, mappedBy = "order")
    private List<OrderItem> items;
}

// Repository with JOIN FETCH — one query, no N+1
public interface OrderRepository extends JpaRepository<Order, Long> {
    @Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.createdAt > :since")
    List<Order> findRecentWithItems(@Param("since") LocalDateTime since);

    Page<Order> findByStatus(OrderStatus status, Pageable pageable);
}

// Service with caching and pagination
@Service
@RequiredArgsConstructor
public class OrderService {

    @Cacheable(value = "orderSummaries", key = "#status + '-' + #pageable.pageNumber")
    public Page<OrderSummary> getOrders(OrderStatus status, Pageable pageable) {
        return orderRepository.findByStatus(status, pageable)
                .map(OrderSummary::from);
    }

    @CacheEvict(value = "orderSummaries", allEntries = true)
    @Transactional
    public OrderResponse updateOrderStatus(Long orderId, OrderStatus newStatus) {
        Order order = orderRepository.findOrThrow(orderId);
        order.setStatus(newStatus);
        return OrderResponse.from(orderRepository.save(order));
    }
}

Lazy loading prevents loading object graphs you don't need. JOIN FETCH loads what you do need in one query. Caching prevents repeated database hits. Pagination prevents unbounded memory growth.

Complete .cursorrules File

Drop this into your project root as .cursorrules:

# Java Production Rules

## Spring Boot Architecture
- Controllers: HTTP concerns only. Request validation, response mapping, status codes.
  Never contain business logic. Return DTOs (records), never entities.
- Services: All business logic. @Transactional boundary. Accept/return DTOs or domain objects.
- Repositories: Spring Data interfaces. Custom queries use @Query JPQL.
- Use constructor injection (@RequiredArgsConstructor). All injected fields: private final.
- Use Java records for DTOs. Use compact constructors for validation.

## Maven
- Use spring-boot-starter-parent BOM. Never hardcode managed dependency versions.
- Explicit <scope> for test/provided. Group: starters, domain libs, test.
- Target Java 21. UTF-8 encoding. Surefire for unit tests, Failsafe for integration.

## Error Handling
- Domain exceptions extend a base DomainException (RuntimeException subclass).
- Include context: entity ID, operation, machine-readable error code.
- @RestControllerAdvice maps domain exceptions to RFC 7807 ProblemDetail.
- Catch checked exceptions at service boundary, wrap in domain exceptions.
- Never catch/throw generic Exception or RuntimeException.

## Async
- CompletableFuture with custom executor for I/O — never ForkJoinPool.
- Chain with thenApply/thenCompose — never .get()/.join() on request threads.
- @Async requires configured ThreadPoolTaskExecutor.
- Handle errors in chains: exceptionally() or onErrorResume().

## Testing
- Unit tests: @ExtendWith(MockitoExtension.class). Mock boundaries only.
- Name: methodName_givenCondition_expectedResult.
- Assert behavior and return values, not mock interactions.
- Integration tests: @SpringBootTest + Testcontainers.
- Shared test fixtures with builder methods.

## Documentation
- Javadoc on public classes and methods. Focus on WHY and WHEN, not WHAT.
- @param, @return, @throws with meaningful descriptions.
- Inline comments for business rules only — never restate the code.

## Refactoring
- Extract methods named after purpose, not implementation.
- Use generics to eliminate duplication. Bounded wildcards in params.
- Replace instanceof chains with polymorphism.
- Abstract shared behavior only when 3+ classes share it.

## Performance
- @Cacheable for read-heavy data. @CacheEvict on mutations. Explicit TTL.
- FetchType.LAZY default. JOIN FETCH or @EntityGraph for needed relations.
- Stream for transformations, not side effects. toList() over Collectors.toList().
- Always paginate with Pageable. Never load unbounded collections.
- parallelStream() only for CPU-bound work with 10,000+ elements.

.mdc Rule File

For Cursor's .cursor/rules/ directory, save this as java-production.mdc:

---
description: Production Java patterns for Spring Boot applications
globs: ["**/*.java", "pom.xml"]
alwaysApply: false
---

You are working on a Spring Boot 3.x application with Java 21.

Follow these production patterns:
- Layer separation: Controllers (HTTP only) → Services (business logic, @Transactional) → Repositories (data access)
- Constructor injection with @RequiredArgsConstructor, all fields private final
- Java records for DTOs with bean validation annotations
- Domain exceptions extending a base DomainException, mapped to RFC 7807 via @RestControllerAdvice
- CompletableFuture with custom executors for async I/O — never block request threads
- JUnit 5 + MockitoExtension for unit tests, @SpringBootTest + Testcontainers for integration
- @Cacheable with explicit eviction, FetchType.LAZY default, JOIN FETCH where needed
- Javadoc on public API: explain WHY and contracts, not WHAT the code does

When generating Spring components:
1. Controller returns ResponseEntity<DTO> or uses @ResponseStatus
2. Service method is @Transactional and maps between entities and DTOs
3. Repository uses @Query for custom JPQL, Page<T> for list endpoints
4. Exception classes include entity ID, operation context, and error codes

Put These Rules to Work

These 8 rules cover the production patterns where AI coding assistants fail hardest in Java projects. Spring scaffolding that respects layer boundaries. Maven builds that don't create version conflicts. Error handling that helps you debug at 2 AM. Async code that doesn't block your thread pool. Tests that actually catch bugs. Documentation that tells you why. Refactoring that improves design. Performance that survives load testing.

Add them to your .cursorrules or .cursor/rules/ directory and the difference is immediate — fewer review comments, production-grade code from the first generation, and less time rewriting AI output.

Better rules mean faster time to production. If you're shipping Java professionally, the rules pay for themselves on the first feature.

I've packaged these rules (plus 40+ more covering microservices, JPA, security, and observability patterns across 10 languages) into a ready-to-use rules pack: Cursor Rules Pack v2

Drop it into your project directory and stop fighting your AI assistant.

Why Claude Ignores Your Instructions (And How to Fix It With CLAUDE.md)

Olivia Craft — Fri, 24 Apr 2026 11:55:47 +0000

Why Claude Ignores Your Instructions (And How to Fix It With CLAUDE.md)

You write clear instructions. Claude reads them. Then it does something completely different.

Not wrong, exactly. Just... not what you asked for. It adds docstrings you didn't request. It refactors code you told it to leave alone. It "improves" things that were fine. You correct it, it apologizes, and three prompts later it drifts again.

This isn't a bug. It's how large language models process context — and once you understand the mechanism, you can fix it with a single file.

Why LLMs Drift From Your Instructions

Large language models don't "remember" your instructions the way you remember a conversation. They process a context window — a fixed block of text that includes the system prompt, your messages, and the model's own responses.

Here's the problem: as the conversation grows, your original instructions get pushed further from the active generation point. The model's attention shifts toward recent context. Your carefully written rules become background noise.

This is called context drift, and it happens in every long coding session. The model isn't ignoring you on purpose. Your instructions are just losing the attention competition against more recent tokens.

There's a second problem: instruction ambiguity. When you say "keep it simple," Claude interprets that against its training data. Its definition of "simple" might include adding type annotations, error handling, and comments — things that feel helpful but weren't what you meant.

Verbal instructions in chat are inherently lossy. They decay with every new message.

Passive Rules vs. Enforcement Hooks

Most developers try to fix drift by writing longer prompts. More detail, more examples, more emphasis. This doesn't work because it treats the symptom (bad output) instead of the cause (attention decay).

There are two fundamentally different approaches to controlling AI behavior:

Passive rules are instructions you write in a prompt or system message. They work at the start of a conversation but degrade over time. They have no mechanism to reassert themselves.

Enforcement hooks are structural — they exist in the environment, not just the conversation. Claude Code's CLAUDE.md file is an enforcement hook. It gets loaded into context at the start of every interaction, regardless of conversation length. It doesn't decay because it's re-read, not remembered.

The difference matters. A passive rule says "don't add comments." An enforcement hook says "don't add comments" in a file that Claude re-reads every time it acts on your code.

3 CLAUDE.md Patterns That Actually Stick

After testing dozens of configurations, these three patterns consistently prevent drift.

Pattern 1: Negative Constraints Before Positive Instructions

Claude's training biases it toward being helpful — which means adding things. Counter this by leading with explicit prohibitions.

Before (drifts after ~5 interactions):

## Rules
- Write concise code
- Follow existing patterns
- Use TypeScript

After (holds across long sessions):

## Rules
# DO NOT
- Do not add comments or docstrings to code you didn't write
- Do not refactor code unrelated to the current task
- Do not add error handling unless explicitly asked
- Do not introduce new dependencies without approval

# DO
- Follow existing patterns in the codebase
- Write concise code — fewer lines is better
- Use TypeScript with strict mode

Why this works: negative constraints create hard boundaries. They're easier for the model to evaluate ("did I add a comment? yes → remove it") than vague positive guidance ("is this concise enough?").

Pattern 2: Scope Anchoring With Task Boundaries

Drift happens when Claude expands the scope of a task beyond what you asked. Anchor the scope explicitly.

Before:

- Keep changes minimal

After:

## Scope Rules
- Only modify files directly related to the current request
- One logical change per response — if a task requires multiple changes, list them and wait for approval
- If you notice a bug or improvement outside the current scope, mention it but do NOT fix it
- Never modify test files unless the task specifically involves tests

The key phrase is "mention it but do NOT fix it." This gives Claude a pressure release valve — it can still flag issues without acting on them, which satisfies its helpfulness training without corrupting your task.

Pattern 3: Format Enforcement With Concrete Examples

Abstract style rules ("be concise") get reinterpreted. Concrete examples don't.

Before:

- Write clean commit messages

After:

## Commit Messages
Format: <type>: <description in lowercase, max 72 chars>
Types: fix, feat, refactor, test, docs

Example:
  fix: resolve race condition in websocket reconnection

NOT:
  Fixed the race condition bug that was causing websocket reconnection issues
  Updated websocket handler to fix race condition and improve reliability

Showing the wrong output is as important as showing the right output. Claude is trained on pattern matching — giving it a negative example is a stronger signal than a positive rule alone.

Before and After: A Real Session

Here's what a typical coding session looks like without and with these patterns.

Without CLAUDE.md:

You: "Add a retry mechanism to the API client"

Claude: adds retry logic, refactors the error handling, adds JSDoc comments to three functions, creates a new RetryConfig type, and suggests moving the client to a separate module

Five changes when you asked for one.

With CLAUDE.md (using all three patterns):

You: "Add a retry mechanism to the API client"

Claude: adds retry logic with exponential backoff to the existing fetch wrapper. Notes: "I noticed the error handling could be simplified, but that's outside the current scope — want me to address it separately?"

One change. One note. No drift.

The Mechanism Behind the Fix

CLAUDE.md works because it changes where instructions live. Instead of existing in conversation context (which decays), instructions exist in the project structure (which persists). Every time Claude Code reads your project, it re-reads CLAUDE.md. Your rules don't compete with recent context — they reset with every interaction.

This is the difference between telling someone a rule once and posting it on the wall where they work.

Start With Structure, Not Hope

If Claude is ignoring your instructions, don't write longer prompts. Write a CLAUDE.md file with explicit negative constraints, scope boundaries, and concrete format examples.

I've packaged 40+ production-tested rules into a drop-in CLAUDE.md file that covers scope control, code style enforcement, commit formatting, and drift prevention. If you want a ready-made starting point: CLAUDE.md Rules Pack.

If you're using Cursor, the same structural principles apply to .cursorrules files. I have a separate pack for that: Cursor Rules Pack v2.

Stop hoping the AI will remember. Make it re-read.

Forem: Olivia Craft

Cursor Rules for Vue 3 and Nuxt: AI Dev Guide 2026

How Cursor Rules Work for Vue Projects

Rule 1: Composition API + <script setup> Only — No Options API, No Mixins, No Vue.extend()

Rule 2: Typed defineProps + defineEmits + defineModel — Generics Syntax, Never Mutate Props

Rule 3: Reactivity Discipline — ref By Default, reactive Rarely, computed For Derivations

Rule 4: Pinia For State — Setup Stores, storeToRefs, Scoped Per Feature, Never Vuex

Rule 5: Composables — Extract Reusable Logic Into composables/use*.ts, Return Refs, Cleanup With onScopeDispose

Rule 6: Nuxt 3 Data Fetching & SSR — useFetch / useAsyncData With Explicit Keys, useState For Shared State

Rule 7: Vue Router 4 With Typed Routes — File-Based Or Unplugin-Vue-Router, definePageMeta In Nuxt

Rule 8: Testing — Vitest For Units, @vue/test-utils + Vue Testing Library For Components, Playwright For E2E, MSW For Mocks

The Complete .cursorrules File

End-to-End Example: A Nuxt 3 Profile Page With Form, Composable, Pinia Store, And SSR Data

Get the Full Pack

Cursor Rules for Ruby on Rails 8: AI Dev Guide 2026

How Cursor Rules Work for Rails Projects

Rule 1: Skinny Controllers, Fat Service Objects — Business Logic In app/services/* POROs With Result Types

Rule 2: ActiveRecord Models — Modern validates, Scopes, Typed enum, No default_scope, No Business Callbacks

Rule 3: N+1 Prevention And Query Discipline — includes / preload / eager_load, pluck, find_each, No String Interpolation

Rule 4: Strong Parameters And Form Objects — Per-Action Param Shape, Multi-Model Forms In app/forms/*

Rule 5: ActiveJob With Solid Queue / Sidekiq — Idempotent, retry_on / discard_on, Always perform_later, Never Synchronous Side Effects In Controllers

Rule 6: Hotwire Over JavaScript SPAs — Turbo Frames, Turbo Streams, Stimulus For Sprinkles, Importmap

Rule 7: Authorization — Pundit Policies For Every Resource, authorize In Controllers, policy_scope For Index Queries

Rule 8: Testing — RSpec, FactoryBot, System Specs With Cuprite, Request Specs Over Controller Specs, VCR For HTTP

The Complete .cursorrules File

End-to-End Example: A Comments Feature With Background Email, Authorization, And Hotwire

Get the Full Pack

Cursor Rules for PHP and Laravel: AI Dev Guide 2026

How Cursor Rules Work for Laravel Projects

Rule 1: Eloquent Models — Explicit $fillable, Typed $casts, Observers Over boot(), Attribute::make() Accessors

Rule 2: Skinny Controllers, Single-Action Invokable Controllers, Service/Action Classes For Business Logic

Rule 3: Form Requests For Validation — Authorization, Custom Rule Objects, DTO Conversion

Rule 4: Database Queries & N+1 Prevention — Eager Loading, Scopes, select() Only Needed Columns, chunk()/lazy() For Large Sets

Rule 5: Queues & Background Jobs — ShouldQueue, Idempotent handle(), WithoutOverlapping, Redis In Production, Never Sync Mailers

Rule 6: API Resources & Typed Responses — JsonResource For Every Endpoint, Conditional Fields, OpenAPI Generation

Rule 7: Authorization — Policies For Every Model, Gates For Non-Model Checks, $this->authorize() Everywhere, Never if ($user->is_admin)

Rule 8: Testing — Pest By Default, RefreshDatabase, Factories With States, Bus::fake() / Queue::fake() / Mail::fake(), Parallel Testing

The Complete .cursorrules File

End-to-End Example: Posting a Comment On A Blog Post

Get the Full Pack

Cursor Rules for Kubernetes: AI-Assisted K8s Guide 2026

How Cursor Rules Work for Kubernetes Projects

Rule 1: Declarative GitOps — Never kubectl apply Against Production

Rule 2: Resource Requests and Limits — On Every Container, No Exceptions

Rule 3: Probes — Liveness, Readiness, and Startup, Each Tuned for Its Job

Rule 4: Image Pinning — By Digest, Not Tag, Never :latest

Rule 5: Security Context — Non-Root, Read-Only Root Filesystem, Drop Capabilities

Rule 6: Secrets — External Managers and Ephemeral Mounts, Never Inline

Rule 7: Rollouts — Strategy, PodDisruptionBudget, HPA, and Graceful Shutdown

Rule 8: Observability — Structured Labels, Logs, Metrics, and Namespace Hygiene

The Complete .cursorrules File for Kubernetes

Real Examples: AI-Generated Manifests Before and After Rules

Example 1: "Give me a Deployment and Service for my Node API."

Get the Full Pack

Cursor Rules for Elixir: AI-Assisted Dev Guide 2026

How Cursor Rules Work for Elixir Projects

Rule 1: Pattern Match Over Conditionals — Function Heads First, with for Chains

Rule 2: Tagged Tuples Are the Error Protocol — {:ok, value} / {:error, reason}

Rule 3: Let It Crash — Use Supervisors, Not try/rescue

Rule 4: GenServer Discipline — State Per Process, Not a Global Dictionary

Rule 5: Ecto in Contexts — Queries Live in the Domain, Transactions Use Multi

Rule 6: Structured Concurrency — Task.Supervisor, Timeouts, Linked Tasks

Rule 7: @spec and Dialyzer on Every Public API

Rule 8: Phoenix Contexts Are the Domain — Web Layer Stays Thin

The Complete .cursorrules File for Elixir

Real Examples: AI-Generated Code Before and After Rules

Example 1: "Write a function that creates an order and charges the customer."

Example 2: "Fetch 100 product records from 3 upstream APIs in parallel."

Get the Full Pack

Cursor Rules for Scala: AI-Assisted Dev Guide 2026

How Cursor Rules Work for Scala Projects

Rule 1: Immutability First — val Over var, Immutable Collections, No null

Rule 2: Option, Either, Try — Not null and Not Thrown Exceptions

Rule 3: For-Comprehensions for Monadic Composition

Rule 4: Algebraic Data Types — Sealed Traits + Case Classes (or Scala 3 enum)

Rule 5: Type Classes Over Inheritance for Polymorphism

Rule 6: Effect Types — IO / ZIO Over Raw Future, No Blocking on the Main Pool

Rule 7: Collections — Immutable by Default, Lazy with Care, No java.util

Rule 8: Strict sbt — -Werror, Fatal Warnings, scalafmt, scalafix

The Complete .cursorrules File for Scala

Rule 1: Composition API + `<script setup>` Only — No Options API, No Mixins, No `Vue.extend()`

Rule 2: Typed `defineProps` + `defineEmits` + `defineModel` — Generics Syntax, Never Mutate Props

Rule 3: Reactivity Discipline — `ref` By Default, `reactive` Rarely, `computed` For Derivations

Rule 4: Pinia For State — Setup Stores, `storeToRefs`, Scoped Per Feature, Never Vuex

Rule 5: Composables — Extract Reusable Logic Into `composables/use*.ts`, Return Refs, Cleanup With `onScopeDispose`

Rule 6: Nuxt 3 Data Fetching & SSR — `useFetch` / `useAsyncData` With Explicit Keys, `useState` For Shared State

Rule 7: Vue Router 4 With Typed Routes — File-Based Or Unplugin-Vue-Router, `definePageMeta` In Nuxt

Rule 8: Testing — Vitest For Units, `@vue/test-utils` + Vue Testing Library For Components, Playwright For E2E, MSW For Mocks

The Complete `.cursorrules` File

Rule 1: Skinny Controllers, Fat Service Objects — Business Logic In `app/services/*` POROs With Result Types

Rule 2: ActiveRecord Models — Modern `validates`, Scopes, Typed `enum`, No `default_scope`, No Business Callbacks

Rule 3: N+1 Prevention And Query Discipline — `includes` / `preload` / `eager_load`, `pluck`, `find_each`, No String Interpolation

Rule 4: Strong Parameters And Form Objects — Per-Action Param Shape, Multi-Model Forms In `app/forms/*`

Rule 5: ActiveJob With Solid Queue / Sidekiq — Idempotent, `retry_on` / `discard_on`, Always `perform_later`, Never Synchronous Side Effects In Controllers

Rule 7: Authorization — Pundit Policies For Every Resource, `authorize` In Controllers, `policy_scope` For Index Queries

The Complete `.cursorrules` File

Rule 1: Eloquent Models — Explicit `$fillable`, Typed `$casts`, Observers Over `boot()`, `Attribute::make()` Accessors

Rule 4: Database Queries & N+1 Prevention — Eager Loading, Scopes, `select()` Only Needed Columns, `chunk()`/`lazy()` For Large Sets

Rule 5: Queues & Background Jobs — `ShouldQueue`, Idempotent `handle()`, `WithoutOverlapping`, Redis In Production, Never Sync Mailers

Rule 6: API Resources & Typed Responses — `JsonResource` For Every Endpoint, Conditional Fields, OpenAPI Generation

Rule 7: Authorization — Policies For Every Model, Gates For Non-Model Checks, `$this->authorize()` Everywhere, Never `if ($user->is_admin)`

Rule 8: Testing — Pest By Default, `RefreshDatabase`, Factories With States, `Bus::fake()` / `Queue::fake()` / `Mail::fake()`, Parallel Testing

The Complete `.cursorrules` File

The Complete `.cursorrules` File for Kubernetes

Rule 1: Pattern Match Over Conditionals — Function Heads First, `with` for Chains

Rule 2: Tagged Tuples Are the Error Protocol — `{:ok, value}` / `{:error, reason}`

Rule 5: Ecto in Contexts — Queries Live in the Domain, Transactions Use `Multi`

Rule 6: Structured Concurrency — `Task.Supervisor`, Timeouts, Linked Tasks

The Complete `.cursorrules` File for Elixir

Rule 1: Immutability First — `val` Over `var`, Immutable Collections, No `null`

Rule 2: `Option`, `Either`, `Try` — Not `null` and Not Thrown Exceptions

Rule 4: Algebraic Data Types — Sealed Traits + Case Classes (or Scala 3 `enum`)

Rule 6: Effect Types — `IO` / `ZIO` Over Raw `Future`, No Blocking on the Main Pool

Rule 7: Collections — Immutable by Default, Lazy with Care, No `java.util`

Rule 8: Strict sbt — `-Werror`, Fatal Warnings, scalafmt, scalafix

The Complete `.cursorrules` File for Scala

Rule 3: `context.Context` is the first argument, always

Rule 6: `init()` is for registration, not business logic

Rule 7: Tests are table-driven with `t.Run` subtests

Rule 8: `gofmt`, `go vet`, `golangci-lint` — clean or it doesn't ship

Rule 1: Stores Over Prop Drilling — `writable`, `readable`, `derived`

Rule 2: Reactive Declarations With `$:` — Pure, Statically Analyzable, No Side Effects

Rule 3: Lifecycle Discipline — `onMount` Async Safety, `onDestroy` Cleanup

Rule 4: Typed Props With TypeScript Generics — `export let` Without `: T` Is a Bug

The Complete `.cursorrules` File