Workflow Best Practices
Mastering the correct workflow can increase your development efficiency by 10x. This article shares community-verified Opencode best practices.
Core Concept: From Conversation to Orchestration
Traditional AI programming tool mindset:
I ask → AI answers → I ask again → AI answers again
Opencode mindset:
I give instructions → AI breaks down tasks → Multiple Agents collaborate → Auto-complete
When you master "orchestration" instead of "conversation", you transform from an AI user to an AI team manager.
Basic Workflow: Five-Step Method
Universal process suitable for all development tasks:
1. Solution Design
Let AI think first, rather than jumping straight into action:
@architect Design a user authentication system with requirements:
1. Support email and phone login
2. Support OAuth (Google, GitHub)
3. Include JWT token management
4. Consider security and scalability
Please provide:
- System architecture diagram
- Database table structure
- API interface design
- Security measures
- Potential risks
Why do this?
- Avoid rework: Confirm solution before implementation
- Discover issues: Find potential problems in design phase
- Facilitate discussion: Discuss pros and cons of solution with AI
2. Gather Evidence
Let AI search existing code and best practices:
@explorer Search in project:
1. Existing authentication-related code
2. Database connection configuration
3. Middleware usage patterns
@librarian Find:
1. JWT best practices
2. OAuth 2.0 implementation examples
3. Common security vulnerabilities
3. Define Boundaries
Define clear task boundaries:
@plan Create implementation plan, noting:
1. Don't modify existing user table structure
2. Maintain compatibility with existing APIs
3. Add complete error handling
4. Each step should be independently testable
Please provide detailed Todo list
4. Implement Gradually
Progress step by step according to plan:
@build Implement step 1 according to plan: Create database tables
After completion, have @reviewer review code
Then continue to next step
5. Code Review
Have AI review its own code:
@reviewer Review the just-implemented code, focusing on:
1. Security: SQL injection, XSS, CSRF
2. Performance: Database query optimization, caching strategy
3. Error handling: Edge cases, exceptions
4. Code quality: Readability, maintainability
Provide detailed review report and improvement suggestions
Advanced Workflow: Scenario-Based Practices
Scenario 1: New Feature Development
Complete feature development process:
# Phase 1: Requirement Analysis
I want to develop a blog comment feature supporting:
- User comments and replies
- Likes and reports
- Markdown format
- Real-time notifications
@architect Analyze requirements and design solution
# Phase 2: Technical Research
@explorer Search in project:
- Existing comment-related code
- Notification system implementation
- Markdown renderer usage
# Phase 3: Solution Confirmation
Based on research results, @architect update design solution
# Phase 4: Task Breakdown
@plan Create detailed implementation plan
# Phase 5: Gradual Implementation
@build Implement according to plan
# Phase 6: Integration Testing
@tester Write integration tests
# Phase 7: Documentation
@documenter Write API documentation
Scenario 2: Bug Fixing
Efficient bug fixing process:
# Problem Description
User login occasionally fails with error:
"Token validation failed"
# Step 1: Problem Localization
@explorer Search all Token validation-related code
@architect Analyze possible causes
# Step 2: Reproduce Problem
@build Write test case to reproduce issue
# Step 3: Root Cause Analysis
Based on test results, @architect determine root cause
# Step 4: Fix Implementation
@build Implement fix solution
# Step 5: Regression Testing
@tester Run all related tests
# Step 6: Code Review
@reviewer Review fix code
Scenario 3: Code Refactoring
Safe refactoring process:
# Refactoring Goal
Auth module code is messy, needs refactoring
Requirements:
1. Split into smaller modules
2. Improve testability
3. Maintain API compatibility
# Step 1: Current State Analysis
@explorer Analyze auth module
@architect Evaluate:
- Existing problems
- Refactoring risks
- Refactoring solution
# Step 2: Create Plan
@plan Create refactoring plan
# Step 3: Gradual Refactoring
@build Refactor according to plan
# Step 4: Performance Testing
@tester Compare performance before and after refactoring
# Step 5: Code Review
@reviewer Review refactored code
Advanced Tips
1. Use AGENTS.md
Create AGENTS.md in project root to help AI remember project specifications:
# Project Specifications
## Tech Stack
- Frontend: React 18 + TypeScript + Vite
- Backend: Node.js + Express + PostgreSQL
- Deployment: Docker + AWS
## Coding Standards
- Use ESLint + Prettier
- Components use functional + Hooks
- State management uses Zustand
- API calls use React Query
## Directory Structure
- `/src/components` - Reusable components
- `/src/features` - Feature modules
- `/src/hooks` - Custom Hooks
- `/src/utils` - Utility functions
2. Use Todo-Driven Development
Have AI create Todo list, then complete items one by one:
@plan Create detailed Todo list for this feature
Then @build complete items one by one, after each item:
1. Mark as complete
2. Run tests
3. Commit code
4. Continue to next item
3. Parallel Development
Have multiple Agents work simultaneously:
Simultaneously:
1. @build Implement backend API
2. @frontend-dev Implement frontend components
3. @documenter Write API documentation
Integration testing after completion
Common Pitfalls
Pitfall 1: Completing Large Tasks at Once
❌ Wrong approach:
Help me implement a complete e-commerce system
✅ Correct approach:
Step 1: Design e-commerce system architecture
Step 2: Implement user module
Step 3: Implement product module
...
Pitfall 2: No Clear Boundaries
❌ Wrong approach:
Optimize this module's performance
✅ Correct approach:
Optimize this module's performance, requirements:
1. Don't modify API interfaces
2. Maintain backward compatibility
3. Add performance tests
4. Target: Response time < 100ms
Efficiency Tips
1. Use Shortcuts
Cmd/Ctrl + K- Quick invoke AICmd/Ctrl + L- Open chat panelCmd/Ctrl + .- Code explanation
2. Use Commands
/models- Switch models/agents- Switch Agents/compact- Compress context/share- Share session
3. Use Templates
Create common prompt templates for frequently used tasks.
Team Collaboration
1. Unified Configuration
Team shares opencode.json
2. Unified Specifications
Team shares AGENTS.md to ensure AI follows team standards
3. Code Review
Use AI to assist Code Review
Summary
Good workflow should:
- Think before acting - Design solution → Gather evidence → Implement
- Small steps, fast iterations - Break down tasks → Implement gradually → Verify promptly
- Continuous review - Code review → Test verification → Continuous improvement
- Clear boundaries - Clear task scope → Controllable risks
- Team collaboration - Unified configuration → Unified specifications → Unified process
Next Steps
Compiled by the OpenCodex community. Welcome to share your workflow experience.