just-works: Skill for Claude Code

REST API Design

Project conventions override these defaults. Read 2-3 existing endpoints first, and check for an OpenAPI spec, the existing error format, and the authentication pattern.

references/http-reference.md holds the status code decision list (400 vs 422, 401 vs 403), versioning and deprecation headers, authentication mechanisms and scopes, caching and conditional requests, long-running operations, webhook signature verification, and file upload patterns. Read it when the task touches one of those.

Never rules

• Never return only the first validation error. Return all errors at once with field paths.
• Never use offset pagination on datasets over about 10K rows. The database scans and discards every skipped row, so deep pages get slower. Use cursors.
• Never omit Retry-After on 429 responses.
• Never verify webhook signatures against re-serialized JSON. Verify against the raw request body bytes.
• Never bind raw client input to internal models. That allows mass assignment (is_admin: true in a body). Use DTOs or schemas that allowlist writable fields, and reject unknown fields.
• Never trust a client-supplied resource ID without a server-side ownership check. Broken object level authorization (BOLA, also called IDOR) is the most common API vulnerability. Respond 404 when the caller does not own the object, and use unpredictable IDs for resources that cross trust boundaries; opaque IDs slow enumeration but do not replace the check.
• Never combine Access-Control-Allow-Origin: * with credentials. Browsers reject it. Validate Origin against an allowlist and reflect the specific origin; set Access-Control-Max-Age for preflight caching.
• Never expose internal error details in production responses. Stack traces, SQL, file paths, and dependency versions go to logs, not clients.

Resource design

Use plural, lowercase nouns, and one casing convention for multi-word segments (kebab-case is the web default). Express CRUD with HTTP methods, not verbs in paths: DELETE /users/123, not POST /users/123/delete. Nest only when the child's ID is scoped to its parent, and no deeper than 3 levels; otherwise expose it top-level: