Claude Code CLAUDE.md template for react-query.gen

[Andrew-Chen-Wang]

Does anyone have a CLAUDE.md/AGENT.md file that helps their Claude Code properly write out useQuery and useMutation? Currently, my LLMs are hallucinating like crazy, importing the wrong code (see screenshot here upstash/context7#566 (comment)), unable to interpret the options (such as path parameters, body types, etc.), and unable to infer the response type either.

What I've written so far:

Using the API

Use Tanstack Query v5 for all API calls. You'll typically import from "@/services/client/@tanstack/react-query.gen"
To get what options to put in the body of mutations, you can look at the function parameters
such as options which will lead you to a file called types.gen.ts.

To perform a GET request, you can use the useQuery and useMutation hook. For example, to fetch user data:

import {
  getApiV1FeedFeedOptions,
  postApiV1FriendFindFriendsMutation,
} from "@/services/client/@tanstack/react-query.gen"
import { useMutation, useQuery } from "@tanstack/react-query";
import { postApiV1FriendFindFriendsMutation } from "./react-query.gen";

useQuery({
  ...getApiV1FeedFeedOptions()
})

useMutation({
  ...postApiV1FriendFindFriendsMutation(),
  onSuccess: (data) => {
    // custom logic
  }
})

An example of identifying the necessary types for passing in the parameters or body for a mutation:

export const deleteApiV1FriendByIdDeleteSentInviteMutation = (
  options?: Partial<Options<DeleteApiV1FriendByIdDeleteSentInviteData>>,
): UseMutationOptions<
  DeleteApiV1FriendByIdDeleteSentInviteResponse,
  DeleteApiV1FriendByIdDeleteSentInviteError,
  Options<DeleteApiV1FriendByIdDeleteSentInviteData>
> => {}

DeleteApiV1FriendByIdDeleteSentInviteData is in types.gen.ts and includes the path parameters
in the path property. The body is also typically located in the body property for mutations.

export type DeleteApiV1FriendByIdDeleteSentInviteData = {
  body?: never
  path: {
    id: string
  }
  query?: never
  url: "/api/v1/friend/{id}/delete-sent-invite"
}

The response object can be used for typing throughout the app (though with autocompletion, it's
not necessary to import the type unless it's necessary for a function signature).
DeleteApiV1FriendByIdDeleteSentInviteResponse in this case leads to:

export type DeleteApiV1FriendByIdDeleteSentInviteResponses = {
  /**
   * Invite deleted successfully
   */
  200: {
    [key: string]: unknown
  }
}

export type DeleteApiV1FriendByIdDeleteSentInviteResponse =
  DeleteApiV1FriendByIdDeleteSentInviteResponses[keyof DeleteApiV1FriendByIdDeleteSentInviteResponses]

[dosubot]

There aren’t any public CLAUDE.md or AGENT.md templates specifically for react-query.gen, but you can reduce LLM hallucinations by giving Claude explicit, example-driven instructions based on the actual generated hooks and usage patterns.

For best results, include concrete code snippets showing how to use the generated hooks, clarify the naming conventions (e.g. getPetByIdInfiniteQueryKey, addPetMutation), and specify how to pass parameters (like path, body) and handle response types. For example:

# Claude Code Instructions for react-query.gen

When generating code for data fetching or mutations, use the hooks and functions generated by openapi-ts with the @tanstack/react-query plugin.

## Imports
Import hooks and functions directly from the generated client, e.g.:
import { useQuery, useMutation, getPetByIdInfiniteQueryKey, addPetMutation } from 'src/client';

## useQuery Example
const { data, error } = useQuery({
  ...getPetByIdInfiniteQueryKey({
    path: { petId: 1 }
  }),
});

## useMutation Example
const addPet = useMutation({
  ...addPetMutation(),
  onError: (error) => { console.log(error); },
});

addPet.mutate({
  body: { name: 'Kitty' }
});

## Guidelines
- Always use the generated functions for query keys and mutations.
- Pass parameters as objects with `path`, `body`, etc., matching the OpenAPI schema.
- Infer response types from the generated function signatures.

This approach helps Claude avoid guessing imports or parameter structures and instead rely on the actual generated API. For more details and examples, see the plugin documentation.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[Andrew-Chen-Wang]

oops, this could probably go into Discussions rather than GitHub issues

[mrlubos]

Do you think this is something that should be provided by this package?

[Andrew-Chen-Wang]

that's interesting/bold. It would be neat to have it generated for sure as an optional flag (maybe on by default?)!

[mrlubos]

Definitely not enabled by default, but I don't see why it wouldn't make sense as a feature request. Who else has all the context to create this file if not us! As long as we know what a good format looks like and don't introduce breaking changes somehow, this all sounds reasonable to me. What would happen if TanStack Query output lives scattered across multiple files? What if there are other, unrelated functions in those files?