Keep Prompts as Code and Product Configuration
A good prompt is useless if it lives in someone's head and gets edited by eye. A production prompt must have an owner, a version, a compatible model, a dataset, a release gate, and a rollback. Editing text in a dashboard with no link to code kills reproducibility.
In practice this is an ordinary repository structure: instructions, schemas, examples, and evals next to the code.
prompts/
support/
system.ts
output-schema.ts
examples.yaml
evals/
faq.jsonl
refunds.jsonl
escalation.jsonl
export const SUPPORT_PROMPT = {
id: "support-v17",
checkedAt: "2026-07-31",
compatibleModels: ["pinned-provider-snapshot"],
retrievalContract: "support-kb-v8",
toolRegistry: "support-tools-v4",
evalBaseline: "support-suite-2026-07-29"
};Two properties of this layout are worth keeping in mind deliberately.
- Cache-friendly. Stable instructions, examples, and tool definitions go into a repeatable prefix, and variable data later. That is how prompt caching works.
- Rollback-friendly. The prompt version, the model snapshot, and the retrieval version are written to the trace, and the old combination can be restored whole.
And one fresh detail that is easy to miss.
A current OpenAI detail. As of the review date the documentation states: reusable prompt objects began being deprecated on June 3, 2026, and the v1/prompts endpoint is scheduled for shutdown on November 30, 2026. For new development OpenAI recommends versioned, code-managed helpers. Before adopting anything, recheck the timeline on the deprecations page.