gh-hikanner-agent-skills-prompt-optimizer/skills/prompt-optimizer/references/prompt-best-practices.md

# Prompt Engineering Best Practices

This reference document contains comprehensive best practices for crafting effective prompts for AI models like Claude.

## Core Principles

### 1. Be Clear and Direct

**Principle:** Tell the model explicitly what is wanted, without assuming it will infer the intent.

**Why it matters:** Modern AI models follow instructions literally. Vague requests lead to generic or misaligned outputs.

**Examples:**

**Poor:** "Create an analytics dashboard"
- Problem: No clarity on scope, features, or requirements

**Better:** "Create an analytics dashboard. Include as many relevant features and interactions as possible"
- Improvement: Specifies scope and expectations

**Poor:** "Write a summary"
- Problem: Unclear about length, focus, or audience

**Better:** "Write a 3-paragraph executive summary highlighting key financial metrics and strategic recommendations for C-level executives"
- Improvement: Defines length, focus, and audience

### 2. Provide Context and Motivation

**Principle:** Explain WHY certain requirements matter to help the AI understand the underlying goal.

**Why it matters:** Context helps the AI make better decisions when facing ambiguous situations or trade-offs.

**Examples:**

**Less effective:** "NEVER use bullet points"
- Problem: Sounds arbitrary, AI doesn't understand the reasoning

**More effective:** "I prefer responses in natural paragraph form rather than bullet points because I find flowing prose easier to read and more suitable for formal reports"
- Improvement: Explains the reasoning, helps AI understand when to apply this preference

**Less effective:** "Use simple language"
- Problem: Vague definition of "simple"

**More effective:** "Use simple language suitable for a general audience without technical background, as this content will be published in a consumer-facing blog"
- Improvement: Defines audience and purpose

### 3. Be Specific with Requirements

**Principle:** Provide concrete details about constraints, requirements, and desired outcomes.

**Why it matters:** Specificity reduces ambiguity and ensures outputs match expectations.

**Examples:**

**Vague:** "Create a meal plan for a Mediterranean diet"
- Problem: No constraints on calories, dietary restrictions, or goals

**Specific:** "Design a Mediterranean diet meal plan for pre-diabetic management. 1,800 calories daily, emphasis on low glycemic foods, avoid processed sugars, include 5-6 small meals throughout the day"
- Improvement: Defines medical context, caloric target, food restrictions, and meal frequency

**Vague:** "Analyze this code for issues"
- Problem: Unclear what types of issues to focus on

**Specific:** "Analyze this Python code for security vulnerabilities, focusing on SQL injection risks, XSS vulnerabilities, and improper input validation. Also check for performance bottlenecks in database queries"
- Improvement: Specifies analysis focus areas

### 4. Use Examples (Few-Shot Learning)

**Principle:** Show concrete examples of desired input-output patterns.

**Why it matters:** Modern models like Claude 4.x pay close attention to examples, often more than written instructions.

**Structure:**
```
[Task description]

Example 1:
Input: [example input]
Output: [example output]

Example 2:
Input: [example input]
Output: [example output]

Now process:
Input: [actual input]
```

**Use cases:**
- Defining output format
- Establishing tone and style
- Showing edge case handling
- Demonstrating complex transformations

### 5. Allow Expression of Uncertainty

**Principle:** Explicitly permit the AI to say "I don't know" rather than guessing or fabricating information.

**Why it matters:** Prevents hallucination and builds trust through honesty.

**Examples:**

**Standard prompt:** "What was the Q4 revenue for Company X?"
- Problem: AI may fabricate numbers if data is unavailable

**Better prompt:** "What was the Q4 revenue for Company X? If the data is insufficient to draw conclusions, say so rather than speculating"
- Improvement: Explicitly permits uncertainty

**Standard prompt:** "Analyze this medical report"
- Problem: AI may overreach its capabilities

**Better prompt:** "Analyze this medical report. Focus on factual observations from the data. If any medical interpretation requires expertise beyond pattern recognition, clearly state that and recommend consulting a medical professional"
- Improvement: Sets boundaries and encourages appropriate caution

## Advanced Techniques

### 1. Prefill (Response Priming)

**Technique:** Start the AI's response to guide format, tone, or structure.

**Use cases:**
- Forcing specific output formats (JSON, XML)
- Eliminating preamble text
- Establishing tone immediately
- Starting with specific phrases

**Example - JSON Output:**
```
User: Extract the name and price from this product description into JSON.
Assistant: {
```

Result: The AI continues directly with JSON, no preamble.

**Example - Direct Answer:**
```
User: What's the capital of France?
Assistant: The capital is
```

Result: AI completes with "Paris" instead of adding "The capital of France is Paris"

### 2. Chain of Thought (Step-by-Step Reasoning)

**Technique:** Request explicit step-by-step reasoning before the final answer.

**Why it matters:** Improves accuracy on complex reasoning tasks, makes logic transparent.

**Three approaches:**

**a) Basic Chain of Thought:**
```
Solve this problem step-by-step: [problem]
```

**b) Guided Chain of Thought:**
```
Analyze this contract clause. Follow these reasoning stages:
1. Identify the key obligations
2. Note any ambiguous language
3. Assess potential risks
4. Provide final interpretation
```

**c) Structured Chain of Thought:**
```
Solve this problem. Use this format:

<reasoning>
[Your step-by-step thinking]
</reasoning>

<answer>
[Your final answer]
</answer>
```

### 3. Control Output Format

**Principle:** Explicitly specify the desired output structure.

**Guidelines:**
- Tell the AI what TO do, not what NOT to do
- Match prompt style to desired output style
- Use prefilling for strict format requirements
- Provide format examples

**Examples:**

**For structured data:**
```
Extract key information in this JSON format:
{
  "company": "string",
  "revenue": "number with currency",
  "year": "YYYY"
}
```

**For analytical reports:**
```
Provide analysis in this structure:
1. Executive Summary (2-3 sentences)
2. Key Findings (bullet points)
3. Detailed Analysis (paragraphs)
4. Recommendations (numbered list)
```

### 4. Prompt Chaining

**Technique:** Break complex tasks into sequential prompts where each builds on previous outputs.

**Why it matters:**
- Improves quality by focusing on one aspect at a time
- Allows intermediate verification
- Enables iterative refinement

**Example - Research Summary:**

**Prompt 1:** "Summarize the key findings from this 50-page research paper"
**Prompt 2:** "Review this summary for accuracy. Identify any misrepresentations or missing critical points"
**Prompt 3:** "Based on the review feedback, create an improved summary"

**Example - Code Review:**

**Prompt 1:** "Analyze this code for security vulnerabilities"
**Prompt 2:** "Now review the same code for performance issues"
**Prompt 3:** "Based on both analyses, prioritize the issues and suggest an implementation order"

## Common Patterns to Avoid

### 1. Over-Constraining with Roles

**Problem:** Overly specific role definitions can limit helpfulness.

**Poor:** "You are a Senior Java Enterprise Architect with exactly 15 years of experience who only uses Spring Boot and refuses to discuss other frameworks"
- Too rigid, may prevent useful suggestions

**Better:** "Provide architectural guidance for a Java Spring Boot application, focusing on enterprise-scale best practices"
- Provides context without unnecessary constraints

### 2. Assuming Mind-Reading

**Problem:** Leaving requirements implicit rather than explicit.

**Poor:** "Make it better"
- AI doesn't know what "better" means in this context

**Better:** "Improve code readability by: adding descriptive variable names, extracting complex logic into well-named functions, and adding explanatory comments for non-obvious algorithms"
- Explicitly defines improvement criteria

### 3. Negative Instructions

**Problem:** Telling AI what NOT to do is less effective than saying what TO do.

**Less effective:** "Don't be too technical, don't use jargon, don't make it too long"

**More effective:** "Use conversational language suitable for a general audience, explain concepts with everyday analogies, keep the response under 300 words"

### 4. Over-Engineering

**Problem:** Using all advanced techniques when simple clarity would suffice.

**When to use simple prompts:** Single-step tasks, straightforward requests, well-defined operations

**When to use advanced techniques:** Multi-step reasoning, complex analysis, tasks requiring specific formats, ambiguous requirements

## Troubleshooting Guide

### Response is too generic
**Solutions:**
- Add specific constraints and requirements
- Provide concrete examples
- Include context about the use case
- Specify the audience and purpose

### AI goes off-topic
**Solutions:**
- State the objective more clearly at the beginning
- Provide more context about the goal
- Break complex requests into smaller prompts
- Use structured output format

### Format is inconsistent
**Solutions:**
- Add explicit format examples
- Use prefilling to start the response
- Provide a template or schema
- Use structured tags (e.g., `<answer>`, `<reasoning>`)

### Includes unnecessary preamble
**Solutions:**
- Use prefilling to skip straight to content
- Add explicit instruction: "Begin directly with [content type], no introduction"
- Provide example that starts immediately with content

### Task is too complex
**Solutions:**
- Use prompt chaining to break into steps
- Apply chain of thought reasoning
- Create a multi-stage workflow
- Simplify the request scope

### Contains fabricated information
**Solutions:**
- Explicitly permit expressions of uncertainty
- Request citations or source attribution
- Ask for confidence levels
- Request "I don't know" when data is insufficient

## Quality Checklist

Before finalizing a prompt, verify:

- [ ] **Clarity:** Is the request unambiguous?
- [ ] **Specificity:** Are constraints and requirements concrete?
- [ ] **Context:** Does the AI understand WHY this matters?
- [ ] **Examples:** Are there examples for complex or ambiguous requirements?
- [ ] **Format:** Is the desired output structure clear?
- [ ] **Uncertainty:** Is the AI permitted to express limitations?
- [ ] **Scope:** Is the task appropriately scoped (not too complex)?
- [ ] **Tone:** Is the desired communication style specified?
- [ ] **Success criteria:** Is it clear what constitutes a good output?

## Decision Framework

Use this flowchart to select appropriate techniques:

1. **Is the request clear and specific?**
   - No → Add clarity, specificity, context
   - Yes → Continue

2. **Is the task simple and straightforward?**
   - Yes → Use basic clear prompt
   - No → Continue

3. **Is a specific format required?**
   - Yes → Add format specification or prefilling
   - No → Continue

4. **Is the task complex or multi-faceted?**
   - Yes → Consider prompt chaining
   - No → Continue

5. **Does it require reasoning or analysis?**
   - Yes → Use chain of thought
   - No → Use basic prompt

6. **Are there ambiguous or nuanced requirements?**
   - Yes → Add examples (few-shot)
   - No → Proceed with current prompt