AI-Assisted Implementation

You have generated a Counterfact project from an OpenAPI spec and want to go beyond random responses quickly — without writing all the handler logic yourself.

Problem

Counterfact generates a working server immediately, but the handlers return random data. Writing realistic, stateful implementations for every route by hand is tedious, especially on large APIs.

Solution

Delegate the implementation work to an AI coding agent. The combination of a simple, consistent handler API, TypeScript types derived from the spec, and one file per route gives AI agents the context they need to produce correct code with a small number of tokens and a low risk of hallucination. The agent can replace .random() calls one route at a time, guided by the type signatures already in place.

Example

After generating the project, point an AI agent at a handler file and ask it to implement the route:

Given the TypeScript types in api/types/, implement the GET handler in api/routes/pet/{petId}.ts
to look up a pet from context by path parameter and return 200 with the pet or 404 if not found.

The agent sees the fully typed $ parameter, the spec-derived response types, and the context definition — all in one file. It produces something like:

// api/routes/pet/{petId}.ts
export const GET: HTTP_GET = ($) => {
  const pet = $.context.get($.path.petId);
  return pet ? $.response[200].json(pet) : $.response[404].text("Not found");
};

If the result does not match the spec’s response schema, TypeScript flags it immediately in the IDE. The agent can correct its output without requiring you to understand the full type system.

Repeat for each route, or ask the agent to implement all routes in a single pass. The clear file structure and isolated scopes minimize interference between routes.

Consequences