10 Prompts That Make Cursor and Copilot Do the Heavy Lifting

# .cursor/rules/backend.md  (applies to: src/api/**, src/services/**)

## Stack
TypeScript strict mode. Node 22. Fastify, not Express.
Prisma ORM — use the existing client from src/db/prisma.ts, never instantiate a new one.

## Conventions
- Function names: camelCase. Files: kebab-case. Types: PascalCase.
- All async functions return Result, never throw.
- No `any`. No unhandled promise rejections.
- Every new public function needs a JSDoc comment with @param and @returns.

## Testing
Jest + Supertest. Tests live in __tests__/ mirroring src/ structure.
Always test happy path, null/empty inputs, and one error case minimum.

## What NOT to do
- Never log sensitive fields (email, password, token, card numbers).
- Never commit .env changes.
- Never modify the Prisma schema without a migration file.

Review the changes in @git:staged as a senior engineer doing a PR review.

For each issue you find:
1. State the file and line number
2. Explain what's wrong and why it matters
3. Write the corrected code inline

After listing all issues, run `npm run typecheck` and `npm run lint`.
Fix anything that fails. Show me a summary of what you changed.

Issues found:

1. src/api/orders.ts:47 — `userId` accessed without null check.
   The `getUser()` call on line 43 can return null on cache miss.

   Fixed:
   const user = await getUser(userId);
   if (!user) return reply.status(404).send({ error: 'User not found' });

2. src/services/inventory.ts:112 — O(n²) loop. Fetching product
   inside the order loop. Moved query outside.

Running typecheck... ✓ no errors
Running lint... 1 warning: unused variable `tempResult` line 89

Fixed: removed unused variable.

Summary: 2 logic fixes, 1 lint cleanup. 3 files changed.

Look at @src/ and @__tests__/ and generate a .cursor/rules/project.md file for this codebase.

Infer and document:
- The tech stack (languages, frameworks, libraries and their versions from package.json)
- Naming conventions actually used in the code (not ideal, actual)
- Error handling patterns used consistently
- Test structure and what gets tested
- Any patterns that appear in 3+ places (these are de facto conventions)
- A "never do this" section based on anti-patterns you spot

Format it as rules an AI agent should follow, not as a description.

@linear:issue-ENG-847

The bug described in this ticket is happening in our production payments service.
@sentry:recent-errors service:payments last:24h

Look at @src/services/payments/ and find the root cause.
Don't write any code yet — explain what's wrong and what the fix should be,
referencing the actual error stack from Sentry and the schema from the DB.

Task: Add pagination to the GET /api/orders endpoint.

Context:
- Current endpoint is in @src/api/orders.ts
- We use cursor-based pagination elsewhere — see @src/api/users.ts for the pattern
- The Order model is in @src/db/schema.prisma
- Tests live in @__tests__/api/orders.spec.ts

Done means:
- Endpoint accepts `cursor` and `limit` query params (limit default 20, max 100)
- Returns `{ data: Order[], nextCursor: string | null }`
- At least these test cases pass: first page, second page, last page (nextCursor null), limit=0 rejected
- TypeScript strict mode passes
- No changes to existing endpoint response shape for requests without pagination params

Do NOT:
- Change the authentication middleware
- Modify any other endpoints
- Add any new dependencies

You are adversarial QA. Your job is to break @src/services/rateLimit.ts.

First, list every way this code can:
- Return a wrong result (allow when it should block, or block when it should allow)
- Crash or throw unexpectedly
- Fail silently
- Behave differently under concurrent requests
- Create a security vulnerability

Then write test cases for the three most severe issues you found.
Run them. If they pass (meaning the bug exists and is caught by the test), report what you found.
If they fail (meaning the code handles it), mark that issue as already handled.

Implement email verification for new user signups.

Acceptance criteria:
- After registration, user receives a verification email with a time-limited token (24h)
- GET /api/auth/verify?token= verifies the token and marks the user as verified
- Unverified users can log in but see a banner; they cannot access /api/orders or /api/payments
- Verified status is stored on the User model (migration required)
- Token is invalidated after use

Patterns to follow:
- Email sending: see how password reset emails work in src/services/auth/passwordReset.ts
- Token generation: use the existing crypto utility in src/utils/tokens.ts
- Middleware pattern: see src/middleware/requiresVerified.ts if it exists, or create it following requiresAuth.ts

Tests required: registration flow, valid token verification, expired token, already-used token, unverified user hitting restricted endpoint.

Look at these recent PR review comments: [paste 5-10 recurring comments]

And look at @src/ to understand the codebase patterns.

Do two things:
1. Write .cursor/rules entries that would have prevented each of these issues
2. Scan @src/ for existing violations of these patterns and list them (don't fix them yet — just find them)

"Use the Result type, don't throw"
"Logs are missing the requestId field"
"Why is this query inside the loop?"
"This needs a test for the null case"
"Don't import directly from @prisma/client, use our wrapper"

## .cursor/rules additions:

### Error handling
- NEVER use throw for expected errors. Use Result from src/types/result.ts
- NEVER catch and re-throw without adding context. Use Result.mapErr() to annotate.

### Logging
- Every log.info/warn/error call MUST include requestId from the request context.
  Pattern: log.info({ requestId: ctx.requestId, ...data }, 'message')

### Database
- NEVER execute a database query inside a loop. Batch queries using Prisma's findMany with `in` operator.

### Testing  
- ALWAYS include a test case for null/undefined inputs on public functions.

### Imports
- NEVER import from '@prisma/client' directly. Use the typed client from src/db/client.ts

---

## Existing violations found:
- src/services/checkout.ts:89 — query inside loop (3 occurrences)
- src/api/webhooks.ts:34 — throws instead of Result
- src/utils/email.ts:12 — direct @prisma/client import
[...8 more]

I need to implement: user-facing webhook configuration (let users register URLs to receive order events).

@linear:issue-ENG-912 has the full requirements.
Check @src/api/ for existing endpoint patterns.
Check @src/services/webhooks.ts if it exists.

Don't write any implementation yet.

Write a complete test suite for this feature covering:
- Happy path (webhook registered, event fires, URL receives POST)
- Duplicate URL registration (should update, not create a second)
- Invalid URL format (should reject at validation)
- Webhook delivery failure (should retry 3 times with exponential backoff)
- Delivery after retry exhaustion (should mark as failed, not keep retrying)
- User can list their webhooks
- User can delete a webhook

Use the test patterns from @__tests__/api/orders.spec.ts.

Once I approve the tests, implement the feature to pass them.

I'm new to this codebase. Give me an architectural orientation by reading:
@src/ @package.json @README.md

Tell me:
1. What does this application actually do? (one paragraph, plain English)
2. What's the folder structure and what lives where?
3. What's the request lifecycle? (a user hits an endpoint — what happens, in order, from network to database and back)
4. Where are the 3 most complex parts of the codebase? (files/modules I should understand before touching anything)
5. What are the patterns I'll need to follow? (error handling, auth, DB access, testing)
6. What are the landmines? (deprecated patterns still in use, known rough edges, things that look wrong but aren't)

I need to build out the notifications module. Start three background agents in parallel:

Agent 1 — Database layer:
  Create the Notification model in @prisma/schema.prisma with a migration.
  Build the NotificationRepository following the pattern in @src/db/userRepository.ts.
  Done when: migration runs cleanly, repository has CRUD methods, unit tests pass.

Agent 2 — Service layer:
  Build NotificationService in @src/services/notifications.ts.
  It should queue outbound notifications, handle channel routing (email/SMS/push),
  and implement retry logic.
  Use @src/services/email.ts and @src/services/sms.ts for the actual sending.
  Done when: service unit tests pass with mocked channels.

Agent 3 — API layer:
  Build GET/POST/DELETE /api/notifications endpoints.
  Follow the patterns in @src/api/orders.ts.
  Done when: integration tests pass and TypeScript is clean.

After all three complete, I'll review the diffs together and handle any interface mismatches.