X · Governance & ObservabilityEmerging★

Own Your Prompts (12-Factor Agents)

also known as 12-Factor Prompts, Production-Owned Prompts

Every prompt in a production agent is versioned, tested, and owned by the team in the application repo — never inherited as a framework default.

This pattern helps complete certain larger patterns —

  • specialisesPrompt Versioning★★— Treat prompts as immutable, hashed, semver'd artefacts in a registry; deploy and roll back like code.

Context

A team uses an agent framework (LangChain, LlamaIndex, etc.) that ships default system prompts. Production agents inherit these defaults without auditing them. When the framework updates, the prompt changes silently.

Problem

Framework-default prompts are not visible in the team's codebase, are not versioned by the team, are not tested by the team's eval suite. The team has no record of what prompt was in production at any historical moment. Differs from existing prompt-versioning by adding the no-framework-defaults stance — version is necessary but not sufficient.

Forces

  • Framework defaults are convenient; rewriting them is initial effort.
  • Some framework defaults are quite good and reinventing them is a regression risk.
  • Team-owned prompts mean team-owned maintenance burden.

Example

A team uses LangChain. Initial audit reveals the agent uses 3 prompts (ReAct system, tool-summary, retry-suggestion) inherited from LangChain defaults. Team copies all 3 into app/prompts/, wires the agent to use those, removes default-inheritance code path. A later LangChain upgrade changes the default ReAct prompt — team's agent is unaffected. Eval suite covers the actual prompts in use.

Diagram

Solution

Therefore:

At project start, audit every prompt the framework uses; copy into application repo as first-class files. Wire the agent to use the team-owned copies, not framework defaults. Version with git. Test in eval suite. Framework upgrades cannot change agent behavior without a team-controlled prompt change. Pair with prompt-versioning, eval-as-contract, deterministic-control-flow-not-prompt, stateless-reducer-agent.

What this pattern forbids. No prompt the agent uses is sourced from a framework default; all prompts live in the application repo under team ownership.

And the patterns that stand alongside it, or against it —

  • complementsEval as Contract★★— Treat the eval suite as the contract the agent must satisfy; releases ship only if evals pass.
  • complementsDeterministic Control Flow, Not Prompt★— Branching decisions live in deterministic application code while the LLM is invoked at strategic points to produce structured signals that the code branches on.
  • complementsStateless Reducer Agent★— Design the agent as a pure function (state, event) → newState; entire execution history is held in an external event log; enables pause / resume / replay / time-travel without bespoke checkpointing.
  • complementsSpec-Driven Loop★— Run the same prompt against a fixed spec in a deterministic outer loop until the spec is satisfied.
  • complementsAgentic Golden Path★— Constrain an agent to the platform's curated golden path of living, machine-readable standards and check for drift as it works, so its output is compliant by construction rather than corrected later.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

References

Provenance