GraphQL API taste — ChatGPT and Claude prompt: schema design rules
A prompt that steers an agent to shape a GraphQL schema from client use cases rather than database tables. Useful when the API exists but the types no longer match what the frontend needs.
Open on GitHubWhat GraphQL API taste does
The prompt hands the model a platform engineer's opinions, each tagged with a confidence level. Schemas get built around client scenarios and domain wording instead of mirroring tables. Server and client types are generated from the schema with GraphQL Code Generator or something equivalent; hand-written response types are ruled out.
A second group covers resilience and data access. Fields backed by other services stay nullable so one failing dependency does not blank the whole response. Per-request caching through DataLoader keeps N+1 queries away. Lists use Relay-style cursor connections with a cap on first/last, and the gateway enforces depth and complexity limits.
Schema lifecycle gets equal weight. Changes are additive, retiring fields means @deprecated(reason: ...) first, and removal waits until usage metrics show no traffic across a full release cycle. A schema diff step in CI fails the build on breaking edits. Softer notes are there too: reach for federation only when separate teams own separate subgraphs, and keep subscriptions for data that genuinely changes in real time.
What it helps with
- shape a GraphQL schema around client scenarios instead of tables
- kill N+1 queries with per-request DataLoader caching
- return business errors as typed payload members
- paginate lists with Relay cursor connections
- fail the CI build on a breaking schema change
Example prompts for the agent
- Design a GraphQL schema for cart and order around our checkout flow
- Rework the
updateProductmutation to take an input object and return a payload with typed errors - Check this schema for breaking changes and propose an additive version using
@deprecated
How to install GraphQL API taste
How to use
Paste the text at the start of a chat or into project instructions
Manually: put the files in place
.claude/commands/prompts.csv.mdQuestions about GraphQL API taste
How do I install GraphQL API taste in Claude?
Paste the prompt text at the top of a conversation or into the instructions of a custom Claude. No marketplace entry is given for Claude.
What does GraphQL API taste do?
It gives the agent a fixed set of GraphQL design rules: client-driven types, codegen, DataLoader, gateway limits and additive schema evolution.
Why use this prompt instead of just asking the agent about GraphQL?
Generic answers stay vague. Here each rule is stated outright, down to failing the build when a schema diff breaks compatibility.
Source text
prompts.csv · CC0-1.0
# GraphQL API taste of a platform engineer - Design the schema around client use cases and domain language, not around database tables. Confidence: 0.90 - Generate types for both server and client from the schema (GraphQL Code Generator or equivalent); never hand-write response types. Confidence: 0.90 - Make fields non-null by default only when the server can always resolve them; keep fields that depend on other services nullable so one failure does not null out the whole response. Confidence: 0.80 - Use one input object per mutation (createOrder(input: CreateOrderInput!)) and return a payload type, not the bare entity. Confidence: 0.85 - Return expected business errors as typed union members in the payload (e.g. OrderCreated | InsufficientStock); reserve the top-level errors array for unexpected failures. Confidence: 0.75 - Paginate lists with Relay-style cursor connections (edges, node, pageInfo) and cap first/last at a sane maximum. Confidence: 0.80 - Batch and cache data loading per request with DataLoader to kill N+1 queries. Confidence: 0.95 - Enforce query depth and complexity limits at the gateway. Confidence: 0.90 - Use persisted queries (allowlisted operation hashes) for first-party clients in production. Confidence: 0.80 - Disable introspection on public production endpoints unless the API is meant to be public. Confidence: 0.70 - Evolve the schema additively and mark old fields with @deprecated(reason: ...); never version the endpoint with /v2. Confidence: 0.90 - Remove a deprecated field only after field-usage metrics show no traffic for a full release cycle. Confidence: 0.85 - Run schema diff checks in CI and fail the build on breaking changes. Confidence: 0.90 - Use globally unique opaque IDs and implement the Node interface for refetching. Confidence: 0.70 - Keep resolvers thin: they call domain services, and authorization lives in that service layer, not in resolver if-statements. Confidence: 0.85 - Name operations in every client query so traces, logs and metrics are readable. Confidence: 0.90 - Colocate fragments with the UI components that use them. Confidence: 0.80 - Prefer custom scalars (DateTime, URL, Email) with validation over plain String. Confidence: 0.75 - Use subscriptions only for genuinely real-time data; polling is fine for anything that changes every few minutes. Confidence: 0.70 - Reach for federation only when several teams own separate subgraphs; one team means one schema. Confidence: 0.75 - Trace every resolver with OpenTelemetry and alert on slow fields, not just slow requests. Confidence: 0.80 - Document every type and field with schema descriptions; the schema is the API reference. Confidence: 0.85
© f · CC0-1.0 · f/prompts.chat
