Clear Instructions Beat Clever Prompts

For a while I treated model instructions like chat. Ask, revise, hope, and repeat.

That works when you are playing. It falls apart when the output has to drive a product step that a real user will see, or a review decision that can freeze money, or a brand kit someone will ship into social posts. The shift for me was simple. I stopped writing instructions as casual messages and started writing them as contracts.

The contract model

When I write a function, I care about four things: what goes in, what comes out, how the body bridges them, and what happens on failure. A production instruction set needs the same shape.

The input type is what the caller is allowed to pass. The output type is the exact shape I expect back, whether that is structured JSON, a short verdict, or a clear refusal. The body is the rules and examples. The failure handling is what should happen when the input is messy, incomplete, or trying to override the rules. If those four pieces are missing, I do not have a reliable instruction. I have a wish.

What the Google prompting course actually changed

The useful lesson was not a magic template. It was a reading habit. I read my own instruction as if I were a smart, literal intern who has never met me. Where would that person choose differently than I intended? That is the bug.

Then I read it as if I were trying to break it. Where can user text override the rules? Where can a new role sneak in? Those holes show up in production eventually, so it is better to close them on day one.

Real examples from the products I ship

In Vectra, a downtime brief has to stay useful for Ops and Maintenance. The instruction asks for a symptom, a likely cause, and a next action in plain language. It does not get to invent plant data that was never provided, and it does not get to sound confident when the signal is weak. Humans still decide. The brief only has to make the decision faster and clearer.

In PixelBrief, one prompt has to return a logo SVG pack, a palette, a type pairing, and social copy that an other system can drop into code. That means the output schema has to stay stable. If the schema drifts, the product breaks even when the words sound nice.

In Arb Guardian, spend review needs a short verdict and a reason a gaming team can act on. Freeze controls are serious. A soft paragraph that “maybe looks risky” is not enough. The review path has to return a clear shape every time.

The first versions of these instructions were short and failed often. The later versions fail much less on my own tests. The model did not magically get wiser. I got stricter about the contract.

Failure modes I keep rediscovering

Conflicting instructions are quiet killers. “Be concise” and “always give three examples” in the same block will fight each other. Vague role fluff can make the model sound confident while inventing details, so if the role does not help I delete it. Clever nested JSON breaks first, while flat and boring schemas survive longer. Long context buries rules, so I put constraints early, data next, and the actual question last.

Why this matters for the products I ship

I build systems that settle value, protect treasuries, or deliver assets people pay for. When money moves or a brand kit ships, fuzzy instructions are not a personality quirk. They are a risk.

Clear writing is part of the trust boundary around those systems. Treat the instruction like code, test it like code, and keep the failures visible. If you found this while searching for Sithu Nyein, product writing, or builders from Myanmar, that is the standard I am trying to hold.

Sithu Nyein, Yangon