Prompt and Context Engineering as a Team Practice: Versioned Prompts That Survive Model Changes
Prompt engineering stops being a personal knack the day a customer-facing feature depends on it. From that day the prompt is a production asset, and most teams still keep it the way they keep a favorite browser tab: in one person's notes, pasted into the code, and half-remembered in a vendor dashboard. This lesson shows you how to turn prompt engineering and its bigger sibling, context engineering, into a team practice: one home, one owner, a version history, a pinned model, and a test run behind every change. You will finish with a Prompt Record and Change Log you can fill in this week, and with a clear answer to the question every model retirement notice forces on you: what happens to our assistant when the model changes?
The Problem: Prompt Engineering Nobody Owns, and What It Costs
Picture this, and remember it is an illustration: the equipment distributor we have followed since Lesson 6. At 8:40 on a Monday the service desk lead forwards you three screenshots from the warranty assistant. In the first, it gives a 24-month term for a pump that carries 36 months in that region. In the second, it answers a question about an injured operator as if it were a routine parts claim. In the third, it mentions a product line the company does not sell in that country. Her note says: "This started over the weekend. What did you change?"
You ask the obvious question. What changed? The prompt, the model, or the data?
Nobody can say. The engineer finds a prompt pasted into the code. The product owner has a newer one in her notes, with three extra paragraphs she added after a complaint in the spring. There is a third in the vendor's dashboard, and nobody is sure whether the application reads from there or from the code. The person who wrote the original is on leave. And sitting in the shared inbox is an email from the vendor: the model version you run on is being retired.
No breach, no headline. Just a team that cannot answer a three-part question about its own product, and will now spend days on archaeology instead of fixing anything.
What happened to OpenAI's hosted prompt objects, and why should you care?
Here is a real event from 2026. For a period, OpenAI offered reusable prompt objects: prompts stored, versioned and managed on its platform rather than in your own code. It was convenient, and plenty of teams took the convenience.
On 3 June 2026, OpenAI's API deprecations page listed "/v1/prompts and reusable prompt objects" as deprecated and set 30 November 2026 as the shutdown date. The recommended replacement is one line: "Move prompt content into your application code." OpenAI's prompt engineering guide (as fetched in November 2026) says it more directly: "Store production prompts in your application code instead of creating reusable prompt objects", so that you gain typed inputs, code review, tests and normal deployment. Its migration guide adds: "Move versioning to your repo using git commits, PR review, and tests or evals."
Teams whose only copy of a production prompt lived in those hosted objects had a forced migration with a hard date, whether or not it was on the backlog. The migration guide itself tells readers to check the deprecations page for the current timeline, so confirm the status there before you plan anything around it.
This is not a criticism of a vendor; the change is arguably toward better practice. The point is narrower and more useful: where a prompt lives is a design decision with a shelf life. If the only copy of your production prompt sits in one vendor's console, the vendor's roadmap is your roadmap. The portfolio-wide version of that problem, across every model and provider you depend on, is the subject of the capstone lesson on avoiding model lock-in and staying adaptive as models change. Here we fix it for one prompt.
Do the vendors at least agree on where prompts should live?
They do not. Google went the other way. On 16 October 2025 the Google Cloud blog announced that Prompt Management was generally available in the Vertex AI SDK: prompts created, versioned and shared as central resources in a cloud project, stored together with the model name and variables.
What matters more than the product is how Google described the problem it was solving. Teams, it said, design prompts in one place, track versions in spreadsheets or text files, and paste them into code, which causes "inefficiencies, versioning chaos, and collaboration bottlenecks". That is a large vendor describing the Monday morning above.
So one major vendor says put prompts in code, and another ships a managed registry. You will have to choose, and this lesson gives you a way to choose that survives either vendor changing its mind again.
So what does an unmanaged prompt actually cost?
I will be straight with you about the evidence. There is no survey I can point you to showing how many teams version their prompts, and no measured study of what a shared prompt library saves. Anyone who quotes you a percentage here is guessing. What you can observe is the cost in your own shop:
- Diagnosis time. When behavior shifts, you cannot separate prompt, model and data, so every incident starts with a search party.
- Forced migrations. A vendor retires a feature or a model, and you discover what you depend on only when the deadline arrives.
- Untested changes. Somebody edits a sentence on Friday afternoon and nothing is run behind it. Every golden-set failure you catalogued in the last lesson can come back that way.
- Key-person risk. The only person who knows why line 14 is there goes on leave, or leaves.
Where this sits on the ladder: you are at Level 2, AI Capable, lesson 4 of 5. The previous lesson, building a golden test set before hallucinations reach customers, gave you 40 graded tasks, a regression suite and a calibrated judge, which means you can now measure whether an answer is right. This lesson puts the thing being measured under control. The next one, designing an AI pilot with baselines, success metrics and a go or no-go decision, takes the whole kit in front of real users, in a pilot built to end in a decision.
How It Works: Prompt Engineering, Context Engineering and the Controlled Drawing
Three terms first, each in one plain sentence.
- Prompt engineering is writing the instructions you give the model.
- Context engineering is deciding everything the model sees at the moment it answers.
- A versioned prompt is a prompt stored with its history, its owner, the exact model it was tested on and its last test result.
Why is a production prompt like an engineering drawing?
Your distributor sells parts, so borrow an idea from the machine shops that make them. Every part made to order is made from a drawing, and in a well-run shop that drawing is controlled. It carries a drawing number, so everyone means the same part. It carries a revision letter, so everyone knows which version is current. It records the machine and process it was proven on, because the same dimensions behave differently on a different machine. It has change notes saying what changed in each revision and why. And nothing is released to the floor without inspection: the first part made to a new revision is measured against the drawing before production runs.
Superseded revisions are stamped and pulled from the floor, so nobody machines to Rev B when Rev D is current.
Now picture a shop that skips all of that. The drawing lives in the lead machinist's head and in three photocopies, each with different pencil marks. When she is on shift, the parts are fine. When she is away, one cell works from the copy with the old tolerance, and the customer's goods-in inspection rejects the batch.
Then the shop replaces a machine. A shop with controlled drawings runs a first-article inspection of every affected part on the new machine. A shop without them finds out from the customer.
Map it across:
| On the shop floor | In your AI team |
|---|---|
| Drawing number | The prompt's name and purpose |
| Revision letter | The prompt version |
| Machine it was proven on | The pinned model snapshot |
| Change notes | The change log, with the test case behind each change |
| No release without inspection | No version ships without a run against the golden set |
| Superseded copies pulled from the floor | One live copy, in one home you control |
There is one more character worth meeting: the drawing covered in forty redline markups, each added after a complaint and never consolidated into a clean revision. Nobody can tell which markups still apply, so nobody dares remove any. Hold on to that one. It is the bloated prompt, and you will meet it in the workshop.
What does the model actually see when it answers?
Far more than your instructions. Anthropic's engineering team, in an article published on 29 September 2025, defines context engineering as "the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference". Prompt engineering, the writing of instructions, is a subset of that. (A token is a small piece of text, roughly a word fragment, and it is the unit models read and are billed in.)
Why does that matter? Because when the warranty assistant gives a wrong answer, the instruction text is only one suspect. At answer time the model also sees:
- the examples you included,
- the passages your retrieval pipeline pulled from the knowledge base (Lesson 7),
- the descriptions of any tools it is allowed to call,
- the conversation so far.
In shop terms, the drawing is not the only thing at the machine. There is the work order, the material certificate, the fixture and the notes from the last job. A perfect drawing cut from the wrong bar stock still makes scrap. A team that versions the instruction text and ignores the rest of the context has controlled only part of what matters.
How should a production prompt be structured?
Use a fixed order with clearly marked sections. OpenAI's guide (as fetched in November 2026) describes a developer message as usually running in this order: identity, then instructions, then examples, then context, with the context near the end. It recommends Markdown headers and XML tags to mark where each section starts and stops, and suggests putting reusable content first so you benefit from prompt caching, a mechanism that rewards sending the same opening text repeatedly.
The value for a team is mostly about people. When every prompt in the company has the same four sections in the same order, a reviewer can find the instructions in ten seconds, and a diff between two versions is readable.
What is the "right altitude" for instructions?
It is the level of detail that guides the model without scripting it. Anthropic's September 2025 article warns against two extremes. At one end are brittle, hard-coded if-else rules: "if the customer mentions model X and region Y and the purchase was before March, say Z". At the other is vague guidance that assumes shared context: "be helpful and accurate", which assumes the model knows what accurate means in your warranty policy.
Think of briefing a capable new hire. You would not hand them a flowchart for every call, and you would not just say "do a good job". You would explain the role and the rules that really matter, and show a few good examples.
On examples, both vendors point the same way. Anthropic says a small set of diverse, canonical examples beats a list of every edge case. OpenAI says few-shot examples (a handful of worked samples included in the prompt) should cover a diverse range of inputs.
Why not just keep adding instructions?
Because more text makes the model worse at using any of it. Anthropic's guiding principle is to "find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome". The same article describes context rot: as the context window (the total text the model can read at once) fills up, the model's accuracy at recalling what is in it declines gradually, and this happens across models.
So the habit most teams have, a new paragraph after every incident, works against them. That is the redlined drawing. Anthropic's advice is the reverse: start minimal, and add an instruction only in response to an observed failure. The discipline I want you to adopt is one step stricter: every line in the prompt should trace to a test case. If no task in your golden set depends on a line, it is a candidate for deletion.
Why pin the model, and what does "model class" have to do with it?
Pinning means your application names one specific, dated model version rather than a general alias that the vendor can repoint. OpenAI's guide recommends "pinning your production applications to specific model snapshots" to "ensure consistent behavior". On the drawing, this is "proven on machine 4", not "any lathe".
The same guide notes that reasoning models give better results with only high-level guidance, while GPT models benefit from precise instructions. So a prompt written for one class may need rewriting, not copying, for the other, and the record must say which class it was written for.
And a model upgrade is a change like any other. Anthropic's guide to evals, published 9 January 2026, recommends eval-driven development and regression suites that sit near 100%, precisely to catch breakage when prompts or models change. Hamel Husain's practitioner guide to LLM judges (29 October 2024, updated 1 September 2026) adds that the judge validation process is repeated after material changes such as a model update. Put together: new machine, first-article inspection, and recalibrate the gauge as well.
The Workshop: Six Steps From Private Prompts to a Prompt Record
Run this for one use case, the same one you have carried through Lessons 6 to 8. It takes two sittings, because the first needs many people for a short time and the second needs few people for longer.
Sitting one, 45 minutes (steps 1 and 2): everyone who has ever written or edited a copy of the prompt, plus the product owner and the engineer who deploys. They bring copies, agree where the live one will live, and most can leave after step 2.
Sitting two, about half a day (steps 3 to 6): the prompt owner, the engineer, and the domain expert who graded your golden set in Lesson 8. Everything from here is a test run followed by a judgement call on whether a failure is real, so the expert is the one person you cannot do without. The steering committee does not attend; it gets the copy count from step 1 and the decision from step 6.
What to bring: every prompt currently in use for the use case, the golden test set and judge from Lesson 8, and the pipeline configuration sheet from Lesson 7.
We follow one illustrative example throughout. It is invented for teaching, not a real company: the equipment distributor from the opening, with its warranty and parts assistant for the service desk, a golden set of 40 tasks and a regression suite of 15.
Step 1. Collect every copy and count the differences
Ask everyone to bring every version of the prompt they can find: from code, vendor dashboards, personal notes and chat histories. Put them side by side. Count the copies, and count the differences between them.
Do not skip the counting. That number is your starting evidence, and the most persuasive slide you will show a steering committee on this topic.
The distributor finds five copies: two in code, one in a vendor dashboard, two in personal notes. No two are identical. One has a paragraph about a promotion that ended last year. Another has a fix for questions about discontinued parts that somebody wrote and never merged.
Step 2. Choose one home and one owner
Pick a single place under your control where the live prompt will be stored, and name one owner per prompt. You have two patterns to choose from:
| Pattern | What it is | Likely strengths | Watch out for |
|---|---|---|---|
| Code repository | The prompt is a file in the application's source code | Review, tests and rollback through the normal engineering process | Non-developers need a route to propose changes |
| Prompt registry | The prompt is a managed, versioned resource outside the code | Easier for non-developers and for sharing across teams | You must hold an exportable copy, and changes must still pass the tests |
An honest caveat: those strengths are reasoned inference, not measured results. Nobody has published a fair trial of one against the other. The working conclusion is that either can serve you if two conditions hold: you control a copy, and every change is run against the golden set. Write down which you chose and why, so the next person does not reopen the debate from scratch.
The distributor chooses the code repository, because its engineers already review and deploy everything there, and names the service desk product owner as prompt owner. Notice the owner is not the engineer. The owner is the person accountable for what the assistant says, in the same way the design engineer, not the machinist, signs the drawing.
Step 3. Map the context and set a baseline
First, list everything the model sees at answer time and roughly how large each part is. This is the step most teams have never done, and it usually produces a surprise.
| Part of the context | What it contains | Source | Approximate size |
|---|---|---|---|
| Instructions | Identity and rules for the assistant | Prompt file | Fill in (tokens) |
| Examples | Worked sample questions and answers | Prompt file | Fill in |
| Retrieved passages | How many chunks, from which corpus | Pipeline configuration (Lesson 7) | Fill in |
| Tool descriptions | Each tool the model may call | Application code | Fill in |
| Conversation history | How many earlier turns are kept | Application code | Fill in |
Look for parts nobody knew were there, and for one part dwarfing the rest. Either is a lead worth following.
Then merge the copies into one prompt in the order identity, instructions, examples, context, with clear section markers. Do not improve the wording yet. The goal is one consolidated version you can run through the golden set to get a baseline. Think of it as redrawing the part cleanly at Rev A before anyone touches a dimension.
The distributor's consolidated version 1.0 scores 31 of 40 on the golden set and 14 of 15 on the regression suite, the same 31 the team reached at the end of Lesson 8 after its cheap fixes. Consolidating changed nothing in the score, which is what a clean baseline should show. Every later change is judged against 31.
Step 4. Cut to minimal, then add back only from observed failures
This step has two halves, and the order matters.
Cut first. Go through the instructions line by line and ask of each: which golden-set task depends on this? Remove every instruction that nobody can connect to a task, re-run the set, and keep the cut if the pass rate holds. This is the redlined-drawing moment. It feels risky, which is exactly why you do it with the test set in hand rather than on instinct.
The distributor removes 11 legacy instructions that nobody in the room could explain. The score stays at 31 of 40 and 14 of 15. Shorter prompt, same result. Those eleven lines cost tokens on every request and slowed every review, for nothing.
Then add, one change at a time. Sort the remaining failures into clusters. For each cluster, write one instruction, add it alone, re-run, and record the task IDs that motivated it. One change at a time is slow, and it is the only way to know which change did what.
Tasks T-07, T-17, T-22 and T-29 failed because the assistant answered for the wrong region. The team adds "state the region and product line you are answering for". The score rises to 35 of 40, and the regression suite to 15 of 15. Next, two of the four should-escalate tasks (T-37 to T-40), T-38 among them, still fail: the assistant answers the warranty question and ignores the injury. The team adds "if the question mentions an injury or a safety incident, hand it to a person and do not rule on the claim". The score rises to 37 of 40.
Now look at what the team did not do. The last three failures all trace to two versions of the warranty policy that contradict each other. An instruction such as "prefer the newer policy" might lift the score, but it would hide a data problem inside the prompt. Those three go back to the data owner from Lesson 6. Knowing which failures are not a prompt problem is half of prompt engineering.
Step 5. Pin the model and write the change rule
Open the configuration and check what the application actually calls. If it names a moving alias, change it to a dated snapshot. Then write on the record which model class the prompt was written for.
Next, agree one rule and write it at the top of the record:
Every prompt, context or model change is a new version. A second person reviews it. It is merged only if the regression suite stays near 100% and the full golden-set pass rate does not fall.
Note the three nouns. A change to the number of retrieved chunks is a context change. A new snapshot is a model change. Both get a version number and a test run, exactly like an edit to the wording. At Level 3, the lesson on shipping, monitoring and rolling back AI in production turns this rule into an automated release gate with a rollback path. For now, a rule people follow by hand is enough.
Step 6. Rehearse a model change
Finally, run the unchanged prompt on the next model snapshot, or on an alternative model. Record the result and make an explicit decision: hold or upgrade. It is the first-article inspection on a new machine, done before the old machine is taken away. You learn what a model change costs you on a quiet afternoon instead of under a vendor's deadline.
The distributor runs version 1.3, unchanged, on a newer snapshot. The golden set drops from 37 to 33 and the regression suite from 15 to 13. Decision: hold on the pinned snapshot, and open tasks to adapt the prompt for the new one before the old one is retired.
The filled-in change log
Here is the distributor's log after the workshop. Remember, it is an illustration.
| Version | Change | Linked tasks | Model snapshot | Golden set (40) | Regression suite | Decision |
|---|---|---|---|---|---|---|
| 1.0 | Consolidated from five copies, restructured | none | Pinned snapshot A | 31 pass | 14 of 15 | Baseline |
| 1.1 | Removed 11 legacy instructions nobody could explain | none | A | 31 pass | 14 of 15 | Keep: shorter, same score |
| 1.2 | Added "state the region and product line you are answering for" | T-07, T-17, T-22, T-29 | A | 35 pass | 15 of 15 | Ship |
| 1.3 | Added "if the question mentions an injury or a safety incident, hand it to a person" | Should-escalate tasks, including T-38 | A | 37 pass | 15 of 15 | Ship |
| 1.3 | No prompt change; rehearsal on newer snapshot B | none | B | 33 pass | 13 of 15 | Hold on A; open tasks to adapt for B |
Two rows deserve a second look. Version 1.1 deleted eleven instructions and lost nothing, which is what "the smallest set of high-signal tokens" looks like in practice. And the last row shows the same prompt scoring lower on a newer snapshot. Newer is not automatically better for your use case. Without the pin and the golden set, the team would have learned that from the service desk.
Your artifact: the Prompt Record and Change Log
You leave with one record per production prompt: the title block and revision table for the drawing. The fields below are a synthesis of the vendor advice in this lesson, not an industry standard, so adapt them to your shop.
| Field | What to write |
|---|---|
| Prompt name and purpose | One line: which feature, for which users |
| Owner and reviewer | Two named people, not a team |
| Storage location | Repository path or registry reference, and why you chose it |
| Prompt text | In the standard structure: identity, instructions, examples, context |
| Variables and their types | Each placeholder and what fills it |
| Context map | What else the model sees, and the size of each part |
| Intended model class and pinned snapshot | The class the prompt was written for and the exact dated version |
| Linked golden set and version | The Lesson 8 artifact this prompt is tested against |
| Last results | Golden-set pass rate and regression result, with date |
| Change log | Version, change, reason, linked task IDs, author, reviewer, before and after scores |
| Rollback pointer | The last known good version |
| Next rehearsal date | When you will next test against a new snapshot |
Failure Modes, How to Spot Them, and the Metrics to Track
Each of these has a tell you can check in under ten minutes.
What goes wrong with team prompt management?
| Failure mode | How to spot it |
|---|---|
| Prompt sprawl | The copy count in step 1 is above one, or nobody can say which copy is live. |
| Single point of knowledge | Only one person can explain why a given line is there. |
| Bloat | The prompt grows every month and the pass rate does not. |
| Wrong altitude | Long if-then lists for individual cases, or instructions like "be helpful and accurate" that assume the model knows your business. |
| Silent model drift | The configuration points at a moving model alias instead of a dated snapshot. |
| Untracked context changes | The change log shows only wording edits, yet the retrieval settings or tool list changed in the same period. |
| Prompts patching data | Instructions such as "ignore the old policy" or "prefer the newer document" are standing in for a fix the data owner should make. |
The one teams most easily underestimate is bloat, because every individual addition looked sensible on the day. Plot prompt size against pass rate per version. If one line climbs and the other is flat, you are drawing redlines on redlines.
And check one thing separately, because it is a supplier risk rather than a team habit: is the only copy of any production prompt held in a vendor-hosted object or console? If yes, export it into your chosen home this week, whatever that vendor's current timeline says.
Which metrics show the practice is working?
Four measures, all cheap to collect once the record exists. The regression suite is not on this list on purpose: it is a gate every merge must pass, not a number to trend.
| Metric | How to measure it | What good looks like |
|---|---|---|
| Prompt record coverage | Production prompts with a complete record, divided by all production prompts | Climbing toward every production prompt |
| Tested-change rate | Prompt, context or model changes with a recorded golden-set run, divided by all such changes in the period | Every change has a run behind it |
| Prompt and context size against pass rate | Tokens per request, tracked per version beside the golden-set score | Size grows only when the pass rate does |
| Model-change rehearsal time | Time from "new snapshot available" to a recorded hold or upgrade decision | Shrinking, and never "we have not looked" |
Report the first two to your steering committee. Coverage tells them how much of the estate is under control. Tested-change rate tells them whether the control is real or decorative.
Frequently Asked Questions
What is the difference between prompt engineering and context engineering?
Prompt engineering is writing the instructions; context engineering is managing everything the model sees when it answers, of which the instructions are one part. Anthropic (September 2025) defines context engineering as the strategies for curating and maintaining the optimal set of tokens during inference, which also covers examples, retrieved passages, tool descriptions and conversation history.
Should production prompts be stored in code or in a prompt management tool?
Either can work, provided you hold a copy you control and every change is tested against your golden set. OpenAI's guide says to store production prompts in application code, while Google offers managed prompt versioning in the Vertex AI SDK. What does not work is a production prompt whose only copy sits in a vendor console.
How can a team version prompts without slowing everyone down?
Give each production prompt one owner and one home, and make every change a small new version with one reviewer and one test run. Changing one thing at a time is what keeps reviews quick, because each diff is short and each score change has a single cause.
What does it mean to pin a model snapshot?
It means your application calls one specific, dated model version instead of an alias the vendor can move to a newer model. OpenAI recommends pinning production applications to snapshots for consistent behavior, and you move to a new snapshot only after it passes your golden set.
How do you test a prompt change before it goes live?
Run the new version against your regression suite and your full golden set, and merge it only if the regression suite stays near 100% and the golden-set pass rate does not fall. Anthropic's January 2026 evals guide recommends regression suites near 100% precisely to catch breakage when prompts or models change.
Key Takeaways
- A prompt that a product depends on is a shared production asset. Treat it like a controlled drawing: one live copy in a home you control, one named owner and a reviewer.
- Prompt engineering is writing the instructions; context engineering is everything the model sees. Map the whole context, and version context and model changes exactly like wording changes.
- Use one structure everywhere (identity, instructions, examples, context) and write at the right altitude: neither a flowchart nor a slogan.
- Smaller is better. Cut every instruction no golden-set task depends on, add new ones only from observed failures, one at a time, and send data problems back to the data owner instead of patching them in the prompt.
- Pin the model snapshot and record the model class. A model upgrade gets a test run first, and a rehearsal before any vendor deadline.
- OpenAI set 30 November 2026 as the shutdown date for its hosted prompt objects; the lasting lesson is that the only copy of a production prompt must never sit in a vendor's console.
- Lesson 10 puts this controlled prompt, with your data, pipeline and golden set, in front of real users in a pilot built to end in a decision.
Skill.re