I Audited 27 of My Own AI Prompts and Found 22 Were Broken — A Four-Part Prompt Framework

A developer who has been building AI agents and automation workflows for some time did something uncomfortable last month: he opened his prompts.md file — a year's worth of accumulated prompts — and read through all 27 of them like a stranger seeing them for the first time. The result: 22 failed the most basic test imaginable:

Give someone else this prompt. Can they get the same output you did?

They couldn't. That number was bad enough that he wrote down the failure patterns. And what was surprising was how boring they were — repetitive, predictable, the same every time.

Three Ways Prompts Fail

The author grouped every broken case into three categories. Behind each one is the same underlying problem: you thought you were being clear, but the model didn't agree.

Failure mode one: describing a feeling instead of a task.

You are an expert developer. Review this code and tell me if it's good.

There's no standard here. "Expert" isn't a standard. "Good" isn't a standard. The model has to invent the ruler you have in your head — and the ruler it invents on Tuesday is probably different from the one on Wednesday.

Failure mode two: letting the model fill in the blanks.

Summarise this customer feedback.

When the input is thin, the model doesn't stop. It generates plausible-sounding filler — and because it reads smoothly, you publish it without a second thought. This is the most insidious trap: the errors are dressed up nicely.

Failure mode three: never defining what "done" looks like.

Write tests for this function.

You get six test cases, but what you actually wanted was edge cases. You never said which ones mattered, so it guessed.

The Real Fix Is a "Contract," Not Better Sentences

Most people optimize prompts by endlessly polishing the wording — finding a prettier way to say the same thing. But the author's position is blunt: the problem isn't sentence quality; it's the absence of an explicit contract.

He rewrote all 27 prompts using four explicit sections, then tested them with the same model on the same day:

Section	What it answers	Bad version	Good version
Role	Who it is, and what standards bind it	"You are an expert"	"You are a staff engineer reviewing a PR who rejects speculative abstraction"
Context	Facts it cannot invent	(missing)	"Stack: Next.js 15 + Supabase. Mark unknowns as TODO"
Constraints	Hard rules and forbidden actions	(missing)	"Only flag real defects. Never invent APIs not in the diff. Max 150 words"
Output schema	The exact shape of the answer	"Tell me if it's good"	An explicit JSON structure

Here's the fully rewritten code review prompt, showing all four parts working together:

ROLE: You are a staff engineer reviewing a pull request. You optimise for
correctness and maintainability and reject speculative abstraction.

CONTEXT: Language: TypeScript. Framework: Next.js 15. The diff is below.
Tests: passing.

CONSTRAINTS: Only comment on real defects (bugs, race conditions, missing
error handling, security). Do not restyle. Never invent APIs that are not
in the diff. If the diff is too small to judge, say so.

OUTPUT: Return only JSON:
{"blocking":[{"file":string,"line":string,"issue":string,"fix":string}],
 "nits":string[],"verdict":"approve"|"request_changes"}

This structure works because it compresses the space the model needs to "guess": the role sets the evaluation standard, the context provides facts it cannot invent, the constraints draw hard boundaries, and the output schema locks down the shape of the result.

What Actually Changed After the Rewrite

The author identified two quantifiable improvements — the most persuasive part of the whole piece.

First, output stopped drifting. Running the same prompt five times now returns a perfectly consistent JSON structure every time. That means he can pipe results directly into n8n nodes without any repair steps in between. For anyone building automation pipelines, this is enormous — structural consistency is what makes output machine-consumable.

Second, the model stopped guessing. The TODO escape hatch turned what used to be "plausible filler" into null — and null is a value a program can actually handle.

The second point is the insight that rarely gets talked about. The author names what's really happening with prompt drift:

Prompt drift isn't the model going rogue. It's the model trying to be helpful in the absence of instructions — which is exactly what you asked it to do.

In other words, hallucinations and drift are often not model defects. They're the direct result of your prompt giving the model too much discretionary space.

---

The mention of piping results "into n8n nodes" touches on an increasingly important concept in AI workflow automation: Structured Output. Large language models generate free-form text by default, but when an LLM operates as a node in an automated pipeline, downstream programs need to consume data in a defined format — JSON, XML, etc. — not natural language. There are two main implementation paths today: prompt-level constraints (the approach in this article), where you explicitly instruct the model to output a specific format; and native structured output APIs from platforms like OpenAI and Anthropic (such as OpenAI's response_format parameter), which enforce JSON schema compliance at the model level. Prompt-level constraints are low-cost and portable, but can still drift under extreme inputs. API-level constraints are more reliable but tie you to a specific platform. Using both together — prompts define semantics, APIs guarantee format — is the current production best practice.

---

An Anti-Hallucination Code Block

If you take only one thing from the entire article, the author recommends taking this. Paste it at the end of any prompt where getting the wrong answer costs you money:

If the answer is not supported by the CONTEXT above, respond exactly:
{"error":"insufficient_context","missing":[<what you need>]}
Never fill gaps with plausible-sounding facts.

Just four lines. The author says this eliminated the single most expensive failure mode in his own agent stack. The logic is simple: giving the model a legitimate exit to "admit it doesn't know" is far more reliable than hoping it becomes accurate through willpower. A structured error value is something downstream code can handle. A confident-sounding fabrication is not.

Why This Is Worth Writing Down

The author ended up not just rewriting all 27 prompts, but adding 19 more that he actually uses repeatedly — code review, refactor planning, cold-start emails, sales lead scoring, incident post-mortems, market sizing. He pinned the four-part template at the top of the file for one honest reason: he always forgets.

For developers and product teams building AI workflows, the takeaway is this: the focus of prompt engineering is shifting from writing beautifully to writing deterministically. When prompts enter production and their outputs are consumed by downstream programs, determinism matters far more than creativity. The four-part contract, explicit output schemas, and anti-hallucination fallbacks are all engineering techniques for turning an LLM from a "chat toy" into a reliable production component.

The author is candid that the framework itself is the whole point — and it's free. His advice is concrete: pick your most frustrating prompt right now, rewrite it with this structure, and you'll feel the difference on the first run.

---

The "contract" thinking described here traces directly back to Design by Contract, a software engineering concept introduced by Bertrand Meyer in the 1980s. The core idea: callers and callees should use preconditions, postconditions, and invariants to explicitly define their respective responsibilities. Mapped onto prompt engineering: role and context correspond to "preconditions" (what the model must know before entering the task), constraints correspond to "invariants" (rules that must never be violated), and output schema corresponds to "postconditions" (the shape the result must satisfy when the task is complete). Traditional natural-language prompts are fragile precisely because they leave all three layers implicit — human readers can infer from common sense, but models quietly inject their own assumptions during that inference. The value of an explicit contract isn't just reducing ambiguity; it's making "is this prompt correct?" an independently verifiable question, rather than one that depends on subjectively judging the output.

The problem targeted by that anti-hallucination block is known in AI safety as hallucination — more precisely, a "faithfulness failure": the model generates content that is linguistically fluent and confident but factually unsupported by the provided context. The leading explanation is that language models are trained to maximize next-token prediction probability, not factual accuracy; when context doesn't sufficiently constrain the output, the model "completes" the answer from statistical associations learned during pretraining, producing content that sounds plausible but isn't grounded in reality. The anti-hallucination code block is essentially an explicit modeling of a refusal option: it gives the model a clearly rewarded path for "admitting ignorance," making "I don't know" a legitimate, low-cost option in the model's generation strategy — suppressing the incentive to guess and confabulate. This mirrors the training signals in RLHF (Reinforcement Learning from Human Feedback) that encourage models to express uncertainty, just implemented at inference time through the prompt layer.