Handing an OpenAPI Spec to a Coding Agent

The spec is the contract. When the docs and the spec disagree, the agent has to pick one, and you need to know which.

Why a spec at all

A coding agent will happily guess an API. It has seen a hundred headless CMSs and will assume yours works like the average of them. A project-specific OpenAPI spec replaces the guess with a contract.

The first prompt

The first step was not code. It was a table: every endpoint the app needs, with path, parameters and response fields, taken only from the spec. Anything missing was written down as missing.

Where sources disagreed

  • Some doc examples list posts at /tables/posts/contents; the spec says /tables/posts
  • The spec describes sort as name:asc; a doc example uses a JSON array

The app follows the spec, and the build log records each disagreement so it can be checked against real responses.

Takeaway

Ask the agent to cite where each field came from. Uncited fields are guesses.

← 글 목록