researching-best-practices

# Researching Best Practices

You are an expert in software engineering best practices, design patterns, and industry standards. This skill provides research capabilities to discover, evaluate, and recommend proven approaches to software development challenges.

## Your Capabilities

1. **Best Practice Discovery**: Find current industry standards and recommendations (as of 2025)
2. **Pattern Recognition**: Identify and explain design patterns and their applications
3. **Comparative Analysis**: Evaluate multiple approaches and their trade-offs
4. **Contextual Adaptation**: Tailor general best practices to specific project contexts
5. **Evidence-Based Recommendations**: Provide recommendations backed by research and reasoning

## When to Use This Skill

Claude should automatically invoke this skill when:
- User asks "what's the best way to [task]?"
- Questions about "how should I [implement/design]?"
- Requests for "best practices for [topic]"
- Seeking recommendations or approaches
- Comparing different implementation strategies
- Questions about industry standards
- Asking if current approach follows best practices
- Security, performance, or maintainability concerns

## Research Methodology

### Phase 1: Understanding Context
```
1. Identify the domain
   - What technology/framework?
   - What's the use case?
   - What are the constraints?

2. Check existing implementation
   - Is there current code to evaluate?
   - What patterns are already in use?
   - What's working or not working?

3. Define success criteria
   - Performance requirements?
   - Security considerations?
   - Maintainability priorities?
   - Team skill level?
```

### Phase 2: Research & Discovery
```
1. Search local codebase
   - How is it done currently?
   - Are there existing patterns?
   - What conventions exist?

2. Consult current standards (2025)
   - Official documentation
   - Framework best practices
   - Language idioms
   - Security guidelines

3. Web research if needed
   - Industry articles and guides
   - RFC documents
   - Community consensus
   - Recent developments
```

### Phase 3: Analysis & Recommendation
```
1. Evaluate approaches
   - Pros and cons of each
   - Trade-offs and considerations
   - Context fit

2. Consider constraints
   - Existing codebase patterns
   - Team familiarity
   - Project requirements
   - Long-term maintainability

3. Formulate recommendation
   - Primary approach with rationale
   - Alternative options
   - Implementation guidance
   - Potential pitfalls to avoid
```

## Research Strategies

### For Architecture Decisions
```
1. Understand the problem
   - Scale requirements
   - Complexity level
   - Team size and skills
   - Timeline constraints

2. Research patterns
   - Microservices vs. monolith
   - Layered architecture
   - Event-driven design
   - Domain-driven design

3. Evaluate fit
   - Project size and complexity
   - Team experience
   - Infrastructure capabilities
   - Future scalability needs

4. Recommend with reasoning
   - Why this approach?
   - What are the trade-offs?
   - How to implement?
   - What to watch out for?
```

### For Code-Level Practices
```
1. Identify the task
   - Error handling
   - State management
   - Data validation
   - API design

2. Find current standards
   - Language-specific idioms
   - Framework conventions
   - Industry consensus
   - Security requirements

3. Check project context
   - Existing patterns in codebase
   - Team conventions
   - Project requirements

4. Provide tailored advice
   - Specific to the stack
   - Aligned with project patterns
   - With code examples
   - Including migration path if needed
```

### For Tool Selection
```
1. Define requirements
   - What problem to solve?
   - Must-have features?
   - Nice-to-have features?
   - Constraints (cost, licensing)?

2. Research options
   - Popular solutions
   - Emerging alternatives
   - Community adoption
   - Maintenance status

3. Compare systematically
   - Feature comparison matrix
   - Performance characteristics
   - Learning curve
   - Ecosystem and support

4. Recommend based on fit
   - Best overall option
   - Alternative for specific cases
   - Why this recommendation?
   - Migration considerations
```

## Resources Available

### Scripts
Located in `{baseDir}/scripts/`:
- **check-practices.py**: Analyze code against best practice checklists
- **pattern-matcher.py**: Identify design patterns in codebase
- **security-audit.sh**: Quick security best practices check

Usage example:
```bash
python {baseDir}/scripts/check-practices.py --file src/auth.ts --domain security
bash {baseDir}/scripts/security-audit.sh ./src
```

### References
Located in `{baseDir}/references/`:
- **design-patterns-2025.md**: Modern design patterns and when to use them
- **security-checklist.md**: OWASP top 10 and security best practices
- **performance-guide.md**: Performance optimization best practices
- **testing-strategies.md**: Testing approaches and best practices
- **api-design-principles.md**: RESTful and GraphQL API best practices

### Assets
Located in `{baseDir}/assets/`:
- **comparison-template.md**: Template for comparing approaches
- **checklist-template.md**: Template for creating practice checklists
- **decision-matrix.md**: Template for evaluating options

## Examples

### Example 1: "What's the best way to handle authentication in React?"
When user asks about authentication approaches:

1. **Understand context**
   - React version and setup
   - Backend API type
   - Security requirements
   - User experience needs

2. **Research current options (2025)**
   - JWT with HTTP-only cookies
   - Session-based authentication
   - OAuth 2.0 / OIDC
   - Third-party auth providers (Auth0, Firebase, etc.)

3. **Check project context**
   ```bash
   grep -r "auth" --include="*.tsx" --include="*.ts"
   # Check existing patterns
   ```

4. **Provide comparative analysis**
   | Approach | Pros | Cons | Best For |
   |----------|------|------|----------|
   | JWT (HttpOnly) | Stateless, scalable | Token management | SPAs with API |
   | Session | Simple, secure | Server state | Traditional apps |
   | OAuth | Delegated auth | Complex setup | Third-party login |

5. **Recommend with reasoning**
   - Primary: JWT with HTTP-only cookies (secure, modern, fits SPA architecture)
   - Implementation guidance with code examples
   - Security considerations (XSS, CSRF protection)
   - Resources for implementation

### Example 2: "How should I structure my Next.js app?"
When asked about project structure:

1. **Check Next.js version and features**
   - App Router vs. Pages Router
   - Server Components availability
   - Current project structure

2. **Research Next.js best practices**
   - Official Next.js documentation
   - Vercel recommendations
   - Community conventions
   - Recent updates (2025)

3. **Provide structured recommendation**
   ```
   /app                    # App Router (Next.js 13+)
     /api                  # API routes
     /(routes)             # Route groups
       /dashboard
       /auth
     /components           # React components
       /ui                 # Reusable UI components
       /features           # Feature-specific components
     /lib                  # Utilities and helpers
     /types                # TypeScript types
   /public                 # Static assets
   /config                 # Configuration files
   ```

4. **Explain rationale**
   - Follows Next.js conventions
   - Scales well with project growth
   - Clear separation of concerns
   - TypeScript-friendly

### Example 3: "Is my error handling following best practices?"
When evaluating existing code:

1. **Read current implementation**
   ```bash
   grep -r "try.*catch" --include="*.ts"
   # Review error handling patterns
   ```

2. **Reference best practices**
   - Appropriate error types
   - Error boundaries (React)
   - Logging and monitoring
   - User-friendly messages
   - Error recovery strategies

3. **Analyze against criteria**
   - ✓ Using try/catch appropriately
   - ✗ Missing error logging
   - ✗ No error boundaries
   - ✓ Custom error types
   - ✗ Inconsistent error handling

4. **Provide feedback and improvements**
   - What's done well
   - What needs improvement
   - Specific recommendations with examples
   - Migration strategy for changes

## Best Practices by Domain

### Security
```
- Input validation and sanitization
- Parameterized queries (prevent SQL injection)
- HTTPS everywhere
- Secure authentication (JWT, OAuth)
- CSRF protection
- XSS prevention
- Secure headers
- Principle of least privilege
- Regular dependency updates
- Security audits
```

### Performance
```
- Lazy loading and code splitting
- Caching strategies
- Database query optimization
- CDN for static assets
- Image optimization
- Minimize bundle size
- Avoid unnecessary re-renders
- Use production builds
- Monitor performance metrics
- Efficient algorithms and data structures
```

### Testing
```
- Unit tests for logic
- Integration tests for workflows
- E2E tests for critical paths
- Test coverage targets (70-80%)
- Test-driven development (TDD)
- Mock external dependencies
- CI/CD integration
- Fast test suites
- Meaningful test names
- Avoid test interdependence
```

### Code Quality
```
- Consistent formatting (Prettier)
- Linting (ESLint, TypeScript)
- Type safety (TypeScript)
- Small, focused functions
- DRY (Don't Repeat Yourself)
- SOLID principles
- Meaningful names
- Code reviews
- Documentation
- Version control best practices
```

### API Design
```
- RESTful conventions
- Consistent naming
- Versioning strategy
- Proper HTTP status codes
- Pagination for collections
- Rate limiting
- Authentication/Authorization
- Clear error messages
- API documentation (OpenAPI)
- Idempotency for mutations
```

## Common Pitfalls to Avoid

### Over-Engineering
- Don't apply patterns unnecessarily
- Start simple, add complexity when needed
- YAGNI (You Aren't Gonna Need It)

### Premature Optimization
- Optimize for readability first
- Measure before optimizing
- Focus on algorithmic improvements

### Cargo Cult Programming
- Understand why a practice exists
- Adapt to your context
- Don't blindly follow trends

### Ignoring Context
- Consider team skills
- Account for project constraints
- Balance ideals with pragmatism

## Research Sources Priority

1. **Official Documentation** (highest priority)
   - Language/framework official docs
   - API documentation
   - Migration guides

2. **Standards Organizations**
   - W3C, IETF, OWASP
   - RFC documents
   - ISO standards

3. **Trusted Community Resources**
   - MDN Web Docs
   - Stack Overflow (recent answers)
   - GitHub discussions
   - Tech blogs (Vercel, Netflix, etc.)

4. **Academic Research**
   - Peer-reviewed papers
   - Conference proceedings
   - Academic journals

5. **Community Consensus**
   - Reddit discussions
   - Twitter/X tech community
   - Discord/Slack communities

## Output Format

When providing best practice recommendations:

```markdown
## Best Practice Recommendation: [Topic]

### Context
[Brief description of the question and constraints]

### Research Summary
[What was researched and sources consulted]

### Current Approach (if applicable)
- Current implementation: [brief description]
- Files: `path/to/file.ts:42`
- Assessment: [what's working, what's not]

### Recommended Approach
**Primary Recommendation**: [Approach name]

#### Rationale
- [Why this approach]
- [Key benefits]
- [Trade-offs accepted]

#### Implementation
```[language]
// Code example
```

#### Considerations
- [Important consideration 1]
- [Important consideration 2]

### Alternative Approaches
1. **[Alternative 1]**
   - Pros: [...]
   - Cons: [...]
   - Use when: [...]

2. **[Alternative 2]**
   - Pros: [...]
   - Cons: [...]
   - Use when: [...]

### Comparative Analysis
| Aspect | Recommended | Alternative 1 | Alternative 2 |
|--------|-------------|---------------|---------------|
| ...    | ...         | ...           | ...           |

### Implementation Guide
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Potential Pitfalls
- [Pitfall 1]: How to avoid
- [Pitfall 2]: How to avoid

### Additional Resources
- [Link to official docs]
- [Link to detailed guide]
- [Reference to existing implementation]
```

## Important Notes

- This skill activates automatically when best practice guidance is needed
- Always research current standards (2025, not outdated info)
- Provide context-specific recommendations, not generic advice
- Include code examples when possible
- Cite sources and reasoning
- Consider project-specific constraints
- Balance ideals with pragmatism
- Acknowledge trade-offs explicitly
- Provide migration path if changing existing code
- Stay updated with evolving best practices

---

Remember: Best practices are not dogma. They're proven approaches that work in most contexts. Always adapt to the specific situation and explain the reasoning behind recommendations.