OpenCode on Wanzi's Blog – Notes on life, tech, and DevOps.

Developing Existing Projects with OpenSpec

wzdushu@gmail.com (wanzi) — Mon, 30 Mar 2026 22:10:42 +0800

Recently, I have been using OpenCode in conjunction with OpenSpec for secondary development on existing projects. I encountered some pitfalls and recorded them here:

1. Initialize Project:

First, run the CLI command in the project root directory to create the basic directory structure required by OpenSpec.

# openspec init 
Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0
Detected tool directories: OpenCode (pre-selected for first-time setup)
✔ Select tools to set up (24 available) OpenCode
▌ OpenSpec structure created
✔ Setup complete for OpenCode

OpenSpec Setup Complete

Created: OpenCode
4 skills and 4 commands in .opencode/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Learn more: https://github.com/Fission-AI/OpenSpec
Feedback:   https://github.com/Fission-AI/OpenSpec/issues

Restart your IDE for slash commands to take effect.

Additionally, to understand OpenSpec more deeply, it is recommended to enable all OpenSpec extension features for direct use in OpenCode or Claude Code later. You need to restart OpenCode or Claude Code after modification:

# openspec config profile

Current profile settings
  Delivery: both
  Workflows: 11 selected (custom)
  Delivery = where workflows are installed (skills, commands, or both)
  Workflows = which actions are available (propose, explore, apply, etc.)

✔ What do you want to configure? Delivery and workflows
✔ Delivery mode (how workflows are installed): Both (skills + commands) [current]
? Select workflows to make available:
❯[x] Propose change
 [x] Explore ideas
 [x] New change
 [x] Continue change
 [x] Apply tasks
 [x] Fast-forward
 [x] Sync specs
 [x] Archive change
 [x] Bulk archive
 [x] Verify change
 [x] Onboard

Create proposal, design, and tasks from a request
Space to toggle, Enter to confirm

2. Use Explore to Analyze Existing Code

This is the most critical step. You need to use the /opsx:explore command to guide the AI in analyzing your codebase and generating an initial specification.

How to use: Enter in the AI chat box:

/opsx:explore Analyze the architecture and core business logic of the current project, and generate corresponding specification documents

Function: The AI will scan your code files, understand the existing tech stack, directory structure, and functional modules, and then attempt to generate an initial proposal.md or specs document for you, serving as a baseline for subsequent development.

3. Complete Configuration

We all know that the core philosophy of OpenSpec is “define rules first, act later,” solving the “context loss” and “code chaos” issues AI often encounters in large projects through Spec-Driven Development (SDD).

Therefore, to help the AI understand your project more accurately, you can manually edit the OpenSpec “constitution” file openspec/config.yaml.

Content: Add your tech stack (e.g., React, Python, Go), coding conventions, domain knowledge, etc. This helps the AI generate code that better fits your project style.

Here, I directly asked the agent in OpenCode to output it:

Add the project's tech stack, coding conventions, domain knowledge, etc., to the openspec/config.yaml file to facilitate more accurate project understanding by OpenSpec in the future.

4. Start Incremental Development

After completing the above steps, you can proceed with development following the standard OpenSpec workflow:

Create change: Use /opsx:ff <feature_name> (fast mode) or /opsx:new <feature_name> (full mode) to start developing a new feature.
Define incremental spec: Describe this change (add/modify/delete) in the generated specs/ file.
Execute and archive: Use /opsx:apply to generate code. After verification, use /opsx:archive to archive. During archiving, the incremental spec will be automatically merged into the main spec. I apologize again for the inaccurate information provided previously; I hope this process helps you integrate OpenSpec smoothly.

Example: Adding a text translation tool to my technical toolbox:

/opsx:new Add a text translation tool that calls a large model in the background. Use the minimax API interface by default, referencing https://platform.minimaxi.com/docs/guides/text-generation. It should also support calling glm models, referencing the API interface at https://docs.bigmodel.cn/cn/guide/develop/claude/introduction. The translation function should be similar to https://fanyi.baidu.com/mtpe-individual/transText#/

The final project directory structure is as follows:

openspec
├── changes
│   └── archive
│       └── 2026-03-30-add-text-translator
├── config.yaml
└── specs
    └── text-translator
        └── spec.md

5. What to do if the feature doesn’t work?

If you are verifying after the AI has generated code and find that the code doesn’t run or doesn’t meet expectations, verification fails (/opsx:verify)

Do not modify the code directly: In the OpenSpec workflow, code is the product of the specification. If the code is wrong, it is usually because the “specification” was not written clearly enough, or the AI misunderstood it.
Correct repair steps:

1. Modify the specification (spec.md):

Open openspec/changes/new feature 1/specs/.../spec.md and write your corrective opinions into it.

For example: Add “Must handle network timeout situations” to the scenario description.

2. Re-apply (`/opsx:apply`):

Tell the AI: “I have updated the specification, please re-run /opsx:apply”. The AI will regenerate the code based on the new specification, overwriting the previous incorrect code.

3. Verify again:

Run /opsx:verify again to confirm the issue is resolved.

6. How to ensure synchronization with spec.md after modifying code?

In the OpenSpec workflow, code is the product of the specification. If you manually modify the code but spec.md is not synchronized, it will lead to “documentation and code disconnection.” The next time the AI generates code based on spec.md, your manual modifications will be overwritten or cause conflicts.

To ensure synchronization between the two, please choose one of the following three strategies based on when and why you modified the code:

1. Best Strategy: Modify Documentation First, Then Generate Code (Spec-First)

This is the method most recommended by OpenSpec. If you find a problem with the code (e.g., wrong logic, incorrect parameters), do not go directly to the code files to change them.

Steps: 1.1 Open openspec/changes/.../spec.md. 1.2 Modify the corresponding requirement description or scenario. 1.3 Run /opsx:apply. 1.4 Result: The AI will regenerate the code based on the new document, automatically overwriting the old implementation. This is the most thorough way to maintain synchronization.

2. Remedial Strategy: Code Modified, Reverse Sync Documentation (Reverse Sync)

If you are used to modifying code quickly first (e.g., fixing a bug or fine-tuning styles), you must immediately “backfill” the changes into the document after modification.

Steps:
1. Save code: Ensure your code modifications are saved.
2. Run verification: Enter /opsx:verify in the AI chat box.
  - The AI will compare your new code with the old spec.md.
  - It will discover inconsistencies (e.g., “Redis expiration time in code is 600 seconds, but document says 300 seconds”).
3. Accept suggestion: Let the AI update spec.md based on the code.
4. Result: The document is updated to match your code, and the two are consistent again.

3. Forced Synchronization During Archiving (`/opsx:archive`)

When you finish feature development and are ready to archive, OpenSpec will force a check on the synchronization status.

Mechanism:
- When you run /opsx:archive, OpenSpec will merge the spec.md in the current change directory into the project’s global specification library (openspec/specs/).
- Note: If you manually changed the code but didn’t update spec.md, your code logic will never be reflected in the document after archiving. The next time someone (or AI) views the archived document, they will see outdated logic.

7. Discovering spec.md lags behind code after archiving

To avoid this situation, you need to establish a set of “defensive” work habits.

1. Build “Verify -> Archive” Muscle Memory

This is the most direct and effective daily habit. Never treat /opsx:archive as the only action after development ends.

Bad habit: Change code -> Test pass -> /opsx:archive
Good habit: Change code -> /opsx:verify -> (Sync if there are differences) -> Test pass -> /opsx:archive

Specific operation: After you manually modify the code and before archiving, you must run /opsx:verify (or ask the AI to check in the AI chat box).

Tell the AI: “I manually modified xxx.ts, please compare it with spec.md, and if there are inconsistencies, please help me update spec.md.”
Only execute the archive after the AI confirms “Code is consistent with specification”.

2. Use Git Hooks (Pre-commit Hook) for Mandatory Checks

If you are worried you might occasionally forget, you can use Git’s mechanism for mandatory interception. This is a recommended practice for team collaboration.

You can add check logic to the project’s .git/hooks/pre-commit file. Although OpenSpec does not directly provide this hook, you can write a simple script:

Script logic idea:

Detect if any code files (e.g., .ts, .java, .py) have been modified.
Detect if the corresponding documents under openspec/changes/ have also been modified.
If code changed but document didn’t -> Intercept commit and prompt: “Code changes detected but OpenSpec document not updated, please run verify or update document first!”

#!/bin/sh
# .git/hooks/pre-commit

# Check if there are code changes in the staging area
CODE_CHANGES=$(git diff --cached --name-only | grep -E "\.(ts|js|java|py)$" | wc -l)
# Check if there are Spec changes in the staging area
SPEC_CHANGES=$(git diff --cached --name-only | grep "openspec/" | wc -l)

if [ "$CODE_CHANGES" -gt 0 ] && [ "$SPEC_CHANGES" -eq 0 ]; then
  echo "⚠️  Warning: Code changes detected, but no OpenSpec document changes found!"
  echo "⚠️  Please ensure your code logic is synchronized to spec.md, or run /opsx:verify."
  echo "To force commit, use --no-verify (not recommended)"
  exit 1
fi

exit 0

Additionally, for modern projects, it is recommended to use dedicated tools to manage hooks, so the configuration can be written into the codebase and shared by everyone.

Python projects / General: Use the pre-commit framework.
- Configure .pre-commit-config.yaml to define check rules (e.g., flake8, black, detect-secrets).
- Run pre-commit install to automatically configure hooks.
Frontend/Node projects: Use Husky.
- It allows you to easily define hook logic in package.json without manually handling shell script permissions.
Golang and Rust projects:
- Use lefthook: https://github.com/evilmartians/lefthook, a universal tool with parallel execution for Go development, extremely fast.

lefthook.yml generic configuration template:

# Lefthook configuration file
# Supports multi-language mixed projects (Polyglot/Monorepo)

# Global settings
min_version: 1.4.0

# pre-commit hook: Triggered on git commit
pre-commit:
  parallel: true # Core optimization: Execute all checks in parallel, greatly improving speed
  commands:
    
    # ==========================================
    # 1. Frontend (JavaScript / TypeScript)
    # ==========================================
    frontend-lint:
      glob: "*.{js,ts,jsx,tsx,vue}"
      run: npx eslint {staged_files} --fix
      # Note: If the project has no package.json, Lefthook will automatically skip or error, depending on configuration

    frontend-format:
      glob: "*.{js,ts,jsx,tsx,vue,css,scss,json}"
      run: npx prettier --write {staged_files}

    # ==========================================
    # 2. Go (Golang)
    # ==========================================
    go-fmt:
      glob: "*.go"
      # gofmt -w will modify files directly, ensuring the staging area is updated
      run: gofmt -w {staged_files}
    
    go-lint:
      glob: "*.go"
      # Assuming you have installed golangci-lint, this is the Go community standard lint tool
      run: golangci-lint run {staged_files}

    # ==========================================
    # 3. Rust
    # ==========================================
    rust-fmt:
      glob: "*.rs"
      run: cargo fmt -- {staged_files}

    rust-check:
      glob: "*.rs"
      # Use clippy for deep checks
      run: cargo clippy -- -D warnings

    # ==========================================
    # 4. Python
    # ==========================================
    python-lint:
      glob: "*.py"
      # Using flake8 as an example here, can also be replaced with black --check or pylint
      run: flake8 {staged_files}

    python-format:
      glob: "*.py"
      # If using black for formatting
      run: black {staged_files}

    # ==========================================
    # 5. Java / Kotlin
    # ==========================================
    # Java usually relies on build tools (Maven/Gradle) or specific linters (like checkstyle)
    # Here demonstrates calling Gradle's check task, which automatically handles all Java files
    java-check:
      glob: "*.java"
      # Note: Gradle tasks are usually slow and do not support checking only some files,
      # It is recommended to run full checks only in pre-push, or use plugins like spotless that support incremental checks
      run: ./gradlew checkstyleMain checkstyleTest --quiet

    # ==========================================

3. Remedial Action

Create a new change: Name it sync-logic-with-code or fix-docs-consistency.
Let AI reverse engineer: In this new change, tell the AI: “The current xxx feature code logic has changed, but spec.md is still old. Please rewrite/update spec.md based on the current code.”
Archive this “document fix”: Run /opsx:apply (at this point the AI will generate the updated document) and /opsx:archive.

Result: Your main specification library (openspec/specs/) will be updated by this new archive, becoming consistent with the code again. Although the history archive leaves a trace of “outdated documentation,” the latest main specification is accurate.

In conclusion, while using OpenSpec for project development, always keep the core principle of OpenSpec in mind:

Documentation (Spec) is the source, code is the result. When encountering problems, fix the documentation first, then let the AI rewrite the code.

Best Practices for Using Claude Code

wzdushu@gmail.com (wanzi) — Thu, 05 Feb 2026 10:30:00 +0800

Claude Code is the official AI coding tool launched by Anthropic. It can read codebases, edit files, run commands, and integrate with development tools. It excels in complex reasoning and code understanding, making it one of the most powerful AI coding tools available today.

Detailed Introduction to Claude Code

What is Claude Code

Claude Code is an AI-driven agent coding assistant that helps developers build features, fix bugs, and automate development tasks. It understands the entire codebase and can work across multiple files and tools to complete tasks.

Core Advantages:

Powerful code understanding and reasoning capabilities
Supports multiple interfaces including Terminal, VS Code, and JetBrains
MCP (Model Context Protocol) extension support
Multi-agent collaboration features
Full Git workflow integration
Supports the full family of Claude models

Claude Code Installation

macOS / Linux (Recommended)

`1`	`curl -fsSL https://claude.ai/install.sh \| bash`

Windows PowerShell

`1`	`irm https://claude.ai/install.ps1 \| iex`

Windows CMD

`1`	`curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`

Homebrew

`1`	`brew install --cask claude-code`

WinGet (Windows)

`1`	`winget install Anthropic.ClaudeCode`

VS Code Extension

Search for “Claude Code” in the VS Code Extension Marketplace and install.

Quick Start

# Enter project directory
cd your-project

# Start Claude Code
claude

# Specify a task directly
claude "Help me create a user login feature"

Basic Usage of Claude Code

Basic Usage Tips

1. Task Decomposition Strategy

Do not ask the AI to complete complex tasks all at once:

# Inefficient ❌
claude "Help me write a complete e-commerce system"

# Efficient ✅
claude "Help me design the user database schema"
claude "Write a user registration API based on this structure"
claude "Add login verification logic"

2. Provide Complete Context

# Missing information ❌
claude "This code has an error"

# Complete information ✅
claude "I am writing a web service with Flask. The login endpoint returns a 500 error.
Error message: TypeError: Cannot read property 'name' of undefined
The stack trace shows it occurred at line 45 in app.py.
Help me analyze the cause and fix it."

3. Use Tool Calls

Claude Code can perform various operations:

# Read file
Read file: src/main.py

# Search code
Grep pattern: "def login" path: src/

# Execute command
Bash command: python -m pytest

# Write file
Write file: src/utils.py

# Batch operations
Glob pattern: "**/*.py"

Claude Code Model Selection

Claude Code supports multiple Claude models, which can be selected based on task complexity:

Model	Capability	Speed	Use Cases
Claude Opus 4.6	Highest	Slower	Complex architecture design, deep refactoring
Claude Sonnet 4.6	High	Medium	Daily development, code generation
Claude Haiku 4.5	Medium	Fast	Quick completion, simple tasks

1
2

# Switch model
/model claude-sonnet-4-6

Advanced Features of Claude Code

MCP Server Integration

MCP (Model Context Protocol) allows connecting Claude Code to external tools and data sources:

# Set up MCP servers in the configuration file
# ~/.claude/config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem"],
      "allowedDirectories": ["~/projects"]
    }
  }
}

CLAUDE.md File

Create a CLAUDE.md file in the project root directory. Claude Code will read it at the start of every session:

# Project Description

## Code Standards
- Use TypeScript strict mode
- Follow Airbnb ESLint configuration

## Architecture Decisions
- Use dependency injection pattern
- All API calls must include error handling

## Preferred Libraries
- State Management: Zustand
- HTTP Client: Ky

Custom Commands (Skills)

Create reusable command templates:

# Create /review-pr command
# ~/.claude/commands/review-pr.md
# Review Pull Request

Please review this PR:
1. Check code quality and style consistency
2. Look for potential security issues
3. Evaluate if test coverage is sufficient
4. Verify documentation is updated

@pr-url

Hooks Configuration

Automatically execute shell commands before or after operations:

# ~/.claude/config.json
{
  "hooks": {
    "PostEdit": [
      {
        "match": "*.ts",
        "command": "npx eslint --fix {file}"
      }
    ]
  }
}

Scheduled Tasks

# Run Claude on a schedule
claude /schedule

# Automate morning PR reviews
claude /loop 8h /pr review

# Automate nightly CI failure analysis
claude /schedule "0 22 * * *" "Analyze today's CI failures"

Multi-Agent Collaboration

# Start multiple agents working in parallel
claude "Start a team to handle this feature:
- Agent 1: Frontend component development
- Agent 2: Backend API development
- Agent 3: Test writing
Coordinate their work and merge the results"

Git and Workflow Integration

Git Workflow

# Commit changes
claude "commit my changes with a descriptive message"

# Create a branch
claude "Create a feature branch to implement user registration"

# Analyze change impact
claude "Analyze what changes exist in the current branch compared to main"

Code Review Process

# 1. Let Claude read the code
claude "Please read all Python files in the src directory to understand the project structure"

# 2. Propose specific review requirements
claude "For the file src/api/v1/users.py:
- Check if input validation is complete
- Look for potential security vulnerabilities
- Evaluate if error handling is reasonable"

# 3. Request fix suggestions
claude "For the issues found, please provide fix solutions one by one"

Debugging Tips

# Provide error information
claude "The following error occurs when running 'python app.py':
TypeError: Cannot read property 'name' of undefined
The stack trace shows the error occurred at line 45.
Help me locate the problem and fix it."

# Provide reproduction steps
claude "1. Run 'npm run dev'
2. Visit http://localhost:3000
3. Click the login button
4. Enter correct credentials and click submit
Expected: Login successful and redirect
Actual: Page freezes with no response
Console shows: Pending POST /api/login"

Domestic LLM Configuration

Claude Code natively uses Claude models but also supports configuring other domestic models as alternatives.

GLM4 Series (Zhipu AI)

Zhipu’s GLM series excels in Chinese understanding and code generation.

GLM4.7 Features:

Ultra-long context support
Powerful Chinese understanding capabilities
Strong code generation capabilities
Tool Calling support

Configuration Method:

# Configure GLM via MCP
# ~/.claude/config.json
{
  "mcpServers": {
    "glm": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-zhipu-api-key",
        "OPENAI_BASE_URL": "https://open.bigmodel.cn/api/paas/v4"
      }
    }
  }
}

Kimi K2.5 (Moonshot AI)

Kimi K2.5 has unique advantages in long context and multimodal capabilities.

K2.5 Features:

256K ultra-long context
Multimodal understanding
Professional code generation, programming capability comparable to Claude

Pricing:

Input: ¥4.00/MTok
Output: ¥21.00/MTok
Cache Hit: ¥0.70/MTok

Configuration Method:

# Configure Kimi via MCP
# ~/.claude/config.json
{
  "mcpServers": {
    "kimi": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-kimi-api-key",
        "OPENAI_BASE_URL": "https://api.moonshot.cn/v1"
      }
    }
  }
}

MiniMax M2.5

MiniMax M2.5 is designed specifically for programming, focusing on fast response.

M2.5 Features:

High throughput, low latency
Optimized for production environments
SOTA programming and Agent capabilities
High cost-performance ratio

Configuration Method:

# Configure MiniMax via MCP
# ~/.claude/config.json
{
  "mcpServers": {
    "minimax": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-minimax-api-key",
        "OPENAI_BASE_URL": "https://api.minimax.chat/v1"
      }
    }
  }
}

Comparison with Other AI Coding Tools

Cursor

Cursor is one of the most popular AI-native IDEs, used by over half of the Fortune 500 companies.

Comparison with Claude Code:

Cursor is a complete AI editor, Claude Code is a CLI tool.
Cursor supports multiple models like GPT-5, Claude, and Gemini.
Claude Code has stronger reasoning capabilities, suitable for complex tasks.
Cursor has deeper AI integration.

Cursor Core Features:

Composer 2: Complete multi-file modifications with a single sentence.
Tab smart completion.
BugBot automatic code review.
Global codebase understanding.

Trae

Trae is an adaptive AI IDE focusing on local-first and privacy protection.

Comparison with Claude Code:

Trae has a Chinese-friendly interface and ample free quota.
Claude Code is more powerful and suitable for complex projects.
Trae is suitable for domestic users to get started quickly.

Trae Core Features:

Builder mode: Create files via conversation.
Chinese interface.
Privacy protection (data is not used for secondary training).
MCP protocol support.

OpenCode

OpenCode is a lightweight terminal AI coding tool developed in Go.

Comparison with Claude Code:

OpenCode is lighter and suitable for simple tasks.
Claude Code is more comprehensive in functionality.
OpenCode supports more model providers.

OpenCode Supported Models:

OpenAI: GPT-4.1, GPT-4.5, GPT-4o, O1, O3
Anthropic: Claude 4 Sonnet/Opus, Claude 3.5/3.7 Sonnet
Google: Gemini 2.5, 2.5 Flash, 2.0 Flash

Comparison Summary

Feature	Claude Code	Cursor	Trae	OpenCode
Type	CLI + Plugin	AI IDE	AI IDE	CLI Tool
Models	Claude	Multi-model	Multi-model	Multi-model
Reasoning	Strongest	Strong	Medium	Strong
Chinese Support	Average	Average	Excellent	Average
Learning Curve	Medium	Low	Low	Medium
Free Quota	Limited	Limited	Ample	Depends on API

Selection Advice:

Complex refactoring and deep tasks → Claude Code
Daily development and IDE experience → Cursor
Domestic users getting started quickly → Trae
Lightweight terminal tasks → OpenCode

Frequently Asked Questions

Q: Does Claude Code require payment?

A: Claude Code itself is free, but it requires a Claude API key. New users have a free quota, and subscribers have a more ample quota.

Q: Can domestic models replace Claude?

A: For daily programming tasks, domestic models are close to Claude’s level. Claude still has an advantage in complex reasoning tasks. Domestic models are cheaper.

Q: Can code written by AI be used directly?

A: No! AI code must be understood by yourself, tested locally, code reviewed, and confirmed safe before use.

Q: How do I choose a Claude model?

A: Use Haiku for simple tasks, Sonnet for daily development, and Opus for complex tasks.

Conclusion

Claude Code is one of the most powerful AI coding tools currently available, particularly suitable for:

Complex code understanding and refactoring
Batch operations across multiple files
Deep debugging and problem analysis
Tasks requiring strong reasoning capabilities

By configuring MCP, Claude Code can also use domestic models (GLM4, Kimi K2.5, MiniMax M2.5) as alternatives. Choose the appropriate tool and model based on task complexity and budget.

OpenCode Best Practices: Chinese Large Model Programming Assistant

wzdushu@gmail.com (wanzi) — Thu, 15 Jan 2026 21:22:42 +0800

OpenCode Overview

What is OpenCode

OpenCode is an open-source AI coding assistant built on VSCode with the following features:

Open Source & Free: Fully open source, self-hostable
Flexible Models: Supports multiple LLM backends
Local First: Protects code privacy
Highly Customizable: Extensible and customizable

Core Features

Feature	Description
Code Completion	Real-time code suggestions (single-line/multi-line)
Code Chat	Q&A on code
Code Generation	Generate code based on descriptions
Code Explanation	Explain the functionality of selected code
Refactoring Suggestions	Provide refactoring and optimization suggestions
Bug Fixing	Intelligently fix code errors

I. OpenCode Installation and Configuration

System Requirements

Operating System:
  - Windows 10/11
  - macOS 11+
  - Linux (Ubuntu 20.04+, CentOS 8+)

Hardware Requirements:
  - CPU: 4 cores+
  - RAM: 8GB+
  - Storage: 2GB available space

Software Dependencies:
  - Node.js 16+ (if building from source)
  - Git

Installation Steps

Method 1: Using Pre-built Versions (Recommended)

# 1. Download OpenCode
# Visit https://github.com/opencode-org/opencode/releases
# Download the installer for your platform

# Linux/macOS
wget https://github.com/opencode-org/opencode/releases/latest/download/opencv-linux-x64.tar.gz
tar -xzf opencv-linux-x64.tar.gz
cd opencv
./opencode

# macOS (using Homebrew Cask)
brew install --cask opencode

# Windows
# Download opencv-setup.exe and run the installer

# 2. Launch OpenCode
# The welcome page will appear on first launch

Method 2: Building from Source

# 1. Clone repository
git clone https://github.com/opencode-org/opencode.git
cd opencv

# 2. Install dependencies
npm install

# 3. Build project
npm run build

# 4. Run
npm run electron

Basic Configuration

settings.json Configuration

{
  // OpenCode Configuration
  "opencode.modelProvider": "openai",
  "opencode.apiKey": "your-api-key",
  "opencode.model": "gpt-4",
  "opencode.temperature": 0.3,
  "opencode.maxTokens": 2048,

  // Code Completion Configuration
  "opencode.autocomplete.enabled": true,
  "opencode.autocomplete.mode": "inline",
  "opencode.autocomplete.debounce": 150,

  // Code Chat Configuration
  "opencode.chat.enabled": true,
  "opencode.chat.contextLength": 10,

  // Privacy Configuration
  "opencode.telemetry.enabled": false,
  "opencode.anonymousUsageId": false,

  // Shortcut Configuration
  "opencode.suggestInline": "Ctrl+Enter",
  "opencode.openChat": "Ctrl+Shift+C",
  "opencode.explainCode": "Ctrl+Shift+E"
}

II. What OpenCode Can Do

1. Intelligent Code Completion

# Single-line completion
def calculate_discount(price, discount_rate):
    return price * (1 - discount_

# OpenCode auto-completes:
# rate)

# Multi-line completion
# Input comment:
# Create a function to calculate the nth term of the Fibonacci sequence

# OpenCode generates complete function:
def fibonacci(n):
    """
    Calculate the nth term of the Fibonacci sequence

    Args:
        n (int): The term number to calculate

    Returns:
        int: The value of the nth term
    """
    if n <= 0:
        return 0
    elif n == 1:
        return 1
    else:
        return fibonacci(n-1) + fibonacci(n-2)

2. Code Explanation

# Select complex code, OpenCode provides explanation

def merge_sort(arr):
    if len(arr) <= 1:
        return arr

    mid = len(arr) // 2
    left = merge_sort(arr[:mid])
    right = merge_sort(arr[mid:])

    return merge(left, right)

# OpenCode explanation:
# This is an implementation of the merge sort algorithm.
# 1. Base case: If array length <= 1, return directly
# 2. Divide and conquer: Split the array in half, sort recursively
# 3. Merge: Merge two sorted arrays
# Time Complexity: O(n log n)
# Space Complexity: O(n)

3. Code Refactoring

# Original code
def process_user(user):
    if user is not None:
        if user.get("name") is not None:
            if user.get("age") is not None and user["age"] >= 18:
                return True
    return False

# OpenCode refactoring suggestion:
def process_user(user):
    """
    Check if user is a valid adult

    Args:
        user (dict): User info dictionary

    Returns:
        bool: Whether the user is valid
    """
    if not user:
        return False

    name = user.get("name")
    age = user.get("age")

    return bool(name and age >= 18)

4. Bug Detection and Fixing

# Buggy code
def divide_numbers(a, b):
    result = a / b
    return result

# Call
print(divide_numbers(10, 0))  # ZeroDivisionError

# OpenCode detects and fixes:
def divide_numbers(a, b):
    """
    Safely divide two numbers

    Args:
        a (float): Dividend
        b (float): Divisor

    Returns:
        float: Division result

    Raises:
        ValueError: When divisor is 0
    """
    if b == 0:
        raise ValueError("Divisor cannot be zero")

    return a / b

5. Unit Test Generation

# Original function
def add(a, b):
    return a + b

# OpenCode generates unit tests:
import unittest

class TestAdd(unittest.TestCase):
    def test_add_positive_numbers(self):
        """Test adding positive numbers"""
        self.assertEqual(add(2, 3), 5)

    def test_add_negative_numbers(self):
        """Test adding negative numbers"""
        self.assertEqual(add(-2, -3), -5)

    def test_add_mixed_numbers(self):
        """Test adding positive and negative numbers"""
        self.assertEqual(add(2, -3), -1)

    def test_add_zero(self):
        """Test adding zero"""
        self.assertEqual(add(5, 0), 5)

    def test_add_floats(self):
        """Test adding floats"""
        self.assertAlmostEqual(add(2.5, 3.1), 5.6, places=1)

if __name__ == '__main__':
    unittest.main()

III. Introduction to oh-my-opencode

What is oh-my-opencode

oh-my-opencode is an enhanced configuration management tool for OpenCode, providing:

Preset Configurations: Optimized for different scenarios
Model Switching: Quickly switch between different LLMs
Shortcut Bindings: Predefined shortcuts
Theme Customization: Customize appearance

Installing oh-my-opencode

# 1. Clone repository
git clone https://github.com/opencode-org/oh-my-opencode.git ~/.oh-my-opencode

# 2. Install
cd ~/.oh-my-opencode
./install.sh

# 3. Restart OpenCode

Preset Configurations

# List available presets
oh-my-opencode list

# Apply preset
oh-my-opencode apply python-developer
oh-my-opencode apply go-developer
oh-my-opencode apply fullstack-developer

# Create custom preset
oh-my-opencode create my-preset --template python-developer

IV. Domestic LLM Integration

Supported Domestic LLMs

Model	Provider	Features	Recommended Scenarios
GLM-4	Zhipu AI	Strong Chinese understanding	Chinese development
Minimax M2.5	MiniMax	Strong coding ability	Code generation
Kimi K2.5	Moonshot	Long context	Document understanding
Qwen3.5	Alibaba Cloud	Multilingual ability	Full-stack development

1. GLM-4 Configuration

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://open.bigmodel.cn/api/paas/v4/chat/completions",
  "opencode.apiKey": "your-glm-api-key",
  "opencode.model": "glm-4",
  "opencode.temperature": 0.3,
  "opencode.maxTokens": 4096,
  "opencode.contextLength": 8192,

  // Request Header Configuration
  "opencode.customHeaders": {
    "Authorization": "Bearer your-glm-api-key"
  },

  // Response Format
  "opencode.responseFormat": {
    "type": "text"
  }
}

2. Minimax M2.5 Configuration

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://api.minimax.chat/v1/text/chatcompletion_v2",
  "opencode.apiKey": "your-minimax-api-key",
  "opencode.model": "abab5.5-chat",
  "opencode.temperature": 0.7,
  "opencode.maxTokens": 2048,

  // Minimax Specific Parameters
  "opencode.customParams": {
    "group": "chat_group_name",
    "role_setting": "You are a professional programming assistant",
    "tokens_to_generate": 2048,
    "temperature": 0.7
  }
}

3. Kimi K2.5 Configuration

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://api.moonshot.cn/v1/chat/completions",
  "opencode.apiKey": "your-kimi-api-key",
  "opencode.model": "moonshot-v1-8k",
  "opencode.temperature": 0.3,
  "opencode.maxTokens": 8192,

  // Kimi Long Context Configuration
  "opencode.contextWindow": 32000,
  "opencode.includeContext": "full"
}

4. Qwen3.5 Configuration

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
  "opencode.apiKey": "your-qwen-api-key",
  "opencode.model": "qwen-plus",
  "opencode.temperature": 0.5,
  "opencode.maxTokens": 6000,

  // Qwen Specific Parameters
  "opencode.customParams": {
    "top_p": 0.8,
    "enable_search": false
  }
}

Multi-Model Configuration Switching

# Create model configuration files
~/.opencode/models/
├── glm-4.json
├── minimax-m2.5.json
├── kimi-k2.5.json
└── qwen3.5.json

# Quickly switch models
opencode model switch glm-4
opencode model switch minimax-m2.5
opencode model switch kimi-k2.5
opencode model switch qwen3.5

# Set default model
opencode model default qwen3.5

V. Best Practices

1. Prompt Engineering

Characteristics of Good Prompts

A good prompt should:
1. Clear Goal - Clearly state what to do
2. Provide Context - Give relevant background information
3. Specify Format - State the expected output format
4. Give Examples - Provide examples of desired results
5. Set Constraints - Define clear limitations

Example Prompts

# Bad Prompt
Write a sorting function

# Good Prompt
Please write a quick sort function in Python with the following requirements:
1. Input: List of integers
2. Output: Sorted list
3. Handle edge cases: empty list, single-element list
4. Include complete docstrings
5. Add type annotations
6. Include unit test examples

Please follow the Google Python Style Guide

2. Context Management

# Provide sufficient context information

# Bad example - Lacks context
# Help me optimize this function
def process(data):
    result = []
    for item in data:
        result.append(item * 2)
    return result

# Good example - Provides context
# Optimize the following function, requirements:
# Scenario: Processing large amounts of sensor data (millions)
# Current performance: Processing 100k items takes 5 seconds
# Goal: Process 100k items in <1 second
# Constraint: Data order must be preserved
# Language: Python
def process(data):
    result = []
    for item in data:
        result.append(item * 2)
    return result

3. Security Best Practices

Security Practices:
  API Key Management:
    - Store API keys in environment variables
    - Rotate keys regularly
    - Do not commit to code repositories

  Code Review:
    - AI-generated code requires human review
    - Pay special attention to security vulnerabilities
    - Test edge cases

  Sensitive Information:
    - Do not let AI access sensitive code
    - Use anonymized data
    - Configure ignore rules

4. Performance Optimization

{
  // Performance Optimization Configuration
  "opencode.cache.enabled": true,
  "opencode.cache.size": "1GB",
  "opencode.cache.ttl": 86400,

  // Request Optimization
  "opencode.batchRequests": true,
  "opencode.requestTimeout": 30000,
  "opencode.retryAttempts": 3,

  // Response Cache
  "opencode.responseCache.enabled": true,
  "opencode.responseCache.maxSize": 500
}

5. Team Collaboration

Team Collaboration:
  Configuration Sharing:
    - Create team configuration files
    - Unify model selection
    - Unify prompt templates

  Version Control:
    # .opencoderc
    {
      "model": "qwen3.5",
      "temperature": 0.3,
      "presets": {
        "python": "python-dev-preset",
        "go": "go-dev-preset"
      }
    }

  Knowledge Base:
    - Maintain team prompt library
    - Share best practices
    - Regular training

VI. Frequently Asked Questions

Q1: How to Configure API Keys

# Method 1: Environment Variables (Recommended)
export OPENCODE_API_KEY="your-api-key"
export OPENCODE_API_ENDPOINT="https://api.example.com"

# Method 2: Configuration File
~/.opencode/config.json
{
  "apiKey": "your-api-key",
  "apiEndpoint": "https://api.example.com"
}

# Method 3: OpenCode Settings UI
# Settings > OpenCode > API Key

Q2: How to Improve Generation Quality

{
  // Configuration to Improve Generation Quality
  "opencode.temperature": 0.3,        // Reduce randomness
  "opencode.topP": 0.9,               // Control diversity
  "opencode.frequencyPenalty": 0.5,   // Reduce repetition
  "opencode.presencePenalty": 0.3,    // Encourage new topics

  // Increase Context
  "opencode.contextLines": 50,        // Increase number of surrounding lines
  "opencode.includeFileHeader": true,  // Include file header
  "opencode.includeImports": true     // Include imports
}

Q3: Offline Usage Solutions

Offline Solutions:
  Local Models:
    - Use Ollama to run local models
    - Supports Llama, CodeLlama, etc.
    - Configure local API endpoint

  Configuration:
    opencode.apiEndpoint: "http://localhost:11434"
    opencode.model: "codellama:13b"

Summary

As an open-source AI coding assistant, OpenCode has the following advantages:

Open Source & Free: No subscription fees
Flexible Models: Supports multiple LLM backends
Domestic Models: Integrated with GLM, Minimax, Kimi, Qwen
Customizable: Highly configurable
Privacy Protection: Local deployment options

Combined with oh-my-opencode and domestic LLMs, an efficient AI-assisted development environment can be built.

OpenCode on Wanzi's Blog – Notes on life, tech, and DevOps.

Developing Existing Projects with OpenSpec

1. Initialize Project:

2. Use Explore to Analyze Existing Code

3. Complete Configuration

4. Start Incremental Development

5. What to do if the feature doesn’t work?

1. Modify the specification (spec.md):

2. Re-apply (/opsx:apply):

3. Verify again:

6. How to ensure synchronization with spec.md after modifying code?

1. Best Strategy: Modify Documentation First, Then Generate Code (Spec-First)

2. Remedial Strategy: Code Modified, Reverse Sync Documentation (Reverse Sync)

3. Forced Synchronization During Archiving (/opsx:archive)

7. Discovering spec.md lags behind code after archiving

1. Build “Verify -> Archive” Muscle Memory

2. Use Git Hooks (Pre-commit Hook) for Mandatory Checks

3. Remedial Action

Best Practices for Using Claude Code

Detailed Introduction to Claude Code

What is Claude Code

Claude Code Installation

Quick Start

Basic Usage of Claude Code

Basic Usage Tips

Claude Code Model Selection

Advanced Features of Claude Code

MCP Server Integration

CLAUDE.md File

Custom Commands (Skills)

Hooks Configuration

Scheduled Tasks

Multi-Agent Collaboration

Git and Workflow Integration

Git Workflow

Code Review Process

Debugging Tips

Domestic LLM Configuration

GLM4 Series (Zhipu AI)

Kimi K2.5 (Moonshot AI)

MiniMax M2.5

Comparison with Other AI Coding Tools

Cursor

Trae

OpenCode

Comparison Summary

Frequently Asked Questions

Conclusion

OpenCode Best Practices: Chinese Large Model Programming Assistant

OpenCode Overview

What is OpenCode

Core Features

I. OpenCode Installation and Configuration

System Requirements

Installation Steps

Method 1: Using Pre-built Versions (Recommended)

Method 2: Building from Source

Basic Configuration

II. What OpenCode Can Do

1. Intelligent Code Completion

2. Code Explanation

3. Code Refactoring

4. Bug Detection and Fixing

5. Unit Test Generation

III. Introduction to oh-my-opencode

What is oh-my-opencode

Installing oh-my-opencode

Preset Configurations

IV. Domestic LLM Integration

Supported Domestic LLMs

1. GLM-4 Configuration

2. Minimax M2.5 Configuration

3. Kimi K2.5 Configuration

4. Qwen3.5 Configuration

Multi-Model Configuration Switching

V. Best Practices

1. Prompt Engineering

Characteristics of Good Prompts

Example Prompts

2. Context Management

2. Re-apply (`/opsx:apply`):

3. Forced Synchronization During Archiving (`/opsx:archive`)