AI Workflow Versioning: A Plain Guide to Safe Changes.

AI workflow versioning means saving every change to your AI system as a numbered version. You can compare versions. You can go back to an old one when a new one breaks.

Think of a recipe book. Each time you change a recipe, you write a new edition and keep the old one. If guests hate the new dish, you cook the old one again.

The hard part is knowing what counts as "the recipe" in an AI system. It is more than code.

TL;DR

• Version four things: prompts, model settings, workflow logic and test data. Code alone is not enough.
• Give each version a unique ID. Never point production at "latest".
• Test a new version beside the old one before you switch.
• Keep the old version ready, so a rollback takes minutes, not days.
• Let running jobs finish on the old version. Send only new jobs to the new one.

Why AI workflows break in quiet ways

Normal software breaks loudly. An error shows up and someone fixes it.

AI workflows break quietly. You change one word in a prompt (the instruction you give the AI). The output still looks fine, but it is a bit worse. Nobody notices for a week.

That is why versioning matters more here. You need a record of what changed and when. Without one, you guess.

The usual causes of a quiet break:

• Someone edited a prompt in a live tool.
• The AI provider updated the model behind the same name.
• A step in the chain changed its output format.
• New data came in that the old logic never saw.

With versions, you check the change log, find the cause, then fix it or roll back.

What to version in an AI workflow

Most people version only the code. That misses most of the risk.

AWS guidance on prompt, agent and model lifecycle says prompts are as critical as code. It says to version prompts as templates, along with model settings and the state of your data, and to give each prompt version a unique ID.

Here is the full recipe card, not just the ingredient list.

Layer	Kitchen version	What to record
Prompts	The written recipe	Full text, examples, system instructions
Model settings	Oven type and temperature	Model name, exact version, temperature and other settings
Workflow logic	The order of steps	Which step runs first, what passes between steps
Test data	The taste-test panel	The sample cases you check each version against

Add one more: the knowledge your agents read from, like documents or a database. If that changes, the output changes. Note which snapshot each version used.

Give every version a plain ID

Keep the pattern simple, for example support-triage-v1.4. Add a short note on what changed and why.

Never rename an old version. Never edit one after you ship it. A shipped version is frozen, and any change makes a new version.

Keep a draft and frozen copies

Work in a draft. When it passes your checks, freeze a copy and give it an ID. Many production workflow tools work this way: one editable draft, many locked versions. You can copy the idea by hand with a folder and a spreadsheet.

Pin your model version

This one catches people out.

Many AI providers offer names like "latest". That name can point to a new model next month. Your workflow changes and you did nothing.

So pin the model. In kitchen terms, you want the same flour every time. You do not want the shop swapping brands without telling you.

1. Use the full, dated model name in your settings.
2. Write it in your version record.
3. When a new model arrives, treat it as a new version.
4. Test it on your sample cases first.

We wrote about testing models on real work in our guide to choosing an LLM. The same habit applies when you upgrade.

Record where each change came from

A list of edits helps. A list of reasons helps more.

The MLflow guide to version tracking describes a "LoggedModel". It is one record for a whole AI application. It captures or links the code, the settings, the test results and the traces (a step-by-step log of what the AI did). That lets you repeat a result, find why something got worse, and compare versions fairly.

You may not use MLflow. Copy the idea. Keep one short page per version that answers:

• What changed?
• Why did we change it?
• Which test cases did we run?
• How did it score against the last version?
• Who approved it?

Write the record so a machine can read it too

Agents now read your files as well as people do. The Atomic guide to version control for AI agents makes the same point for code. It says agent changes need stable identities and evidence attached, so a human or another agent can review them later. A paper on reproducibility in agentic systems, by Jimmy Lin, argues for "agent-legible" artefacts: files built so other agents can read and run them.

In plain words: use set fields, not loose paragraphs. Then a person and an AI agent can both read your notes.

version: support-triage-v1.4
model: (exact dated name)
prompt: prompts/triage-v1.4.txt
change: added rule for refund requests
tests: 40 cases, 38 passed
approved_by: ops lead

That is clear to you. It is also clear to a script.

Roll out new versions without breaking live jobs

Some AI workflows run for hours or days. They wait for a person to approve, or for a file to arrive. If you change the workflow halfway through, that job can get lost.

The Temporal documentation on Go workflow versioning explains the hard rule. Long-running workflow code must be deterministic, which means it does the same thing when replayed. Change that code and you need patching or versioned worker deployments. Otherwise in-progress runs can hit non-determinism errors when the system replays their state.

You do not need that tool to use the lesson:

Old jobs finish on the old version. New jobs start on the new version.

Think of a restaurant changing its menu. Seated tables keep the old menu. New guests get the new one.

A safe rollout in four steps

1. Shadow run. Run the new version beside the old one on real inputs. Keep its output away from customers. Just compare.
2. Small slice. Send a small share of live work to the new version and watch it.
3. Full switch. If the scores hold, move all new jobs over.
4. Retire the old one. Only when no jobs still run on it.

The same AWS guidance points to shadow mode and confidence thresholds before a full rollout. A confidence threshold is a minimum score. Below it, a person checks the work.

Test before you ship, and test again after

A version with no test is a guess with a number on it.

Build a small set of real cases. Start with 20 to 50. Include normal ones, odd ones, and the cases that went wrong before. Run every new version against the same set.

If a new prompt fixes one case and breaks three, you see it at once. That is what versions buy you: fair comparisons.

More in our posts on AI agent testing with replay and CI checks and how AI systems handle edge cases.

Keep sessions clean

Long chats get messy.

A recent arXiv paper on a phased workflow for operating LLM-based coding agents warns that conversation logs can get poisoned with hallucinations (made-up facts the AI states as true). Its practitioners use fresh sessions for new tasks and curate their prompt files by hand. They do not lean on one long-running agent state.

For versioning, that means your instructions live in files you control. A chat history should never be the only copy of what the agent "knows". Start each new task clean and load the right version of the instructions.

Prompt governance for sensitive work

Some output carries real risk: health advice, legal text, financial guidance. Here versioning is not optional.

AWS guidance says that when prompts shape user-facing or regulated output, you should formalise how prompts are written, reviewed and tested. That often includes automated checks where one AI model grades another's work.

In practice:

• A named person approves each prompt change.
• Every approval is logged against a version ID.
• You can show later which prompt produced which output.

If you work in finance, read about generative AI compliance rules for US advisers. Check with your own compliance officer or lawyer before you rely on AI output in a regulated setting.

For the wider frame, see our 90-day plan for AI system governance.

Our view: version the judgment, not just the files

Most versioning advice is about files. Prompt files, config files. That matters. But our clients are founders and experts running $1M+ businesses, and what they need to protect is their judgment.

A founder knows when to bend a rule. They know which client needs a call, not an email. That knowledge goes into the agents we build with Claude Code, so it has to be versioned too.

We do three things:

• Write the rules down. We pull the founder's decisions into plain rules and examples.
• Turn them into agent instructions. Each rule lives in a versioned file.
• Check each version against the founder's own calls. If a new version disagrees with how the founder would act, we find out before clients do.

There is a second reason. Founders should own what gets built. A system you cannot read or move is a trap. Clear versions let you see what each agent does and why.

Versioning will not fix a bad process, though. If the workflow is unclear, ten versions of it are still unclear. Fix the process first, then version it.

This is the same idea behind an AI operating system, a set of AI employees that carry your IP. Njin explains it well in what an AI operating system for business is. To see how the agents fit together, start with our guide to six AI orchestration patterns. The glossary covers the terms.

James Killick

Start small: a one-week setup

You do not need a big tool to begin.

1. Day 1. List every prompt and setting in your workflow. Put them in one folder.
2. Day 2. Give each a version ID. Freeze what is live today as v1.0.
3. Day 3. Write 20 test cases from real work.
4. Day 4. Pin your model to an exact version.
5. Day 5. Write the one-page change record template.
6. From then on. No edits to live prompts. Every change is a new version.

That alone puts you ahead of most teams.

Common mistakes

• Editing live. Someone tweaks a prompt in the tool. No record, no rollback.
• Using "latest". The ground moves under you.
• Versioning code only. Prompts and data drive the output.
• No test set. You cannot tell better from worse.
• No owner. Nobody approves, nobody is accountable.
• Deleting old versions. Keep them. Storage is cheap. A rollback is not.

Where we can help

If you run a consulting or education business and your team still waits on you for decisions, this is our work.

The AI Orchestrators Program is a 90-day done-with-you build at $18,500 one-off. We turn your expertise into a network of AI agents, with versioning and testing built in. You keep full ownership.

Want to start smaller? The Foundation Month is $3,500 one-off and puts one done-for-you AI win live in 30 days. See the Program page.

Prefer to build it yourself? Platform Access is $90 per month or $900 per year.

Next step

Want a working, versioned AI system built around your expertise? Look at the 90-day Program and book a call.

Sources

• AWS Prescriptive Guidance: Prompt, agent, and model lifecycle management
• Atomic: Version Control for AI Agents
• MLflow: Version Tracking for GenAI Applications
• ACM: Jimmy Lin on agent-legible reproducibility
• Temporal documentation: Go workflow versioning
• arXiv: A Phased Workflow for Operating LLM-Based Coding Agents