Prompt packs drift just like undocumented APIs. A reviewer skims the code diff, merges, and never notices that the system prompt quietly dropped a safety clause. Treat prompt changes as first-class diffs during pull request review. Use the same scrutiny, ownership, and expectation of tests.
Put Prompt Files Where Diffs Stay Obvious
Store prompts as versioned text beside code, not as hidden dashboard fields. Pull requests should show unified diffs for instructions, tool lists, and model pins. This continues the habit of how you version prompt packs the same way you version APIs.
Review Semantics, Not Just Wording
Ask which behavior changed: tool access, refusal rules, output schema, or retry policy. Even a synonym swap can alter agent behavior. Require the author to state intended behavior change in the PR body. Pin model IDs in config rather than chat, as you do when you pin model IDs in config, never in chat history logs.
Attach Eval Evidence to Prompt Diffs
Every meaningful prompt change needs fixtures or a short eval note. Show a before and after on the same cases. If the pack owns tool calling, ship fixtures with the skill the way you ship eval fixtures beside every new agent skill pack.
Separate Planner Text From Executor Belts
When a PR mixes planner instructions with executor tool allowlists, split the review into two parts. Planner tone changes are not the same risk class as new write tools. Keep those concerns apart the way you separate planner prompts from executor tool belts.
Watch Cost and Retry Side Effects
Prompt edits can increase tool-call volume without changing application code. Reviewers should check cost logs and retry budgets when instructions encourage more tool use. Track spend with the same seriousness as how you log tool-call costs per agent turn in plain metrics.
Reject Silent Dashboard Edits
If someone changed production prompts outside git, open a follow-up PR that captures the live text and freezes further out-of-band edits. Prompt review works only when the diff is the source of truth.
When in doubt, ask for a one-paragraph risk note: what the agent can newly do after merge, and what test proves it cannot do the dangerous path.
Add a checklist item on the PR template: prompt diff reviewed, behavior note present, fixtures linked. A template beats memory when review load spikes.
If two prompt files change in one PR, require a summary table of each file’s behavior delta. Bundled prompt PRs hide risk when reviewers only skim the largest diff hunk.
Block merges that only update a prompt screenshot in Notion. Screenshots are not diffs and cannot be audited cleanly.
FAQ
Why review prompts like code?
Because they change runtime behavior, tool access, and failure modes the same way code does.
What belongs in the PR description?
Intended behavior change, risk notes, and which fixtures cover the edit.
Do tiny wording tweaks need review?
Yes if they touch safety, tools, or output contracts. Pure typos can be lighter.
Where should prompts live?
In versioned files in the repo so diffs are visible and auditable.
What if marketing owns copy in the prompt?
Still route changes through PR review with eng cosign on tool and safety sections.
How do we catch dashboard drift?
Periodic export of live prompts into git, plus alerts on out-of-band edits.