Generated API Client

Scenario

You maintain a frontend application that consumes a backend API through a generated TypeScript client.

The client is generated from an API specification.

Developers should not manually edit generated client files because those changes will disappear the next time generation runs.

You want coding agents to understand the relationship:

API specification
       ↓
client generator
       ↓
generated client
       ↓
frontend application

Repository Structure

web-app/
├── src/
│   ├── api/
│   │   ├── generated/
│   │   │   ├── users-api.ts
│   │   │   ├── projects-api.ts
│   │   │   └── models.ts
│   │   └── client.ts
│   └── features/
├── api/
│   └── openapi.yaml
├── scripts/
│   └── generate-api-client.ts
├── package.json
└── AGENTS.md

AGENTS.md

# Project Instructions

## Generated API Client

- Treat `src/api/generated` as generated output.
- Do not manually edit files under `src/api/generated`.
- Make API contract changes in the source API specification.
- Regenerate the client using the repository generation command.

## Generation

After changing the API specification, run:

- `pnpm generate:api`

Review the generated diff before using the new client API.

## Application Code

- Use the generated client through the existing application API layer.
- Do not duplicate generated request or response types manually unless the repository has an explicit reason.
- Keep application-specific behavior outside the generated directory.

## Validation

After regenerating the API client:

- inspect generated changes;
- run `pnpm typecheck`;
- run relevant tests;
- run the application build when public client behavior changes.

What This Does

This identifies:

api/openapi.yaml

as the source of truth and:

src/api/generated/

as derived output.

Suppose the generated client contains:

export interface User {
  id: string;
  email: string;
}

and the API now needs:

displayName: string;

The wrong approach is editing:

src/api/generated/models.ts

directly.

The correct workflow is:

Update API specification
        ↓
Run generator
        ↓
Generated models change
        ↓
Update application consumers
        ↓
Validate

What This Does NOT Do

The instructions do not prohibit reading generated code.

Generated output can be useful for understanding:

• available client methods;
• generated types;
• naming conventions;
• how a specification change affected the client.

The restriction concerns manual modification.

The file also does not require every application API abstraction to be generated.

Application-specific wrappers may still exist outside the generated directory.

Why These Instructions Matter

Generated files often look like ordinary source code.

An agent may see:

export type CreateUserRequest = {
  email: string;
};

and make the obvious local change:

export type CreateUserRequest = {
  email: string;
  name: string;
};

The application may compile.

But the next execution of:

pnpm generate:api

can overwrite that change.

Now the repository contains behavior that cannot be reproduced from its actual source of truth.

Explicit instructions prevent this class of temporary fix.

Key Decisions

Identify generated directories clearly

Agents should not have to infer whether a file is generated.

Modify the source of truth

Generated output should reflect another authoritative artifact.

Change that artifact first.

Regenerate using repository commands

Use the project's established generator rather than reconstructing output manually.

Review generated diffs

Generation is automated, but generated changes still deserve review.

A small source change can sometimes produce a large output change.

Keep application logic outside generated code

Custom behavior should not be inserted into files that can be replaced automatically.

When to Use This Pattern

Use this pattern when:

• API clients are generated;
• generated files are committed;
• API specifications drive client code;
• developers sometimes need to modify API contracts;
• accidental edits to generated output are possible.

The core rule is:

generated code can be consumed and inspected, but its source should be changed instead of its output.