Providing an OpenAPI Spec

Why It Helps

An OpenAPI (or Swagger) spec is the most precise description of your backend you can give Claude.

With a spec, Claude knows exactly: what endpoints exist, what parameters they take, what response shapes they return, and what errors are possible.

The mock will accurately mirror your real backend. When you switch NEXT_PUBLIC_API_BASE_URL, the app should work without frontend changes.

How to Provide It

Drop your spec file into documentation/ before typing /start:

documentation/
└── api.yaml        # or api.json, openapi.yaml, swagger.yaml; any name works

Claude will find it and use it during planning.

If You Don’t Have a Spec

That’s fine. Claude infers a reasonable API shape from your requirements and sample data.

The trade-off: you may need to adjust mock responses when you integrate the real backend, since Claude’s inferred shape may not exactly match your actual API.

You can always add a spec later. Update documentation/ and mention it to Claude at the start of the next session.