Skip to main content

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:

  1. 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.
  2. You own the ontology. A word in a spec that isn’t in the final schema reveals a bug.
  3. 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.

Post topics: AI & ML•Software Development