Prompt packs drift like folklore. Someone pastes a better system message into prod on a Friday. Nobody can say which version an eval used last week. Version prompt packs the same way you version APIs, with ids people can cite in incidents.
Treat prompts as deployable artifacts with versions, changelogs, and rollback. Agents inherit whatever you ship. If the pack is anonymous, every incident becomes archaeology across chat logs and screenshots.
Give every pack a semver and a hash
Store prompts in git or an artifact store with a version string and content hash. Runtime loads by version, not by latest file on disk. Pin versions in environment config the way you pin library versions so staging and prod cannot silently diverge.
When tools change, bump the pack that documents their use. Schema and prompt move together. See bound tool schemas before agents call them for the contract side of that pairing and keep them in the same release notes.
Ship packs through the same review gate as code
Require a pull request for prompt edits. Reviewers check safety, tone, and tool policy, not just grammar. Block direct edits on production paths. Prompt injection defenses belong in the pack notes when assistants touch untrusted content, as in prompt injection in app assistants.
Attach eval snippets to the PR. A pack without a smoke eval is a guess with better formatting. Fail the merge if the smoke path regresses, even when the prose looks nicer.
Log the pack version on every trace
Every agent run should emit pack id, version, and hash beside tool events. When quality drops, you can bisect. Structured traces make that cheap, which is the point of structured agent traces for cheaper debug instead of guessing from user complaints alone.
Never log raw secrets that prompts reference. Fetch secrets through tools, keep them out of context packs, following keep agent secrets out of live session context packs. Versioning is useless if the pack itself leaks credentials.
Rollback without redeploying folklore
Keep the previous two pack versions loadable. A bad ship should flip a config flag, not require hunting Slack for yesterday’s paste. Document breaking changes the way API owners document field removals, with dates and owners.
Cache-aware serving can hide which text actually ran. Watch prompt caching cost traps so a version bump is not silently ignored by a stale cache key that still serves old instructions.
Retire packs on a calendar
Mark deprecated packs with a removal date. Agents pinned to ghosts create surprise behavior when someone finally deletes a file. Inventory quarterly. Delete only after traces show zero traffic for a full billing cycle.
Versioning feels heavy until the first silent prompt edit costs a week. Then it feels obvious, and the changelog becomes the cheapest insurance you own.
FAQ
What is a prompt pack?
The versioned set of system and tool instructions an agent loads for a product surface.
Why hash the content?
Hashes prove which text ran even if labels collide or caches lie about freshness.
Do tiny wording tweaks need a version bump?
Yes. Small wording changes can alter tool use. Bump patch versions for copy, minor for tool policy shifts.
Where should versions be pinned?
In environment or feature config, not inside free-form chat history that nobody audits.
What belongs in the PR?
Diff, risk notes, and a smoke eval or fixture that failed before and passes after.
How do I roll back?
Point config at the prior version and confirm traces show the old hash within minutes.