The first prompt in a codebase usually lives wherever it was convenient: inline in the function that calls the model, or in a single prompts.py file nobody thought twice about. That's fine at one prompt. By the twentieth, most teams have a folder of loosely related text files, several of which are near-duplicates of each other because someone needed "basically the same prompt but for the enterprise tier" and copied rather than parameterized. Nobody remembers which version is current, and the only reliable way to find out what a prompt actually does in production is to grep the deployed code.

The underlying problem isn't discipline — it's that prompts don't fit neatly into the tooling teams already use for shared code. They're text, not functions, so they don't get the safety net of type checking or a compiler catching a broken reference. And they change for reasons that have nothing to do with a code review: a support ticket reveals a phrasing that confuses the model, someone tweaks a sentence to fix it, and the change ships without anyone treating it as a change to a shared asset.

Conventions that actually hold up

A handful of practices make the difference between a prompt library that stays legible and one that quietly rots:

  • One owner per prompt, not per prompt file. A file with five prompts in it, each maintained by a different feature team, guarantees someone edits a neighboring prompt by accident. Split prompts by owner boundary even if that means more files.
  • Name prompts by what they do, not by the feature that first needed them. summarize_ticket_for_agent_handoff survives a rename of the feature that uses it. q3_support_prompt doesn't, and six months later nobody's sure if it's still q3-specific or just named that way.
  • Treat a prompt change like an API change if more than one caller depends on it. If three different code paths call the same prompt, changing its output format is a breaking change for two of them, not just an edit. Either version the prompt explicitly or fan it out into per-caller variants once the callers' needs diverge — don't let one shared prompt quietly serve two masters with different expectations.
  • Store the eval or example set next to the prompt, not in a separate tribal-knowledge doc. A prompt without a checked-in set of inputs it's expected to handle well is a prompt nobody can safely change, because there's no fast way to tell if an edit made things worse.
  • Deprecate loudly. When a prompt is superseded, leave a stub that points to the replacement instead of deleting it outright. The next engineer who finds the old one via search needs to know it's not the one to copy from.

The real test

The test of whether a prompt library is actually working isn't how many prompts it holds — it's whether a new engineer can find the prompt behind a given feature, tell whether it's still current, and see evidence of what it's supposed to handle, all without asking the person who wrote it. If that only works when the original author is in the room, it's not a library yet. It's notes.

AI ToolsDeveloper ToolsSoftware Engineering