Building Reliable AI Agents Series: Factor 2 – Own Your Prompts

This is the second post in a series of posts about building reliable AI agents.

When building AI agents, where do your prompts live? If they're hidden inside frameworks or scattered across configuration files, you're missing a fundamental principle of maintainable AI systems: treating prompts as first-class code citizens.

Factor 2: Own Your Prompts

When building AI agents, where do your prompts live? If they're hidden inside frameworks or scattered across configuration files, you're missing a fundamental principle of maintainable AI systems: treating prompts as first-class code citizens.

The Hidden Prompt Problem

Most AI frameworks abstract away prompts, promising simplicity. But this convenience comes at a cost. When your agent misbehaves, how do you debug it? When you need to improve responses, where do you look? Without visibility into prompts, you're essentially flying blind.

Factor 2 of the 12-Factor Agent methodology solves this by establishing a simple principle: prompts should be explicit, version-controlled code artefacts. No hidden abstractions, no mysterious instructions - just clear, manageable code.

Why Explicit Prompts Matter

Consider this scenario: your customer service agent suddenly starts giving incorrect information. With hidden prompts, you're left guessing. With explicit prompts, you can:

• Check the exact instructions your AI received
• Review recent prompt changes in version control
• Roll back to a previous working version
• Test different prompt variations systematically

The formula is simple: Same Question + Different Prompts = Different Behaviour (Predictably).

Implementing Factor 2

Here's what explicit prompt management looks like in practice:

const PROMPTS = {
  basicV1: `You are a helpful assistant.`,

  basicV2: `You are a helpful and friendly assistant.
Always be polite, clear, and provide helpful explanations.
When asked about calculations, use the available math tools.`,

  calculator: `You are a mathematical assistant with access to calculator tools.
When asked to perform calculations:
1. Use the appropriate math tool
2. Show the calculation step by step
3. Explain the result clearly`,
};

Notice how each prompt version is clearly defined, labelled, and ready for version control. No magic, no hidden configuration - just code.

The Benefits in Production

When you own your prompts, several things become possible:

Systematic A/B Testing: Compare prompt performance with real metrics. Which version leads to better customer satisfaction? Which reduces support tickets?

Team Collaboration: Prompts become reviewable artefacts. Team members can suggest improvements through standard pull requests.

Compliance and Auditing: Track exactly what instructions your AI received at any point in time. Essential for regulated industries.

Debugging: When issues arise, you can immediately see the exact prompt that caused the problem.

Moving Beyond Guesswork

Traditional prompt engineering often feels like alchemy - mysterious incantations that sometimes work. Factor 2 transforms it into engineering - systematic, testable, and reproducible.

By treating prompts as code, you gain the same benefits that version control brought to software development: collaboration, history, rollbacks, and systematic improvement.

Getting Started

Implementing Factor 2 doesn't require complex frameworks. Start simple:

1. Extract all prompts from configuration into explicit constants
2. Version these prompts alongside your code
3. Create a simple system for switching between prompt versions
4. Track which prompts are used in production

The key is visibility. When every team member can see, understand, and improve your prompts, your AI systems become truly maintainable.

Conclusion

Hidden prompts are technical debt. They make debugging harder, improvement slower, and collaboration impossible. By owning your prompts - making them explicit, versioned, and testable - you transform AI development from guesswork into engineering.

The next time you're building an AI agent, ask yourself: can I see exactly what instructions it's receiving? If not, it's time to take ownership of your prompts.

Want to see Factor 2 in action? Check out the complete working example.