Best Practices¶
This guide provides best practices for using MCP Sub-Agents effectively to build high-quality, production-ready applications.
Agent Selection¶
Choosing the Right Agent¶
Use Savants For:¶
- Architecture decisions and system design
- Technology stack selection
- Complex cross-cutting problems
- Full-stack feature coordination
- Making tradeoffs between options
- Learning about entire ecosystems
Example:
# Good savant usage
Use fullstack-js-savant to design an e-commerce platform architecture
# Not ideal for savant
Use fullstack-js-savant to create a button component
Use Specialists For:¶
- Framework-specific implementation
- Detailed code generation
- UI component development
- API endpoint creation
- Domain-specific optimization
- Focused tasks with clear scope
Example:
# Good specialist usage
Use frontend-ui to create a product card component with shadcn/ui
# Better handled by savant
Use frontend-ui to design entire application architecture
Agent Chaining¶
Chain agents for complex tasks:
# 1. Architecture
Use architect to design system architecture
# 2. Database
Use database to create Prisma schema
# 3. API
Use backend-api to implement tRPC routers
# 4. UI
Use frontend-ui to create components
# 5. Review
Use code-reviewer to review implementation
Communication with Agents¶
Be Specific¶
Provide detailed context and requirements:
# Good - specific and detailed
Use frontend-ui to create a multi-step checkout form with steps for shipping, payment, and confirmation. Include Zod validation, progress indicator, and ability to navigate between steps.
# Less effective - vague
Use frontend-ui to create a form
Provide Context¶
Include relevant information:
# Good - includes context
Use backend-api to create a posts API. Users should only be able to edit their own posts. Include pagination with cursor-based approach for infinite scroll.
# Less effective - missing context
Use backend-api to create a posts API
Ask for Explanations¶
Request explanations for learning:
Request Best Practices¶
Ask about recommended approaches:
Use security to explain OWASP Top 10 vulnerabilities and prevention strategies for Next.js applications
Workflow Commands¶
When to Use Workflow Commands¶
Use workflow commands when:
- Learning - New to a pattern or technology
- Completeness - Want comprehensive checklists
- Structure - Need step-by-step guidance
- Quality - Ensuring nothing is missed
- Onboarding - Training new team members
When to Use Direct Invocation¶
Use direct agent invocation when:
- Speed - Quick, specific tasks
- Experience - Familiar with the workflow
- Precision - Know exactly what's needed
- Iteration - Small fixes or changes
Effective Command Sequencing¶
Follow logical progression:
# Recommended sequence
/mcp-design-nextjs # 1. Design
/mcp-implement-fullstack # 2. Implement
/mcp-review-code # 3. Review
/mcp-review-security # 4. Security
/mcp-qa-e2e # 5. Test
/mcp-deploy # 6. Deploy
Avoid skipping design:
# Avoid this
/mcp-implement-fullstack # Implementing without design
/mcp-design-nextjs # Design should come first
Code Quality¶
Review Proactively¶
Review code regularly, not just at the end:
# After each feature
/mcp-implement-fullstack
/mcp-review-code
# Not just at the end
# ... multiple features ...
/mcp-review-code # Too late
Multi-Aspect Review¶
Use multiple review specialists:
/mcp-review-code # Code quality
/mcp-review-security # Security
/mcp-review-performance # Performance
Iterate on Feedback¶
Address issues and re-review:
/mcp-review-code # Review
Use code-reviewer to fix issues # Address feedback
/mcp-review-code # Verify fixes
Testing¶
Test as You Build¶
Write tests alongside implementation:
Comprehensive Test Coverage¶
Cover multiple testing layers:
# Unit tests
Use qa-tester to write Vitest unit tests for utility functions
# Integration tests
Use qa-tester to write integration tests for API routes
# E2E tests
/mcp-qa-e2e
Test Critical Paths¶
Focus on high-value test coverage:
- Authentication flows
- Payment processing
- Data mutations
- User workflows
- Error handling
Performance¶
Optimize Early¶
Consider performance from the start:
# During design
/mcp-design-nextjs
# Ask about performance considerations
# During implementation
Use fullstack-nextjs with focus on Core Web Vitals optimization
Regular Performance Checks¶
Monitor performance continuously:
Measure Before Optimizing¶
Always audit before optimizing:
# Good approach
/mcp-review-performance # Identify issues
Use performance to fix # Address specific problems
/mcp-review-performance # Verify improvements
# Avoid premature optimization
Use performance to optimize # Without measuring first
Security¶
Security First¶
Consider security from day one:
Regular Security Audits¶
Schedule regular security reviews:
Defense in Depth¶
Apply security at multiple layers:
- Input validation (client and server)
- Authentication and authorization
- Data encryption
- Security headers
- Rate limiting
- Audit logging
Documentation¶
Document as You Build¶
Create documentation alongside code:
Comprehensive Documentation¶
Cover all aspects:
- README with quick start
- API reference
- Architecture documentation
- User guides
- Deployment instructions
Keep Documentation Updated¶
Update docs when code changes:
Deployment¶
Automate Early¶
Set up CI/CD from the start:
Multiple Environments¶
Use staging before production:
Deployment Checklist¶
Always use pre-deployment checklist:
- Code review complete
- Security audit passed
- Performance verified
- Tests passing
- Documentation updated
- Database migrations ready
- Monitoring configured
Project Organization¶
Consistent Structure¶
Use consistent project structure:
app/
├── (auth)/
├── (dashboard)/
├── api/
├── actions/
components/
├── ui/
├── forms/
lib/
├── db.ts
├── auth.ts
Type Safety¶
Maximize type safety:
- Use TypeScript strict mode
- Zod for runtime validation
- tRPC for type-safe APIs
- Prisma for type-safe database
Separation of Concerns¶
Keep concerns separated:
- Server Components for data fetching
- Client Components for interactivity
- Server Actions for mutations
- Route Handlers for external APIs
Team Collaboration¶
Shared Agent Usage¶
Use project-specific installation:
# In project .claude directory
mkdir -p .claude/agents .claude/commands
cp -r agents/* .claude/agents/
Consistent Patterns¶
Use workflow commands for consistency:
Code Review with Agents¶
Use code-reviewer before human review:
Continuous Improvement¶
Learn from Reviews¶
Study agent feedback to improve:
Use code-reviewer to review my implementation
# Read feedback carefully
# Understand recommendations
# Apply learnings to future code
Regular Audits¶
Schedule regular comprehensive audits:
Stay Updated¶
Keep agents and practices current:
Common Pitfalls to Avoid¶
Don't Skip Design¶
# Avoid
/mcp-implement-fullstack # Without design
# Better
/mcp-design-nextjs
/mcp-implement-fullstack
Don't Ignore Security¶
# Avoid
# ... build entire app ...
/mcp-review-security # Too late
# Better
/mcp-review-security # Regular audits during development
Don't Skip Testing¶
# Avoid
/mcp-implement-fullstack
# Move to next feature without tests
# Better
/mcp-implement-fullstack
/mcp-qa-e2e
Don't Optimize Prematurely¶
# Avoid
Use performance to optimize # Without measuring
# Better
/mcp-review-performance # Measure first
Use performance to fix issues # Then optimize
Summary¶
Key best practices:
- Choose the right agent - Savants for architecture, specialists for implementation
- Be specific - Provide detailed context and requirements
- Review proactively - Regular code, security, and performance reviews
- Test continuously - Write tests as you build
- Document thoroughly - Keep documentation updated
- Automate deployment - CI/CD from the start
- Prioritize security - Security-first approach
- Optimize wisely - Measure before optimizing