APAW/.kilo/rules/prompt-engineering.md

# Prompt Engineering Rules

Guidelines for crafting effective prompts for AI agents.

## General Principles

### Be Clear and Specific

- Clearly state what you want the agent to do
- Avoid ambiguity and vague instructions
- Include specific file paths, function names, and line numbers when relevant

**Bad:** Fix the code.
**Good:** Fix the bug in the `calculateTotal` function that causes it to return incorrect results when cart is empty.

### Provide Context

- Use context mentions (`@/path/to/file`) to refer to specific files
- Include relevant code snippets or error messages
- Reference related issues or previous changes

**Good:** `@/src/utils.ts` Refactor the `calculateTotal` function to use async/await instead of callbacks.

### Break Down Tasks

- Divide complex tasks into smaller, well-defined steps
- Use numbered lists for multi-step instructions
- Specify the order of operations

**Good:**
```
1. First, analyze the current implementation
2. Identify performance bottlenecks
3. Refactor the main loop to use caching
4. Add unit tests for the new implementation
5. Verify the changes don't break existing tests
```

### Give Examples

- If you have a specific coding style in mind, provide examples
- Show the expected input/output format
- Include code snippets that demonstrate the pattern

### Specify Output Format

- If you need output in a particular format, specify it
- Common formats: JSON, Markdown, TypeScript interfaces
- Include example structure when necessary

## Thinking vs. Doing

Guide agents through a "think-then-do" process:

### Analyze Phase
Ask the agent to analyze the current code, identify problems, or plan the approach.

**Prompt Pattern:**
```
Analyze the current implementation of [feature].
Identify:
- Potential issues
- Areas for improvement
- Security vulnerabilities
```

### Plan Phase
Have the agent outline the steps it will take to complete the task.

**Prompt Pattern:**
```
Before making any changes, provide a plan:
1. What files will be modified
2. What functions will be added/changed
3. What dependencies are needed
4. What tests should be written
```

### Execute Phase
Instruct the agent to implement the plan, one step at a time.

**Prompt Pattern:**
```
Now implement the plan:
1. Start with [first step]
2. Then [second step]
...
```

### Review Phase
Carefully review the results of each step before proceeding.

**Prompt Pattern:**
```
Review the changes:
- Do they meet the requirements?
- Are there any side effects?
- Do the tests pass?
```

## Custom Instructions

### Global Custom Instructions

Apply to all agents and modes. Place in `.kilo/rules/global.md` or `AGENTS.md`.

**Examples:**
- Enforce coding style guidelines
- Specify preferred libraries
- Define project-specific conventions

### Mode-Specific Custom Instructions

Apply only to specific agents. Place in `.kilo/agents/[agent].md`.

**Examples:**
- Lead Developer: "Always write tests before code (TDD)"
- Code Skeptic: "Check for security vulnerabilities first"
- Frontend Developer: "Use Tailwind CSS for all styling"

## Handling Ambiguity

### When Request is Unclear

The agent should:

1. **Ask clarifying questions** using the `question` tool
2. **Not make assumptions** without user confirmation
3. **Provide options** for the user to choose from

**Example:**
```
I need clarification:
- Option A: Implement as a new module
- Option B: Add to existing service
- Option C: Create a separate microservice
```

### Providing Multiple Options

When presenting choices:
- Use clear, concise labels
- Provide descriptions for each option
- Recommend a default choice
- Allow custom input

## Providing Feedback

### Rejecting Actions

When the agent proposes an incorrect action:

1. Explain *why* the action is wrong
2. Provide the correct approach
3. Give an example if helpful

**Example:**
```
This approach won't work because [reason].
Instead, use [correct approach].
Here's an example: [code snippet]
```

### Rewording Requests

If initial prompt doesn't produce desired results:

1. Be more specific about requirements
2. Add constraints or boundaries
3. Provide examples of expected output
4. Break into smaller sub-tasks

## Prompt Patterns

### Feature Request Pattern

```markdown
## Feature: [Feature Name]

### Requirements
1. [Requirement 1]
2. [Requirement 2]

### Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]

### Files to Modify
- `path/to/file1.ts`
- `path/to/file2.ts`

### Constraints
- Use [library/framework]
- Follow [pattern/style]
- Must be backward compatible
```

### Bug Fix Pattern

```markdown
## Bug: [Bug Description]

### Current Behavior
[What's happening now]

### Expected Behavior
[What should happen]

### Steps to Reproduce
1. [Step 1]
2. [Step 2]

### Files Involved
- `path/to/file.ts` (line X)

### Error Message
```
[Stack trace or error message]
```
```

### Refactoring Pattern

```markdown
## Refactor: [What to Refactor]

### Current Implementation
[Brief description or code snippet]

### Target Implementation
[What it should become]

### Reason
[Why this refactoring is needed]

### Files to Update
- [File list]

### Requirements
- Maintain existing functionality
- Keep tests passing
- Update documentation
```

## Examples

### Good Prompts

**Feature Implementation:**
> `@/src/components/Button.tsx` Refactor the `Button` component to support three variants: primary, secondary, and danger. Use the design tokens from `@/src/styles/tokens.ts`.

**Bug Fix:**
> `@problems` Fix the TypeError in `calculateTotal` when the cart is empty. The function should return 0 for empty arrays.

**Architecture:**
> Create a new service for handling user notifications. Follow the pattern in `@/src/services/EmailService.ts`. The service should support email, SMS, and push notifications.

### Bad Prompts

**Too Vague:**
> Fix the button. (What's wrong with it?)

**No Context:**
> Write some Python code. (What should it do?)

**Too Broad:**
> Fix everything. (What is "everything"?)

**No Constraints:**
> Create a new feature. (What feature? For what?)

## Prompt Anti-Patterns

### Avoid These Patterns

1. **Kitchen Sink Prompts**
   - Asking for too many things at once
   - Better: Break into multiple focused prompts

2. **Missing Constraints**
   - Not specifying required libraries or patterns
   - Better: Always mention relevant constraints

3. **Assuming Knowledge**
   - Expecting the agent to know project context
   - Better: Provide `@file` references

4. **Ignoring Output**
   - Not reviewing agent's changes
   - Better: Always review and provide feedback

5. **No Iteration**
   - Accepting first result without refinement
   - Better: Iterate on prompts for better results

## Context Mentions

Use context mentions to provide specific file references:

| Mention | Description |
|---------|-------------|
| `@file.js` | Reference a specific file |
| `@/src/utils/` | Reference a directory |
| `@problems` | Reference all errors in the file |
| `@git` | Reference git history |
| `@terminal` | Reference terminal output |

## Iterative Prompting

When initial results aren't perfect:

1. **Identify Issues:** What's wrong with the current output?
2. **Clarify Requirements:** Add more specific instructions
3. **Provide Examples:** Show the expected format or pattern
4. **Break Down:** Split complex tasks into smaller ones
5. **Refine:** Adjust constraints or add context

## Verification Checklist

After receiving agent output:

- [ ] Does it meet all stated requirements?
- [ ] Are there any syntax errors?
- [ ] Does it follow project conventions?
- [ ] Are edge cases handled?
- [ ] Is it backward compatible?
- [ ] Are tests included/updated?
- [ ] Is documentation updated?