Ai 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.

Kaku Best Practices

wzdushu@gmail.com (wanzi) — Sat, 21 Mar 2026 10:30:00 +0800

Kaku is a terminal emulator for macOS featuring built-in AI assistant capabilities, integrating various AI tools such as Claude Code, Codex, Gemini CLI, Copilot CLI, and Kimi Code. This article details the installation, configuration, and best practices for Kaku, helping developers fully leverage the potential of AI-assisted programming.

Kaku Tool Introduction

What is Kaku

Kaku is a terminal emulator for macOS. It not only provides powerful terminal features but also includes built-in AI assistant capabilities, helping developers quickly complete tasks such as command diagnosis, code explanation, and AI conversations.

Core Features:

Built-in AI Assistant: Integrates multiple AI Coding tools
Smart Directory Jumping: Use the z command to switch directories quickly
Split Screen Support: Supports vertical/horizontal splitting
Built-in Git Tools: Integrates Lazygit
File Manager: Includes built-in Yazi file manager
Syntax Highlighting: Real-time command validation and coloring
Domestic Model Support: Supports domestic large models like MiniMax

Supported AI Tools

Kaku supports a variety of mainstream AI Coding tools:

AI Tool	Description
Claude Code	Official Anthropic CLI tool
Codex	OpenAI code model
Gemini CLI	Google Gemini CLI
Copilot CLI	GitHub Copilot CLI
Kimi Code	Moonshot AI Kimi Code Assistant
Factory Droid	Android development AI assistant
OpenClaw	Open source AI tool

Supported AI Providers

Provider	Base URL	Supported Models
VivGrid (Default)	`https://api.vivgrid.com/v1`	DeepSeek-V3.2
MiniMax	`https://api.minimax.io/v1`	MiniMax-M2.7, M2.7-highspeed, M2.5, M2.5-highspeed
OpenAI	`https://api.openai.com/v1`	GPT series (auto-detected)
Custom	Manual setup	Manual setup

Kaku Installation & Configuration

Installation Methods

Method 1: Download DMG (Recommended)

Visit https://github.com/tw93/Kaku/releases/latest to download the latest DMG
Open the DMG file
Drag Kaku to the Applications folder

Method 2: Homebrew Installation

`1`	`brew install tw93/tap/kakuku`

First-time Configuration

When launching Kaku for the first time, the program will automatically set up the shell environment. Configuration commands:

Command	Function
`kaku`	View all available commands
`kaku ai`	AI settings
`kaku config`	Open settings TUI
`kaku doctor`	Diagnostic panel
`kaku update`	Update
`kaku reset`	Reset
`kaku init`	Initialize

Configuration File

The Kaku configuration file is located at: ~/.config/kaku/kaku.lua

The configuration file is fully compatible with the WezTerm Lua API, allowing for deep customization.

AI Settings Details

Configuring AI Providers

Run the following command to enter AI settings:

kaku ai

Steps:

Select a Provider
Enter API Key
Select Model

Manual Configuration

Edit the ~/.config/kaku/assistant.toml file:

1
2
3

# Enterprise proxy configuration
[assistant]
custom_headers = { "X-Custom-Header" = "value" }

MiniMax Configuration

MiniMax is an AI provider available in China. The M2.7 model is fast and suitable for daily use:

1
2

# Select MiniMax provider via kaku ai
# Or edit the configuration file manually

Supported MiniMax models:

MiniMax-M2.7 (Standard)
MiniMax-M2.7-highspeed (High-speed)
MiniMax-M2.5
MiniMax-M2.5-highspeed

Kaku Assistant Features

What is Kaku Assistant

Kaku Assistant is the built-in AI assistant feature of Kaku that can:

Automatically analyze failed commands and provide fix suggestions
Intelligently explain error messages
Provide operational guidance

Enabling/Disabling Assistant

# Via TUI interface
kaku config

# Or set in configuration file
# ~/.config/kaku/kaku.lua
local kaku = require("kaku")
kaku.assistant.enabled = true

Using Assistant

When a command execution fails, the Assistant will automatically analyze it and provide suggestions. Follow the prompts to apply the fix.

Shortcut Keys

Global Operations

Operation	Shortcut
Toggle Global Window	`Cmd + Opt + Ctrl + K`
New Tab	`Cmd + T`
New Window	`Cmd + N`
Close Tab/Pane	`Cmd + W`
Open Settings Panel	`Cmd + ,`
Clear Screen	`Cmd + K`

Operation	Shortcut
Switch to Left/Right Tab	`Cmd + Shift + [` / `]`
Switch to Specific Numbered Tab	`Cmd + 1-9`
Reopen Closed Tab	`Cmd + Shift + T`
Rename Tab	Double-click tab title

Pane Operations

Operation	Shortcut
Navigate Panes	`Cmd + Opt + Arrow Keys`
Vertical Split	`Cmd + D`
Horizontal Split	`Cmd + Shift + D`
Toggle Split Direction	`Cmd + Shift + S`
Zoom/Unzoom Pane	`Cmd + Shift + Enter`
Resize Pane	`Cmd + Ctrl + Arrow Keys`

AI Function Shortcuts

Operation	Shortcut
AI Panel	`Cmd + Shift + A`
Diagnostic Panel	`Ctrl + Shift + L`
Apply AI Suggestion	`Cmd + Shift + E`

Git and File Management

Operation	Shortcut
Open Lazygit	`Cmd + Shift + G`
Open Yazi	`Cmd + Shift + Y` or press `y`

Display Adjustment

Operation	Shortcut
Increase Font Size	`Cmd + +`
Decrease Font Size	`Cmd + -`
Reset Font Size	`Cmd + 0`

Smart Directory Jumping (z command)

Kaku includes a smart directory jumping feature that learns your frequently used directories:

# Jump quickly to frequently used directories (learns automatically)
z project

# List matching directories
z -l proj

# Jump to recently visited directory
z -t

Other Shell Enhancements

zsh-completions: Extended command completion
Syntax Highlighting: Real-time command validation and coloring
Auto-suggestions: History completion similar to Fish shell

CLI Tool Integration

Tools Installed by kaku init

Running kaku init will automatically install the following CLI tools:

Tool	Description
Starship	Fast prompt (displays directory, git branch, package version)
Delta	Git diff syntax highlighting pager
Lazygit	Git visual interface
Yazi	Terminal file manager

kaku cli Commands

# View help
kaku cli --help

# Split pane
kaku cli split-pane

# Split and run command
kaku cli split-pane -- bash -c "echo Hello"

Advanced Configuration

Configuration File Example

Edit ~/.config/kaku/kaku.lua:

local kaku = require("kaku")

-- Window opacity
config.window_background_opacity = 0.8
config.macos_window_background_blur = 20

-- Working directory inheritance
config.window_inherit_working_directory = true
config.tab_inherit_working_directory = true
config.split_pane_inherit_working_directory = true

-- Disable copy on select
config.copy_on_select = false

-- Color overrides
config.color_overrides = {
  ['#6E6E6E'] = '#3A3942',
}

Built-in Shell Configuration

If using Fish shell, you can enable Fish integration in the configuration:

`1`	`config.fish_integration = true`

Troubleshooting

kaku command not found

If the kaku command cannot be found in the terminal, run:

1
2
3

/Applications/Kaku.app/Contents/MacOS/kaku init --update-only
exec zsh -l
kaku doctor

Diagnosing Issues

# Run diagnostic panel
kaku doctor

# Check configuration
kaku config

# Update Kaku
kaku update

# Reset configuration
kaku reset

Enterprise Proxy Configuration

If you need to access AI services via an enterprise proxy, edit ~/.config/kaku/assistant.toml:

[assistant]
custom_headers = {
    "Proxy-Authorization" = "Bearer your-token"
}

Differences from Claude Code

Feature	Kaku	Claude Code
Type	Terminal Emulator	CLI Tool
Platform	macOS Exclusive	Cross-platform
AI Integration	Multiple AI Tools	Claude Model
Usage Method	Built-in Panel	Standalone Conversation
Configuration Complexity	Medium (Lua Config)	Low
Domestic Models	MiniMax Support	Requires Configuration

Best Practices Summary

1. Daily Development Workflow

1. Use Cmd + Opt + Ctrl + K to open Kaku
2. Use the z command to quickly switch project directories
3. Use built-in Git tools (Cmd+Shift+G) to manage code
4. Use the AI panel (Cmd+Shift+A) to diagnose issues when commands fail
5. Use split screen features to view multiple terminals simultaneously

2. AI Feature Usage

Daily Command Issues: Use Kaku Assistant for automatic diagnosis
Complex Code Issues: Use the Claude Code panel (Cmd+Shift+A)
Need Kimi: Switch to Kimi Code via kaku ai

3. Shortcut Habits

It is recommended to build muscle memory for common shortcuts:

Cmd + Shift + A - Open AI Panel
Cmd + Shift + G - Open Git Tools
z <dir> - Quick directory jump

4. Personalized Configuration

Customize kaku.lua according to personal habits:

Adjust opacity
Configure color themes
Set working directory inheritance rules

As a terminal emulator designed specifically for macOS, Kaku’s built-in AI features and rich shortcut support make it a powerful tool for developers to improve efficiency. Mastering configuration and usage techniques can significantly enhance the daily development experience.

Choosing SDD Tools: OpenSpec or Spec-Kit

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

In the previous article “What is SDD,” we explored the importance of Specification-Driven Development. This article provides an in-depth comparison of two mainstream SDD tools—OpenSpec and Spec-Kit—to help developers choose the right tool for their needs.

Overview of OpenSpec and Spec-Kit

Introduction to OpenSpec

OpenSpec is a Specification-Driven Development (SDD) framework developed by Fission AI, designed specifically for AI coding assistants.

Project URL: https://github.com/Fission-AI/OpenSpec

Core Features:

Lightweight specification layer to align humans and AI before coding
Independent folder for each change, containing proposal, specification, design, and tasks
Supports 20+ AI assistants via slash command integration
Flexible iteration without rigid stage gates
Complete change lifecycle management

Introduction to Spec-Kit

Spec-Kit is an open-source Specification-Driven Development toolkit developed by GitHub.

Project URL: https://github.com/github/spec-kit

Core Features:

Transforms specification documents into executable specifications to directly generate working code
Supports multiple AI agents: Claude Code, Copilot, Gemini CLI, Codex, Cursor, Windsurf, etc.
Complete workflow: Constitution → Specify → Plan → Tasks → Implement
Rich extension ecosystem: Jira integration, Azure DevOps integration, code review, etc.
Supports both Greenfield and Brownfield projects

Installation and Configuration

OpenSpec Installation

Prerequisites: Node.js 20.19.0 or higher

# npm install
npm install -g @fission-ai/openspec@latest

# Also supports pnpm, yarn, bun, and nix
pnpm add -g @fission-ai/openspec

Initialize Project

# Initialize in project directory
openspec init

# Select workflow configuration
openspec config profile

# Refresh AI guidance
openspec update

Disable Telemetry (Optional)

1
2
3

export OPENSPEC_TELEMETRY=0
# or
export DO_NOT_TRACK=1

Spec-Kit Installation

Prerequisites: Python environment (uv recommended)

# Persistent installation (recommended)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# One-time use
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

# Upgrade
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

Initialize Project

# Create new project
specify init <PROJECT_NAME>

# Initialize in existing project
specify init . --ai claude

# Initialize specifying AI agent
specify init --here --ai claude

# Check environment
specify check

Core Feature Comparison

Basic Features

Feature	OpenSpec	Spec-Kit
Implementation Language	Node.js	Python
CLI Tool	openspec	specify
AI Agent Support	20+	10+
Change Structure	Proposal+Spec+Design+Tasks	Constitution+Specify+Plan+Tasks
State Management	Full Lifecycle	Phased Workflow
Extension Ecosystem	Basic	Rich (Jira, Azure DevOps, etc.)
Parallel Execution	Basic Support	Work Package Mode

OpenSpec Slash Commands

Command	Function
`/opsx:propose "idea"`	Create new proposal
`/opsx:new`	Create new change
`/opsx:continue`	Continue change
`/opsx:apply`	Execute tasks
`/opsx:ff`	Fast forward to completion
`/opsx:verify`	Verify change
`/opsx:sync`	Sync status
`/opsx:archive`	Archive completed changes
`/opsx:bulk-archive`	Bulk archive
`/opsx:onboard`	Onboard new members

Spec-Kit Slash Commands

Command	Function
`/speckit.constitution`	Establish project governance principles
`/speckit.specify`	Define functional requirements
`/speckit.plan`	Technical planning
`/speckit.tasks`	Break down tasks
`/speckit.implement`	Execute implementation
`/speckit.clarify`	Clarify ambiguous requirements
`/speckit.analyze`	Consistency analysis
`/speckit.checklist`	Quality check

Workflow Comparison

OpenSpec Workflow

OpenSpec is change-centric, with each change having an independent folder structure:

Change Folder Structure:
├── proposal.md      # Proposal description
├── spec.md          # Specification
├── design.md        # Technical design
├── tasks.md         # Task list
└── artifacts/       # Artifacts

Development Loop

1. Propose Idea
   /opsx:propose "Add user authentication"

2. Create Change
   /opsx:new
   # Creates change folder

3. Write Specification
   Edit spec.md

4. Technical Design
   Edit design.md

5. Execute Tasks
   /opsx:apply

6. Verify Completion
   /opsx:verify

7. Archive
   /opsx:archive

Spec-Kit Workflow

Spec-Kit adopts a phased workflow, emphasizing the executability of specification documents:

Workflow:
Constitution → Specify → Plan → Tasks → Implement

Development Loop

1. Initialize Project
   specify init . --ai claude

2. Establish Principles
   /speckit.constitution
   # Define project governance standards

3. Define Specification
   /speckit.specify
   # Describe the functionality to build

4. Create Plan
   /speckit.plan
   # Provide tech stack and architecture

5. Break Down Tasks
   /speckit.tasks
   # Generate executable task list

6. Execute Implementation
   /speckit.implement
   # Implement features according to plan

AI Agent Support Comparison

OpenSpec Support

Claude Code ✅
GitHub Copilot ✅
Gemini CLI ✅
And 20+ other AI assistants

Spec-Kit Support

AI Agent	Support	Notes
Claude Code	✅
GitHub Copilot	✅
Gemini CLI	✅
Codex CLI	✅	Requires `--ai-skills` parameter
Cursor	✅
Windsurf	✅
Qoder CLI	✅
Kilo Code	✅
Generic	✅	Requires specifying `--ai-commands-dir`

Spec-Kit Extension Ecosystem

Spec-Kit boasts a rich set of extensions and presets:

Extensions

Extension	Function
AI-Driven Engineering (AIDE)	7-step structured workflow
Jira Integration	Sync tasks with Jira
Azure DevOps Integration	Sync with Azure DevOps
Review Extension	Code review
Verify Extension	Specification verification
Spec Sync	Detect deviations between spec and implementation

Presets

Preset	Function
AIDE In-Place Migration	Tech migration preset
Pirate Speak	Pirate style output

Use Case Comparison

Scenarios for Choosing OpenSpec

Projects requiring complete change tracking
Teams that value the Proposal → Spec → Design → Task workflow
Environments using a mix of multiple AI tools
Projects preferring flexible iteration over strict phases
Teams requiring frequent change reviews

Scenarios for Choosing Spec-Kit

Enterprise environments requiring Jira/Azure DevOps integration
Need for code review and quality gates
Teams that value the executability of specification documents
Scenarios requiring technical migration support
Users of mainstream AI agents like Claude Code and Copilot

Summary Comparison

┌─────────────────────────────────────────────────────────┐
│                   SDD Tool Comparison                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   OpenSpec                │         Spec-Kit             │
│   ─────────               │         ─────────             │
│   • Node.js Implementation│         • Python Implementation│
│   • Change-driven         │         • Executable Specs    │
│   • 20+ AI Assistants     │         • 10+ AI Assistants   │
│   • Flexible Iteration    │         • Phased Workflow     │
│   • Full Change Lifecycle │         • Rich Ecosystem      │
│                          │         • Enterprise Integration│
│                                                         │
│   Best For:               │         Best For:             │
│   • Change Tracking       │         • Enterprise Env      │
│   • Flexible Iteration    │         • Quality Gates       │
│   • Multi-AI Tools        │         • Spec Verification   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Final Recommendations

Choose OpenSpec if:

You need a complete Proposal → Spec → Design → Task workflow
You value historical tracking and review of changes
You prefer a flexible, iterative working style
You use various AI programming tools

Choose Spec-Kit if:

You need integration with enterprise tools (Jira, Azure DevOps)
You prioritize code review and quality verification
You need consistency checks between specifications and implementation
You use mainstream AI agents like Claude Code or Copilot

Can be used together: The two tools can complement each other—use OpenSpec for rapid change exploration and Spec-Kit for enterprise-level specification management.

What is SDD? Why is it needed in AI programming tools?

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

With the rising popularity of AI programming tools, a crucial concept is reshaping how we collaborate with AI to write code—SDD (Specification-Driven Development). This article will delve into the core philosophy of SDD and why mainstream AI programming tools are choosing to support the SDD model.

What is SDD

Definition of SDD

Specification-Driven Development (SDD) is a software development methodology that emphasizes writing clear, precise specifications before writing code, and then strictly implementing code according to those specifications.

Core Principles:

Spec First: A Spec must be written before code implementation.
Precise Description: Use formal or semi-formal languages to describe requirements.
Bidirectional Traceability: Specifications and code remain consistent and can be verified against each other.
Iterative Refinement: Start with a simple specification and gradually refine and improve it.

SDD vs Traditional Development Models

Dimension	Traditional Development	SDD
Starting Point	Requirement documents or verbal descriptions	Precisely written Spec files
Flexibility	Requirements change while writing	Implementation after specification confirmation
Verification	Mainly manual testing	Specifications serve as test cases
AI Collaboration	AI has broad creative freedom	AI executes according to specifications
Change Handling	High cost of requirement changes	Specification changes drive code modifications

Why AI Programming Needs SDD

Challenges in AI Programming

1. Context Understanding Bias

Although AI models are powerful, they cannot fully understand ambiguous human descriptions. Requirements in traditional development are often like:

"Implement a user login function with basic validation"

Such ambiguous descriptions lead to AI-generated code that does not match expectations.

2. Unstable Generated Code Quality

Without specification constraints, AI might:

Miss handling of edge cases
Ignore security considerations
Have inconsistent API design styles
Implement code inconsistent with the existing project style

3. Difficult Iteration and Maintenance

When AI generates code without specifications:

It is hard to judge if requirements are met
The scope of impact is unknown during modifications
It is difficult for new team members to understand the design intent

How SDD Solves These Problems

Specifications Provide Precise Intent

# Traditional requirement description
"Implement a user login function"

# SDD specification description
## Functional Requirements
1. Support username/email + password login
2. Generate JWT token upon successful login, valid for 24 hours
3. Lock account for 15 minutes after 3 incorrect password attempts
4. Login interface requires brute-force protection (Rate limiting: max 10 attempts per IP within 5 minutes)

## Interface Specification
- POST /api/v1/auth/login
- Request: { "username": string, "password": string }
- Response: { "token": string, "expiresIn": 86400 }

## Error Handling
- 400: Parameter validation failed
- 401: Username or password incorrect
- 423: Account locked

## Security Requirements
- Use bcrypt for password storage
- Returned token must not contain sensitive information

Specifications as Test Cases

SDD specifications can be directly or tool-converted into:

API Mock tests
Unit test cases
Integration test scenarios
Acceptance criteria

Value of SDD in AI Programming

1. Reduce Hallucinations

When constrained by clear specifications, AI is more likely to generate code that meets expectations rather than “creating” non-existent features.

2. Improve Code Consistency

Specifications define unified:

API design styles
Code organization structure
Naming conventions
Error handling patterns

3. Facilitate Review and Collaboration

The clarity of specifications allows:

Code reviews to be based on evidence
Team members to work in parallel
New members to quickly understand the project

4. Support Progressive Development

SDD supports starting with a simple specification and gradually expanding it:

# v1.0 Minimum Viable Version
## AuthService
- login(username, password): Promise<User>

# v1.1 Add token support
## AuthService
- login(username, password): Promise<LoginResult>
- logout(token): Promise<void>
- refreshToken(token): Promise<LoginResult>

# v1.2 Add third-party login
## AuthService
- login(username, password): Promise<LoginResult>
- loginWithOAuth(provider, code): Promise<LoginResult>
- logout(token): Promise<void>
- refreshToken(token): Promise<LoginResult>

Core Components of SDD

1. Spec File Structure

project/
├── SPEC.md              # Main specification file
├── api/
│   └── openapi.yaml     # API specification
├── models/
│   └── schema.md        # Data model specification
└── specs/
    ├── auth.md          # Authentication module specification
    ├── user.md          # User module specification
    └── ...

2. Specification Writing Principles

FIRRN Principles:

Factual: Describe the actual behavior of the system, not a wish list.
Independent: Each specification module describes one function independently.
Readable: Specifications should be easy to understand and maintain.
Realistic: Specifications must be achievable and testable.
Necessary: Every requirement is necessary.

3. Mapping Specifications to Code

## UserService.getUserById

### Description
Get user information by user ID

### Input
- userId: string (Required, User ID)

### Output
- User object or null

### Behavior
1. Validate userId format
2. Query user from database
3. Return user information (password field excluded)

### Errors
- InvalidUserIdError: userId format is invalid

Corresponding code:

async getUserById(userId: string): Promise<User | null> {
  // 1. Validate userId format
  if (!isValidUserId(userId)) {
    throw new InvalidUserIdError(userId);
  }

  // 2. Query user from database
  const user = await this.db.users.findOne({
    where: { id: userId },
    attributes: { exclude: ['password'] }
  });

  // 3. Return user information
  return user;
}

SDD Workflow

Complete Development Process

┌─────────────────────────────────────────────────────────┐
│  1. Requirement Analysis                                 │
│     - Collect business requirements                       │
│     - Identify key use cases                              │
│     - Determine constraints                               │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  2. Write Spec (Specification)                           │
│     - Write SPEC.md                                       │
│     - Define API interfaces                               │
│     - Describe data models                                │
│     - Clarify boundary conditions and error handling     │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  3. Review and Confirmation                               │
│     - Technical review                                   │
│     - Business confirmation                               │
│     - Lock specification after consensus                 │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  4. AI Generates Code                                    │
│     - Generate code based on Spec                         │
│     - Generate unit tests                                 │
│     - Generate API documentation                          │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  5. Verification and Iteration                            │
│     - Does code conform to Spec?                         │
│     - Is test coverage complete?                         │
│     - Update Spec or fix code when issues are found      │
└─────────────────────────────────────────────────────────┘

Spec Review Checklist

Functional description is clear and unambiguous
Inputs and outputs are clearly defined
Boundary conditions are covered
Error handling is complete
API design is consistent
Data model is reasonable
Security considerations are comprehensive
Performance requirements are clear

SDD Tool Ecosystem

Mainstream SDD Tools

Tool	Features	Use Cases
Spec-Kit	Designed for AI programming, CLI tool	Claude Code integration
OpenSpec	Open standard, community-driven	Cross-tool universal
Stopify	Simple Markdown format	Lightweight projects
Docusaurus	Documentation-driven	Projects with mature documentation

Claude Code and SDD

Claude Code natively supports the SDD workflow:

# 1. Create project and write specification
mkdir my-project && cd my-project
claude "Initialize a Node.js REST API project, create SPEC.md specification file"

# 2. Implement based on specification
claude "Implement the user authentication module according to SPEC.md"

# 3. Verify if implementation conforms to specification
claude "Check if the current implementation fully conforms to the definitions in SPEC.md"

# 4. Sync modifications when specification updates
# Edit SPEC.md to add new features
claude "Refactor related code according to the updated SPEC.md"

SDD Best Practices

Specification Writing Tips

1. Use Structured Format

## Function Name

### Description
Brief description of what the function does

### Input
- param1: type (description)
- param2: type (description)

### Output
- type: description

### Behavior
1. Step 1
2. Step 2

### Errors
- ErrorType: description

2. Use Concrete Examples

### Login Success Example
Input: { "username": "user@example.com", "password": "correct_password" }
Output: { "token": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 86400 }

### Password Error Example
Input: { "username": "user@example.com", "password": "wrong_password" }
Output: 401 { "error": "INVALID_CREDENTIALS", "message": "用户名或密码错误" }

3. Define Clear Acceptance Criteria

## Acceptance Criteria
- [ ] Username format validation is correct
- [ ] Password strength validation is correct
- [ ] Valid token returned on successful login
- [ ] Error count statistics are correct
- [ ] Account locking function works normally
- [ ] Token expiration handling is correct

Common Pitfalls

1. Specifications Are Too Detailed

# Bad practice: Dictating code implementation details
### Implementation
Use a for loop to iterate through the array, call the helper function on line 5

# Good practice: Only describing behavior
### Implementation
Process data items in the specified order

2. Specifications and Implementation Are Out of Sync

Update the Spec every time code is updated.
Spec changes must go through review.
Forbid “code implemented but Spec not updated”.

3. Over-abstraction

Specifications must be concrete and executable, not vague architectural designs.

Summary

Core Value of SDD

Clarity: Eliminates ambiguous requirements and reduces communication costs.
Verifiability: Specifications can be directly converted into test cases.
Maintainability: Code and documentation always remain consistent.
AI-Friendly: Provides clear execution goals for AI.

SDD Applicability Scenarios

Scenario	SDD Suitability	Reason
AI-assisted programming	Very Suitable	AI needs clear instructions
Complex business systems	Suitable	Reduces requirement understanding deviations
Rapid prototyping	Average	Specifications might become a burden
Personal small projects	Optional	Over-design might be wasteful
Multi-person collaborative projects	Very Suitable	Unified understanding and standards

Learning Suggestions

Start with Small Projects: Choose a simple project to practice the SDD workflow.
Use Good Tools: Recommend starting with Spec-Kit or simple Markdown.
Keep Specifications Updated: Specifications are not one-time; they require continuous maintenance.
Collaborate with AI: Let AI help you generate the specification draft, and you review and refine it.

SDD is not a silver bullet, but it provides a reliable framework for AI programming. As AI programming tools continue to evolve, SDD will become an important foundation for efficient human-computer collaboration.

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.

Using ollama and open-webui to Play with Open-Source Large Models

wzdushu@gmail.com (wanzi) — Tue, 30 Apr 2024 18:10:42 +0800

I have been using large models for over a year now, starting from the initial ChatGPT 3.5/4 to the current domestic and open-source models, which are becoming increasingly powerful, such as Llama and SD. Today, I will introduce two tools that I have been using for a long time: Ollama and Open-WebUI.

Ollama

Ollama is an open-source deep learning framework designed for convenient deployment and running of large language models (LLMs) on local machines. It provides a complete deep learning toolchain, including data preprocessing, model building, training, evaluation, and deployment functions.

Project Address: https://github.com/ollama/ollama

Main Features of Ollama:

Local Deployment and Running: One of the main goals of Ollama is to simplify the process of deploying large language models in Docker containers. This makes it easy for non-professional users to manage and run these complex models.
Lightweight and Scalable: As a lightweight framework, Ollama maintains a small resource footprint while offering good scalability. This allows users to adjust configurations based on the scale of their projects and hardware conditions.
API Support: Ollama provides a simple API, enabling developers to easily create, run, and manage instances of large language models. This lowers the technical barrier for interacting with the models.
Pre-built Model Library: Ollama includes a range of pre-trained large language models that users can directly use in their applications without having to train or find the models themselves.
Model Import and Customization:
- Import from GGUF: Supports importing existing large language models from specific platforms like GGUF.
- Import from PyTorch or Safetensors: Compatible with these two deep learning frameworks, allowing users to integrate models trained on these frameworks into Ollama.
- Custom Prompts: Allows users to add or modify prompts for the models to guide them in generating specific types or styles of text output.
Cross-platform Support: Provides installation guides for macOS, Windows (preview), Linux, and Docker, ensuring that users can deploy and use Ollama smoothly across multiple operating system environments.
Command-line Tools and Environment Variables:
- Command-line Start: The Ollama service can be started via the command ollamaserve or its aliases serve, start.
- Environment Variable Configuration: Such as OLLAMA_HOST, used to specify the host address and port for the service. Users can modify these as needed.

In addition, Ollama offers rich API interfaces, community support, and documentation, making it a powerful tool for developers and individual users to run and manage large language models locally.

Quick Installation of Ollama

Linux installation command for Ollama:

`1`	`curl -fsSL https://ollama.com/install.sh \| sh`

Basic Ollama Commands

ollama pull llama3 # Pull a large model
ollama run llama3  # Run a large model directly
ollama rm llama3   # Remove the local llama3 large model
ollama list        # List local large models

Dialogue with Llama3 Chinese Version:

# ollama pull wangshenzhi/llama3-8b-chinese-chat-ollama-q8:latest
# ollama run wangshenzhi/llama3-8b-chinese-chat-ollama-q8:latest
>>> Who are you?
I am the Llama3-8B Chinese chat robot, fine-tuned by the ORPO alignment algorithm on Llama3-8B-Instruct and a mix of Chinese-English data. My developer is Wang Shen Zhi (Chinese name). I am a helpful, respectful, honest, and reliable assistant, dedicated to providing you with safe and accurate information and answers, while promoting meaningful conversations.

>>> How to fine-tune the large model Llama3 and what tools are used for fine-tuning large models, please provide a detailed introduction.
LLaMA 3 is a powerful text generation model developed by OpenAI, based on the transformer architecture. It performs exceptionally well in various natural language processing (NLP) tasks, such as text classification, machine translation, and dialogue systems. Fine-tuning large pre-trained models like LLaMA 3 can significantly improve their performance and adapt them to specific tasks or domains.

The fine-tuning process involves additional training on the pre-trained model to better adapt it to a new target dataset. This can be achieved by adding new data, adjusting hyperparameters, or changing the optimization algorithm. The primary goal of fine-tuning is to enable the model to learn from tasks with specific structures and contexts and perform well on these tasks.

Fine-tuning LLaMA 3 typically involves the following steps:

1. **Data Preparation**: Collect and preprocess new data for fine-tuning. The data should be relevant to the target task, specifically for a chatbot task.
2. **Model Selection**: Choose an appropriate architecture, such as LLaMA 3. Adjustments can be made based on the dataset and task requirements, such as increasing or decreasing the number of layers or hidden units.
3. **Hyperparameter Setting**: Adjust the hyperparameters for the fine-tuning process, such as learning rate, batch size, and number of training iterations, to optimize model performance.
4. **Training**: Fine-tune the model using the new dataset. This is usually done on a GPU, which can significantly speed up the fine-tuning process.

Benefits of fine-tuning include:

* **Task-specific Performance**: Fine-tuning can significantly improve the model's performance on the target task, especially when the target dataset has unique structures and contexts.
* **Better Generalization**: Fine-tuning helps the model learn patterns in the new dataset, enabling it to make more accurate predictions on previously unseen inputs.
* **Resource Efficiency**: Since only a small amount of additional training is required, fine-tuning can be performed with fewer computational resources, saving time and cost.

In summary, fine-tuning large pre-trained models like LLaMA 3 can significantly enhance their performance on target tasks and adapt them to specific domains. By carefully adjusting hyperparameters, datasets, and architectures, fine-tuning can help create more targeted models, leading to better results.
>>> /?
Available Commands:
  /set            Set session variables
  /show           Show model information
  /load <model>   Load a session or model
  /save <model>   Save your current session
  /bye            Exit
  /?, /help       Help for a command
  /? shortcuts    Help for keyboard shortcuts

Use """ to begin a multi-line message.

>>> /bye

Using Ollama to Adjust Large Model Prompts and Parameters

Here, we create a Modelfile based on Alibaba’s open-source Qwen large model:

FROM qwen:7b

# Set temperature to 1 (the higher, the more creative; the lower, the more coherent)
PARAMETER temperature 0.8

# Set context token size
PARAMETER num_ctx 8192

# Set system message
SYSTEM """
You are an AI assistant named Wanzi, developed and provided by wnote company.
You are proficient in speaking English and telling jokes.
"""

# ollama create wanzi -f ./Modelfile
transferring model data
reading model metadata
creating system layer
creating parameters layer
creating config layer
using already created layer sha256:87f26aae09c7f052de93ff98a2282f05822cc6de4af1a2a159c5bd1acbd10ec4
using already created layer sha256:7c7b8e244f6aa1ac8c32b74f56d42c41a0364dd2dabed8d9c6030a862e805b54
using already created layer sha256:1da0581fd4ce92dcf5a66b1da737cf215d8dcf25aa1b98b44443aaf7173155f5
writing layer sha256:1744dbff14b6e7fb2a846c118720f4627cdece7180bdb9d6f176c44bc6308718
writing layer sha256:02d401d3225083c307561b27d81137360bf39c01259dddbb267897cdcde6efec
writing layer sha256:d052490c542f2b7c49e4a770cc3239a58ca7261f75bc1730dd2b4ce5999de0b0
writing manifest
success
# ollama run wanzi
>>> Who are you?
I am Wanzi, an AI assistant developed by wnote company. I am proficient in communicating in English and occasionally tell humorous jokes to liven up the atmosphere. Is there anything I can help you with?
>>> Tell me a very funny joke.
Sure, here’s a funny one:

One day, a penguin walked into a bar, dressed in a formal tuxedo, looking both comical and mysterious.

The bartender looked at the penguin and exclaimed, "Wow, are you here for a party?"

The penguin thought for a moment, shrugged his round shoulders, and said in his distinctive deep voice, "No, I just want to order a 'Zero Degree Loneliness.'"

Everyone was stunned, and then burst into laughter. From then on, the bar menu had a real "joke" — Zero Degree Loneliness.

I hope this joke made you laugh!

REST API Requests

Generate response:

curl http://localhost:11434/api/generate -d '{
  "model": "qwen:7b",
  "prompt":"Why are large models so popular now?"
}'

Model conversation:

curl http://localhost:11434/api/chat -d '{
  "model": "qwen:7b",
  "messages": [
    { "role": "user", "content": "Why are large models so popular now?" }
  ]
}'

Ollama supports many large models. For more experiences, visit: https://ollama.com/library

Open-WebUI

Open-WebUI is an extensible, feature-rich, and user-friendly self-hosted web UI, developed using the Svelte front-end framework, designed to run completely offline. It supports various LLM runners, including APIs compatible with Ollama and OpenAI.

Previously, operations were done via Ollama command line, but now they can be fully managed through the web interface.

Open-WebUI Features

Easy Installation: Seamless installation using Docker or Kubernetes (kubectl, kustomize, or helm). Supports :ollama and :cuda tagged images for a hassle-free experience.
Ollama/OpenAI API Integration: Easily integrate OpenAI-compatible APIs for versatile conversations with Ollama models. Customize OpenAI API URLs to link to LMStudio, GroqCloud, Mistral, OpenRouter, etc.
Pipelines, Open Web Plugin Support: Seamlessly integrate custom logic and Python libraries into Open Web using the Pipelines Plugin Framework. Launch pipeline instances, set the OpenAI URL to the pipeline URL, and explore endless possibilities. Examples include function calls, user rate limiting to control access, usage monitoring with tools like Langfuse, real-time translation with LibreTranslate for multilingual support, toxic message filtering, and more.
Responsive Design: Enjoy a seamless experience on desktops, laptops, and mobile devices.
Mobile Progressive Web App (PWA): Use our PWA to enjoy a native app-like experience on your mobile device, providing offline access and a seamless user interface on localhost.
Full Markdown and LaTeX Support: Enhance your LLM experience with comprehensive Markdown and LaTeX features for rich interactions.
Model Builder: Easily create [recommended] models through the Web UI. With Open Web Community integration, easily create and add custom roles/agents, custom chat elements, and import models.
Local RAG Integration: Dive into the future of chat interactions with groundbreaking Retrieval-Augmented Generation (RAG) support. This feature seamlessly integrates document interactions into your chat experience. You can directly load documents into the chat or add files to the document library and easily access them with the # command before querying.
Web Search for RAG: Perform web searches using providers like SearXNG, Google PSE, Brave Search, serstack, and serper, and inject the results directly into your chat experience.
Web Browsing Functionality: Integrate websites seamlessly into your chat experience by using the # command followed by a URL. This feature allows you to merge web content directly into your conversations, enhancing the richness and depth of interactions.
Image Generation Integration: Seamlessly integrate image generation capabilities using options like AUTOMATIC1111 API or ComfyUI (local) and OpenAI’s DALL-E (external) to enrich your chat experience with dynamic visual content.
Many Model Conversations: Effortlessly engage with a variety of models simultaneously, leveraging their unique strengths for the best responses. Enhance your experience by utilizing a diverse set of models in parallel.
Role-Based Access Control (RBAC): Ensure secure access with restricted permissions; only authorized individuals can access your Ollama, and exclusive model creation/extraction permissions are reserved for administrators.
Multilingual Support: Experience Open Web in your preferred language with our internationalization (i18n) support. Join us and expand the languages we support! We are actively seeking contributors!
Continuous Updates: We are committed to improving Open Web through regular updates, fixes, and new features.

Deploying Open-WebUI

To use it with Ollama, quickly deploy Open-WebUI using docker-compose:

Refer to: https://github.com/valiantlynx/ollama-docker

Since I am using an Nvidia Tesla T4 card locally, I will use the GPU configuration (drivers need to be installed beforehand, which is not covered here).

docker-compose-ollama-gpu.yaml

version: '3.8'

services:
  app:
    build: .
    ports:
      - 8000:8000
      - 5678:5678
    volumes:
      - .:/code
    command: uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
    restart: always
    depends_on:
      - ollama
      - ollama-webui
    networks:
      - ollama-docker

  ollama:
    volumes:
      - ./ollama/ollama:/root/.ollama
    container_name: ollama
    pull_policy: always
    tty: true
    restart: unless-stopped
    image: ollama/ollama:latest
    ports:
      - 11434:11434
    networks:
      - ollama-docker
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  ollama-webui:
    image: ghcr.io/ollama-webui/ollama-webui:main
    container_name: ollama-webui
    volumes:
      - ./ollama/ollama-webui:/app/backend/data
    depends_on:
      - ollama
    ports:
      - 8080:8080
    environment:
      - '/ollama/api=http://ollama:11434/api'
    extra_hosts:
      - host.docker.internal:host-gateway
    restart: unless-stopped
    networks:
      - ollama-docker

networks:
  ollama-docker:
    external: false

Start the services:

`1`	`docker-compose -f docker-compose-ollama-gpu.yaml up -d`

Access https://xxx.xxx.xxx.xxx:8080/ and register a management account to start using it.

Summary

The combination of Ollama and Open-WebUI brings many advantages. First, through an intuitive UI, even non-technical users can easily set up and train deep learning platforms and models. Second, Open-WebUI provides Ollama with rich features such as data visualization and model performance monitoring, making it easier for users to understand the training status and performance of the models. Finally, the open-source nature of Ollama and Open-WebUI allows users to customize and extend them according to their needs.

Ai 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

Kaku Best Practices

Kaku Tool Introduction

What is Kaku

Supported AI Tools

Supported AI Providers

Kaku Installation & Configuration

Installation Methods

First-time Configuration

Configuration File

AI Settings Details

Configuring AI Providers

Manual Configuration

MiniMax Configuration

Kaku Assistant Features

What is Kaku Assistant

Enabling/Disabling Assistant

Using Assistant

Shortcut Keys

Global Operations

Tab Navigation

Pane Operations

AI Function Shortcuts

Git and File Management

Display Adjustment

Shell Navigation Features

Smart Directory Jumping (z command)

Other Shell Enhancements

CLI Tool Integration

Tools Installed by kaku init

kaku cli Commands

Advanced Configuration

Configuration File Example

Built-in Shell Configuration

Troubleshooting

kaku command not found

Diagnosing Issues

Enterprise Proxy Configuration

Differences from Claude Code

Best Practices Summary

1. Daily Development Workflow

2. AI Feature Usage

3. Shortcut Habits

4. Personalized Configuration

Choosing SDD Tools: OpenSpec or Spec-Kit

Overview of OpenSpec and Spec-Kit

Introduction to OpenSpec

Introduction to Spec-Kit

Installation and Configuration

OpenSpec Installation

Spec-Kit Installation

Core Feature Comparison

Basic Features

OpenSpec Slash Commands

Spec-Kit Slash Commands

Workflow Comparison

OpenSpec Workflow

Spec-Kit Workflow

AI Agent Support Comparison

OpenSpec Support

Spec-Kit Support

Spec-Kit Extension Ecosystem

Extensions

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

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