Every team that ships an LLM feature goes through the same stage. The prompt starts life as a string in a function. Then someone tweaks a sentence in a chat window, someone else pastes a "better version" into a ticket, and a month later nobody can say which wording is actually running in production or why last Tuesday's answers looked different.
The fix is not a new platform. For a small team, it is the oldest tool you already have: Git. In this post I'll show a tiny Node.js module that treats prompts as versioned files, refuses to render a prompt with missing or unexpected variables, and gives every prompt a short hash you can put in your logs. It is about 60 lines and I ran its tests, so you can copy it with confidence.
Why prompts deserve the same care as code
A prompt changes behavior as surely as a code change does. Reword one instruction and the model may start refusing things it used to accept, or return a field in a different shape. If that edit lives in a dashboard or a chat thread, you have three problems:
- No history. You can't see who changed what, or revert to the version that worked.
- No review. A one-word change goes live without a second pair of eyes.
- No traceability. When a user reports a bad answer, you can't tell which prompt produced it.
Prompts also carry risk. They often contain business rules and instructions that interact with untrusted input, which is exactly where prompt injection happens. OWASP lists it as the first risk in its LLM application top 10. That is another reason to keep them where changes are visible and reviewed.
The layout: one file per version
I keep prompts in a prompts/ folder, one file per version, named <name>.v<N>.md. A short header declares the name, version and the variables the prompt expects. Old versions stay in the repo. Git already keeps history, but keeping the files means you can load an older version for a comparison run without checking out an old commit.
ticket-triage.v3.md
---
name: ticket-triage
version: 3
vars: customer_message, product
---
You triage support tickets for {{product}}.
Classify the message below as one of: billing, bug, feature, other.
Reply with JSON only: {"category": "...", "urgent": true|false}
Customer message:
"""
{{customer_message}}
"""
The vars line is documentation that the code also enforces. If the template mentions {{product}} and the caller forgets to pass it, we want a loud failure in development, not a prompt that says "You triage support tickets for {{product}}" to the model.
The loader
The module does four things. It parses the header, computes a 12-character SHA-256 hash of the template text, indexes prompts by name@version, and renders with strict checking. The hash is the part I'd miss most. Put it next to the model name in every log line, and "which prompt produced this?" becomes a search instead of an investigation.
prompts.js
import { readFileSync, readdirSync } from "node:fs";
import { createHash } from "node:crypto";
import path from "node:path";
// File name convention: <name>.v<N>.md with a small front-matter header.
function parse(file) {
const raw = readFileSync(file, "utf8");
const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
if (!m) throw new Error(`${file}: missing front matter`);
const meta = Object.fromEntries(
m[1].split("\n").map((l) => {
const i = l.indexOf(":");
return [l.slice(0, i).trim(), l.slice(i + 1).trim()];
}),
);
const vars = meta.vars ? meta.vars.split(",").map((v) => v.trim()) : [];
const template = m[2].trim();
// A short content hash goes into every log line: "which exact prompt produced this?"
const hash = createHash("sha256").update(template).digest("hex").slice(0, 12);
return { name: meta.name, version: Number(meta.version), vars, template, hash };
}
export function loadPrompts(dir) {
const prompts = new Map();
for (const f of readdirSync(dir).filter((f) => /\.v\d+\.md$/.test(f))) {
const p = parse(path.join(dir, f));
prompts.set(`${p.name}@${p.version}`, p);
}
return {
get(name, version) {
if (version === undefined) {
// default to the highest version, but callers in production should pin one
const all = [...prompts.values()].filter((p) => p.name === name);
if (!all.length) throw new Error(`unknown prompt ${name}`);
return all.sort((a, b) => b.version - a.version)[0];
}
const p = prompts.get(`${name}@${version}`);
if (!p) throw new Error(`unknown prompt ${name}@${version}`);
return p;
},
};
}
export function render(prompt, values) {
const used = new Set();
const text = prompt.template.replace(/{{\s*(\w+)\s*}}/g, (_, key) => {
if (!(key in values)) throw new Error(`${prompt.name}@${prompt.version}: missing variable "${key}"`);
used.add(key);
return String(values[key]);
});
const extra = Object.keys(values).filter((k) => !used.has(k));
if (extra.length) throw new Error(`${prompt.name}@${prompt.version}: unused variables ${extra.join(", ")}`);
return text;
}
Three design choices are worth explaining:
- Missing variables throw. A silent blank in a prompt is one of the hardest bugs to notice, because the model will happily answer anyway.
- Unused variables throw too. If a caller passes
toneand the template ignores it, someone believes they changed behavior when they didn't. - Callers should pin a version. The loader can return "the latest", which is handy in a notebook. In production code,
get("ticket-triage", 3)means a new file can't change behavior until someone edits the call and gets it reviewed.
Tests that protect the contract
The tests are short and cover what actually goes wrong: the right version loads, variables render, a missing or extra variable fails loudly, and an unknown version is an error.
prompts.test.js
import test from "node:test";
import assert from "node:assert/strict";
import { loadPrompts, render } from "./prompts.js";
const lib = loadPrompts(new URL("./prompts", import.meta.url).pathname);
test("loads a pinned version and exposes a stable hash", () => {
const p = lib.get("ticket-triage", 3);
assert.equal(p.version, 3);
assert.match(p.hash, /^[0-9a-f]{12}$/);
assert.equal(lib.get("ticket-triage").hash, p.hash); // latest == v3 here
});
test("renders variables", () => {
const out = render(lib.get("ticket-triage", 3), { product: "Acme", customer_message: "I was charged twice" });
assert.match(out, /triage support tickets for Acme/);
assert.match(out, /I was charged twice/);
});
test("fails loudly on a missing or extra variable", () => {
const p = lib.get("ticket-triage", 3);
assert.throws(() => render(p, { product: "Acme" }), /missing variable "customer_message"/);
assert.throws(() => render(p, { product: "Acme", customer_message: "x", tone: "kind" }), /unused variables tone/);
});
test("unknown version throws", () => {
assert.throws(() => lib.get("ticket-triage", 9), /unknown prompt/);
});
Run them with node --test prompts.test.js. They passed here: four tests, no failures. The template uses a simple {{name}} syntax on purpose. If you need loops or conditionals, resist the urge to build a templating language. Two prompt versions with different shapes are easier to review than one clever template.
Rolling out a new version
My routine for changing a prompt is the same every time:
- Copy the file to the next version (
v4) and make the change there. Never edit a version that has shipped. - Run your evaluation set against both versions. If you don't have one yet, build a small one first. Without it you are comparing prompts by feel.
- Open a pull request. Reviewers see the diff in the prompt exactly as they would a code change.
- Switch the pinned version in one commit, so rolling back is a one-line revert.
- Log the hash. After release, check that production logs show the new hash and nothing else.
What I would not do
- Don't store secrets in prompt files. API keys and customer data belong in your secret manager and your database, not in a file that gets reviewed and logged.
- Don't build a prompt management UI first. If non-engineers need to edit prompts, the right answer may be a pull-request workflow with a friendly template, not a new product.
- Don't hash the rendered prompt in your logs. Hash the template. The rendered text includes user data, and logging that is a privacy problem.
- Don't forget the model. A prompt version is only half the story. Log the model name and settings next to the hash, because changing the model changes the behavior just as much.
Reviewing a prompt change properly
A prompt diff is small, which makes it easy to approve without thinking. I ask reviewers three questions. Did the instruction that changed also change the output format that other code parses? Did a rule get softened, such as "never" turning into "avoid"? And does the pull request include evaluation results from before and after? A reviewer who can see a failing-case list next to the diff is far more useful than one who reads the wording and says it looks fine.
It also helps to keep each version's change note in the file header, one line long. Six months later, "v4: stop the model inventing order numbers" is worth more than any commit message you'll remember.
Where this stops being enough
This pattern is for a handful of prompts and a small team. If you run hundreds of prompts, need per-customer variants, or want non-technical editors with approval flows, a dedicated tool may earn its keep. Start with files and Git, and move only when you can name what the files can't do.
Need an AI feature your team can maintain?
I build AI tools and full-stack apps for clients, including the unglamorous parts like evaluation, logging and safe rollouts. If you'd like a second opinion on your setup, get in touch.
See services Get in touchWhat I ran this against
- Node.js 24.22.1 on 17 November 2026, using the built-in
node:testrunner. No provider API was called: the examples use stubs, so they cost nothing to run. - Four tests pass (loading a pinned version, rendering variables, failing on missing or extra variables, unknown versions).
Sources checked
- OWASP Top 10 for LLM Applications, the prompt-injection entry (why prompts need the same care as code): genai.owasp.org, site reachable 17 November 2026.