sf-agent-framework/sf-core/data/salesforce-best-practices.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# Salesforce Best Practices Knowledge Base (Summer '25)

This document contains embedded Salesforce best practices that agents can
reference to ensure high-quality implementations, updated for Summer '25
features including Agent Force, Einstein Copilot, and Data Cloud Native.

## 🤖 Agent Force Best Practices (NEW)

### Agent Design Principles

1. **Clear Agent Boundaries**
   - Define specific agent responsibilities
   - Set clear escalation paths to humans
   - Implement guardrails for decision-making
   - Monitor agent confidence scores

2. **Trust and Safety**

   ```yaml
   agent_safety:
     - Enable hallucination detection
     - Implement data grounding
     - Set response boundaries
     - Audit all agent actions
     - Regular performance reviews
   ```

3. **Agent Performance Optimization**
   - Train agents on company-specific data
   - Use feedback loops for continuous improvement
   - Monitor response accuracy metrics
   - Implement A/B testing for agent responses

4. **Multi-Agent Orchestration**
   - Design clear handoff protocols
   - Implement shared context management
   - Use Agent Force Studio for visual orchestration
   - Monitor inter-agent communication

### Einstein Copilot Integration

1. **Copilot Actions Development**

   ```apex
   // Summer '25 Pattern: Copilot Action
   @CopilotAction(label='Create Quote',
                  description='Generate quote for opportunity')
   public static QuoteResult createQuote(Id oppId) {
       // AI-assisted implementation
       return AI.generateQuote(oppId);
   }
   ```

2. **Natural Language Processing**
   - Use semantic search for better understanding
   - Implement context-aware responses
   - Enable multi-language support
   - Train on industry-specific terminology

## Development Best Practices (Updated for Summer '25)

### Apex Development (Summer '25 Updates)

1. **AI-Powered Development**

   ```apex
   // Use AI for code generation
   @AIGenerated(prompt='Calculate customer lifetime value')
   public static Decimal calculateCLV(Id customerId) {
       // AI generates optimized implementation
   }

   // Async/Await Pattern (NEW)
   public async static void processLargeDataSet() {
       List<Account> accounts = await Database.queryAsync(
           'SELECT Id, AnnualRevenue FROM Account'
       );
       await processAccountsInParallel(accounts);
   }
   ```

2. **Modern Bulkification Patterns**
   - Use parallel processing for large operations
   - Implement streaming for real-time data
   - Leverage platform cache aggressively
   - Use Data Cloud native queries

3. **Enhanced Governor Limits (Summer '25)**
   - SOQL queries: 200 (sync), 400 (async)
   - DML operations: 150 (increased)
   - Callouts: 100 (sync), 200 (async)
   - CPU time: 10 seconds (sync), 60 seconds (async)
   - Heap size: 12 MB (sync), 24 MB (async)

4. **Advanced Error Handling**

   ```apex
   // Summer '25 Pattern: Smart Error Recovery
   try {
       // Business logic
   } catch (Exception e) {
       // AI-powered error analysis
       ErrorInsight insight = AI.analyzeError(e);

       if (insight.isRecoverable()) {
           // Automatic recovery attempt
           return insight.suggestedFix();
       }

       // Log with full context
       Logger.error(e).withContext(insight).send();
   }
   ```

5. **Zero Trust Security Model**
   - Use User Mode by default for all database operations
   - Implement field-level encryption for sensitive data
   - Enable real-time threat detection
   - Use AI for anomaly detection
   - Implement data masking in non-production

### Lightning Web Components (LWC)

1. **Performance**
   - Use wire adapters when possible
   - Implement lazy loading for large datasets
   - Minimize imperative Apex calls
   - Cache data appropriately

2. **Component Design**
   - Keep components small and focused
   - Use composition over inheritance
   - Implement proper error boundaries
   - Follow naming conventions

3. **Security**
   - Use Lightning Data Service
   - Implement proper CSP headers
   - Validate all user inputs
   - Use secure coding practices

### Flow Best Practices

1. **Design Principles**
   - One flow per object when possible
   - Use subflows for reusability
   - Implement proper error handling
   - Document complex logic

2. **Performance**
   - Minimize DML operations
   - Use Get Records efficiently
   - Avoid loops when possible
   - Consider batch processing for large volumes

3. **Maintenance**
   - Use meaningful API names
   - Version flows before changes
   - Test thoroughly in sandbox
   - Document business logic

## Architecture Best Practices

### Data Model Design

1. **Relationships**
   - Use lookup for loose coupling
   - Use master-detail for tight coupling
   - Consider junction objects for many-to-many
   - Avoid excessive relationship depth

2. **Custom Objects**
   - Follow naming conventions
   - Plan for scalability
   - Consider sharing model early
   - Document purpose and usage

3. **Fields**
   - Use appropriate field types
   - Set field-level security properly
   - Make fields required at database level when critical
   - Use validation rules for complex logic

### Integration Patterns

1. **API Design**
   - Use REST for modern integrations
   - Implement proper authentication
   - Version your APIs
   - Handle errors gracefully

2. **Middleware**
   - Consider ESB/iPaaS for complex integrations
   - Implement retry logic
   - Log all transactions
   - Monitor performance

3. **Real-time vs Batch**
   - Use Platform Events for real-time
   - Use Batch Apex for large volumes
   - Consider CDC for data sync
   - Implement proper error recovery

## Security Best Practices

### Access Control

1. **Profiles and Permission Sets**
   - Use Permission Sets for scalability
   - Minimize profile customization
   - Follow principle of least privilege
   - Regular access reviews

2. **Sharing Model**
   - Private by default
   - Use sharing rules judiciously
   - Implement Apex sharing when needed
   - Test sharing thoroughly

3. **Field Level Security**
   - Hide sensitive fields by default
   - Grant access only when needed
   - Use field tracking for audit
   - Regular security reviews

### Data Protection

1. **Encryption**
   - Use Shield Encryption for sensitive data
   - Implement field encryption where needed
   - Manage encryption keys properly
   - Test encryption impact

2. **Data Masking**
   - Mask sensitive data in sandboxes
   - Use data masking for support access
   - Implement proper data retention
   - Regular data cleanup

## Deployment Best Practices

### Change Management

1. **Version Control**
   - Use Git for all metadata
   - Implement branching strategy
   - Code review all changes
   - Maintain deployment history

2. **Environment Strategy**
   - Separate Dev, QA, UAT, Prod
   - Refresh sandboxes regularly
   - Use scratch orgs for development
   - Maintain environment documentation

3. **Deployment Process**
   - Automate deployments
   - Test in lower environments first
   - Use change sets only for simple changes
   - Implement rollback procedures

### Testing Strategy

1. **Test Coverage**
   - Unit tests for all code
   - Integration tests for workflows
   - UI tests for critical paths
   - Performance tests for scale

2. **Test Data**
   - Use test data factories
   - Maintain test data sets
   - Test with production-like volumes
   - Regular test data refresh

## Performance Best Practices

### Query Optimization

1. **SOQL Best Practices**
   - Use selective filters
   - Index custom fields when needed
   - Avoid SELECT \*
   - Use SOQL best practices

2. **Data Volume**
   - Archive old data
   - Use Big Objects for history
   - Implement data retention policies
   - Monitor data growth

### UI Performance

1. **Page Load Time**
   - Minimize component count
   - Use lazy loading
   - Optimize images and resources
   - Monitor performance metrics

2. **Caching Strategy**
   - Use Platform Cache
   - Implement client-side caching
   - Cache expensive operations
   - Monitor cache effectiveness

## Governance Best Practices

### Technical Debt Management

1. **Code Quality**
   - Regular code reviews
   - Refactor legacy code
   - Maintain coding standards
   - Use static analysis tools

2. **Documentation**
   - Keep documentation current
   - Document all customizations
   - Maintain architecture diagrams
   - Regular documentation reviews

### Center of Excellence

1. **Standards**
   - Establish coding standards
   - Define naming conventions
   - Create development guidelines
   - Regular standards review

2. **Training**
   - Regular developer training
   - Certification requirements
   - Knowledge sharing sessions
   - Mentorship programs

## Common Pitfalls to Avoid

1. **Over-customization**
   - Use standard features first
   - Avoid complex code when declarative works
   - Consider maintenance burden
   - Plan for upgrades

2. **Poor Testing**
   - Don't test only happy path
   - Include negative test cases
   - Test with production volumes
   - Automate regression testing

3. **Security Shortcuts**
   - Never bypass security
   - Don't use without sharing carelessly
   - Always validate inputs
   - Regular security audits

4. **Performance Issues**
   - Don't ignore governor limits
   - Test with realistic data volumes
   - Monitor production performance
   - Plan for growth

## Salesforce Release Management

1. **Stay Current**
   - Review release notes
   - Test in preview sandboxes
   - Plan for API retirements
   - Update dependencies

2. **Feature Adoption**
   - Evaluate new features
   - Pilot before rollout
   - Train users properly
   - Monitor adoption

This knowledge base should be continuously updated with new Salesforce releases
and emerging best practices.