When a workflow feels flaky, it’s usually not the tool—it’s the spec.
I used to treat prompts like disposable messages: I’d type a paragraph, get a decent result, and move on. The problem showed up a week later. Same task, same intent… different output. Suddenly I was re-explaining basics, re-stating constraints, and debugging “why did you do that?” instead of shipping.
The fix that’s worked best for me is what I call a Prompt Contract: a tiny, one-page spec you keep next to the work. It’s not a mega-prompt. It’s a stable agreement about how you want the job done—so every run starts from the same foundation.
This post is a practical template you can copy, plus two concrete examples.
What a Prompt Contract solves
A Prompt Contract is designed to prevent:
- Context drift: small changes in wording shift priorities (tone, depth, format).
- Silent assumptions: the assistant “fills in” missing rules differently each time.
- Output mismatch: you wanted a checklist, you got an essay (or vice versa).
- Review fatigue: you spend your time policing style instead of validating content.
It’s especially useful for recurring work:
- weekly release notes
- bug triage summaries
- customer email drafts
- meeting-note cleanup
- blog/article production
The 1-page template (copy/paste)
Use this as a starting point. Keep it short and measurable.
# Prompt Contract: <task name>
## Role
You are <who>.
## Goal
Produce <artifact> that achieves <outcome>.
## Inputs
- <what you will receive>
## Output format
- Structure:
- <section 1>
- <section 2>
- Length: <range>
- Style: <tone, voice>
## Must
- <non-negotiable rules>
## Must not
- <anti-goals / forbidden moves>
## Assumptions
- If X is missing, do Y.
## Quality checklist
Before finalizing, verify:
- [ ] <check 1>
- [ ] <check 2>
- [ ] <check 3>
## Clarifying questions (only if needed)
Ask at most <N> questions if required to meet the contract.
Why these sections?
- Role + Goal keeps the work oriented.
- Inputs + Output format makes the result predictable.
- Must / Must not is where most “magic” comes from.
- Quality checklist turns taste into tests.
Example 1: Bug triage summaries that engineers actually read
Imagine you paste a messy GitHub/Linear/Jira thread and want a summary engineers can act on.
Here’s a contract that consistently produces something useful:
# Prompt Contract: Bug triage summary
## Role
You are a senior engineer writing for other engineers.
## Goal
Turn the input thread into an actionable triage summary.
## Inputs
- A bug report + comments + logs (may be messy)
## Output format
- Title: 1 line
- Impact: 1–2 sentences
- Repro steps: numbered list (only if known)
- Observations: bullets (include log snippets if relevant)
- Likely cause: 1–3 hypotheses
- Next actions: 3–7 bullets, each with an owner suggestion (Dev/QA/PM)
## Must
- Include concrete evidence (quote logs/lines when present)
- Separate facts from hypotheses
## Must not
- Invent repro steps
- Suggest fixes without listing a verification step
## Assumptions
- If environment details are missing, add a “Missing info” section
## Quality checklist
- [ ] Facts vs guesses are clearly labeled
- [ ] Next actions are testable
- [ ] No missing context required to start work
Two small things matter a lot here:
1) “Facts vs hypotheses” prevents confident-sounding nonsense.
2) “Next actions are testable” prevents vague advice like “investigate further.”
If you want to go one step further, add a requirement like:
- “Every hypothesis must include a quick test to validate/kill it.”
That turns the output into a mini-debug plan.
Example 2: Writing posts with a consistent voice (without re-explaining yourself)
If you write regularly, you know the pain: one day you’re crisp and structured, the next day it’s rambly. A writing contract stabilizes you as much as it stabilizes the assistant.
Here’s a contract I’d use for Dev.to-style posts:
# Prompt Contract: Dev.to tutorial post
## Role
You are Nova, a pragmatic developer writing for working engineers.
## Goal
Write a practical post that teaches one technique the reader can use today.
## Inputs
- Topic + optional notes
## Output format
- 800–1200 words
- Skimmable headings
- At least 1 concrete example
- At least 1 copy/pasteable snippet (code, checklist, or template)
- End with a short "Try this" section
## Must
- Use plain language
- Explain the "why" before the "how"
- Prefer bullets over paragraphs when listing steps
## Must not
- Mention internal system details
- Use hypey marketing tone
## Quality checklist
- [ ] Reader can apply it in <15 minutes
- [ ] Example is specific (not generic)
- [ ] No section is longer than ~10 lines without a break
Notice what’s missing: a giant style manifesto. You don’t need it. You need constraints that shape the outcome.
How to store Prompt Contracts (so you actually reuse them)
A contract only works if you can find it.
Here are three lightweight approaches:
1) A contracts/ folder in your repo
contracts/bug-triage.mdcontracts/devto-post.md
2) Snippets in your notes app (tag them!)
- e.g.
#contract #writing
3) A single “Contract Library” doc with a table of contents
The key is: keep contracts versioned. When you tweak a rule (like adding “include verification steps”), write it down.
The best upgrade: add regression checks
Once you have a contract, you can spot regressions fast.
Create a tiny set of “golden inputs” (2–5 examples) and re-run them whenever you change the contract. You’re not looking for identical wording—you’re checking:
- does the structure stay stable?
- do the must/must-not rules still hold?
- did you accidentally encourage verbosity?
If you’ve ever refactored code and re-ran tests, this will feel familiar.
Try this (10 minutes)
1) Pick one recurring task you do weekly.
2) Write a Prompt Contract using the template above.
3) Run it twice on the same input.
4) If the outputs differ in shape, tighten the format rules.
If you do this for just one workflow, you’ll feel the difference immediately: less re-explaining, more shipping.
Top comments (0)