From the free book Delta: Closing the Specification Gap (Dhuri, 2026). The PDF is the canonical edition — figures, tables, and code formatting are simplified online.
Version-controlled prompt artifacts that compound team capability over time
“A prompt buried in a chat history is institutional knowledge that leaves the building with whoever had the conversation. A prompt in a reviewed .md file is institutional knowledge your team owns forever.” — The team that version-controls its prompts has a compounding asset. Every model upgrade is an improvement opportunity, not a regression risk. In This Chapter
Prompts are code. Code that is not version-controlled, reviewed, and tested will degrade. When a model is upgraded, prompts that worked on the previous model may produce different output on the new one. Without version control, you can’t see what changed. Without tests, you cannot detect the regression until a developer notices the output is wrong. Without review, no one knows which prompts encode hard-won domain knowledge and which are first drafts. Apply the same discipline to your prompt library as you apply to your application code.
A team built a .prompts/ directory in sprint four. By sprint eight, it had 23 files. By sprint fifteen, it had 23 files and nobody remembered writing most of them. A model upgrade in month seven changed the output format of three generation prompts silently — the new outputs were structurally correct but missing the Error Cases section that the team had carefully added to the prompts after a production incident. The CI pipeline did not catch it because there were no tests. The generation prompts were producing incomplete code. The team noticed six weeks later when a PR reviewer asked why the new service had no error cases. The library was not a library. It was an unreviewed, untested, undocumented collection of text files. The fix: YAML frontmatter with last_ validated date and validated_by field. promptfoo CI for every .md file with at least three assertions.
THE COST OF THIS MISTAKE Incident: Prompt library without CI testing — model upgrade silently ,→ removed error cases from generated code Total cost: Six weeks of generated services missing error cases — 4 ,→ PRs needed rework, 2 reached staging Time to resolve: 6 weeks undetected, 1 sprint to remediate all ,→ affected services Prevention: "promptfoo CI against every prompt file. Assertion: ,→ output contains Error Cases section."
6 months
83 average time between prompt creation and first detected regression in teams without automated prompt testing. With promptfoo CI: same regression caught in the next pipeline run. Source: Illustrative figure. The directional claim — that automated prompt testing dramatically shortens regression-detection time — follows directly from the well-established pattern that automated tests catch issues at the next pipeline run rather than after manual discovery. See Research & Statistics Notes (see Appendix J)
11.1 The .md Prompt File Standard A note on model names (current as of mid-2026). The examples in this chapter pin specific models — claude-sonnet-4-6 as a sensible production default, with claude-opus-4-8 (the current flagship at the time of writing) shown where maximum capability matters. These identifiers are pinned snapshots, and the lineup moves quickly: by the time you read this, the current names will likely differ. That is precisely the point of this chapter. Treat the model name as perishable configuration — pinned in version control, swapped deliberately, and gated by the prompt CI shown below — not as a fact baked into your prose or your code. The discipline (pin it, version it, test the upgrade) is durable; the specific string is not. The workflows in this book run the same on any frontier coding assistant — GPT-5-class, Gemini-class, or Claude-class; the examples pin one stack so they stay concrete and reproducible, but the constraint craft is identical everywhere. --# Required YAML frontmatter name: hipaa-patient-service-java version: 3.0.0 model: claude-sonnet-4-6 temperature: 0.1 platform: java-21 framework: spring-boot-3 domain: healthcare-hipaa tags: [generation, hipaa, java, patient] last_validated: '2026-03' validated_by: '@alice' output_quality: production-ready required_inputs: - name: existing_interface type: java_interface required: true - name: task_description type: text required: true cache_prefix: true changelog: - version: 3.0.0 date: '2026-03' change: 'Added @AuditLog assertion. Updated for claude-sonnet ,→ -4-6.' --## Prompt Template ```xml <role>Senior Java engineer on HIPAA EHR platform.</role> <existing_interface>{{existing_interface}}</existing_interface> <task>{{task_description}}</task> <constraints>@AuditLog REQUIRED. PHI never in logs.</constraints> ```
84 .prompts/ README.md
# Index, contribution guide, governance
CHANGELOG.md
# Library changes and model migration notes
_partials/
# Shared constraint blocks constraints-hipaa.md constraints-pci.md role-dotnet-ca.md role-java-spring.md generation/ cqrs-handler-csharp.md spring-service-java.md hipaa-service-java.md pci-payment-csharp.md review/ pr-review-general.md hipaa-audit.md prompt-injection-audit.md thread-safety.md debugging/ evidence-brief.md bigdecimal-precision.md testing/ edge-case-discovery.md junit5-suite-java.md xunit-suite-csharp.md database/ ef-core-migration.md flyway-migration.md devops/ dockerfile-java.md dockerfile-dotnet.md github-actions.md
85 11.3 promptfoo CI Configuration # .promptfooconfig.yaml providers: - id: anthropic:claude-sonnet-4-6 config: { temperature: 0.1 } prompts: - file://.prompts/generation/hipaa-service-java.md - file://.prompts/review/hipaa-audit.md tests: - description: 'HIPAA service includes @AuditLog' vars: existing_interface: | public interface PatientService { Result<PatientDto> getPatient(UUID patientId); } task_description: 'Implement getPatient' assert: - type: contains value: '@AuditLog' - type: not-contains value: 'log.info.*patient' - type: contains value: 'Result<PatientDto>' - description: 'HIPAA audit catches PHI in log' vars: code_under_review: | log.info("Patient {} has diagnosis {}", patient.getName(), patient.getDiagnosis()); assert: - type: llm-rubric value: 'The review identifies PHI in the log as a violation' provider: anthropic:claude-sonnet-4-6
86 QUICK WIN — 1 hour
Pick your team’s three most-used prompts. Convert each to a .md file with YAML frontmatter. For each, write two promptfoo assertions: one that confirms something domain-specific is present, one that confirms a known anti-pattern is absent. Run them. This your prompt library, born.
“We set up promptfoo CI before upgrading from claude-sonnet-4-6 to claude-opus-4-8. It caught three regressions: a review prompt that stopped including line numbers, a generation prompt that started using checked exceptions (we forbid them), and a test prompt that changed assertion style. None of them would have been obvious in code review. The CI caught them in the pipeline run.” — Tech Lead, Insurance Technology platform
test, maintain. The same standards that apply to application code apply to the prompts that generate it. + The .md prompt file standard: YAML frontmatter with model target, temperature, platform, required inputs, last_validated, and changelog is the minimum viable structure. + promptfoo CI catches model upgrade regressions before they reach production. Set it up before your next model upgrade. It takes one afternoon. + Quarterly prompt maintenance: run the full test suite against the new model. Update regressions. Retire superseded prompts. This is the prompt library equivalent of dependency upgrades. + The first ten prompt files in your .prompts/ directory are the ten prompts your team uses most often. Start there.
UP NEXT — Chapter 12: Context Engineering — What the Model Knows
You have been managing context intuitively since Chapter 1. Chapter 12 makes that management systematic: five layers, explicit caching strategy, and the cached-prefix cost reduction (up to ~90% on the cached portion) that most teams leave on the table.
88