When AI Starts Writing Your System, Who Tells It What 'Done' Means?
You hand AI a task: build a booking system. Users pick a time slot, submit a reservation, and an admin can cancel it. Fast enough. The page exists. The endpoint exists. The database table exists. Each piece looks right in isolation. Then you connect them. The frontend treats the timestamp as local time. The backend stores UTC. The cancel endpoint returns 200, but the booking list still shows…
When an artificial intelligence generates code for a system, it is critical to determine precisely what "done" means. If the definition of completion exists only during a few interactions with the AI, different parts of the project can interpret it differently, leading to discrepancies. To resolve this, OpenAPI Specification (OAS) proves invaluable. It serves as a structured format that describes endpoints, parameters, responses, and authentication in a way that both humans and tools can easily comprehend.
In Powerduck, the process begins by outlining business requirements, then asking the AI to suggest a design that aligns with the existing specification. This step helps define aspects like timezone format, booking status progression, and error responses when a slot is no longer available. Crucially, it also highlights rules that the requirement does not explicitly cover.
The key aspect is not the volume of AI-generated code, but rather whether the AI proposes changes to the API that clarify field meanings, maintain consistent status models, and cover all necessary failure scenarios from the user's perspective.
Once the AI has finished its initial work, the focus shifts to reviewing the proposed changes. The OpenAPI Specification (OAS) file created earlier becomes a permanent document throughout the AI workflow. It guides the implementation stage where an MCP server provides the coding assistant with a precise contract instead of a static document. Meanwhile, mock services allow the frontend development to proceed using the contract specifications from the OAS.
Verification comes next, where the system sends real requests, executes contract checks, and runs scenario tests. This ensures that the code adheres to the agreed-upon specifications. Finally, when the system is ready for delivery, documentation can be generated from the same OpenAPI Specification file and the MCP endpoint can be published on demand.
The shift towards an AI-native development pattern brings forth feedback loops that validate the AI's output. For instance, after an endpoint is implemented, the AI can query the contract via MCP and make actual requests to the test service. Any mismatches in parameters, missing response fields, or failed scenarios will be immediately apparent, allowing for further iterations.
Though OpenAPI Specifications have their limitations, they provide a crucial foundation for catching gaps early. They are not sufficient to express complex scenarios like race conditions or cross-service transactions, which would require additional testing. Importantly, the OpenAPI Specification lives as a local file, tracked in version control alongside the code, allowing it to survive changes in the AI tools used by the team.
Ultimately, the local-first approach ensures that the specification remains under the control of the project, rather than being restricted to a vendor's chat interface. In conclusion, a shared reference point, such as a local OpenAPI Specification, is vital to connecting the human's goals, the AI's design and implementation phases, and the verification process in modern software development.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
