It is Monday morning. A new coding assistant looks promising, so you open a fresh chat and start the ritual: paste the API docs, explain the auth header, warn that pagination uses cursor, mention that money is integer cents, and remind it that the list payload is data.items, not data.records.
It works for an afternoon. Two weeks later you switch tools, onboard a contractor, or the context window rolls over, and somebody does the ritual again. Meanwhile the backend changed in three places and the pasted docs were already stale on arrival.
This is not a prompting problem. It is a source of truth problem.
The contract has nowhere to live
Most teams run the same stack of implicit knowledge:
- a wiki page last edited during the previous funding round,
- a Postman collection one engineer maintains by hand,
- a
READMEwith three curl examples that all hit localhost, - and the actual behavior of the running service, which is the only one that counts.
AI tools amplify the gap instead of closing it. A chat model is remarkably good at sounding certain about pageSize when the API actually takes limit. It cannot get fired for the integration bug, so it produces the most plausible shape and moves on.
The fix is boring and, in my experience, the only thing that actually works: one machine-readable contract that every workflow reads from and writes back to. For HTTP APIs that contract is an OpenAPI document on disk, in version control, reviewed like code.
What "AI-native" actually means here
The phrase gets used for a chatbot bolted onto a sidebar. I mean something narrower. An API workflow is AI-native when the same spec drives every stage of the lifecycle:
| Stage | What reads or writes the spec |
|---|---|
| Design | AI drafts operations and schemas as reviewable diffs |
| Mocking | A mock server answers real HTTP from the spec's examples |
| Testing | Scenario tests chain requests and assert against documented schemas |
| Debugging | Requests, environments, and auth are derived from the spec |
| Reverse engineering | An AST scanner reconstructs the spec from an existing codebase |
| Agent integration | The spec is served over MCP as tools an agent can discover |
| Publishing | Hosted docs and a hosted MCP endpoint are generated from the same file |
Notice the direction of travel. The file is the source. The AI is a client of the file, the mock is a client of the file, the tests and the docs and the agents are all clients. When the contract changes, every derived artifact changes from the same diff instead of being rediscovered in six different tools.
Local first, not cloud-first
One thing that took me too long to internalize: the spec is local. It sits in the repo next to the code it describes. AI assistance is just a configured provider and an API key you control. When the workflow goes the other direction — scanning an existing codebase — the source code never leaves the machine; only an individual, untyped handler might be sent to your configured model if you explicitly ask for help filling a gap.
That matters because the most valuable contracts describe internal systems nobody wants to upload: pricing logic, internal admin routes, unreleased products. Local-first is not a privacy gimmick in this workflow, it is the precondition for trusting the tool with real code.
What this series covers
I spent the last few months living in this workflow while building and dogfooding Powerduck, a local API workspace built around exactly this loop. This seven-part series is the practical version — one day, one workflow, with the mistakes included:
- Day 2 — design an API with AI before any code exists, with review gates that keep the AI honest
- Day 3 — replace hand-written mock JSON with a mock server generated from the spec
- Day 4 — write scenario tests that walk the business flow instead of celebrating single 200s
- Day 5 — scan a 200-route codebase into OpenAPI with an AST engine and honest gap reports
- Day 6 — connect a coding agent to the spec over MCP so it stops guessing field names
- Day 7 — publish hosted docs and an MCP endpoint without turning it into a website project
None of this requires believing AI will replace backend engineers. It requires the opposite: the contract is where senior engineering judgment lives, and the AI is a fast drafter and a tireless verifier against it.
The one thing to try today
Open whatever API you are integrating with right now and ask yourself a question: if a new agent had to call it correctly on the first try, what single artifact would you hand it? If the honest answer is "the codebase and a Slack thread," the rest of this series is about fixing exactly that.
I wrote the long version of why pasting curl commands into chat fails (and what to do instead) over here. Tomorrow, Day 2 starts at the beginning of the lifecycle: designing the contract before the first route exists.
Top comments (0)