Orchestre Prompt Engineering Guide

Introduction

This guide explains how to write effective prompts for Orchestre following Anthropic's best practices for Claude 4. Orchestre's philosophy of "minimal code, maximum intelligence" means that prompts are the primary way we implement complex functionality.

Core Principles

1. Intelligence in Prompts, Not Code

• Prompts orchestrate workflows
• Tools remain simple and focused
• Complex logic lives in natural language
• AI adapts based on context

2. Dynamic Discovery

• Prompts analyze before acting
• Context drives decisions
• Patterns emerge from exploration
• Each execution can be unique

3. XML Structure for Clarity

• Consistent format across all prompts
• Leverages Claude's understanding
• Self-documenting approach
• Easy to maintain and extend

The Orchestre XML Format

Complete Structure

<objective>
Clear, single-sentence goal that tells Claude exactly what to accomplish.
</objective>

<context>
User provided: {{arguments}}
Additional context about the current state, available tools, and constraints.
This section grounds Claude in the specific situation.
</context>

<thinking>
Questions or considerations that guide Claude's reasoning:
- What patterns should I look for?
- What are the key decisions to make?
- What could go wrong?
- How can I adapt to what I find?
</thinking>

<approach>
1. Discovery phase - understand the current state
2. Analysis phase - identify patterns and needs
3. Planning phase - determine best approach
4. Implementation phase - execute the plan
5. Verification phase - ensure success
6. Documentation phase - update project memory
</approach>

<examples>
[5+ detailed examples showing different scenarios]
</examples>

<constraints>
- Clear boundaries and requirements
- Technical limitations
- Best practices to follow
- Anti-patterns to avoid
</constraints>

<error-handling>
Specific contingency plans for various failure modes
</error-handling>

<expected-outcome>
Concrete success criteria that can be verified
</expected-outcome>

Section Details

<objective>

• One clear sentence
• Action-oriented language
• Specific and measurable
• No ambiguity

Good Example:

<objective>
Create a new API endpoint for user profile management with full CRUD operations, validation, and proper error handling.
</objective>

Bad Example:

<objective>
Help with API stuff and make it work well.
</objective>

<context>

• User input via template variables
• Current environment state
• Available resources
• Relevant constraints

Example:

<context>
User requested: {{arguments}}
Available templates: cloudflare-hono, makerkit-nextjs, react-native-expo
Current directory contains an existing Next.js project
MCP tools available for file operations and git
</context>

<thinking>

• Guide reasoning process
• Ask key questions
• Consider edge cases
• Plan adaptations

Example:

<thinking>
To add this feature effectively, I need to consider:
- Is this a new project or existing codebase?
- What patterns are already established?
- Which database and auth system is in use?
- How should this integrate with existing features?
- What testing approach is appropriate?
</thinking>

<approach>

• Numbered steps
• Logical progression
• Specific actions
• Verification included

Example:

<approach>
1. Analyze project structure and existing patterns
2. Design database schema based on requirements
3. Implement data models with validation
4. Create API endpoints following REST principles
5. Add authentication and authorization
6. Write comprehensive tests
7. Update documentation and API specs
8. Verify everything works correctly
</approach>

<examples>

• At least 5 examples
• Cover different scenarios
• Show complete flow
• Include edge cases

Structure for each example:

Example N - Descriptive Title:
Input: "what the user provides"
Analysis: What Claude understands from this
Implementation:
- Specific action 1
- Specific action 2
- Technologies used
Output: Concrete result achieved

<constraints>

• Technical boundaries
• Best practices
• Security requirements
• Performance limits

Example:

<constraints>
- MUST follow existing code conventions
- NEVER expose sensitive data in logs
- ALWAYS validate user inputs
- LIMIT file operations to project directory
- USE TypeScript for type safety
</constraints>

<error-handling>

• Anticipate failures
• Provide solutions
• Guide recovery
• Never leave users stuck

Example:

<error-handling>
If project type cannot be detected:
  Ask user to specify framework
  List supported options
  Provide example commands
  
If permissions are insufficient:
  Explain what permissions are needed
  Show how to grant them
  Offer alternative approaches
  
If dependencies conflict:
  Identify the conflicts
  Suggest resolution strategies
  Provide rollback instructions
</error-handling>

<expected-outcome>

• Measurable success
• Specific deliverables
• Quality standards
• User value

Example:

<expected-outcome>
Success means:
- API endpoints fully functional
- All CRUD operations working
- Validation preventing bad data
- Tests passing with >80% coverage
- Documentation updated
- No security vulnerabilities
- Response times under 200ms
</expected-outcome>

Writing Effective Examples

The Five-Example Rule

Every prompt needs at least 5 examples covering:

1. Basic Use Case - The most common scenario
2. Complex Use Case - Advanced features
3. Edge Case - Unusual but valid input
4. Error Case - When things go wrong
5. Integration Case - Working with other features

Example Template

Example 1 - Basic User Profile API:
Input: "user profile CRUD"
Analysis: Standard REST API for user profiles needed
Implementation:
- Created GET /api/users/:id endpoint
- Created PUT /api/users/:id endpoint  
- Created DELETE /api/users/:id endpoint
- Added Zod validation schemas
- Implemented auth middleware
Output: Complete user profile API with:
- Routes: GET, PUT, DELETE /api/users/:id
- Validation: Email, name, bio constraints
- Auth: JWT token required
- Tests: 12 passing tests
- Docs: OpenAPI specification updated

Common Patterns

Discovery Before Action

<thinking>
Before implementing, I need to discover:
- What framework is being used?
- What's the current file structure?
- Are there existing patterns to follow?
- What dependencies are available?
</thinking>

<approach>
1. Scan project structure
2. Identify framework and patterns
3. Plan implementation based on findings
4. Execute following discovered conventions
</approach>

Adaptive Implementation

<examples>
Example 3 - Adapting to Existing Patterns:
Input: "add new feature"
Analysis: Need to discover project conventions first
Implementation:
- Found Next.js app with server actions pattern
- Discovered existing validation approach using Zod
- Identified file naming convention (kebab-case)
- Followed established error handling pattern
Output: Feature perfectly integrated with:
- Matching code style
- Consistent validation
- Proper error handling
- Following all conventions
</examples>

Progressive Enhancement

<approach>
1. Start with minimal working implementation
2. Add validation and error handling
3. Enhance with advanced features
4. Optimize for performance
5. Add comprehensive tests
6. Document everything
</approach>

Best Practices

1. Be Specific, Not Prescriptive

• ✅ "Analyze the authentication system and enhance based on findings"
• ❌ "Add JWT to the auth.js file on line 42"

2. Enable Discovery

• ✅ Include discovery steps in approach
• ✅ Let patterns emerge from analysis
• ❌ Assume fixed implementation

3. Provide Rich Context

• ✅ Multiple detailed examples
• ✅ Clear success criteria
• ❌ Vague descriptions

4. Handle Uncertainty

• ✅ Plan for various scenarios
• ✅ Include fallback approaches
• ❌ Single rigid path

5. Document Decisions

• ✅ Update project memory
• ✅ Explain why choices were made
• ❌ Silent implementation

Testing Your Prompts

Validation Checklist

• [ ] All XML sections present and valid
• [ ] Objective is clear and measurable
• [ ] Context includes user input placeholder
• [ ] Thinking section guides reasoning
• [ ] Approach has numbered steps
• [ ] At least 5 diverse examples
• [ ] Constraints are specific
• [ ] Error handling covers failures
• [ ] Expected outcome is verifiable

Test Scenarios

1. Happy Path: Normal expected input
2. Edge Cases: Unusual but valid input
3. Error Cases: Invalid or problematic input
4. Ambiguous Input: Unclear requirements
5. Integration: Working with other features

Quality Metrics

• Clarity: Can another developer understand?
• Completeness: Are all scenarios covered?
• Adaptability: Does it handle variations?
• Reliability: Consistent good results?
• Value: Does it solve real problems?

Advanced Techniques

Compositional Prompts

Reference other prompts for complex workflows:

<approach>
1. Use /discover-context to understand the project
2. Use /analyze-patterns to find conventions
3. Implement following discovered patterns
4. Use /update-memory to document changes
</approach>

Conditional Logic

<thinking>
The approach depends on what I discover:
- If Next.js: Use app router patterns
- If Express: Use middleware approach
- If Fastify: Use plugin system
- If unknown: Ask for clarification
</thinking>

Learning from Context

<examples>
Example 4 - Learning Project Patterns:
Input: "add new endpoint"
Analysis: First endpoint added, need to establish patterns
Implementation:
- Created initial folder structure
- Established naming conventions
- Set up validation approach
- Created reusable utilities
Output: Not just an endpoint, but a pattern for future development
</examples>

Troubleshooting

Common Issues

Problem: Prompt gives inconsistent results Solution: Add more specific examples and constraints

Problem: Claude doesn't understand context Solution: Make thinking section more explicit

Problem: Implementation doesn't match project Solution: Add discovery steps to approach

Problem: Errors aren't handled well Solution: Expand error-handling section

Debugging Process

1. Check XML structure validity
2. Verify examples cover the case
3. Ensure thinking guides properly
4. Test with various inputs
5. Refine based on results

Examples of Excellence

Complete Prompt Example

Here's a full example of a well-crafted Orchestre prompt:

export function featurePrompt({ arguments: args }: PromptArgs): string {
  return `<objective>
Create a complete feature module with database schema, API endpoints, UI components, and tests following project conventions.
</objective>

<context>
User requested: ${args}
This command creates production-ready features that integrate seamlessly with the existing codebase, discovering and following established patterns.
</context>

<thinking>
To create this feature effectively, I need to:
- Understand what type of feature is requested
- Discover the project's architecture and conventions
- Identify integration points with existing code
- Plan the implementation approach
- Consider testing and documentation needs
</thinking>

<approach>
1. Parse and understand feature requirements
2. Analyze project structure and patterns
3. Design data models and schemas
4. Implement backend logic and APIs
5. Create frontend components
6. Add comprehensive tests
7. Update documentation
8. Verify everything works together
</approach>

<examples>
Example 1 - User Dashboard Feature:
Input: "user dashboard with activity stats"
Analysis: Need analytics display with real-time updates
Implementation:
- Created dashboard route /dashboard
- Added activity tracking table
- Implemented aggregation queries
- Built chart components
- Added real-time subscriptions
Output: Complete dashboard with:
- Routes: /dashboard with sub-pages
- Database: activity_logs table
- API: /api/dashboard/stats endpoint
- UI: Chart.js visualizations
- Updates: WebSocket subscriptions

Example 2 - Comment System Feature:
Input: "threaded comments on posts"
Analysis: Nested comment structure with replies
Implementation:
- Designed recursive comment schema
- Created comment CRUD endpoints
- Built nested comment components
- Added real-time updates
- Implemented moderation
Output: Full commenting system:
- Schema: comments table with parent_id
- API: REST endpoints + subscriptions
- UI: Nested comment threads
- Features: Edit, delete, reply
- Moderation: Flag and review system

Example 3 - Search Feature:
Input: "full-text search across content"
Analysis: Need efficient search with filters
Implementation:
- Added PostgreSQL full-text search
- Created search indexes
- Built search API with pagination
- Implemented search UI with filters
- Added search analytics
Output: Comprehensive search:
- Database: tsvector columns + indexes
- API: /api/search with filters
- UI: Search bar + results page
- Performance: <100ms response
- Analytics: Popular searches tracked

Example 4 - File Upload Feature:
Input: "file uploads with preview"
Analysis: Need secure upload with storage
Implementation:
- Integrated cloud storage (S3/R2)
- Added file validation
- Created upload endpoints
- Built preview components
- Implemented access control
Output: Secure file system:
- Storage: Cloud with CDN
- Validation: Type, size, content
- UI: Drag-drop with progress
- Preview: Images, PDFs, videos
- Security: Signed URLs

Example 5 - Notification System:
Input: "in-app notifications"
Analysis: Real-time notifications with preferences
Implementation:
- Created notifications table
- Built notification service
- Added WebSocket delivery
- Created notification center UI
- Implemented preferences
Output: Complete notification system:
- Database: notifications + preferences
- Delivery: Real-time + email fallback
- UI: Bell icon + notification center
- Settings: Per-type preferences
- History: Read/unread tracking
</examples>

<constraints>
- DISCOVER project patterns before implementing
- FOLLOW existing conventions exactly
- INTEGRATE seamlessly with current code
- TEST everything thoroughly
- DOCUMENT all decisions
- SECURE all user inputs
- OPTIMIZE for performance
</constraints>

<error-handling>
If feature type unclear:
  Ask for specific requirements
  Provide feature examples
  Suggest similar features
  
If project structure unknown:
  Run discovery analysis first
  Look for common patterns
  Ask about framework
  
If integration points missing:
  Identify required dependencies
  Suggest architecture changes
  Provide integration plan
  
If performance concerns:
  Analyze bottlenecks
  Suggest optimizations
  Implement caching
</error-handling>

<expected-outcome>
Success means:
- Feature fully functional
- Follows all project conventions  
- Integrated with existing code
- Tests passing (>80% coverage)
- Performance requirements met
- Security vulnerabilities: zero
- Documentation complete
- Ready for production
</expected-outcome>`;
}

Conclusion

Writing effective Orchestre prompts is about enabling Claude to be intelligent and adaptive. By following this guide, you'll create prompts that:

• Discover and adapt to any project
• Provide consistent, high-quality results
• Handle errors gracefully
• Create real value for users
• Maintain Orchestre's vision of minimal code, maximum intelligence

Remember: The prompt is where the intelligence lives. Make it rich, make it adaptive, make it helpful.