Spec-Driven Development: Make Your Coding Agent Ship Mergeable Code

A coding agent will produce a confident diff for almost anything you ask it. The gap between that diff and something you would actually merge is not the model, it is the spec. Ask for "rate limiting on the API" and the agent quietly decides everything that matters: fixed window, which header identifies the caller, what the reset value means. Those were your decisions, and you gave them away in one sentence. This session walks GitHub's spec-kit end to end on a real codebase, not a toy. Init, constitution, specify, clarify, plan, tasks, implement. The interesting part is clarify: before any code exists, the tool interrogates the request and makes you answer the questions you would otherwise discover in review. Can a caller farm fresh quota by rotating X-Client-Id, or do you always key on the network address? You answer once, in the repo, and every future task inherits it. Then the half spec-kit does not give you: a gate. One dependency-free file that reads the changed files out of git, matches them against an allow list and a deny list, and refuses to typecheck or test a diff that went outside its allowed paths. A spec without a fence is a suggestion.