CLAUDE.md for GraphQL & Apollo: 13 Rules That Stop AI From Writing Leaky, Overfetching APIs

// Resolver returns the raw Prisma model.
const resolvers = {
  Query: {
    me: async (_p, _a, ctx) => {
      return await ctx.prisma.user.findUnique({ where: { id: ctx.userId } });
      // → ships passwordHash, stripeCustomerId, internalNotes, ...
    },
  },
};

// Explicit mapper. Schema and DB evolve independently.
function toGraphQLUser(u: PrismaUser): GraphQLUser {
  return {
    id: u.id,
    email: u.email,
    displayName: u.displayName,
    createdAt: u.createdAt.toISOString(),
  };
}

const resolvers = {
  Query: {
    me: async (_p, _a, ctx) => {
      const u = await ctx.prisma.user.findUnique({ where: { id: ctx.userId } });
      return u ? toGraphQLUser(u) : null;
    },
  },
};

Resolvers return domain DTOs, not ORM entities.
Every GraphQL type has a corresponding `toGraphQL<Type>(entity)` mapper, OR
uses codegen-driven resolver types with explicit field selection.
A lint rule forbids `return await prisma.<model>.find...` directly from a resolver.
Adding a DB column never adds a field to the public schema implicitly.

const resolvers = {
  Post: {
    // 1 query per post in the result set. Hello, N+1.
    author: (post, _a, ctx) =>
      ctx.prisma.user.findUnique({ where: { id: post.authorId } }),
  },
};

// One DataLoader per entity, instantiated per request in `context`.
function createContext(req): Context {
  return {
    userLoader: new DataLoader<string, User>(async (ids) => {
      const users = await prisma.user.findMany({ where: { id: { in: [...ids] } } });
      const byId = new Map(users.map((u) => [u.id, u]));
      return ids.map((id) => byId.get(id) ?? null);
    }),
  };
}

const resolvers = {
  Post: {
    // Batched across the whole request. 1 query instead of N.
    author: (post, _a, ctx) => ctx.userLoader.load(post.authorId),
  },
};

Every relation field uses a DataLoader. One loader per entity (`userLoader`,
`commentLoader`, ...), instantiated per-request inside `createContext()`.
Raw ORM calls in field resolvers are forbidden — they go through the loader
or through a method that batches.
A request-level metric counts queries; a regression threshold fails CI on any
endpoint whose query count grows with collection size.

type Query {
  posts(offset: Int = 0, limit: Int = 20): [Post!]!
}

posts: (_p, { offset, limit }, ctx) =>
  ctx.prisma.post.findMany({ skip: offset, take: limit, orderBy: { id: "desc" } });

type Query {
  posts(first: Int, after: String): PostConnection!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

type PostEdge { cursor: String!  node: Post! }
type PageInfo { hasNextPage: Boolean!  endCursor: String }

posts: async (_p, { first = 20, after }, ctx) => {
  const cursor = after ? { id: decodeCursor(after) } : undefined;
  const rows = await ctx.prisma.post.findMany({
    take: first + 1,
    cursor,
    skip: cursor ? 1 : 0,
    orderBy: { id: "desc" },
  });
  const hasNextPage = rows.length > first;
  const nodes = rows.slice(0, first);
  return {
    edges: nodes.map((n) => ({ cursor: encodeCursor(n.id), node: n })),
    pageInfo: { hasNextPage, endCursor: nodes.at(-1) ? encodeCursor(nodes.at(-1)!.id) : null },
  };
};

List queries follow the Relay Connection spec: `first/after` (and `last/before`
when bidirectional), returning `{ edges, pageInfo }`.
Cursors are opaque base64 — never raw IDs or offsets — so the encoding can
evolve without breaking clients.
Offset pagination is reserved for admin/internal tools where stability under
concurrent writes does not matter; production user-facing lists never use it.

const server = new ApolloServer({
  typeDefs,
  resolvers,
  // introspection on by default in dev, often left on in prod by accident.
  // No depth limit. No complexity limit. No persisted-query allowlist.
});

import depthLimit from "graphql-depth-limit";
import { createComplexityRule } from "graphql-query-complexity";

const server = new ApolloServer({
  typeDefs,
  resolvers,
  introspection: process.env.NODE_ENV !== "production",
  validationRules: [
    depthLimit(7),
    createComplexityRule({
      maximumComplexity: 1000,
      estimators: [
        // Cost connections by `first`, fields by 1, expensive resolvers by N.
        fieldExtensionsEstimator(),
        simpleEstimator({ defaultComplexity: 1 }),
      ],
      onComplete: (cost) => { /* log to metrics */ },
    }),
  ],
});

In production: `introspection: false`, `graphql-depth-limit` set to ~7,
`graphql-query-complexity` with field-level cost — bounded by `first` on
connections — capped at a documented maximum.
Public APIs use persisted queries (allowlist of hashed operations) so the
server only ever executes operations shipped from a known client build.
Per-IP / per-token rate limits run in front of the GraphQL endpoint, not
inside it — by the time a request reaches a resolver it has already paid
parse + validate cost.