Initial commit with translated description
This commit is contained in:
280
docs/BEST_PRACTICES.md
Normal file
280
docs/BEST_PRACTICES.md
Normal file
@@ -0,0 +1,280 @@
|
||||
# Prompt Engineering Expert - Best Practices Guide
|
||||
|
||||
This document synthesizes best practices from Anthropic's official documentation and the Claude Cookbooks to create a comprehensive prompt engineering skill.
|
||||
|
||||
## Core Principles for Prompt Engineering
|
||||
|
||||
### 1. Clarity and Directness
|
||||
- **Be explicit**: State exactly what you want Claude to do
|
||||
- **Avoid ambiguity**: Use precise language that leaves no room for misinterpretation
|
||||
- **Use concrete examples**: Show, don't just tell
|
||||
- **Structure logically**: Organize information hierarchically
|
||||
|
||||
### 2. Conciseness
|
||||
- **Respect context windows**: Keep prompts focused and relevant
|
||||
- **Remove redundancy**: Eliminate unnecessary repetition
|
||||
- **Progressive disclosure**: Provide details only when needed
|
||||
- **Token efficiency**: Optimize for both quality and cost
|
||||
|
||||
### 3. Appropriate Degrees of Freedom
|
||||
- **Define constraints**: Set clear boundaries for what Claude should/shouldn't do
|
||||
- **Specify format**: Be explicit about desired output format
|
||||
- **Set scope**: Clearly define what's in and out of scope
|
||||
- **Balance flexibility**: Allow room for Claude's reasoning while maintaining control
|
||||
|
||||
## Advanced Prompt Engineering Techniques
|
||||
|
||||
### Chain-of-Thought (CoT) Prompting
|
||||
Encourage step-by-step reasoning for complex tasks:
|
||||
```
|
||||
"Let's think through this step by step:
|
||||
1. First, identify...
|
||||
2. Then, analyze...
|
||||
3. Finally, conclude..."
|
||||
```
|
||||
|
||||
### Few-Shot Prompting
|
||||
Use examples to guide behavior:
|
||||
- **1-shot**: Single example for simple tasks
|
||||
- **2-shot**: Two examples for moderate complexity
|
||||
- **Multi-shot**: Multiple examples for complex patterns
|
||||
|
||||
### XML Tags for Structure
|
||||
Use XML tags for clarity and parsing:
|
||||
```xml
|
||||
<task>
|
||||
<objective>What you want done</objective>
|
||||
<constraints>Limitations and rules</constraints>
|
||||
<format>Expected output format</format>
|
||||
</task>
|
||||
```
|
||||
|
||||
### Role-Based Prompting
|
||||
Assign expertise to Claude:
|
||||
```
|
||||
"You are an expert prompt engineer with deep knowledge of...
|
||||
Your task is to..."
|
||||
```
|
||||
|
||||
### Prefilling
|
||||
Start Claude's response to guide format:
|
||||
```
|
||||
"Here's my analysis:
|
||||
|
||||
Key findings:"
|
||||
```
|
||||
|
||||
### Prompt Chaining
|
||||
Break complex tasks into sequential prompts:
|
||||
1. Prompt 1: Analyze input
|
||||
2. Prompt 2: Process analysis
|
||||
3. Prompt 3: Generate output
|
||||
|
||||
## Custom Instructions & System Prompts
|
||||
|
||||
### System Prompt Design
|
||||
- **Define role**: What expertise should Claude embody?
|
||||
- **Set tone**: What communication style is appropriate?
|
||||
- **Establish constraints**: What should Claude avoid?
|
||||
- **Clarify scope**: What's the domain of expertise?
|
||||
|
||||
### Behavioral Guidelines
|
||||
- **Do's**: Specific behaviors to encourage
|
||||
- **Don'ts**: Specific behaviors to avoid
|
||||
- **Edge cases**: How to handle unusual situations
|
||||
- **Escalation**: When to ask for clarification
|
||||
|
||||
## Skill Structure Best Practices
|
||||
|
||||
### Naming Conventions
|
||||
- Use **gerund form** (verb + -ing): "analyzing-financial-statements"
|
||||
- Use **lowercase with hyphens**: "prompt-engineering-expert"
|
||||
- Be **descriptive**: Name should indicate capability
|
||||
- Avoid **generic names**: Be specific about domain
|
||||
|
||||
### Writing Effective Descriptions
|
||||
- **First line**: Clear, concise summary (max 1024 chars)
|
||||
- **Specificity**: Indicate exact capabilities
|
||||
- **Use cases**: Mention primary applications
|
||||
- **Avoid vagueness**: Don't use "helps with" or "assists in"
|
||||
|
||||
### Progressive Disclosure Patterns
|
||||
|
||||
**Pattern 1: High-level guide with references**
|
||||
- Start with overview
|
||||
- Link to detailed sections
|
||||
- Organize by complexity
|
||||
|
||||
**Pattern 2: Domain-specific organization**
|
||||
- Group by use case
|
||||
- Separate concerns
|
||||
- Clear navigation
|
||||
|
||||
**Pattern 3: Conditional details**
|
||||
- Show details based on context
|
||||
- Provide examples for each path
|
||||
- Avoid overwhelming options
|
||||
|
||||
### File Structure
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (required metadata)
|
||||
├── CLAUDE.md (main instructions)
|
||||
├── reference-guide.md (detailed info)
|
||||
├── examples.md (use cases)
|
||||
└── troubleshooting.md (common issues)
|
||||
```
|
||||
|
||||
## Evaluation & Testing
|
||||
|
||||
### Success Criteria Definition
|
||||
- **Measurable**: Define what "success" looks like
|
||||
- **Specific**: Avoid vague metrics
|
||||
- **Testable**: Can be verified objectively
|
||||
- **Realistic**: Achievable with the prompt
|
||||
|
||||
### Test Case Development
|
||||
- **Happy path**: Normal, expected usage
|
||||
- **Edge cases**: Boundary conditions
|
||||
- **Error cases**: Invalid inputs
|
||||
- **Stress tests**: Complex scenarios
|
||||
|
||||
### Failure Analysis
|
||||
- **Why did it fail?**: Root cause analysis
|
||||
- **Pattern recognition**: Identify systematic issues
|
||||
- **Refinement**: Adjust prompt accordingly
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### Common Mistakes
|
||||
- **Vagueness**: "Help me with this task" (too vague)
|
||||
- **Contradictions**: Conflicting requirements
|
||||
- **Over-specification**: Too many constraints
|
||||
- **Hallucination risks**: Prompts that encourage false information
|
||||
- **Context leakage**: Unintended information exposure
|
||||
- **Jailbreak vulnerabilities**: Prompts susceptible to manipulation
|
||||
|
||||
### Windows-Style Paths
|
||||
- ❌ Use: `C:\Users\Documents\file.txt`
|
||||
- ✅ Use: `/Users/Documents/file.txt` or `~/Documents/file.txt`
|
||||
|
||||
### Too Many Options
|
||||
- Avoid offering 10+ choices
|
||||
- Limit to 3-5 clear alternatives
|
||||
- Use progressive disclosure for complex options
|
||||
|
||||
## Workflows and Feedback Loops
|
||||
|
||||
### Use Workflows for Complex Tasks
|
||||
- Break into logical steps
|
||||
- Define inputs/outputs for each step
|
||||
- Implement feedback mechanisms
|
||||
- Allow for iteration
|
||||
|
||||
### Implement Feedback Loops
|
||||
- Request clarification when needed
|
||||
- Validate intermediate results
|
||||
- Adjust based on feedback
|
||||
- Confirm understanding
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
### Avoid Time-Sensitive Information
|
||||
- Don't hardcode dates
|
||||
- Use relative references ("current year")
|
||||
- Provide update mechanisms
|
||||
- Document when information was current
|
||||
|
||||
### Use Consistent Terminology
|
||||
- Define key terms once
|
||||
- Use consistently throughout
|
||||
- Avoid synonyms for same concept
|
||||
- Create glossary for complex domains
|
||||
|
||||
## Multimodal & Advanced Prompting
|
||||
|
||||
### Vision Prompting
|
||||
- Describe what Claude should analyze
|
||||
- Specify output format
|
||||
- Provide context about images
|
||||
- Ask for specific details
|
||||
|
||||
### File-Based Prompting
|
||||
- Specify file types accepted
|
||||
- Describe expected structure
|
||||
- Provide parsing instructions
|
||||
- Handle errors gracefully
|
||||
|
||||
### Extended Thinking
|
||||
- Use for complex reasoning
|
||||
- Allow more processing time
|
||||
- Request detailed explanations
|
||||
- Leverage for novel problems
|
||||
|
||||
## Skill Development Workflow
|
||||
|
||||
### Build Evaluations First
|
||||
1. Define success criteria
|
||||
2. Create test cases
|
||||
3. Establish baseline
|
||||
4. Measure improvements
|
||||
|
||||
### Develop Iteratively with Claude
|
||||
1. Start with simple version
|
||||
2. Test and gather feedback
|
||||
3. Refine based on results
|
||||
4. Repeat until satisfied
|
||||
|
||||
### Observe How Claude Navigates Skills
|
||||
- Watch how Claude discovers content
|
||||
- Note which sections are used
|
||||
- Identify confusing areas
|
||||
- Optimize based on usage patterns
|
||||
|
||||
## YAML Frontmatter Requirements
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: Clear, concise description (max 1024 chars)
|
||||
---
|
||||
```
|
||||
|
||||
## Token Budget Considerations
|
||||
|
||||
- **Skill metadata**: ~100-200 tokens
|
||||
- **Main instructions**: ~500-1000 tokens
|
||||
- **Reference files**: ~1000-5000 tokens each
|
||||
- **Examples**: ~500-1000 tokens each
|
||||
- **Total budget**: Varies by use case
|
||||
|
||||
## Checklist for Effective Skills
|
||||
|
||||
### Core Quality
|
||||
- [ ] Clear, specific name (gerund form)
|
||||
- [ ] Concise description (1-2 sentences)
|
||||
- [ ] Well-organized structure
|
||||
- [ ] Progressive disclosure implemented
|
||||
- [ ] Consistent terminology
|
||||
- [ ] No time-sensitive information
|
||||
|
||||
### Content
|
||||
- [ ] Clear use cases defined
|
||||
- [ ] Examples provided
|
||||
- [ ] Edge cases documented
|
||||
- [ ] Limitations stated
|
||||
- [ ] Troubleshooting guide included
|
||||
|
||||
### Testing
|
||||
- [ ] Test cases created
|
||||
- [ ] Success criteria defined
|
||||
- [ ] Edge cases tested
|
||||
- [ ] Error handling verified
|
||||
- [ ] Multiple models tested
|
||||
|
||||
### Documentation
|
||||
- [ ] README or overview
|
||||
- [ ] Usage examples
|
||||
- [ ] API/integration notes
|
||||
- [ ] Troubleshooting section
|
||||
- [ ] Update mechanism documented
|
||||
492
docs/TECHNIQUES.md
Normal file
492
docs/TECHNIQUES.md
Normal file
@@ -0,0 +1,492 @@
|
||||
# Advanced Prompt Engineering Techniques
|
||||
|
||||
## Table of Contents
|
||||
1. Chain-of-Thought Prompting
|
||||
2. Few-Shot Learning
|
||||
3. Structured Output with XML
|
||||
4. Role-Based Prompting
|
||||
5. Prefilling Responses
|
||||
6. Prompt Chaining
|
||||
7. Context Management
|
||||
8. Multimodal Prompting
|
||||
|
||||
## 1. Chain-of-Thought (CoT) Prompting
|
||||
|
||||
### What It Is
|
||||
Encouraging Claude to break down complex reasoning into explicit steps before providing a final answer.
|
||||
|
||||
### When to Use
|
||||
- Complex reasoning tasks
|
||||
- Multi-step problems
|
||||
- Tasks requiring justification
|
||||
- When consistency matters
|
||||
|
||||
### Basic Structure
|
||||
```
|
||||
Let's think through this step by step:
|
||||
|
||||
Step 1: [First logical step]
|
||||
Step 2: [Second logical step]
|
||||
Step 3: [Third logical step]
|
||||
|
||||
Therefore: [Conclusion]
|
||||
```
|
||||
|
||||
### Example
|
||||
```
|
||||
Problem: A store sells apples for $2 each and oranges for $3 each.
|
||||
If I buy 5 apples and 3 oranges, how much do I spend?
|
||||
|
||||
Let's think through this step by step:
|
||||
|
||||
Step 1: Calculate apple cost
|
||||
- 5 apples × $2 per apple = $10
|
||||
|
||||
Step 2: Calculate orange cost
|
||||
- 3 oranges × $3 per orange = $9
|
||||
|
||||
Step 3: Calculate total
|
||||
- $10 + $9 = $19
|
||||
|
||||
Therefore: You spend $19 total.
|
||||
```
|
||||
|
||||
### Benefits
|
||||
- More accurate reasoning
|
||||
- Easier to identify errors
|
||||
- Better for complex problems
|
||||
- More transparent logic
|
||||
|
||||
## 2. Few-Shot Learning
|
||||
|
||||
### What It Is
|
||||
Providing examples to guide Claude's behavior without explicit instructions.
|
||||
|
||||
### Types
|
||||
|
||||
#### 1-Shot (Single Example)
|
||||
Best for: Simple, straightforward tasks
|
||||
```
|
||||
Example: "Happy" → Positive
|
||||
Now classify: "Terrible" →
|
||||
```
|
||||
|
||||
#### 2-Shot (Two Examples)
|
||||
Best for: Moderate complexity
|
||||
```
|
||||
Example 1: "Great product!" → Positive
|
||||
Example 2: "Doesn't work well" → Negative
|
||||
Now classify: "It's okay" →
|
||||
```
|
||||
|
||||
#### Multi-Shot (Multiple Examples)
|
||||
Best for: Complex patterns, edge cases
|
||||
```
|
||||
Example 1: "Love it!" → Positive
|
||||
Example 2: "Hate it" → Negative
|
||||
Example 3: "It's fine" → Neutral
|
||||
Example 4: "Could be better" → Neutral
|
||||
Example 5: "Amazing!" → Positive
|
||||
Now classify: "Not bad" →
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
- Use diverse examples
|
||||
- Include edge cases
|
||||
- Show correct format
|
||||
- Order by complexity
|
||||
- Use realistic examples
|
||||
|
||||
## 3. Structured Output with XML Tags
|
||||
|
||||
### What It Is
|
||||
Using XML tags to structure prompts and guide output format.
|
||||
|
||||
### Benefits
|
||||
- Clear structure
|
||||
- Easy parsing
|
||||
- Reduced ambiguity
|
||||
- Better organization
|
||||
|
||||
### Common Patterns
|
||||
|
||||
#### Task Definition
|
||||
```xml
|
||||
<task>
|
||||
<objective>What to accomplish</objective>
|
||||
<constraints>Limitations and rules</constraints>
|
||||
<format>Expected output format</format>
|
||||
</task>
|
||||
```
|
||||
|
||||
#### Analysis Structure
|
||||
```xml
|
||||
<analysis>
|
||||
<problem>Define the problem</problem>
|
||||
<context>Relevant background</context>
|
||||
<solution>Proposed solution</solution>
|
||||
<justification>Why this solution</justification>
|
||||
</analysis>
|
||||
```
|
||||
|
||||
#### Conditional Logic
|
||||
```xml
|
||||
<instructions>
|
||||
<if condition="input_type == 'question'">
|
||||
<then>Provide detailed answer</then>
|
||||
</if>
|
||||
<if condition="input_type == 'request'">
|
||||
<then>Fulfill the request</then>
|
||||
</if>
|
||||
</instructions>
|
||||
```
|
||||
|
||||
## 4. Role-Based Prompting
|
||||
|
||||
### What It Is
|
||||
Assigning Claude a specific role or expertise to guide behavior.
|
||||
|
||||
### Structure
|
||||
```
|
||||
You are a [ROLE] with expertise in [DOMAIN].
|
||||
|
||||
Your responsibilities:
|
||||
- [Responsibility 1]
|
||||
- [Responsibility 2]
|
||||
- [Responsibility 3]
|
||||
|
||||
When responding:
|
||||
- [Guideline 1]
|
||||
- [Guideline 2]
|
||||
- [Guideline 3]
|
||||
|
||||
Your task: [Specific task]
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
#### Expert Consultant
|
||||
```
|
||||
You are a senior management consultant with 20 years of experience
|
||||
in business strategy and organizational transformation.
|
||||
|
||||
Your task: Analyze this company's challenges and recommend solutions.
|
||||
```
|
||||
|
||||
#### Technical Architect
|
||||
```
|
||||
You are a cloud infrastructure architect specializing in scalable systems.
|
||||
|
||||
Your task: Design a system architecture for [requirements].
|
||||
```
|
||||
|
||||
#### Creative Director
|
||||
```
|
||||
You are a creative director with expertise in brand storytelling and
|
||||
visual communication.
|
||||
|
||||
Your task: Develop a brand narrative for [product/company].
|
||||
```
|
||||
|
||||
## 5. Prefilling Responses
|
||||
|
||||
### What It Is
|
||||
Starting Claude's response to guide format and tone.
|
||||
|
||||
### Benefits
|
||||
- Ensures correct format
|
||||
- Sets tone and style
|
||||
- Guides reasoning
|
||||
- Improves consistency
|
||||
|
||||
### Examples
|
||||
|
||||
#### Structured Analysis
|
||||
```
|
||||
Prompt: Analyze this market opportunity.
|
||||
|
||||
Claude's response should start:
|
||||
"Here's my analysis of this market opportunity:
|
||||
|
||||
Market Size: [Analysis]
|
||||
Growth Potential: [Analysis]
|
||||
Competitive Landscape: [Analysis]"
|
||||
```
|
||||
|
||||
#### Step-by-Step Reasoning
|
||||
```
|
||||
Prompt: Solve this problem.
|
||||
|
||||
Claude's response should start:
|
||||
"Let me work through this systematically:
|
||||
|
||||
1. First, I'll identify the key variables...
|
||||
2. Then, I'll analyze the relationships...
|
||||
3. Finally, I'll derive the solution..."
|
||||
```
|
||||
|
||||
#### Formatted Output
|
||||
```
|
||||
Prompt: Create a project plan.
|
||||
|
||||
Claude's response should start:
|
||||
"Here's the project plan:
|
||||
|
||||
Phase 1: Planning
|
||||
- Task 1.1: [Description]
|
||||
- Task 1.2: [Description]
|
||||
|
||||
Phase 2: Execution
|
||||
- Task 2.1: [Description]"
|
||||
```
|
||||
|
||||
## 6. Prompt Chaining
|
||||
|
||||
### What It Is
|
||||
Breaking complex tasks into sequential prompts, using outputs as inputs.
|
||||
|
||||
### Structure
|
||||
```
|
||||
Prompt 1: Analyze/Extract
|
||||
↓
|
||||
Output 1: Structured data
|
||||
↓
|
||||
Prompt 2: Process/Transform
|
||||
↓
|
||||
Output 2: Processed data
|
||||
↓
|
||||
Prompt 3: Generate/Synthesize
|
||||
↓
|
||||
Final Output: Result
|
||||
```
|
||||
|
||||
### Example: Document Analysis Pipeline
|
||||
|
||||
**Prompt 1: Extract Information**
|
||||
```
|
||||
Extract key information from this document:
|
||||
- Main topic
|
||||
- Key points (bullet list)
|
||||
- Important dates
|
||||
- Relevant entities
|
||||
|
||||
Format as JSON.
|
||||
```
|
||||
|
||||
**Prompt 2: Analyze Extracted Data**
|
||||
```
|
||||
Analyze this extracted information:
|
||||
[JSON from Prompt 1]
|
||||
|
||||
Identify:
|
||||
- Relationships between entities
|
||||
- Temporal patterns
|
||||
- Significance of each point
|
||||
```
|
||||
|
||||
**Prompt 3: Generate Summary**
|
||||
```
|
||||
Based on this analysis:
|
||||
[Analysis from Prompt 2]
|
||||
|
||||
Create an executive summary that:
|
||||
- Explains the main findings
|
||||
- Highlights key insights
|
||||
- Recommends next steps
|
||||
```
|
||||
|
||||
## 7. Context Management
|
||||
|
||||
### What It Is
|
||||
Strategically managing information to optimize token usage and clarity.
|
||||
|
||||
### Techniques
|
||||
|
||||
#### Progressive Disclosure
|
||||
```
|
||||
Start with: High-level overview
|
||||
Then provide: Relevant details
|
||||
Finally include: Edge cases and exceptions
|
||||
```
|
||||
|
||||
#### Hierarchical Organization
|
||||
```
|
||||
Level 1: Core concept
|
||||
├── Level 2: Key components
|
||||
│ ├── Level 3: Specific details
|
||||
│ └── Level 3: Implementation notes
|
||||
└── Level 2: Related concepts
|
||||
```
|
||||
|
||||
#### Conditional Information
|
||||
```
|
||||
If [condition], include [information]
|
||||
Else, skip [information]
|
||||
|
||||
This reduces unnecessary context.
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
- Include only necessary context
|
||||
- Organize hierarchically
|
||||
- Use references for detailed info
|
||||
- Summarize before details
|
||||
- Link related concepts
|
||||
|
||||
## 8. Multimodal Prompting
|
||||
|
||||
### Vision Prompting
|
||||
|
||||
#### Structure
|
||||
```
|
||||
Analyze this image:
|
||||
[IMAGE]
|
||||
|
||||
Specifically, identify:
|
||||
1. [What to look for]
|
||||
2. [What to analyze]
|
||||
3. [What to extract]
|
||||
|
||||
Format your response as:
|
||||
[Desired format]
|
||||
```
|
||||
|
||||
#### Example
|
||||
```
|
||||
Analyze this chart:
|
||||
[CHART IMAGE]
|
||||
|
||||
Identify:
|
||||
1. Main trends
|
||||
2. Anomalies or outliers
|
||||
3. Predictions for next period
|
||||
|
||||
Format as a structured report.
|
||||
```
|
||||
|
||||
### File-Based Prompting
|
||||
|
||||
#### Structure
|
||||
```
|
||||
Analyze this document:
|
||||
[FILE]
|
||||
|
||||
Extract:
|
||||
- [Information type 1]
|
||||
- [Information type 2]
|
||||
- [Information type 3]
|
||||
|
||||
Format as:
|
||||
[Desired format]
|
||||
```
|
||||
|
||||
#### Example
|
||||
```
|
||||
Analyze this PDF financial report:
|
||||
[PDF FILE]
|
||||
|
||||
Extract:
|
||||
- Revenue by quarter
|
||||
- Expense categories
|
||||
- Profit margins
|
||||
|
||||
Format as a comparison table.
|
||||
```
|
||||
|
||||
### Embeddings Integration
|
||||
|
||||
#### Structure
|
||||
```
|
||||
Using these embeddings:
|
||||
[EMBEDDINGS DATA]
|
||||
|
||||
Find:
|
||||
- Most similar items
|
||||
- Clusters or groups
|
||||
- Outliers
|
||||
|
||||
Explain the relationships.
|
||||
```
|
||||
|
||||
## Combining Techniques
|
||||
|
||||
### Example: Complex Analysis Prompt
|
||||
|
||||
```xml
|
||||
<prompt>
|
||||
<role>
|
||||
You are a senior data analyst with expertise in business intelligence.
|
||||
</role>
|
||||
|
||||
<task>
|
||||
Analyze this sales data and provide insights.
|
||||
</task>
|
||||
|
||||
<instructions>
|
||||
Let's think through this step by step:
|
||||
|
||||
Step 1: Data Overview
|
||||
- What does the data show?
|
||||
- What time period does it cover?
|
||||
- What are the key metrics?
|
||||
|
||||
Step 2: Trend Analysis
|
||||
- What patterns emerge?
|
||||
- Are there seasonal trends?
|
||||
- What's the growth trajectory?
|
||||
|
||||
Step 3: Comparative Analysis
|
||||
- How does this compare to benchmarks?
|
||||
- Which segments perform best?
|
||||
- Where are the opportunities?
|
||||
|
||||
Step 4: Recommendations
|
||||
- What actions should we take?
|
||||
- What are the priorities?
|
||||
- What's the expected impact?
|
||||
</instructions>
|
||||
|
||||
<format>
|
||||
<executive_summary>2-3 sentences</executive_summary>
|
||||
<key_findings>Bullet points</key_findings>
|
||||
<detailed_analysis>Structured sections</detailed_analysis>
|
||||
<recommendations>Prioritized list</recommendations>
|
||||
</format>
|
||||
</prompt>
|
||||
```
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### ❌ Vague Chaining
|
||||
```
|
||||
"Analyze this, then summarize it, then give me insights."
|
||||
```
|
||||
|
||||
### ✅ Clear Chaining
|
||||
```
|
||||
"Step 1: Extract key metrics from the data
|
||||
Step 2: Compare to industry benchmarks
|
||||
Step 3: Identify top 3 opportunities
|
||||
Step 4: Recommend prioritized actions"
|
||||
```
|
||||
|
||||
### ❌ Unclear Role
|
||||
```
|
||||
"Act like an expert and help me."
|
||||
```
|
||||
|
||||
### ✅ Clear Role
|
||||
```
|
||||
"You are a senior product manager with 10 years of experience
|
||||
in SaaS companies. Your task is to..."
|
||||
```
|
||||
|
||||
### ❌ Ambiguous Format
|
||||
```
|
||||
"Give me the results in a nice format."
|
||||
```
|
||||
|
||||
### ✅ Clear Format
|
||||
```
|
||||
"Format as a table with columns: Metric, Current, Target, Gap"
|
||||
```
|
||||
338
docs/TROUBLESHOOTING.md
Normal file
338
docs/TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
## Common Prompt Issues and Solutions
|
||||
|
||||
### Issue 1: Inconsistent Outputs
|
||||
|
||||
**Symptoms:**
|
||||
- Same prompt produces different results
|
||||
- Outputs vary in format or quality
|
||||
- Unpredictable behavior
|
||||
|
||||
**Root Causes:**
|
||||
- Ambiguous instructions
|
||||
- Missing constraints
|
||||
- Insufficient examples
|
||||
- Unclear success criteria
|
||||
|
||||
**Solutions:**
|
||||
```
|
||||
1. Add specific format requirements
|
||||
2. Include multiple examples
|
||||
3. Define constraints explicitly
|
||||
4. Specify output structure with XML tags
|
||||
5. Use role-based prompting for consistency
|
||||
```
|
||||
|
||||
**Example Fix:**
|
||||
```
|
||||
❌ Before: "Summarize this article"
|
||||
|
||||
✅ After: "Summarize this article in exactly 3 bullet points,
|
||||
each 1-2 sentences. Focus on key findings and implications."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 2: Hallucinations or False Information
|
||||
|
||||
**Symptoms:**
|
||||
- Claude invents facts
|
||||
- Confident but incorrect statements
|
||||
- Made-up citations or data
|
||||
|
||||
**Root Causes:**
|
||||
- Prompts that encourage speculation
|
||||
- Lack of grounding in facts
|
||||
- Insufficient context
|
||||
- Ambiguous questions
|
||||
|
||||
**Solutions:**
|
||||
```
|
||||
1. Ask Claude to cite sources
|
||||
2. Request confidence levels
|
||||
3. Ask for caveats and limitations
|
||||
4. Provide factual context
|
||||
5. Ask "What don't you know?"
|
||||
```
|
||||
|
||||
**Example Fix:**
|
||||
```
|
||||
❌ Before: "What will happen to the market next year?"
|
||||
|
||||
✅ After: "Based on current market data, what are 3 possible
|
||||
scenarios for next year? For each, explain your reasoning and
|
||||
note your confidence level (high/medium/low)."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 3: Vague or Unhelpful Responses
|
||||
|
||||
**Symptoms:**
|
||||
- Generic answers
|
||||
- Lacks specificity
|
||||
- Doesn't address the real question
|
||||
- Too high-level
|
||||
|
||||
**Root Causes:**
|
||||
- Vague prompt
|
||||
- Missing context
|
||||
- Unclear objective
|
||||
- No format specification
|
||||
|
||||
**Solutions:**
|
||||
```
|
||||
1. Be more specific in the prompt
|
||||
2. Provide relevant context
|
||||
3. Specify desired output format
|
||||
4. Give examples of good responses
|
||||
5. Define success criteria
|
||||
```
|
||||
|
||||
**Example Fix:**
|
||||
```
|
||||
❌ Before: "How can I improve my business?"
|
||||
|
||||
✅ After: "I run a SaaS company with $2M ARR. We're losing
|
||||
customers to competitors. What are 3 specific strategies to
|
||||
improve retention? For each, explain implementation steps and
|
||||
expected impact."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 4: Too Long or Too Short Responses
|
||||
|
||||
**Symptoms:**
|
||||
- Response is too verbose
|
||||
- Response is too brief
|
||||
- Doesn't match expectations
|
||||
- Wastes tokens
|
||||
|
||||
**Root Causes:**
|
||||
- No length specification
|
||||
- Unclear scope
|
||||
- Missing format guidance
|
||||
- Ambiguous detail level
|
||||
|
||||
**Solutions:**
|
||||
```
|
||||
1. Specify word/sentence count
|
||||
2. Define scope clearly
|
||||
3. Use format templates
|
||||
4. Provide examples
|
||||
5. Request specific detail level
|
||||
```
|
||||
|
||||
**Example Fix:**
|
||||
```
|
||||
❌ Before: "Explain machine learning"
|
||||
|
||||
✅ After: "Explain machine learning in 2-3 paragraphs for
|
||||
someone with no technical background. Focus on practical
|
||||
applications, not theory."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 5: Wrong Output Format
|
||||
|
||||
**Symptoms:**
|
||||
- Output format doesn't match needs
|
||||
- Can't parse the response
|
||||
- Incompatible with downstream tools
|
||||
- Requires manual reformatting
|
||||
|
||||
**Root Causes:**
|
||||
- No format specification
|
||||
- Ambiguous format request
|
||||
- Format not clearly demonstrated
|
||||
- Missing examples
|
||||
|
||||
**Solutions:**
|
||||
```
|
||||
1. Specify exact format (JSON, CSV, table, etc.)
|
||||
2. Provide format examples
|
||||
3. Use XML tags for structure
|
||||
4. Request specific fields
|
||||
5. Show before/after examples
|
||||
```
|
||||
|
||||
**Example Fix:**
|
||||
```
|
||||
❌ Before: "List the top 5 products"
|
||||
|
||||
✅ After: "List the top 5 products in JSON format:
|
||||
{
|
||||
\"products\": [
|
||||
{\"name\": \"...\", \"revenue\": \"...\", \"growth\": \"...\"}
|
||||
]
|
||||
}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 6: Claude Refuses to Respond
|
||||
|
||||
**Symptoms:**
|
||||
- "I can't help with that"
|
||||
- Declines to answer
|
||||
- Suggests alternatives
|
||||
- Seems overly cautious
|
||||
|
||||
**Root Causes:**
|
||||
- Prompt seems harmful
|
||||
- Ambiguous intent
|
||||
- Sensitive topic
|
||||
- Unclear legitimate use case
|
||||
|
||||
**Solutions:**
|
||||
```
|
||||
1. Clarify legitimate purpose
|
||||
2. Reframe the question
|
||||
3. Provide context
|
||||
4. Explain why you need this
|
||||
5. Ask for general guidance instead
|
||||
```
|
||||
|
||||
**Example Fix:**
|
||||
```
|
||||
❌ Before: "How do I manipulate people?"
|
||||
|
||||
✅ After: "I'm writing a novel with a manipulative character.
|
||||
How would a psychologist describe manipulation tactics?
|
||||
What are the psychological mechanisms involved?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 7: Prompt is Too Long
|
||||
|
||||
**Symptoms:**
|
||||
- Exceeds context window
|
||||
- Slow responses
|
||||
- High token usage
|
||||
- Expensive to run
|
||||
|
||||
**Root Causes:**
|
||||
- Unnecessary context
|
||||
- Redundant information
|
||||
- Too many examples
|
||||
- Verbose instructions
|
||||
|
||||
**Solutions:**
|
||||
```
|
||||
1. Remove unnecessary context
|
||||
2. Consolidate similar points
|
||||
3. Use references instead of full text
|
||||
4. Reduce number of examples
|
||||
5. Use progressive disclosure
|
||||
```
|
||||
|
||||
**Example Fix:**
|
||||
```
|
||||
❌ Before: [5000 word prompt with full documentation]
|
||||
|
||||
✅ After: [500 word prompt with links to detailed docs]
|
||||
"See REFERENCE.md for detailed specifications"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 8: Prompt Doesn't Generalize
|
||||
|
||||
**Symptoms:**
|
||||
- Works for one case, fails for others
|
||||
- Brittle to input variations
|
||||
- Breaks with different data
|
||||
- Not reusable
|
||||
|
||||
**Root Causes:**
|
||||
- Too specific to one example
|
||||
- Hardcoded values
|
||||
- Assumes specific format
|
||||
- Lacks flexibility
|
||||
|
||||
**Solutions:**
|
||||
```
|
||||
1. Use variables instead of hardcoded values
|
||||
2. Handle multiple input formats
|
||||
3. Add error handling
|
||||
4. Test with diverse inputs
|
||||
5. Build in flexibility
|
||||
```
|
||||
|
||||
**Example Fix:**
|
||||
```
|
||||
❌ Before: "Analyze this Q3 sales data..."
|
||||
|
||||
✅ After: "Analyze this [PERIOD] [METRIC] data.
|
||||
Handle various formats: CSV, JSON, or table.
|
||||
If format is unclear, ask for clarification."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debugging Workflow
|
||||
|
||||
### Step 1: Identify the Problem
|
||||
- What's not working?
|
||||
- How does it fail?
|
||||
- What's the impact?
|
||||
|
||||
### Step 2: Analyze the Prompt
|
||||
- Is the objective clear?
|
||||
- Are instructions specific?
|
||||
- Is context sufficient?
|
||||
- Is format specified?
|
||||
|
||||
### Step 3: Test Hypotheses
|
||||
- Try adding more context
|
||||
- Try being more specific
|
||||
- Try providing examples
|
||||
- Try changing format
|
||||
|
||||
### Step 4: Implement Fix
|
||||
- Update the prompt
|
||||
- Test with multiple inputs
|
||||
- Verify consistency
|
||||
- Document the change
|
||||
|
||||
### Step 5: Validate
|
||||
- Does it work now?
|
||||
- Does it generalize?
|
||||
- Is it efficient?
|
||||
- Is it maintainable?
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Common Fixes
|
||||
|
||||
| Problem | Quick Fix |
|
||||
|---------|-----------|
|
||||
| Inconsistent | Add format specification + examples |
|
||||
| Hallucinations | Ask for sources + confidence levels |
|
||||
| Vague | Add specific details + examples |
|
||||
| Too long | Specify word count + format |
|
||||
| Wrong format | Show exact format example |
|
||||
| Refuses | Clarify legitimate purpose |
|
||||
| Too long prompt | Remove unnecessary context |
|
||||
| Doesn't generalize | Use variables + handle variations |
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
Before deploying a prompt, verify:
|
||||
|
||||
- [ ] Objective is crystal clear
|
||||
- [ ] Instructions are specific
|
||||
- [ ] Format is specified
|
||||
- [ ] Examples are provided
|
||||
- [ ] Edge cases are handled
|
||||
- [ ] Works with multiple inputs
|
||||
- [ ] Output is consistent
|
||||
- [ ] Tokens are optimized
|
||||
- [ ] Error handling is clear
|
||||
- [ ] Documentation is complete
|
||||
Reference in New Issue
Block a user