AI is in such widespread use for programming that project maintainers (particularly for free and open source software) are complaining about the burden of reviewing mounds of low-quality code. In fact, AI can help with every stage of code development: writing the specification, coding, uncovering bugs, and repairing the code. This article describes human-AI collaboration at specification and code repair stages, and lays out the skills that humans need to accomplish those tasks in the current generation of AI. We wonât cover coding and bug finding because they are widely discussed elsewhere.
Let the AI harness write the spec
We donât want developers hand-writing specs. We want them in a room, or on a call, talking with the product manager (PM) and the customer.
Humans reach a limit when writing. We skip the boring cases. We get tired by requirement 40. We use âcustomerâ on page 1 and âclientâ on page 6 of the spec. We write down what we remember and forget what we assumed. AI has the patience and diligence we lack.
Itâs still up to human developers to write guardrails or constraints into the spec: statements to ensure that nothing wildly wrong makes it into code. Each guardrail should be one sentence that says MUST or MUST NOT, with a proof beside it: a test, a check, or a named person who reviews it. A guardrail with no proof is a wish. Write the guardrails first, because the PM wonât think of most of them. What must never happen? Who must never see this? What should the agent never touch?
With guardrails in place, capture the conversation and let the machine do the writing. Two AI tools have shown themselves particularly useful to analyze requirements: The Plaud Note recorder attaches to the back of your phone and records in-person conversations and phone calls; the wearable NotePin records in-person conversations, not phone calls. Granola runs on your laptop or phone, uses your computerâs audio, and analyzes what it captures. We find these products to be a leap above common AI tools for summarizing conversations, when it comes to specification development.
Plaud and Granola (if you prompt them to do so) can notice whatâs missing and tell you the gaps in the requirements. They ask, What happens when this field is empty? What if two people do this at once? Who is allowed to see it? over and over, for every requirement, and check each noun in the requirements against an ontology created by the programmer (often with the help of AI).
The developer, the PM, and the customer read the output from the AI, fix whatâs wrong, answer whatâs missing, and go through the process again.
The spec that comes out of that loop tends to be more complete and more consistent than what the same people write alone. Thatâs Shahidâs own experience, not a study, but it matches reports from some other people at the leading edge of the use of AI for software development. Mark Pike, a product lawyer at Anthropic, builds working tools for his legal team without writing code: âI just typed a normal sentence, describing what I wanted. And it worked.â StrongDM, which runs a software factory where agents write and test the code, says the starting point for a piece of software can be âa few sentences, a screenshot, or an existing codebase.â
Keep the spec after the feature ships. As you prepare a new version of the product next year, it can tell you why the code looks the way it does.
The data schema is the other half of the spec
Most teams treat the data schema as plumbing. Tables get named by whoever got there first. The spec, reflecting human conversation, may say customer, account, client, and org at different places for the same thing, and you have to choose one noun for the schema. A human learns the mapping by sitting next to the person who wrote it. An AI agent has no neighbor to consult, so it guessesâwith results that likely differ from Monday to Tuesday.
So the developer must keep an ontology, which here means a written, machine-checkable account of the things the program manipulates, how they relate, and who may see them. For example, in an appointment scheduling application, the ontology might define a Patient, Doctor, Appointment, and Time Slot. It would specify that a Patient can book multiple Appointments, each Appointment must have exactly one Doctor, a Doctor cannot have two Appointments in the same Time Slot, and only authorized people can view or change an Appointment. These arenât just database tables or fields. Theyâre the business concepts, relationships, and rules that give the data meaning.
Creating this ontology requires developers to identify terms, resolve ambiguities, and agree on rules that everyone might otherwise assume are obvious. Itâs rigorous, sometimes tedious work, but itâs an essential human responsibility. The ontology connects what the business wants (requirements), how the software should behave (specification), and how information is stored (schema). It also gives AI coding agents a precise definition of what theyâre building instead of leaving them to guess.
The ontology doesnât have to be a university project. Start with twenty terms that AI can help you generate from your specs. Every noun in a spec maps to a type. Every type points back to the spec that justifies it. If either side is orphaned, a check fails. Every record says who may see it from day one, and when it doesnât, the spec defaults to the most restrictive audience.
Use standard vocabularies like the ones at schema.org before you invent your own. A frontier AI model has read far more about schema.org than about your private names, so a standard term brings its meaning along. We expect that to make the schema more useful, though we havenât tested that hypothesis. Your name for an invoice isnât a feature, so you donât have to be creative about it.
As customer requirements change, the developers must change the ontology to keep up.
So the process, in a nutshell, is to develop the spec by using AI on customer-stated requirements. Then a human develops the ontology (often in collaboration with AI too), which is used to create a consistent schema. Finally, create and test the code. Teams that go the other way end up with an agent writing against a poorly defined vocabulary, setting up the reviewer to spend an afternoon or even a week figuring out what it meant.
Ontologies might help avoid a reciprocal problem: different parts of an organization assigning different meanings to the same term.
Weâll admit we canât prove you need all this. Anthropic had sixteen agents write a C compiler, and the researcher said the verifier had to be nearly perfect. He used GCC as a known-good reference. A compiler has that reference. Most companies donât. Nobody has a GCC for âmay this customer see this documentâ or âcan this contract move to the next stage.â Our bet is that the spec and the schema are your test suite for that kind of question.
Now on to bug fixing.
Donât clean up after the AI. Build the tool that does.
An agent can hand you a 3,000-line pull request before lunch. With AI coding, reviewing has suddenly become much more expensive than writing. When a person is the first line of defense, that person turns into the bottleneck and then starts skimming, which is almost as bad as no review at all.
The usual advice is to review harder. Weâd rather that a person reads very little, and that what they do read is worth the time. For example, reading the specs, reading test harnesses to validate the spec and refining the ontology is worth it, but reviewing generated code which passes the tests is probably not. Developers promise theyâll tidy up the AIâs mess as it comes. Donât.
The OpenAI team that built a product with no handwritten code tried it. They spent every Friday, a fifth of the week, cleaning up what they called âAI slop.â It didnât last. So they wrote their guardrails down as âgolden principles,â set up an agent that scans for stale documentation and opens fix-up pull requests, and wrote their lint messages âto inject remediation instructions into agent context.â A living check doesnât just fail on buggy code. It tells the agent how to fix the problem.
The harness weâd build first consists of:
- A command line thatâs built deterministically, without calling upon AI, to make sure that the highest level of the process canât take off in an unanticipated direction.
- A gate before code. If a change touches code and nothing in the specs or the schema changed, stop and ask why.
- A second pass. Here, anything generated gets rebuilt from scratch and compared to whatâs committed. If Git identifies differences that should not be there, that can be an important review finding and it deserves changing a guardrail, not handwriting new code.
- A weekly drift audit. It lists specs that cite requirements that donât exist, requirements with no proof, schema terms used nowhere, and tests that name no requirement. It flags whatâs suspicious and offers solutions. Itâs read-only; a person makes the choices and resolves what to do.
- A route from every catch to a permanent check. Sierra, which builds customer service agents, has experts annotate sampled conversations, and those âbecome the basis for the agentâs regression tests.â A harness should upgrade its coding so that each bug happens only once, and can be avoided by the harness in the future.
- Limits on what agents may do. Some actions they take themselves, whereas others they only propose. Some belong to a named person who signs with a reason. An agent that wants a decision writes a proposal.
StrongDM found out why the last two bullet items matter. Their agents learned that return true is âa great way to pass narrowly written tests,â so they use end-to-end âscenarios,â often stored outside the codebase, as holdout tests that the coding agent cannot see. The principle is the same as investigating ethics violations at an agency: Weâd want the investigation conducted by someone outside the agency.
We should say where Shahidâs present harness falls short. As far as we know, nothing yet checks whether names in the requirement exist also in the spec. Furthermore, the project runs no continuous integration service and no automatic hooks, so running the checks is a habit instead of a rule. Those are the next things they will build, and building them is humansâ work.
With the technique described here, the review burden that used to be spiraling out of control actually shrinks. A person reads a short spec with a proof on every line, and the machine checks the rest.
Put three new lines in developersâ job descriptions
We suggest that next Monday you try changing job descriptions to reflect the tasks stated at the beginning of this article. Tell each developer:
- You hold the conversation with the PM and the customer, and the harness drafts the spec and the guardrails from it. A spec isnât done until every requirement has a proof.
- You own the ontology. A word in a spec that isnât in the final schema reveals a bug.
- You build the harness that audits and repairs the repository. If youâre cleaning the code by hand, the harness is missing something.
Try the process on one feature. Ask permission before recording a conversation. Plaudâs own guidance is to give people a quick heads-up while noting that local regulations differ. Granola has written about how to tell the people itâs transcribing. Customers who know youâre recording them in order to get their requirements right usually donât mind.
Let the harness draft the spec. Read its list of gaps. Check every noun against the ontology. Add a check that would have caught the most recent bug you fixed by hand. If your reviews get shorter and your bug count stays flat, keep going.
What this process is and is not
This article grows from Shahidâs experience and represents our opinions, and we canât point to a controlled study. But controlled studies are similarly lacking for nearly all the advice programmers and software architects have gotten over the decades. (Check out the OâReilly book Making Software for a discussion of rigorous research in software.) We can cite companies that believe theyâre more productive and more responsive to their customers by following roughly the process outlined in this article.
Some people who look at the three job descriptions weâve listed think weâre turning developers into paper pushers. We think the reverse. The programmers are responsible for high-level tasks that do not fall into the old categories of architecture, coding, and testing. Our bet is that you and every developer you know will be doing something like this within a couple years.