Spec a void-invoice endpoint that fits house patterns

Vibe codingMedium25 minAnthropic style

Your task

Your billing service is a large Node and TypeScript codebase whose habits live only in people's heads. The last endpoint an agent added worked, but it registered its route the wrong way and checked the body by hand. It also returned its own error shape and logged without the request's correlation id. The next task is an endpoint that voids an invoice.

Write the spec you would hand the agent.

What you know:

  • routes are registered with registerRoute() in src/http/routes.ts, and handlers live in src/http/<area>/
  • request bodies are checked with Zod schemas through the validate() middleware
  • handlers throw AppError(code, status), and middleware turns it into { error: { code, message, correlationId } }
  • req.log is a logger that already carries the correlation id
  • src/http/invoices/refundInvoice.ts is the endpoint everyone points new people to
  • only open invoices can be voided, by callers with the invoices:write scope

Then, in a few sentences: which of these habits would you also enforce with a lint rule or a test, and why?