Coding metaprompt best practices

# Coding Metaprompting Best Practices for Claude Code

## Overview

Metaprompting for coding involves crafting prompts that help Claude Code generate better code, debug more effectively, refactor intelligently, and design robust architectures. This guide focuses on optimizing prompts for all four key scenarios.

## Core Principles

### 1. Context is King

- **Provide Relevant Context**: Include language, framework, and project structure
- **Specify Constraints**: Performance requirements, compatibility needs, style guides
- **Define Success Criteria**: What makes the solution "good" in your context
- **Include Edge Cases**: Mention specific scenarios to handle

### 2. Precision Over Ambiguity

- **Use Technical Terms**: Specific patterns, algorithms, or architectures
- **Define Scope Clearly**: What should and shouldn't be modified
- **Specify Output Format**: File structure, naming conventions, documentation needs
- **State Assumptions**: Make implicit requirements explicit

## Scenario-Specific Guidelines

### 1. Code Generation

#### Best Practices

- **Start with Purpose**: Explain what the code should accomplish, not just how
- **Provide Examples**: Include input/output examples or API signatures
- **Specify Style**: Mention coding standards, patterns, and conventions
- **Request Tests**: Ask for test cases alongside implementation

#### Structure for Generation Prompts

```text
Task: [What needs to be built]
Context: [Language, framework, existing codebase structure]
Requirements:
  - Functional: [What it must do]
  - Non-functional: [Performance, security, maintainability]
  - Constraints: [Compatibility, dependencies, limitations]
Expected Usage: [How it will be used]
Style Guidelines: [Coding standards to follow]
```

### 2. Debugging

#### Best Practices

- **Describe the Problem**: Expected vs. actual behavior
- **Share Error Context**: Full error messages, stack traces, logs
- **Mention What You've Tried**: Previous debugging attempts
- **Provide Minimal Reproduction**: Simplest case that shows the issue

#### Structure for Debugging Prompts

```text
Problem: [What's going wrong]
Expected Behavior: [What should happen]
Actual Behavior: [What actually happens]
Error Messages: [Complete error output]
Code Context: [Relevant code sections]
Environment: [Version numbers, OS, dependencies]
Attempted Solutions: [What you've already tried]
```

### 3. Refactoring

#### Best Practices

- **Define Goals**: Performance, readability, maintainability, or patterns
- **Preserve Behavior**: Emphasize maintaining functionality
- **Specify Scope**: Which parts can change, which must remain
- **Request Incremental Steps**: Ask for step-by-step refactoring

#### Structure for Refactoring Prompts

```text
Current State: [What the code does now]
Refactoring Goals:
  - Primary: [Main improvement needed]
  - Secondary: [Nice-to-have improvements]
Constraints:
  - Must Preserve: [Functionality, interfaces, behavior]
  - Can Change: [Internal implementation, structure]
  - Cannot Change: [Public APIs, database schema]
Quality Metrics: [How to measure improvement]
```

### 4. Architecture Design

#### Best Practices

- **Start with Requirements**: Business needs before technical solutions
- **Consider Scale**: Current needs and future growth
- **Specify Constraints**: Technical, organizational, and resource limits
- **Request Alternatives**: Ask for pros/cons of different approaches

#### Structure for Architecture Prompts

```text
System Purpose: [What the system should accomplish]
Functional Requirements: [Core features and capabilities]
Non-Functional Requirements:
  - Performance: [Response time, throughput]
  - Scalability: [User load, data volume]
  - Security: [Authentication, authorization, data protection]
  - Reliability: [Uptime, fault tolerance]
Constraints:
  - Technical: [Language, framework, infrastructure]
  - Resources: [Team size, timeline, budget]
  - Integration: [Existing systems, APIs]
Expected Evolution: [How the system might grow]
```

## Metaprompt Patterns

### 1. The Contextual Pattern

```text
Given [context/environment/constraints],
Create [specific type of code]
That [achieves goal]
While [maintaining qualities]
Following [standards/patterns]
```

### 2. The Comparative Pattern

```text
I have [current implementation]
I need [desired outcome]
Compare approaches for [specific aspect]
Consider [constraints and trade-offs]
Recommend [best solution with rationale]
```

### 3. The Iterative Pattern

```text
Starting with [basic implementation]
Enhance to support [feature 1]
Then add [feature 2]
Ensure [quality attributes]
Maintain [backwards compatibility]
```

### 4. The Problem-Solution Pattern

```text
Problem: [Detailed problem description]
Context: [Environmental factors]
Forces: [Competing concerns]
Solution: [Requested approach]
Consequences: [Expected trade-offs]
```

## Quality Attributes to Specify

### Performance

- Time complexity requirements
- Space complexity limits
- Response time targets
- Throughput needs

### Maintainability

- Code readability standards
- Documentation requirements
- Modularity preferences
- Testing coverage

### Security

- Input validation needs
- Authentication requirements
- Data encryption standards
- Access control patterns

### Scalability

- Concurrent user limits
- Data volume expectations
- Geographic distribution
- Growth projections

## Common Anti-Patterns to Avoid

### 1. Vague Requirements

❌ "Make it fast"
✅ "Optimize to handle 1000 requests/second with <100ms response time"

### 2. Missing Context

❌ "Write a sorting function"
✅ "Write a stable sort for an array of objects with custom comparison in TypeScript"

### 3. Unclear Scope

❌ "Improve this code"
✅ "Refactor this function to reduce cyclomatic complexity while maintaining its public interface"

### 4. Assumed Knowledge

❌ "Use the usual pattern"
✅ "Implement using the Repository pattern with dependency injection"

## Tips for Effective Metaprompting

### 1. Layer Your Requirements

- Start with core functionality
- Add constraints progressively
- Specify quality attributes last

### 2. Use Examples

- Provide sample inputs/outputs
- Show edge cases
- Include failure scenarios

### 3. Be Explicit About Trade-offs

- Performance vs. readability
- Flexibility vs. simplicity
- Security vs. usability

### 4. Request Reasoning

- Ask for architectural decisions explanation
- Request complexity analysis
- Seek alternative approaches

### 5. Specify Output Format

- Code structure preferences
- Documentation style
- Comment density
- File organization

## Platform-Specific Considerations

### Claude Code Strengths

- Understanding complex contexts
- Following multi-step instructions
- Explaining reasoning
- Suggesting alternatives

### Optimization Strategies

- Break complex tasks into steps
- Use the todo list for multi-part tasks
- Request explanations for learning
- Ask for best practices relevant to your stack

## Checklist for Coding Metaprompts

Before submitting a prompt, ensure you've included:

- [ ] Clear task description
- [ ] Relevant context (language, framework, environment)
- [ ] Specific requirements (functional and non-functional)
- [ ] Constraints and limitations
- [ ] Expected input/output examples
- [ ] Quality criteria
- [ ] Coding standards to follow
- [ ] Scope boundaries