QA loop pattern: Builder → QA Agent (Codex via /codex) → scoped fixes → Release note

[pitimon]

QA loop pattern: Builder → QA Agent (Codex via /codex) → scoped fixes → Release note

A repeatable quality-gate workflow that uses the /codex bridge (see #9) to make OpenAI Codex an independent QA Agent reviewing Claude Code's work before it ships. Proven end-to-end on a real web project.

Core principle: the work isn't done when the AI finishes building — it's done when it passes a quality gate.

Why a separate model for QA

Don't let the agent that built something grade its own work — it tends to overlook what it just made and explain why it's "probably fine". Use distinct roles, ideally distinct models:

• Builder — builds to the brief (here: Claude Code).
• QA — checks against a checklist, independent eyes (here: Codex via /codex).
• Release — summarizes what passed / was fixed / needs customer follow-up.

The 7 steps

1. Define "pass" first (Definition of Done). Before reviewing, write what must be true to ship (e.g. web: responsive, CTA, forms work, copy clear, a11y, perf, basic security). No DoD ⇒ QA is too broad to action.
2. Separate QA from Builder (see above).
3. Review across 7 gates: Goal · Accuracy · UX/Flow · Copy · Edge Case · Security/Privacy · Handoff.
4. Force Pass / Fix / Risk output. Don't ask "is it OK?" (you get polite praise). Demand a table — every Fix cites file / location / reason / how-to-fix; no vague praise while issues remain.
5. Builder fixes ONLY the Fix items. Scope to what failed, don't touch what passed, summarize each fix. Prevents fix-one-break-three.
6. Automate a final quality gate (formatter / lint / test / security script, or Claude Code hooks) so it's not only eyeballed.
7. Release note before shipping: what was asked · what's done · what QA found & fixed · what the customer should re-verify.

Run it with /codex (concrete prompts)

QA pass (read-only — Codex only reads):

/codex You are the QA Agent (separate from the builder) for <project> in this directory.
Definition of Done: <list>.
Run a STRICT pass across 7 gates: Goal, Accuracy, UX/Flow, Copy, Edge Case, Security/Privacy, Handoff.
Output ONE markdown table: Gate | Verdict (Pass/Fix/Risk) | Detail.
Every Fix or Risk MUST cite file + line/function + reason + a concrete how-to-fix. No vague praise.

Scoped Builder fix (write mode) — e.g. delegate back to Codex for code it owns:

/codex --write Fix ONLY these QA findings: <list>.
Do not touch passing code. Summarize each change (file:line + what). Do not commit or deploy.

Discipline that made it reliable (lessons)

• Verify the QA's citations — don't auto-trust. Spot-check the cited file:line before acting; a reviewer can hallucinate line numbers. Cheap grep closes a whole class of false findings.
• Scope fixes to the files you own. With two agents on one repo, don't clobber the other's concurrent work — leave its findings for it to fix, and record a handoff note.
• Check repo == live before deploying a fixed file; back up before overwrite; verify after (the new behavior works and you didn't break the old).
• Don't commit on the QA / other agent's behalf without the human's OK.
• One handoff log entry per unit of work so concurrent agents stay in sync.

What it caught (real run)

One QA pass over a live web demo returned 5 Fix + 2 Risk across the 7 gates — including a real secret-in-repo finding (an internal host address committed in a doc), a silently-stalled-stream edge case (a watchdog gap the happy-path code missed), and copy that overstated what the backend actually produced. Each was fixed scoped-to-owner, verified live, and committed — closing the gate. None of these would have surfaced from a "looks good to me" self-review.

---

Depends on the /codex bridge: #9.