Record Prompt

Intent

Get the model to write down what you should have told it, for it to do the job correctly the first time.

Motivation

The code or text that an agent generates in response to a prompt often differs from your expectation, in small or large ways. One source of such deviation is that the agent’s language model is trained on a wide variety of data, so it’s likely to generate a “median” way of doing things that doesn’t meet your particular expectations, or that isn’t compatible with your team’s rules, cultural norms, or way of working. Another is that your prompt might be ambiguous; there are things you “just know” about your code, or your customers, or your problem, that you don’t think to add to the prompt.

These factors might be things you think obvious and don’t need to write down; for example, tacit knowledge that your team or community of practice shares without verbalising. Alternatively, they might be things you don’t consciously think of when you’re designing a solution to your problem. They might represent different approaches to solving the problem that you’re familiar with, and choose not to use in this circumstance. Finally, they might represent factors you hadn’t thought of in your mental model of the problem you’re working on.

Identifying and addressing all of these factors before you prompt the agent is at best difficult, and time-consuming. At worst, it can be impossible, because you might not be aware of certain problems before they arise.

Carry out a “conversation” with the agent in a session; generate candidate output, review it, suggest improvements, and provide corrections. When you reach a satisfactory state, instruct the model to generate a prompt that captures the decisions made during the session.

Applicability

Use Record Prompt when you want to prompt an agent to perform a task that’s difficult to specify exactly, or for which there is a lot of variance in implementation. If your idea of correct output is “I’ll know it when I see it”, explore the problem, apply You Review to think about what success looks like, and use Record Prompt to capture your findings.

Record Prompt applies even in situations where you retroactively discover hidden complexity in specifying a task. In these situations, you provide a prompt to an agent and the generated response isn’t what you expect, or you have to Intervene to put the agent on the right track. Apply You Reflect or Model Reflects to understand why your expectation wasn't met, steer the model towards a better response, then Record Prompt to document the preferred approach.

You only need to Record Prompt when you expect to use the Recorded Prompt to complete similar tasks. To keep a log of the decisions you made for documentation or review purposes, use Remember What We Did instead.

Consequences

Record Prompt offers the following benefits:

• Iteratively develop a prompt that captures the details of your task.
• Explore ambiguities and assumptions in your understanding of a task.
• Capture review decisions as input for future AI-augmented work.

Implementation

Apply Record Prompt when your first attempt at prompting an agent to complete a task, or generate output, doesn’t go the way you expect. Review the results, potentially asking a model to Disclose Ambiguity to understand why the results diverge from your expectations. Iteratively guide the agent towards a solution you find acceptable. When you have a working solution, prompt the agent to generate a system prompt for an agent that performs the task you just completed, using the decisions you made during the iterative session, and store the prompt in a file.

Review the prompt that the agent creates, and use it as the system prompt for future iterations of similar tasks.

Example

Writing Better Python

Consider applying this prompt in Mistral Vibe with Devstral 2 to generate a script for syncing data between two services:

Use 'bd' for task tracking. Create a python3 tool that searches for text notes on items in a specified Zotero collection, and syncs them to notes in a specified Evernote notebook. Initially, only sync in that direction; don't update Zotero notes based on the content of notes in Evernote.

For any Zotero item that has text notes, find a stable identifier for the Zotero item: preferably the DOI; if that doesn't exist, then the ISBN (and chapter number if the item is a book chapter, not a book); if neither exist, create a "citation key" from the first author's surname, year of publication, and title, and use that. Find a note in the Evernote notebook that has that identifier as its tag, and if there isn't one, create one with that tag and use the item's title and author list as the title of the note. Copy the content of text notes from the Zotero item to the Evernote note.

Use modern python 3.14 practices, and use poetry as your dependency manager. Install flake8 and make sure your code passes its default rules with no warnings or errors. Create tests that use the unittest library and that verify the behaviour of your production code.

I my attempt, the agent made a few mistakes. The first was that it tried to create tests that used the real Evernote and Zotero APIs, at which point I had to Intervene to tell it to use Test Doubles. The second was that it generated a lot of code that doesn't conform with the PEP 8 style guide, so that using the flake8 linter filled its context, slowing the model down and increasing the risk of inattention to important issues.

After correcting these issues, I provided the agent with the following prompt:

Create a system prompt for an agent that writes high-quality, well-tested python3 code, using the code in this project as an exemplar. Give the agent rules that help it avoid flake8 issues, including overlong lines (maximum 79 chars) and incorrectly using f-strings. The agent needs to create test doubles for external integrations so that the tests don't depend on external services and API keys. Write the prompt to a new file, python-coder.md.

This is the system prompt that the agent generated:

# Python Coder Agent System Prompt

## Role
You are an expert Python developer specializing in writing high-quality, well-tested Python 3 code. You follow best practices and maintain strict adherence to coding standards.

## Coding Standards

### General Rules
- Write clean, readable, and maintainable Python 3 code
- Follow PEP 8 style guide strictly
- Use type hints appropriately for better code clarity and IDE support
- Write comprehensive docstrings following Google style
- Keep functions small and focused (single responsibility principle)
- Use meaningful variable and function names
- Avoid magic numbers - use named constants instead

### Line Length (Flake8 Compliance)
- **Maximum line length: 79 characters**
- Break long lines appropriately using parentheses or backslashes
- For function calls with many arguments, use one argument per line if it improves readability
- When breaking lines, align continuation lines with the opening delimiter or use hanging indents

[...more...]

Source code available at python-coder.md.

The new prompt captures what I learned about interacting with the agent on Python code from the coding session, so that the agent is less likely to make the same mistakes if I use this prompt in future sessions.

Related Patterns

Use Disclose Ambiguity to identify areas of the task to clarify before you Record Prompt.

When you Intervene, Record Prompt to account for your intervention in future work.

You Review and Model Reviews the generated output, comparing it with your initial prompt to find situations where your instructions need strengthening, or contains gaps.

You Reflect to consider whether you're relying on tacit assumptions or local conventions in your expectations of the task you Record Prompt for.

After you Extract Prompt, you can Record Prompt to improve the Extracted Prompt.