Prompt Files: Versioning Instructions Like Code

For the first few months I kept prompts inline with my Python calls. It felt fine. Then I started tweaking prompts to fix edge cases, and I could not remember what I changed or why. The output quality drifted and I had no way to bisect.

The Fix Is Boring

Move every prompt over ten lines into its own .md file. Load it at runtime. Commit the file. Tag releases. Now prompts are code.

from pathlib import Path
 
PROMPTS = Path(__file__).parent / 'prompts'
 
def load_prompt(name: str, **vars) -> str:
    template = (PROMPTS / f'{name}.md').read_text()
    return template.format(**vars)
 
# Usage
prompt = load_prompt('extract_entities', text=article_body)

Three things improve immediately. First, diffs on prompt changes are readable in PRs. Second, I can run old prompts against new data to regression-test. Third, non-developers on my team can edit prompts without touching Python.

What I Learned Versioning Them

Prompts evolve just like code. They accumulate edge-case handling, instructional scars from past failures, and specific phrasings that happen to work. Treating them as ephemeral strings means losing that institutional memory every time you rewrite.

I keep a short header comment in each prompt file listing model version and last-tested date. When Anthropic ships a new model, I walk the prompts file by file, retest, and bump the header. It is a checklist, not heroics.

For structured prompt patterns see the Anthropic prompt engineering guide. Start moving prompts out today. Your future self will thank you.