Prompt Contracts: Treat System Prompts Like Production Code

Most teams treat system prompts like notes in a scratchpad: edited live, pasted between environments, and remembered by whoever last touched them. That works until a "tiny tweak" changes tone, breaks a tool call, or invents a new refusal style nobody reviewed. If the prompt shapes production behavior, it deserves the same discipline as the code around it.

A prompt is a product surface

Your system prompt is not documentation. It is a control plane: it sets role, boundaries, output shape, escalation rules, and the words users hear when the model is unsure. Changing it is a product change. Treating it casually is how teams get regressions they cannot explain and "fixes" that only exist in one engineer's local file.

Name the contract

Write the prompt as an explicit contract with sections that stay stable: identity, allowed tools, refusal policy, output format, and examples of good and bad behavior. When someone needs to change tone, they edit the tone section — not rewrite the whole thing from memory.

Version it in git, not in chat

Store prompts next to the feature that uses them. Commit messages should say what behavioral change you intended. Pull requests should show the diff the same way they show TypeScript. If a prompt only lives in a dashboard textbox or a Slack message, you have already lost the ability to roll back, compare environments, or answer "what shipped last Tuesday?"

• Keep prompts in the repo with the feature that depends on them
• Diff every change in review — wording changes are behavior changes
• Tag releases so you can map a user bug to the exact prompt version
• Never hot-edit production prompts without a recorded rollback path

Pair every change with evals

A prompt edit without tests is a deploy without tests. Maintain a small set of golden cases for the jobs the prompt owns: correct answers, safe refusals, structured output, and the failure modes you already burned on once. Run that set before merge. If the score drops, the wording is not "cleaner" — it is worse.

“If you cannot say which cases a prompt change improved, you are guessing with your users as the test suite.”

Separate policy from prose

Long prompts rot when policy, personality, and formatting all live in one paragraph. Split hard rules from soft style. Keep machine-checkable constraints — JSON schema, tool allowlists, max steps — in code where possible. Leave the prompt for judgment and language. That split makes reviews sharper and reduces the chance a stylistic rewrite quietly removes a safety rule.

Ship with an owner

Every production prompt needs a named owner and a change cadence. Owners watch eval scores, user escalations, and model upgrades that can change how the same text behaves. At Brutanix Studios, we treat prompt contracts as part of the shipping surface — versioned, reviewed, measured — because "we tweaked the prompt" is not an incident response plan.