AI Coding Governance with Spec-Driven Prompts

Governance for AI-assisted coding using spec-driven prompts: what the prompt must contain, what boundaries the AI must respect, and the audit trail that makes "AI wrote this" a checkable claim.

Published on 2026-03-10 · Updated 2026-05-06 · 8 min read · Author: Spec Coding Editorial Team · Review policy: Editorial Policy

Field note: governance starts before the model runs

The expensive mistake is waiting until PR review to ask whether AI should have touched a workflow. For billing, permissions, migrations, and API contracts, the governance decision belongs in the prompt packet before generation starts.

AI work classification:
Risk: high
Reason: touches refund state and webhook retry behavior
Allowed output: implementation diff plus tests
Required evidence: replay test, duplicate prevention test, rollback note
Human owner: billing tech lead

Governance starts where the prompt starts

Most AI-coding governance debates get stuck at the wrong layer. People argue whether the model can be trusted. That is the second question. The first is whether the team can state, in writing, what the model was asked to do. If we cannot produce that artifact, nothing downstream is governance. It is vibes with a merge button. The spec the humans argue about has to be the same spec the model reads. Anything else is a game of telephone where the audit trail ends at one engineer's monitor.

The three-layer prompt I actually ship

Every AI-assisted change goes through a three-layer prompt. Each layer is a separate artifact with its own owner.

• System role. Who the assistant is, the language and framework conventions, the repository map, commit format. Rarely changes.
• Feature spec. The active story: acceptance criteria in Given/When/Then, the data model touched, APIs exposed. The product owner signs this.
• Boundaries. The explicit "do not" list: files outside src/api/orders/ off-limits, no new dependencies, schema frozen, run the test suite before proposing a diff.

If any layer is missing, the output is not reviewable. It is a draft that somebody owes me a spec for.

Acceptance criteria belong in the prompt

The trick that turned AI coding from a novelty into something I trust is pasting acceptance criteria straight into the prompt. Not a paraphrase. The exact Given/When/Then the product owner approved. The model writes tests against those criteria before implementation, and the review question changes from "is this code good" to "do the tests match the spec the business signed."

Feature: Add POST /orders/{id}/refund endpoint
  Given an authenticated admin user and an order in state "paid"
  When they POST /orders/{id}/refund with a valid amount
  Then the order transitions to state "refunded"
  And a refund event is emitted to the billing queue
  And the response is 200 with the refunded order payload

  Given an order in state "shipped"
  When an admin attempts a refund
  Then the API returns 409 with code "order_not_refundable"
  And no billing event is emitted

When that block is inside the prompt, spec violations stop being a review taste question. They become a diff. The test file either expresses those cases or it does not.

A real prompt template for a new endpoint

Here is the shape I use for adding an API endpoint. It lives at prompts/feature.new-endpoint.v4.md and the PR links the exact version.

SYSTEM
You are a senior engineer on the Orders service.
Stack: TypeScript, Fastify, Drizzle, Vitest.
Repo map: see prompts/context/repo-map.md.
Commit style: Conventional Commits.

FEATURE SPEC
{{ inject: specs/orders/refund-endpoint.md@sha=ab12cd }}

BOUNDARIES
- Only modify files under src/api/orders/** and tests/api/orders/**.
- Do not add dependencies. Use existing utilities in src/lib/.
- Do not change database schema or migrations.
- Write Vitest cases for every Given/When/Then in the spec before implementation.
- Run `pnpm test --filter orders` and paste the output in your response.
- If the spec is ambiguous, stop and ask. Do not guess.

The inject directive is the point. The spec is content-addressed. If the spec changes, the prompt hash changes, and the PR shows which spec version the model saw.

Prompts are code

Teams that treat prompts as tribal knowledge in a Notion page end up in chaos. I put prompts in the repo next to the code they produce. They get PRs, diffs, and approval from the people who sign the feature spec. When someone loosens a boundary, the edit has an author, a date, and a reviewer. That prevents prompt drift: the unattributed edits that turn a disciplined prompt into a contradictory mess.

The audit trail has to be a chain, not a claim

"AI wrote this" is meaningless unless a reviewer can reconstruct what the AI was told. Every AI-assisted PR carries four links: the prompt version, the spec version, the conversation log, and the test run the model reported. If any link is missing, the PR goes back. A year later, when an incident traces to this endpoint, somebody can open the PR and see exactly which spec was in effect.

The review checklist I use on AI-authored PRs

• Did the tests cover every Given/When/Then, or did the model skip one?
• Did the diff stay inside the boundary list, or modify files it was told to leave alone?
• Did it add any dependency, env var, or configuration the prompt did not authorize?
• Is anything in the diff a plausible-looking solution to a problem the spec did not describe?
• If the model asked a clarifying question, is the answer captured in the conversation log?

The last one matters more than it sounds. If a human answered in chat without updating the spec, the spec is now lying about what was approved.

Failure modes that actually bite

• Prompt drift. Engineers tweak the prompt in-flight and never merge the tweaks back. The canonical prompt and the working prompt diverge.
• Spec drift. Product updates the spec, but the prompt injects the old version. The model produces correct code for a spec nobody has agreed to.
• Review fatigue. AI PRs arrive faster than humans can read. Reviewers rubber-stamp. A rubber-stamped AI PR is worse than a rubber-stamped human PR because the reviewer is the only governance left.

Prompt drift is solved by version control. Spec drift is solved by injecting specs by content hash so a changed spec forces a visible prompt bump. Review fatigue is harder. I cap AI-authored PR throughput per reviewer per day. More throughput means more reviewers, or ship less.

The metrics I watch and the one-hour rule

Four numbers tell me if the flow is healthy: the rate of AI-authored PRs merged without human code changes, the rework rate after review, the rate of spec violations escaped to production versus caught in review, and median time from spec approval to merge.

And one rule I hand every engineer: if the AI cannot produce a passing implementation within an hour against the spec, stop. The problem is almost always the spec. Criteria contradict, the boundary excludes a needed file, or a case is missing. The hour is not a performance budget for the model. It is a smoke detector for the spec. Fix the spec, bump its hash, regenerate the prompt. Engineers who push past the hour by bargaining with the model have already lost governance.

What I want you to take away

AI-assisted coding is governable only if you govern the input. Write the spec the way you want the code. Put it in the prompt with a content hash. Write boundaries as explicit prohibitions. Version the prompt. Link every PR to the exact spec, prompt, and conversation. Review against the spec. If you cannot reconstruct what the AI was told, you do not have AI governance. You just have AI.

AI Review Packet to Copy

Use this before an AI-generated diff reaches code review. It turns the prompt, the allowed scope, and the required proof into one reviewable artifact.

AI coding review packet: AI Coding Governance with Spec-Driven Prompts

Decision to make:
- Governance for AI-assisted coding using spec-driven prompts: what the prompt must contain, what boundaries the AI must respect, and the audit trail that makes 'AI wrote this' a checkable claim.

Owner check:
- Product owner:
- Engineering owner:
- QA or operations reviewer:

Scope boundary:
- In scope:
- Out of scope:
- Assumption that still needs approval:

Acceptance evidence:
- Test or fixture:
- Log, metric, or screenshot:
- Manual review step:

AI boundary: generated changes must stay inside the written scope and attach evidence for each acceptance criterion.

Reviewer prompt:
- What would still be ambiguous to someone who missed the planning meeting?
- What evidence would make this safe enough to ship?

Second-pass reviewer note: governance should reduce review fog

I tightened this page around concrete gates. Governance fails when it becomes a policy document nobody uses. It works when a reviewer can tell whether a generated diff is allowed before reading every line.

Gate check:
- Is the risk class named?
- Is the human owner named?
- Are allowed files or modules named?
- Is required evidence named before generation?
- Is there an exception path for urgent fixes?

Editorial Review Note

Reviewed Apr 28, 2026. This update added a reusable artifact, checked the article against the related topic hub, and tightened the next-step links so the page works as a practical reference rather than a standalone essay.