Prompt files are special text files (typically named `.aider.prompt.org` by default) that automatically enable `aidermacs-minor-mode` when opened. They serve as a dedicated space to compose and store prompts that you want to send to Aider.
## When are prompt files useful?
Prompt files are particularly helpful in these scenarios:
1. **Complex multi-line prompts**: When you need to craft detailed instructions that span multiple lines
2. **Repeatable workflows**: For commands you use frequently across different sessions
3. **Incremental refinement**: When iteratively improving prompts through multiple attempts
4. **Session documentation**: To keep a record of important prompts and their context
5. **Collaborative work**: When sharing prompt strategies with teammates
## How to use prompt files
1. **Create a prompt file**: Use `M-x aidermacs-open-prompt-file` which will create `.aider.prompt.org` in your project root if it doesn't exist
2. **Write your prompts**: The file automatically enables special keybindings:
- `C-c C-n` or `C-<return>`: Send current line or selected region line by line
- `C-c C-c`: Send entire block or selected region as a whole
- `C-c C-z`: Switch to the Aidermacs buffer
3. **Organize with org-mode**: The file uses org-mode, so you can use headings, lists, and other org features to organize your prompts
## Task-based Org Mode Workflow
One particularly effective approach is to utilize Org mode's task management features together with Aidermacs prompt files:
### 1. Structure your work with Org headings
```org
* Project: Add user authentication
** TODO Implement login form
** TODO Set up authentication API
** TODO Add session management
** TODO Create user profile page
```
### 2. Add detailed specifications under each task
```org
* Project: Add user authentication
** TODO Implement login form
We need a login form with the following:
- Username and password fields
- "Remember me" checkbox
- Forgot password link
- Form validation for required fields
- Error message display
Create a responsive login form component using our existing UI library. Make sure to include client-side validation and error handling.
```
### 3. Use keybindings to send each task individually
1. Position your cursor on the line with your prompt
2. Use `C-c C-n` to send just that line
3. Or select multiple lines and use `C-c C-c` to send the entire selection
### 4. Track progress with TODO states
As tasks are completed, update their status:
```org
* Project: Add user authentication
** DONE Implement login form
** IN-PROGRESS Set up authentication API
** TODO Add session management
** TODO Create user profile page
```
### 5. Document AI responses
You can capture key insights from the AI's responses directly in your prompt file:
```org
* Project: Add user authentication
** DONE Implement login form
The AI suggested using formik for validation, which worked well.
Key components created:
- LoginForm.js
- FormValidation.js
- AuthContext.js
```
### 6. Create templates for common prompts
Store templates for frequently used prompt patterns:
```org
* Templates
** Code review template
Please review the following code for:
1. Performance issues
2. Security vulnerabilities
3. Best practices
4. Readability and maintainability
```
## Questions to ask when considering prompt files
1. **Is this a one-off question or a recurring pattern?** Prompt files are more valuable for recurring patterns.
2. **Does my prompt need careful crafting?** Complex prompts benefit from the edit-before-send approach of prompt files.
3. **Am I iterating on a particular problem?** If you're refining prompts through multiple attempts, a prompt file helps track your progress.
4. **Am I working with a team?** Prompt files can document effective prompting strategies for others.
5. **Do I need to reference this prompt later?** Prompt files create a record of your interactions that you can revisit.
6. **Would my workflow benefit from task tracking?** If you're managing multiple tasks with the AI, the Org mode + prompt file approach provides structure and organization.
## Benefits of the Org Mode + Prompt File Approach
- **Structured planning**: Break down complex problems into manageable tasks
- **Sequential execution**: Work through tasks in a logical order
- **Progress tracking**: Clearly see which tasks are complete and which remain
- **Documentation**: Maintain a record of the development process
- **Collaboration**: Share your task list and prompting approach with teammates
- **Refinement**: Easily revise prompts based on previous results
## The `{aidermacs ... aidermacs}` Syntax
In Aidermacs, you might notice the syntax `{aidermacs ... aidermacs}` being used for multiline messages. This is an implementation of Aider's multiline message feature, specifically using a custom tag.
## Aider's Multiline Message Options
According to the Aider documentation, there are two ways to enter multiline messages:
1. **Simple Braces**: Enter `{` alone on the first line to start a multiline message and `}` alone on the last line to end it.
2. **Tagged Braces**: Start with `{tag` (where "tag" is any sequence of letters/numbers) and end with `tag}`. This is particularly useful when your message needs to include closing braces `}`.
## How Aidermacs Uses This Feature
Aidermacs implements the tagged braces approach, using `aidermacs` as the tag. This allows you to send complex, multiline messages to Aider without the message being prematurely terminated by any closing braces that might appear in your code or text.
### Example Usage
```
{aidermacs
Here is a complex message that might include code with braces:
function example() {
if (condition) {
return true;
} else {
return false;
}
}
Please improve this code.
aidermacs}
```
### Behind the Scenes
In the Aidermacs codebase, you'll find this functionality in the `aidermacs--process-message-if-multi-line` function, which checks if a message contains newlines and isn't already wrapped in the `{aidermacs...aidermacs}` tags. If both conditions are true, it automatically wraps the message for you.