Lifting "technically correct" to "a finished product" — turning agent failures into gates in the instructions

Introduction

The tuning you meet most often in practice is prompt tuning. But it is not the work of writing one clever instruction and getting it right in a single shot. Building two systems in parallel and letting agents implement them, I found that prompt tuning is really this — observing the failures an agent hits in real development, investigating the cause, and folding them into “pre-flight gates” and “review lenses” inside the instructions, so that “technically correct” is lifted toward “a finished product”: an evaluation loop.

The difference from fine-tuning, which touches the model’s weights, is in What is the difference between “prompt tuning” and “fine-tuning”?. Deploying agents as a “fleet” is in Building a streaming platform and a bank in parallel.

Tuning is not writing instructions, but fixing behavior

One instruction will always break in front of a situation you didn’t anticipate. What worked was picking up the moment it broke as observation data and folding it into a permanent gate.

[naive] try to write the perfect instruction in one shot ─▶ betrayed for sure by the unanticipated

[real] observe behavior ─▶ investigate cause ─▶ fold into a pre-flight gate / review lens ─▶ kill the same failure
           ▲                                                                          │
           └────────────────────── run it again on the next failure ─────────────────┘

Below are failures I actually folded in through this loop.

”Technically correct” was not “a finished product”

This is the learning that mattered most. I had the implementer (coder) build a customer-facing screen for the platform, and the reviewer review it. The technical layer was all green — but no one looked at the finished-ness from the user’s side.

When the built screen was reviewed
  technical layer : API wiring ✓  input-schema validation ✓  CSRF protection ✓  error handling ✓  → reviewer "no must-fix"
  product layer   : does it hold together as a finished product to the user? ✗
                    checked against the design's navigation / shared UI? ✗   → nobody looked

(CSRF = a forged request sent from a trap on another site, impersonating a logged-in user; the protection rejects it.)

The cause was a missing lens in the reviewer’s discipline (its prompt). At the time, the reviewer’s instructions were only general engineering discipline — type checking, security, avoiding over-implementation — with no product-side lens. So it saw technical correctness but skipped completeness. The fix was to add that lens to the discipline.

# lenses the reviewer's discipline lacked (added from a real-development failure)
(before) type checks, security, no over-implementation, no self-declared "done" … general engineering only
(added)  ✓ does it hold together as a "finished product" to the user?
         ✓ checked against the design's navigation / shared-UI spec?

“No errors” and “finished” are different. Show the review agent only technical correctness and completeness slips past. Write the lens you want seen explicitly into the instructions.

Stop the “mechanical consumption” that loses the goal

Another. I was mechanically consuming the bank system’s remaining tasks one after another with agents in parallel. Each was implemented correctly. But before I noticed, I had lost sight of “what am I even building this for.” This bank exists to add bank-account payment to the streaming platform — that higher purpose was being washed away by the momentum of consumption.

[mechanical consumption] task A ✓ → task B ✓ → task C ✓ … (each is correct on its own)
                                                └─ but loses sight of "what it's for" ×

[tie back to purpose] before starting, confirm "what is this a continuation of / does it match the intent?" → then act

The fix was to add this step to the pre-flight gate.

# CLAUDE.md pre-flight gate (excerpt)
1. Verify against the design doc (if a memo/memory conflicts with the design, the design wins)
2. What is this work a continuation of; does it match the person's latest intent? (has consumption lost the goal?)
3. Before a destructive operation: back up + fingerprint-match the target
→ Do not enter Write / Edit / execute before passing this

The faster the hands, the more dangerously fast you run off-target. Before consuming a task, tie it back to “why.”

Don’t make the review agent the last line of defense

Even letting an agent verify, things slip. When I ran a mechanical check at the finish over output that had supposedly passed the document agents (implementer, reviewer), 9 real bugs came out.

review by the document agents ─▶ passed as "no problem"
        │
insert a mechanical check (script) at the end ─▶ 9 real bugs detected
        └─ e.g. dropped characters when generating anchors from Japanese headings —
           the meaning is right, but a mechanically-determined part is off (hard to catch by eye)

The lesson is don’t make the LLM’s review the last line of defense. Reading meaning is the agent’s strength, but mechanically-determined correctness (link integrity, naming rules, format) should be bracketed by a deterministic check (a script). The human/agent eye and the mechanical check close different holes.

Not the perfect single shot, but folding failures into structure, forever

Letting agents implement in real development, what landed is that the core of prompt tuning is not the polish of the instruction. Make failures into observation data (an implementation that doesn’t look finished, mechanical consumption that loses the goal, a real bug that slipped through — don’t let any of them end as a one-time incident), write the lens you want seen explicitly (add “does it hold as a finished product,” not only “is it technically correct,” to the instructions), and don’t make the LLM the last line of defense (bracket mechanically-determined correctness with a deterministic check). With these three, “technically correct” edged closer to “a finished product.”

Deploying agents as a “fleet” is in Building a streaming platform and a bank in parallel; the enforcement layer that keeps dangerous operations from happening at all is in Building a mechanism that makes an AI coding assistant “not do it”.

The difference between “prompt tuning” and “fine-tuning” (what you are actually touching) is in What is the difference between “prompt tuning” and “fine-tuning”?.
Deploying agents as a “fleet” and assigning models by fit is in Building a streaming platform and a bank in parallel.
How a spanning fleet pulled another project’s decision from shared memory and contaminated ours is in Detecting and separating another project’s decision that had leaked in.
The mechanism that keeps dangerous operations from happening at all (a gate via hooks) is in Building a mechanism that makes an AI coding assistant “not do it” — from advice to enforcement, and the side-door left open in the gate itself.
The table of contents for this whole AI assistant operations series is in AI Assistant Operation Notes — Practical record for raising Copilot/Claude Code as a companion (series table of contents).