The prompt is a file, not a string

Where the prompt ends up

In the generated route, the system prompt is a string literal three lines above the fetch call. It gets edited in place, by you and by the agent, and nobody can say afterwards which version produced which output. When the feature degrades (and it will, because somebody tightens a sentence to fix one case and breaks three others) there is no record of what the prompt was on the day it worked.

A prompt is a piece of the program that changes the program’s behaviour. Treat it like one.

One file per prompt

prompts/
  summarise.md
  categorise-expense.md
  reply-suggestion.md

Plain markdown, read at startup or imported as a string. The file is in git, so every change has a commit, a message and a diff; git log -p prompts/summarise.md is the history of the feature’s behaviour, and the bisecting technique from the breaking block applies to prompts as well as to code.

Keep placeholders explicit and visible:

You summarise notes for a small business owner.
Write at most {{max_sentences}} sentences.
Use the same language as the note.
Do not add information that is not in the note.

Fill them with a small template function rather than string concatenation scattered through the route. The note itself does not go into the template; it goes in the user message, for reasons the next lesson makes concrete.

Stamp the version into the log

Every call should log which prompt produced it. A short hash of the file content, or the git commit of the prompts folder, stored beside the input, the output and the token count:

log.info({ feature: "summarise", promptHash, model, inputTokens, outputTokens, ms });

That one line is what makes “it got worse on Thursday” answerable. Without it, the log shows outputs and no way to group them by cause. The evaluation course covers what to do with such logs at scale; here the point is that the line exists.

Changing a prompt is a change

Edit it on a branch. Run the fixed set of inputs (the later lesson on whether the feature is good sets that up) against the old and new versions, side by side. Merge when the new one is better on the set, not when it fixed the one example that prompted the edit. Prompts drift towards handling the last complaint at the expense of the general case, and the fixed set is the only thing that notices.

Keep the file short enough to read in one screen. A prompt that has grown to two pages of rules contradicts itself somewhere, and the model resolves the contradiction differently on different days. When a rule is added, look for one that can be removed.

What the model does with the file

The system prompt is text the model reads before the user’s message. It is not a configuration the model enforces. “Never mention competitors” is a request the model will honour most of the time, and a well-phrased user message can talk it out of it. The prompting course covers how to write these well; the app builder’s version is one sentence: rules in the prompt shape behaviour, and anything that must be true is checked in code afterwards, not requested in prose.

Secrets do not go in the prompt

A system prompt is delivered to the model, and models repeat their system prompts when asked nicely enough. Nothing in the file should be something you would mind a user reading: no keys, no internal URLs, no “the discount code for staff is”. Assume the file is public and write it so that being public costs nothing.

The agent and the prompt

An agent asked to “make the summaries better” will edit the prompt, and it will do so with the same confidence it edits code, adding rules for the case at hand. Point it at the fixed-set script and ask for a before-and-after, the same way you would ask for a passing test. A prompt change with no measurement is a guess, whoever made it.