A shared prompt update should not automatically change every client's live behavior. Client-level version pins let an agency test and release common policy while preserving approved local configurations.
Separate reusable guidance from business facts, action mappings, and permissions. Record the complete behavior package for each client: shared policy version, local configuration, action schema, knowledge version, and routing state where relevant.
Make inheritance explicit
Define what clients inherit and what they may override. Avoid permanent untracked text copies that gradually diverge. Each exception needs a reason, owner, and review path so the agency can understand why two clients behave differently.
A version pin should select an immutable approved package. Editing a shared document in place while keeping the same version label defeats the ability to reproduce or roll back a call's behavior.
Work through a fictional confirmation-policy release
An agency changes shared guidance so the agent confirms a booking only after a verified remote result. One client books directly; another collects staff-reviewed requests. The new policy is tested against both configurations before either moves to the release.
A small initial cohort receives the update while other clients remain pinned. If a regression appears, the agency restores the previous package for affected clients without changing everyone else.
| Versioning case | Required evidence |
|---|---|
| Shared policy changes | New immutable version |
| Client remains pinned | Approved existing behavior retained |
| Local exception | Reason and owner documented |
| Release cohort | Affected scenarios tested |
| Rollback | Complete previous package restored |
Keep call traces connected to releases
Record the active package with each call or action. Staff investigating an incident need to know which rules were in use, not merely what the current editor displays.
Version pins add coordination and can leave clients on older behavior longer. Automatic global updates are simpler but make regressions broader and harder to attribute. Choose release policy according to consequence, configuration variation, and support capacity.
Review old pins periodically and plan migration deliberately. See cross-client prompt versioning for a concrete client-configuration example.
Questions about shared prompt versions
Should every client have a permanent fork?
Not by default. Share stable policy and represent justified differences as explicit configuration or reviewed exceptions.
Can a prompt rollback fix a mapping change?
Only if the restored package includes the relevant action and configuration state. Text alone may not determine behavior.
What should the release record contain?
Affected clients, package versions, approved scenarios, validation evidence, known limits, rollback owner, and any required staff action.