Writing Maintainable AI Prompts in Rails with Promptly

A few months ago, I was helping a Rails team add AI-generated onboarding emails to their app. It seemed simple at first: drop an OpenAI.chat(...) call inside a mailer, pass in the user’s name, and let the model draft a warm welcome.

By the second week, things got messy.

Different controllers and jobs had their own inline prompts.

Some prompts were copy-pasted with slight tweaks (“friendly tone”, “professional tone”, etc.).

Marketing wanted localized versions for Spanish and Portuguese.

QA asked, “How do we know the prompts didn’t change by accident?”

We ended up with prompt spaghetti—hard to test, impossible to translate cleanly, and brittle whenever we tried to refactor.

That experience sparked the idea for Promptly: a small gem that brings Rails conventions to AI prompt management.

The Problem: Prompts Don’t Belong Scattered in Code

Rails developers already know the pain of hard-coded strings—why we use views, partials, and I18n instead of littering messages across controllers. Yet many of us are now hardcoding AI prompts directly in service objects or background jobs.

It doesn’t scale.

• Duplication: The same wording lives in multiple places.


• Localization headaches: Inline strings don’t play well with I18n.


• No safety net: Refactors can silently change how the AI behaves.

The Solution: Promptly

Promptly lets you define AI prompts as ERB or Liquid templates, stored in a Rails-native directory structure. Just like you’d render a view, you render a prompt:

# app/prompts/welcome_email.erb

Hello <%= @user.name %>, welcome to our service!

We’re excited to have you join.



# In your mailer or service:

render_prompt("welcome_email", user: @user)

This unlocks the same benefits Rails developers already rely on elsewhere:

• 
  Maintainability → All prompts live in one place.


• 
  Localization → Templates can use I18n just like views.


• 
  Testability → You can write RSpec tests that assert on rendered prompt output.

Why Rails Conventions Matter

Rails has always thrived on convention over configuration. Promptly doesn’t reinvent the wheel; it extends familiar concepts (views, templates, helpers) into the AI space.

• Instead of partials, you have prompt templates.


• Instead of locals, you have prompt variables.


• Instead of ad-hoc strings, you have structured, versionable files.

Getting Started

1. Add it to your Gemfile:
   

gem 'promptly'

2.Create your first template in app/prompts.

3.Render it anywhere with render_prompt.

4.Add tests to verify the output.

Full docs are in the GitHub repo.

Looking Ahead

Promptly is intentionally small. It’s not trying to be a full-blown AI orchestration platform. But by solving one narrow pain point—making prompts maintainable, testable, and Rails-friendly—it can help Rails apps adopt AI without chaos.

The next steps may include:

• Prompt versioning.


• Preview workflows in Rails consoles.


• Deeper integration with related gems like semantic search adapters.

If you’re a Rails developer experimenting with AI, try Promptly. It may save you from prompt spaghetti before it starts.

Feedback and contributions are welcome, the best ideas usually come from real-world use.