OpenCode Tutorials
Home
Tutorials
Ecosystem
FAQ
Comparisons
Posts
  • Official Website
  • Official Download
  • Official Docs
  • About
  • Contact
  • Privacy Policy
  • Terms of Service
  • Disclaimer
  • Trademark Notice
  • 简体中文
  • English
  • Deutsch
Home
Tutorials
Ecosystem
FAQ
Comparisons
Posts
  • Official Website
  • Official Download
  • Official Docs
  • About
  • Contact
  • Privacy Policy
  • Terms of Service
  • Disclaimer
  • Trademark Notice
  • 简体中文
  • English
  • Deutsch
  • Ecosystem & Integrations

    • Opencode Ecosystem Integration - Docker, MCP, Antigravity
  • Best Practices

    • Best Practices
  • Troubleshooting

    • Troubleshooting

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 AI
  • Cmd/Ctrl + L - Open chat panel
  • Cmd/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:

  1. Think before acting - Design solution → Gather evidence → Implement
  2. Small steps, fast iterations - Break down tasks → Implement gradually → Verify promptly
  3. Continuous review - Code review → Test verification → Continuous improvement
  4. Clear boundaries - Clear task scope → Controllable risks
  5. Team collaboration - Unified configuration → Unified specifications → Unified process

Next Steps

  • Agent Configuration Guide
  • Permissions and Security Configuration
  • Troubleshooting

Compiled by the OpenCodex community. Welcome to share your workflow experience.

Last Updated: 2/28/26, 2:48 PM