Skip to content

Why prompts should not live in your codebase

Marcus Hale ·

Prompts in your repo feel correct. They are text, text belongs in git, git is where review happens. I argued this position for a year and I now think it is wrong for most teams.

The problem is the deploy cycle

A prompt change is a copy change. The person best placed to make it is usually a product manager or a support lead who has read a thousand of these conversations. Under the prompts-in-repo model, that person has to either learn your PR workflow or file a ticket and wait.

So what actually happens is the copy never gets improved. Not because anyone decided that, but because the friction is high enough that only engineers make prompt changes, and engineers have other things to do.

What you actually want to keep

The objections to a prompt registry are mostly about losing properties that git gives you for free. They are legitimate, and a registry has to replicate them:

  • Diffs and history. Every revision immutable, with a readable diff.
  • Review. Someone signs off before production.
  • Atomicity with code. If a prompt change requires a code change, they have to ship together.
  • Rollback. Instant, without a deploy.

The first, second and fourth are straightforward. The third is the one that bites.

Handling the coupling problem

Prompts and code do get coupled. You add a template variable, the code has to pass it. Version the interface, not just the text:

const prompt = await cloudmind.prompts.get("support-summary", {
  label: "production",
  requires: ["ticket", "tone"],
});

If the production revision does not declare both variables, this throws at startup rather than producing a malformed prompt at 3am. Your deploy fails loudly, which is what you wanted.

For genuinely breaking changes, pin to an explicit revision in code, ship, then move the label. Two steps instead of one, but only for the small fraction of changes that actually need it.

When prompts in the repo are right

I still think repo-based prompts are correct if:

  • You are a solo developer or a two-person team where everyone can ship code.
  • Your prompts are tightly coupled to code and change on the same cadence.
  • You have a regulatory requirement that every production change flow through your existing SDLC.

That last one is real. Some teams cannot move prompt changes outside their audited pipeline, and no amount of convenience beats a compliance requirement.

For everyone else, the friction is costing you more than the coupling is.