菜单
Designs and reviews HTTP/REST and RPC API surfaces — resource naming, verbs, status codes, pagination, versioning, idempotency, error envelopes, and backward compatibility. Use when creating a new endpoint or changing an existing API contract.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/Sir-chawakorn/sanook-cli --skill api-design-review命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Gets machine-parseable JSON out of an LLM reliably — prefer provider-enforced grammar (OpenAI `response_format:{type:"json_schema",strict:true}`, Anthropic tool-calling / `tool_choice:{type:"tool"}`, Gemini `responseSchema`) over a "respond in JSON" prompt, define the contract once as a Pydantic/Zod model and validate every response (never trust the string), use constrained decoding / grammars for open weights (Outlines, llguidance, llama.cpp GBNF, vLLM `guided_json`), keep schemas SHALLOW with required fields + enums + `additionalProperties:false`, and build a repair-and-retry loop that handles refusals, `length`/`max_tokens` truncation, and streaming partial JSON (`partial-json-parser`). Schema-guided generation eliminates parse-error retries; validate-and-repair is the backstop, not the primary mechanism.
Builds production data grids that stay fast and accessible at 10k–1M+ rows — decide server-side vs client-side sort/filter/paginate by the dataset-fits-in-memory test (client only under ~10k rows, otherwise push to the API and treat the table as a controlled view of server state), ROW-VIRTUALIZE with TanStack Virtual or react-window so only the visible window mounts (fixed estimateSize, overscan 5–10, measureElement for dynamic rows, contain:strict, and a real scroll container — never table-layout:auto over thousands of rows), build the headless logic with TanStack Table v8 (or AG Grid when you need pinning/grouping/enterprise out of the box), add column resize/reorder/pin, inline edit with optimistic update + rollback on error, row selection with a stable rowId, full keyboard nav with roving tabindex over an ARIA grid (role=grid/row/gridcell, aria-sort, aria-rowcount/aria-rowindex so virtualization stays announced), position:sticky headers, streaming CSV export that doesn't block the main thread, and explici
Builds semantic/vector search — pick an embedding model + dimensionality (and whether to truncate Matryoshka dims) and the matching distance metric (cosine/dot/L2, normalize to unit length so cosine == dot and IP is correct), an ANN index with the recall/latency/memory tradeoff understood (HNSW M/efConstruction/efSearch for low-latency RAM-resident; IVF-PQ nlist/nprobe/PQ for billion-scale compressed; flat/exact for <100k) in pgvector/Qdrant/Milvus/FAISS/Pinecone, chunking + overlap + per-chunk metadata for filtering, HYBRID retrieval fusing BM25 + dense by Reciprocal Rank Fusion (RRF, k≈60) not score addition, a cross-encoder/Cohere reranker over the top-50→k, correct pre-filter-vs-ANN interaction (filterable HNSW, not post-filter that starves k), and offline eval with recall@k / nDCG@10 / MRR against a labeled qrels set. Quantize (scalar/PQ) only after measuring recall loss; tune efSearch/nprobe to a recall target, not a guess.
基于 SOC 职业分类
正在显示 SKILL.md
| name | api-design-review |
| description | Designs and reviews HTTP/REST and RPC API surfaces — resource naming, verbs, status codes, pagination, versioning, idempotency, error envelopes, and backward compatibility. Use when creating a new endpoint or changing an existing API contract. |
| when_to_use | สร้าง endpoint ใหม่; แก้ request/response schema; เปลี่ยน API contract; ออกแบบ versioning |
Invoke before writing or merging any change that alters an API contract:
Do NOT use for: pure internal refactors with no wire-format change, or UI-only work.
Pin the contract surface. List every consumer-visible element you touch: METHOD /path, query params, request body fields, response body fields, status codes, headers. If you can't enumerate it, you can't review it.
Model resources as nouns, actions as verbs. Path = pluralized noun collection (/orders, /orders/{id}/items). Never put the action in the path (/getOrder, /createOrder are wrong). Map intent to verb:
GET read, no side effects, safe + idempotent.POST create / non-idempotent action → returns 201 + Location header (or 202 for async).PUT full replace, idempotent. PATCH partial update.DELETE remove, idempotent → 204 (or 200 with body).POST /orders/{id}/cancel), not a verb path.Pick the correct status code — not a blanket 200.
201 created (with Location), 202 accepted-async, 204 success-no-body.400 malformed syntax, 401 unauthenticated, 403 authenticated-but-forbidden, 404 not found, 409 conflict (e.g. duplicate, state clash), 422 well-formed but semantically invalid (validation), 429 rate-limited.5xx only for server faults — never for client validation failures.Standardize pagination/filter/sort across the surface. Pick ONE pagination style and apply it everywhere: cursor-based (?cursor=&limit=, opaque cursor, stable for live data — preferred) or offset (?page=&per_page=, simpler but drifts on inserts). Return pagination metadata consistently (e.g. { "data": [...], "next_cursor": "...", "has_more": true }). Filtering/sorting via explicit allow-listed params (?status=open&sort=-created_at); reject unknown params instead of silently ignoring.
Use a single error envelope for every error response. Same shape on every 4xx/5xx so clients parse once:
{ "error": { "code": "VALIDATION_FAILED", "message": "human readable", "details": [ { "field": "email", "issue": "invalid format" } ] } }
code = stable machine string (clients branch on this, never on message). Don't leak stack traces / internal SQL.
Require idempotency for unsafe writes. Non-idempotent POST that creates resources or moves money/state must accept an Idempotency-Key header; server stores key→result and replays the same response on retry. PUT/DELETE must be naturally idempotent (calling twice = same end state, no error on second DELETE of already-gone resource → 204 or 404, pick one and document it).
Version + run a breaking-change diff. Diff the new contract against the existing one. Backward-compatible (safe, no version bump): adding an optional field, adding a new endpoint, adding an enum value clients must tolerate, loosening validation. Breaking (needs new version or is forbidden): removing/renaming a field, changing a type, making an optional field required, tightening validation, changing status-code semantics, changing default behavior. Version via URL (/v2/...) or header — pick the project's existing convention. If a change is breaking, either make it additive instead, or ship under a new version and keep the old one working.
Validate input at the edge. Reject unknown/extra fields or define the policy explicitly. Enforce types, ranges, lengths, and required-ness before any business logic runs. Document every field: type, required?, default, constraints, example.
{"success": false} in the body). Clients then can't rely on HTTP semantics, retries/caching/monitoring all misbehave. Use real status codes.200 for async work. If processing is deferred, return 202 Accepted with a status/polling URL — not 200 implying it's done.404 to hide existence is sometimes intentional; returning 403 reveals the resource exists. Decide deliberately and be consistent.422 vs 400 confusion. 400 = can't even parse the request; 422 = parsed fine but the values are invalid. Mixing them makes client retry logic wrong.200).code field.POSTs accept an idempotency key; PUT/DELETE are idempotent.If a contract test / schema snapshot exists, run it and confirm the diff matches the intended (and documented) changes only.