Free Intensive Nov 21–22Free 2-day hands-on Vibecoding Intensive on Nov 21–22 at 16:00 MSK (Sat–Sun) · Live Cohort 3 starts Nov 23Join Free →Cohort 3 (Nov 23)
ReleaseInsight · On RadarHabr AI→ original

A team moved 203 KB of prompts out of PHP code and into YAML — a third of the codebase

A PHP project team keeps 203 KB of prompts, roughly a third of its total PHP code, in YAML files in Git rather than in the code itself. Previously, prompts were edited in the admin panel, and production drifted from staging with no change history. Now a single file holds the text, the model, the temperature and the response format, and the code calls such a "capability" by name. The takeaway: version prompts like code, together with their generation parameters.

AI-processed from Habr AI; edited by Hamidun News
A team moved 203 KB of prompts out of PHP code and into YAML — a third of the codebase
Source: Habr AI. Collage: Hamidun News.
Listen to article
Article Fact Sheet & Key Figures
ParameterDetails
Primary sourceHabr AI ↗
Editor-in-Chief
Key metric #1User data is substituted with str_replace after Blade rendering
Semantic retries2 attempts; network retries: 3 with increasing backoff
Key metric #3In production, only errors are written to the log, because requests contain user conversations

Where to store prompts is a question every team building a product on an LLM faces sooner or later. One PHP project answered it radically: the repository holds 203 kilobytes of prompts, roughly a third of all its PHP code. Yet the code itself contains no prompts at all.

Everything lives in YAML files (a simple text format for configs) that go through review, are versioned in Git and ship together with the release. The project is under NDA, so the author invented example prompts around a support-bot scenario, but the file structure, the processing code and the pitfalls are real. Along the way it became clear that "moving a prompt into a config" is not a single decision but a dozen small ones, and each is easy to get wrong.

Why not in code or in an admin panel

A prompt in code means a deployment just to change a comma. But prompts have a specific trait: they are edited not by the developer but by the person responsible for the quality of the model's answers. They tweak a phrasing, look at the output, roll back, try something else. The cycle is measured in hours, not sprints.

The obvious answer is an editable field in an admin panel. The team did exactly that in the first version and got the typical result: the production prompt differs from the staging one, nobody remembers who changed the paragraph about response format and why, and rollback is possible only from memory. There is no review, no history, and nowhere to look at a diff. Git solves all four problems at the cost of one thing: to change a prompt, you need to be able to make a commit. For this team, that trade-off was acceptable.

The unit of storage became not a line of text but a "capability", for example summarize-ticket. One file holds the provider, the model, the generation parameters, the system and user templates for each language, and the expected response format. The reason is simple: the same text with temperature 0.2 and 0.9 produces two different behaviors. If the temperature lives in code and the text lives in a file, yesterday's result cannot be reproduced. The code calls a capability by name and knows nothing about the model or the provider.

Templates, security and small pitfalls

A prompt is almost never a constant: message history and context get inserted into it. The team did not write its own template engine and instead connected Blade in one line. The trade-off is clear: Blade compiles a template into PHP and executes it, which means the contents of a YAML file are executable code. As long as the files pass review, this is acceptable. But if product managers want to edit prompts directly in the admin panel, a full-featured template engine must not be allowed there: a restricted engine with no code execution and no file system access is required.

The second safeguard is the order of substitution. The trusted template from the repository is rendered first, and only then are user-supplied strings, such as a name, inserted into the finished text with a plain str_replace. If a user's input were passed into the template engine, a person who entered {{ config('app.key') }} as their name would receive the application key in the response.

A few more practical details:

  • Five languages are not just translation. A model behaves differently in Russian: it holds the format less reliably and more often slips into another language, so non-English templates get additions such as a requirement to answer in the target language. A test that "the meaning matches" is useless, while a check that "every locale has the template and the same set of placeholders" is necessary: a translator can easily turn {user} into the word "user".
  • Inside a capability the model is referenced by a short alias, and the full name is stored in the provider's file. When a provider renames a model, one file is edited instead of nine.
  • The YAML stores the name of an environment variable such as ${FAST_CLOUD_KEY}, not the key itself. A real key pasted "just for a minute" stays in Git history forever, so reviewers check for this separately.
  • Quotes around numbers in YAML turn them into strings, and the provider returns a validation error. The team converts the parameters to numbers in code.

Structured responses, retries and logs

Providers differ in how they return structured output, so the config has three levels: a full JSON schema, JSON mode only, and nothing. The system degrades down this ladder. If the provider understands schemas, the schema goes into response_format.

If it supports only JSON mode, the schema is appended as text to the end of the system prompt in the user's language. But that is a request, not a guarantee, so there is a third layer: everything between the first { and the last } is cut from the response, because models love to add "Of course! Here is your answer:".

The result is parsed and validated against the schema. The author admits he resisted this feature for a long time, until he looked at how many responses it rescues.

Retries come in two kinds. A network failure (timeout, 502, dropped connection) is handled by a plain retry with exponential backoff, up to three attempts. A semantic failure (status 200 but an empty string, invalid JSON, or a structure that fails the schema) requires repeating the whole request, and there are exactly two attempts. Each one costs money and the user's waiting time, and if the model fails twice on the same prompt, the problem lies in the prompt or the model, not in bad luck. It is more honest to show an error and log the case.

In production, only errors are logged. First, the request body, which is the system prompt plus the message history, runs to tens of kilobytes per row, and such a table grows faster than anything else. Second, it contains the user's conversation, that is, personal data subject to retention periods and deletion on request. At the same time, errors must be logged: status, provider, model, execution time and details. Otherwise a complaint that "the bot answered nonsense" has to be reconstructed from the user's description.

On testing, the author notes that a model's response is nondeterministic and cannot be checked with an ordinary assertion, but that does not mean there is nothing to check. The practical conclusion for those building LLM products: treat prompts as code, keep generation parameters next to the text, substitute user data after the template engine, and decide in advance how powerful a template engine you are willing to give the people who edit prompts.

Story

Key Questions Answered

Why not in code or in an admin panel?

A prompt in code means a deployment just to change a comma. But prompts have a specific trait: they are edited not by the developer but by the person responsible for the quality of the model's answers. They tweak a phrasing, look at the output, roll back, try something else. The cycle is measured in hours, not sprints. The obvious answer is an editable field in an admin panel.

What are the key details on Templates, security and small pitfalls?

A prompt is almost never a constant: message history and context get inserted into it. The team did not write its own template engine and instead connected Blade in one line. The trade-off is clear: Blade compiles a template into PHP and executes it, which means the contents of a YAML file are executable code. As long as the files pass review, this is acceptable.

What are the key details on Structured responses, retries and logs?

Providers differ in how they return structured output, so the config has three levels: a full JSON schema, JSON mode only, and nothing. The system degrades down this ladder. If the provider understands schemas, the schema goes into response_format. If it supports only JSON mode, the schema is appended as text to the end of the system prompt in the user's language.

ZK
Zhemal Khamidun — CPO at Alpina Digital, product manager of AlpinaGPT. Building AI products since 2019. Hamidun News is a pet project that grew into a production aggregator with 6,000+ readers.
✦ Unified AI Workspace · Nomad

Test Frontier LLMs & Autonomous Agents in One Workspace

Run Claude Opus 5.5, GPT-6, Gemini 3.1, and DeepSeek side-by-side in Nomad AI (nomadnet.ai) — unified model routing, deep research, and multimodal workflows under one subscription.

Try Nomad AI →Launch Nomad Agent
What do you think?
Loading comments…