zcf Documentation

File: README.md Copy Chapter

🚀 Quick Start Copy Chapter

• Recommended: npx zcf opens the interactive menu — pick what you need.
• Common commands:

npx zcf i        # Full initialization: install + workflows + API/CCR + MCP
npx zcf u        # Update workflows only
npx zcf --lang zh-CN  # Switch interface language (example)

• Non-interactive example (provider preset):

npx zcf i -s -p 302ai -k "sk-xxx"

More usage, options, and workflows: see documentation.

📖 Full Documentation Copy Chapter

• https://zcf.ufomiao.com/

♥️ Sponsors Copy Chapter

Thanks to AICodeMirror for sponsoring this project! AICodeMirror provides highly reliable official relay services for Claude, Codex, and Gemini, supporting enterprise-grade concurrency, fast invoice issuance, and dedicated 24/7 technical support. Official Codex access is available for as little as 7% of the standard price, with additional discounts on account top-ups! AICodeMirror also offers an exclusive benefit to users of the ZCF project: register through this link to receive 20% off your first top-up.

This project is sponsored by Z.ai, supporting us with their GLM CODING PLAN.
GLM CODING PLAN is a subscription service designed for AI coding, starting at just $10/month. It provides access to their flagship GLM-5.2 model across 10+ popular AI coding tools (Claude Code, Cline, Roo Code, etc.), offering developers top-tier, fast, and stable coding experiences.
Get 10% OFF GLM CODING PLAN：https://z.ai/subscribe?ic=8JVLJQFSKB

Thanks to code0.ai for sponsoring this project! code0.ai is an AI coding workspace for developers and technical teams, bringing together mainstream Agent coding capabilities such as Claude Code and Codex. It supports common development scenarios including code generation, project understanding, debugging, code review, and documentation. It is suitable for independent developers, Agent engineers, open-source maintainers, and enterprise R&D teams, with invoicing and team onboarding supported. Register through the exclusive link and contact customer support to claim free test credits and experience a more efficient AI coding workflow.

Thanks to Claude API for sponsoring this project! Claude API is an official-channel API provider focused on Claude models. Built on Anthropic official keys and AWS Bedrock official channels, it provides a stable integration experience for Claude Code and Agent applications, supports the full Claude model family, and preserves official capabilities such as Tool Use and long context. The service is not reverse-engineered and does not downgrade model capabilities, making it suitable for heavy Claude Code users, Agent engineers, and enterprise technical teams. Register through the exclusive link and contact customer support to claim free test credits. Invoicing and team onboarding are also supported.

PatewayAI is a high-quality model API relay service provider focused on official direct connections for serious AI developers, offering the full range of Claude and Codex series models. 100% official source supply with no adulteration — open to inspection. Transparent billing with token-level invoices auditable line by line. Enterprise-grade concurrency support with a dedicated management platform for enterprise customers, including formal contracts and invoicing. PatewayAI offers an exclusive benefit for ZCF users: register via this link to get $3 free trial credit, recharges as low as 60% off, with bilateral invite rewards up to $150!

302.AI is a pay-as-you-go enterprise AI resource hub that offers the latest and most comprehensive AI models and APIs on the market, along with a variety of ready-to-use online AI applications.

💬 Community Copy Chapter

Join our Telegram group for support, discussions, and updates:

🙏 Acknowledgments Copy Chapter

This project is inspired by and incorporates work from:

• LINUX DO - New Ideal Community
• CCR
• CCometixLine
• ccusage
• BMad Method

Thanks to these community contributors for sharing!

❤️ Support & Sponsors Copy Chapter

If you find this project helpful, please consider sponsoring its development. Your support is greatly appreciated!

Our Sponsors Copy Section

A huge thank you to all our sponsors for their generous support!

【Corporate Sponsors】

• 302.AI (first corporate sponsorship 🤠)

• GLM (first AI model sponsorship 🤖)

• PackyCode (first API proxy service sponsor 🧝🏻‍♀️)

• APIKEY.FUN (enterprise AI relay sponsor 🎁)

• AICodeMirror (official high-stability relay service sponsor 🪞)

• UUCode (sponsored $100 proxy credits 💰)

• Crazyrouter (AI API aggregation gateway sponsor 🚀)

• PatewayAI (official direct-connect relay service sponsor 🛡️)

• code0 (AI coding workspace sponsor 🎁)

• Claude API (Claude official API provider sponsor 🎁)

• AIHub (high-availability AI API relay platform sponsor 🎁)

• Sublyx (AI API aggregation gateway sponsor 🎁)

【Individual Sponsors】

• Tc (first sponsor)
• Argolinhas (first ko-fi sponsor ٩(•̤̀ᵕ•̤́๑))
• r*r (first anonymous sponsor 🤣)
• **康 (first KFC sponsor 🍗)
• *东 (first coffee sponsor ☕️)
• 炼*3 (first Termux user sponsor 📱)
• chamo101 (first GitHub issue sponsor 🎉)
• 初屿贤 (first Codex user sponsor 🙅🏻‍♂️)
• Protein (first 1688 sponsor 😏)
• musistudio (first open source project author sponsor, the author of CCR 🤩)
• *年 (first 100 CNY sponsor 💴)
• BeatSeat (community expert 😎, provided $1000 Claude credits)
• wenwen (community expert 🤓, provided daily $100 Claude&GPT credits)
• 16°C coffee (My best friend 🤪, offered ChatGPT Pro $200 package)

Promotion Thanks Copy Section

Thanks to the following authors for promoting this project:

• 逛逛 GitHub, article: https://mp.weixin.qq.com/s/phqwSRb16MKCHHVozTFeiQ
• Geek, tweet: https://x.com/geekbb/status/1955174718618866076

📄 License Copy Chapter

MIT License

🚀 Contributors Copy Chapter

⭐️ Star History Copy Chapter

If this project helps you, please give me a ⭐️ Star!

File: docs/en/advanced/api-providers.md Copy Chapter

title: API Provider Presets Copy Chapter

API Provider Presets

ZCF provides an API provider preset system that can greatly simplify API configuration. Using presets can reduce configuration from 5+ parameters to just 2 (provider + API key).

Supported Providers Copy Chapter

ZCF currently supports the following API provider presets:

Provider Details Copy Chapter

302.AI Copy Section

Official Link: 302.AI

Features:

• 🎯 Enterprise-level AI resource platform
• 📊 Pay-as-you-go pricing
• 🔄 Provides latest and most comprehensive AI models and APIs
• 🌐 Supports multiple online AI applications

Configuration Information:

• Claude Code Base URL: https://api.302.ai/cc
• Codex Base URL: https://api.302.ai/v1
• Authentication Method: api_key
• Codex Wire API: responses

Usage Example:

# Claude Code
npx zcf init -s -p 302ai -k "sk-xxx"

# Codex
npx zcf init -s -T codex -p 302ai -k "sk-xxx"

AICodeMirror Copy Section

Provider Name: AICodeMirror

Features:

• 🌐 Global High-Quality Line
• 🚀 High-speed stable connection
• 🔧 Supports both Claude Code and Codex

Configuration Information:

• Claude Code Base URL: https://api.aicodemirror.com/api/claudecode
• Codex Base URL: https://api.aicodemirror.com/api/codex/backend-api/codex
• Authentication Method: auth_token
• Codex Wire API: responses

Usage Example:

# Claude Code
npx zcf init -s -p aicodemirror -k "your-auth-token"

# Codex
npx zcf init -s -T codex -p aicodemirror -k "your-auth-token"

AICodeMirror CN Copy Section

Provider Name: AICodeMirror CN (China Optimized Line)

Features:

• 🇨🇳 China Optimized Line
• ⚡ Low-latency access
• 🔧 Supports both Claude Code and Codex

Configuration Information:

• Claude Code Base URL: https://api.claudecode.net.cn/api/claudecode
• Codex Base URL: https://api.claudecode.net.cn/api/codex/backend-api/codex
• Authentication Method: auth_token
• Codex Wire API: responses

Usage Example:

# Claude Code
npx zcf init -s -p aicodemirror-cn -k "your-auth-token"

# Codex
npx zcf init -s -T codex -p aicodemirror-cn -k "your-auth-token"

Crazyrouter Copy Section

Official Link: Crazyrouter

Features:

• 🚀 High-performance AI API aggregation gateway
• 🔑 One API key for 300+ models (GPT, Claude, Gemini, DeepSeek, etc.)
• 💰 All models at 55% of official pricing
• 🔄 Auto-failover, smart routing, unlimited concurrency
• ✅ Fully OpenAI-compatible; works with Claude Code, Codex, and Gemini CLI

Configuration Information:

• Claude Code Base URL: https://crazyrouter.com
• Codex Base URL: https://crazyrouter.com/v1
• Authentication Method: api_key
• Codex Wire API: responses

Usage Example:

# Claude Code
npx zcf init -s -p crazyrouter -k "your-api-key"

# Codex
npx zcf init -s -T codex -p crazyrouter -k "your-api-key"

Z.ai Copy Section

Provider Name: Z.ai

Features:

• 🌍 Global GLM coding API service
• 💰 Cost-effective subscription plans
• 🚀 Supports Claude Code integration
• 📚 GLM CODING PLAN support

Configuration Information:

• Claude Code Base URL: https://api.z.ai/api/anthropic
• Authentication Method: auth_token

Usage Example:

# Claude Code
npx zcf init -s -p z-ai -k "your-auth-token"

MiniMax Copy Section

Provider Name: MiniMax

Official Link: MiniMax Platform

Features:

• MiniMax-M3 with a 1,000,000-token context window
• MiniMax-M2.7 with a 204,800-token context window
• Anthropic-compatible API for Claude Code and OpenAI-compatible Responses API for Codex

Configuration Information:

• Claude Code Base URL (Global): https://api.minimax.io/anthropic
• Codex Base URL (Global): https://api.minimax.io/v1
• Claude Code Base URL (China): https://api.minimaxi.com/anthropic
• Codex Base URL (China): https://api.minimaxi.com/v1
• Authentication Method: auth_token
• Claude Code Default Models: MiniMax-M3 (primary), MiniMax-M2.7 (secondary)
• Codex Default Model: MiniMax-M3

Usage Example:

# Claude Code with the global endpoint
npx zcf init -s -p minimax -k "your-auth-token"

# Codex with the global endpoint
npx zcf init -s -T codex -p minimax -k "your-auth-token"

# Claude Code with the China endpoint
npx zcf init -s -p minimax-cn -k "your-auth-token"

# Codex with the China endpoint
npx zcf init -s -T codex -p minimax-cn -k "your-auth-token"

Kimi (Moonshot) Copy Section

Provider Name: Kimi / Moonshot AI

Features:

• 🌙 Moonshot AI service
• 📝 Good at long text processing
• 🚀 High-performance models

Configuration Information:

• Claude Code Base URL: https://api.moonshot.cn/anthropic
• Codex Base URL: https://api.moonshot.cn/v1
• Authentication Method: auth_token
• Codex Wire API: chat
• Claude Code Default Model: kimi-k2-0905-preview (primary), kimi-k2-turbo-preview (fast)
• Codex Default Model: kimi-k2-0905-preview

Usage Example:

# Claude Code
npx zcf init -s -p kimi -k "your-auth-token"

# Codex
npx zcf init -s -T codex -p kimi -k "your-auth-token"

Custom Copy Section

Provider Name: Custom

Features:

• 🔧 Fully customizable configuration
• 🌐 Supports arbitrary API endpoints
• 📝 Requires manual configuration of all parameters

Usage:

# Use custom provider (requires URL)
npx zcf init -s -p custom -k "sk-xxx" -u "https://api.example.com/v1"

# Or use traditional method (without preset)
npx zcf init -s -t api_key -k "sk-xxx" -u "https://api.example.com/v1"

Usage Methods Copy Chapter

Basic Usage Copy Section

Using provider presets is very simple, only need two parameters:

# Use provider preset
npx zcf init -s -p  -k <api-key>

# Example: Use 302.AI
npx zcf init -s -p 302ai -k "sk-xxx"

Automatic Configuration Copy Section

When using presets, ZCF will automatically configure:

1. ✅ Base URL: Automatically fill in correct API endpoint
2. ✅ Authentication Method: Automatically set authentication type (api_key or auth_token)
3. ✅ Default Model: If provider supports, automatically set default model
4. ✅ Codex Configuration: If using Codex, automatically configure wireApi protocol

Override Default Configuration Copy Section

Even when using presets, you can still override default configuration:

# Use preset but override model
npx zcf init -s -p 302ai -k "sk-xxx" \
  -M "claude-sonnet-4-5" \
  -F "claude-haiku-4-5"

# Use preset but override URL (not recommended, unless testing)
npx zcf init -s -p 302ai -k "sk-xxx" \
  -u "https://custom.302.ai/api"

Multi-Configuration Scenarios Copy Chapter

Configure Multiple Providers Copy Section

Using --api-configs or --api-configs-file can configure multiple providers simultaneously:

# Configure multiple providers using JSON string
npx zcf init -s --api-configs '[
  {
    "provider": "302ai",
    "key": "sk-302ai-xxx",
    "default": true
  },
  {
    "provider": "z-ai",
    "key": "sk-glm-yyy"
  },
  {
    "provider": "minimax",
    "key": "sk-minimax-zzz"
  }
]'

Mix Presets with Custom Configuration Copy Section

# Configuration file example (api-configs.json)
{
  "configs": [
    {
      "provider": "302ai",
      "key": "sk-302ai-xxx",
      "default": true
    },
    {
      "name": "custom-api",
      "type": "api_key",
      "key": "sk-custom-xxx",
      "url": "https://custom.api.com/v1",
      "primaryModel": "claude-sonnet-4-5",
      "fastModel": "claude-haiku-4-5"
    }
  ]
}

# Use configuration file
npx zcf init -s --api-configs-file ./api-configs.json

Provider Switching Copy Chapter

After configuring multiple providers, you can switch anytime:

Claude Code Copy Section

# List all configurations
npx zcf config-switch --list

# Switch to specified provider
npx zcf config-switch 302ai-config

Codex Copy Section

# List Codex providers
npx zcf config-switch --code-type codex --list

# Switch to specified provider
npx zcf config-switch minimax-provider --code-type codex

Best Practices Copy Chapter

1. Prefer Presets Copy Section

Use provider presets whenever possible, which can:

• ✅ Reduce configuration errors
• ✅ Automatically get latest endpoints
• ✅ Simplify configuration process

# Recommended: Use preset
npx zcf init -s -p 302ai -k "sk-xxx"

# Not recommended: Manually configure all parameters
npx zcf init -s -t api_key -k "sk-xxx" -u "https://api.302.ai/cc" -M "claude-sonnet-4-5"

2. Test Configuration Copy Section

Before formal use, it's recommended to test configuration first:

# 1. Initialize using preset
npx zcf init -s -p 302ai -k "test-key"

# 2. Test API connection
# Test conversation in Claude Code or Codex

# 3. If normal, reconfigure with production key
npx zcf init -s -p 302ai -k "production-key"

3. Multi-Provider Strategy Copy Section

Configure different providers for different projects:

# Project A: Use 302.AI provider
npx zcf config-switch 302ai-provider

# Project B: Use Z.ai provider
npx zcf config-switch z-ai-provider

# Project C: Use MiniMax provider
npx zcf config-switch minimax-provider

4. Key Security Copy Section

• ⚠️ Do not commit keys to version control
• ✅ Use environment variables to manage keys
• ✅ Regularly rotate keys
• ✅ Use principle of least privilege

# Use environment variables
export ZCF_API_KEY="sk-xxx"
npx zcf init -s -p 302ai -k "$ZCF_API_KEY"

# Or read from file (ensure file permissions are correct)
npx zcf init -s -p 302ai -k "$(cat ~/.zcf/api-key)"

Troubleshooting Copy Chapter

Provider Not Supported Copy Section

If using unsupported provider ID:

# Error message will display all valid values
npx zcf init -s -p invalid-provider -k "sk-xxx"
# Error: Invalid provider 'invalid-provider'. Valid providers: 302ai, z-ai, minimax, kimi, custom

Authentication Failed Copy Section

If authentication fails:

1. Check API Key Format: Confirm key format is correct
2. Check Authentication Method: Confirm using correct authentication type
3. Verify Endpoint URL: Confirm endpoint URL is correct

# Verify configuration
cat ~/.claude/settings.json | jq .env.ANTHROPIC_API_KEY
cat ~/.codex/config.toml | grep apiKey

Model Unavailable Copy Section

If default model is unavailable:

# Override default model
npx zcf init -s -p 302ai -k "sk-xxx" -M "claude-sonnet-4-5"

# Or manually edit configuration file
vim ~/.claude/settings.json

Related Resources Copy Chapter

• Quick Start - Installation and initialization guide
• Configuration Management - Detailed configuration management
• Config Switch - Multi-configuration switch command

💡 Tip: Using API provider presets can greatly simplify the configuration process. It's recommended to prefer presets, only use custom configuration when necessary. Regularly check provider documentation to get latest configuration information.

File: docs/en/advanced/configuration.md Copy Chapter

title: Configuration Management Copy Chapter

Configuration Management

ZCF provides a comprehensive configuration management system, supporting incremental management, backup strategies, and flexible configuration switching. Understanding the structure and mechanisms of the configuration system can help you better manage and maintain your development environment.

Directory Structure Overview Copy Chapter

ZCF's configurations are distributed across the following directories:

Main Configuration Directories Copy Section

Configuration File Details Copy Section

Claude Code Configuration

~/.claude/
├── settings.json          # Main configuration file (API, MCP, permissions, etc.)
├── CLAUDE.md              # Project memory and system prompts
├── prompts/               # Prompts directory
│   ├── output-style/      # Output style templates
│   └── memory/            # Memory templates
└── workflows/             # Workflows directory
    ├── zcf-workflow/      # Six-stage workflow
    ├── feat/              # Feature development workflow
    ├── git/               # Git workflow
    └── bmad/              # BMad workflow

Codex Configuration

~/.codex/
├── config.toml            # Main configuration file (TOML format)
├── auth.json              # API key configuration (encrypted storage)
├── AGENTS.md              # System prompts and agent configuration
├── prompts/               # Prompts directory
│   └── workflow/          # Workflow prompts
└── system-prompt/         # System prompt templates

ZCF Global Configuration

~/.ufomiao/zcf/
├── config.toml            # ZCF global configuration (TOML format)
│   ├── preferredLang      # CLI language preference
│   ├── templateLang       # Template language preference
│   ├── aiOutputLang       # AI output language preference
│   └── codeToolType       # Current active tool type
└── backup/                # ZCF configuration backup

Incremental Management Mode Copy Chapter

When ZCF detects existing configuration, it will ask for operation strategy.

Configuration Handling Strategies Copy Section

Automatic Strategy Application Copy Section

In non-interactive mode (--skip-prompt), ZCF will automatically apply default strategy:

• Default strategy: backup
• Can specify strategy via --config-action parameter

# Specify configuration handling strategy
npx zcf init -s --config-action merge

# Only update documents
npx zcf init -s --config-action docs-only

Merge Strategy Details Copy Section

merge strategy will try to intelligently merge configurations:

• ✅ MCP Services: New services will be merged into existing configuration
• ✅ Workflows: New workflows will be added to existing workflows
• ⚠️ API Configuration: May require manual confirmation
• ⚠️ Output Styles: New styles will be added to existing styles

API Model Configuration Copy Chapter

Four-Model Architecture Copy Section

ZCF uses a four-model architecture to provide granular control over AI model selection:

Model Configuration Parameters Copy Section

When configuring API settings, you can specify each model individually:

# Configure all four models
npx zcf i -s \
  --api-key "sk-xxx" \
  --api-model "claude-sonnet-4-5" \
  --api-haiku-model "claude-haiku-4-5" \
  --api-sonnet-model "claude-sonnet-4-5" \
  --api-opus-model "claude-opus-4-5"

Multi-Profile Model Configuration Copy Section

When using multiple API profiles, each profile can have its own model configuration:

{
  "name": "production",
  "type": "api_key",
  "key": "sk-prod-xxx",
  "primaryModel": "claude-sonnet-4-5",
  "defaultHaikuModel": "claude-haiku-4-5",
  "defaultSonnetModel": "claude-sonnet-4-5",
  "defaultOpusModel": "claude-opus-4-5"
}

Environment Variable Mapping Copy Section

The configuration system maps profile model settings to environment variables:

• primaryModel → ANTHROPIC_MODEL
• defaultHaikuModel → ANTHROPIC_DEFAULT_HAIKU_MODEL
• defaultSonnetModel → ANTHROPIC_DEFAULT_SONNET_MODEL
• defaultOpusModel → ANTHROPIC_DEFAULT_OPUS_MODEL

Migration from Legacy Configuration Copy Section

If you're upgrading from the old two-model system:

Old Configuration (Deprecated):

{
  "primaryModel": "claude-sonnet-4-5",
  "fastModel": "claude-haiku-4-5"
}

New Configuration (Recommended):

{
  "primaryModel": "claude-sonnet-4-5",
  "defaultHaikuModel": "claude-haiku-4-5",
  "defaultSonnetModel": "claude-sonnet-4-5",
  "defaultOpusModel": "claude-opus-4-5"
}

💡 Note: The old fastModel parameter is still supported for backward compatibility but is deprecated. The system will automatically clean up the legacy ANTHROPIC_SMALL_FAST_MODEL environment variable when switching profiles.

Model Selection Best Practices Copy Section

1. Haiku: Use for simple tasks like formatting, basic transformations, quick responses
2. Sonnet: Default choice for most development workflows and general coding tasks
3. Opus: Reserve for complex reasoning, architectural decisions, and critical code generation
4. Primary: Acts as the fallback when no specific model is requested

AI Output Language Directives Copy Chapter

Configuration Mechanism Copy Section

The applyAiLanguageDirective function will write corresponding language directives to system prompt files based on --ai-output-lang parameter.

Supported Language Options Copy Section

• zh-CN: Chinese output directive
• en: English output directive
• custom: Custom language directive

Custom Language Directives Copy Section

Using custom option allows input of custom language directives:

npx zcf init --ai-output-lang custom
# Enter: Reply in Japanese, maintain professional and polite tone

Custom directives will be written to:

• Claude Code: ~/.claude/CLAUDE.md
• Codex: ~/.codex/AGENTS.md

Configuration Location Copy Section

Language directive configuration locations:

• Claude Code: Top of CLAUDE.md file
• Codex: Top of AGENTS.md file

Template Language Selection Copy Chapter

Language Resolution Mechanism Copy Section

The resolveTemplateLanguage function determines template language by considering the following factors:

1. Command Line Parameters: --config-lang or --all-lang
2. Configuration File: templateLang in ~/.ufomiao/zcf/config.toml
3. Interactive Input: If not specified, will prompt user to select
4. System Default: Finally fallback to en

Language Independence Copy Section

Template language and AI output language are independent of each other and can be flexibly combined:

# Chinese templates + English output (suitable for projects requiring English code comments)
npx zcf init --config-lang zh-CN --ai-output-lang en

# English templates + Chinese output (suitable for international teams)
npx zcf init --config-lang en --ai-output-lang zh-CN

Template Language Effects Copy Section

Template language affects:

• Language version of workflow templates
• Language of prompts and instructions
• Language of system prompt templates
• Language of output style templates

Change Tracking Recommendations Copy Chapter

Use Version Control Copy Section

It's recommended to use Git to manage configuration directories:

# Create configuration repository
mkdir ~/zcf-configs
cd ~/zcf-configs
git init

# Add configuration files (note: exclude sensitive information)
cat > .gitignore << EOF
*.key
auth.json
settings.json
config.toml
EOF

# Add templates and workflows (without sensitive information)
git add prompts/ workflows/ templates/
git commit -m "Add ZCF templates and workflows"

Compare Differences Copy Section

Compare differences before and after executing zcf update:

# Before update
git add ~/.claude/
git commit -m "Before update"

# Execute update
npx zcf update

# View differences
git diff ~/.claude/

# Review changes then commit
git add ~/.claude/
git commit -m "After update"

Backup Restoration Copy Section

If custom content is accidentally overwritten, you can restore from backup directory:

# View backups
ls -lt ~/.claude/backup/

# Restore specific backup
cp -r ~/.claude/backup/backup_2025-01-15_10-30-45/* ~/.claude/

# Or restore specific file
cp ~/.claude/backup/backup_*/workflows/custom/my-workflow.md ~/.claude/skills/custom/

Configuration Management Best Practices Copy Chapter

1. Layered Configuration Management Copy Section

• Global Configuration: Team-shared templates and workflows
• Personal Configuration: Personal API keys and preferences
• Project Configuration: Project-specific workflows and templates

2. Sensitive Information Handling Copy Section

• ⚠️ Do not commit sensitive information to version control
• ✅ Use environment variables to manage API keys
• ✅ Use .gitignore to exclude sensitive files
• ✅ Regularly rotate keys

3. Configuration Synchronization Copy Section

Synchronize configurations across multiple devices:

# Method 1: Use Git
git clone ~/zcf-configs
cp -r zcf-configs/templates/* ~/.claude/skills/

# Method 2: Use cloud storage
rsync -av ~/.claude/skills/ ~/Cloud/.claude/workflows/

# Method 3: Use Git Worktree
/git-worktree migrate

4. Regular Review Copy Section

Regularly review and clean configurations:

# Clean old backups (keep last 30 days)
find ~/.claude/backup -name "*.bak" -mtime +30 -delete

# Review unused configurations
ls -la ~/.claude/skills/
# Remove custom workflows that are no longer needed

5. Team Collaboration Copy Section

In team environments:

• Unify configuration templates and standards
• Share workflows and output styles
• Maintain configuration change logs
• Regularly sync configuration updates

Configuration Migration Copy Chapter

Migrate from Old Version Copy Section

If upgrading from old version of ZCF:

# ZCF will automatically detect and migrate configuration
npx zcf init

# Or manually check migration
cat ~/.ufomiao/zcf/config.toml
# Check if there are migration prompts

Cross-Tool Migration Copy Section

Migrate from Claude Code to Codex:

# 1. Backup Claude Code configuration
cp -r ~/.claude ~/.claude.backup

# 2. Initialize Codex
npx zcf init -T codex

# 3. Manually migrate workflows and templates (if needed)
# Note: Template formats for Claude Code and Codex may differ

Troubleshooting Copy Chapter

Configuration Conflicts Copy Section

If you encounter configuration conflicts:

# 1. View conflict details
npx zcf init
# View conflict prompts when selecting merge strategy

# 2. Manually merge configuration
# Edit configuration file, manually merge conflicting items

# 3. Use backup strategy to start over
npx zcf init --config-action backup

Configuration Lost Copy Section

If configuration is lost:

# 1. Find backup
ls -lt ~/.claude/backup/ | head -5

# 2. Restore backup
cp -r ~/.claude/backup/backup_latest_timestamp/* ~/.claude/

# 3. Reinitialize (if backup unavailable)
npx zcf init --config-action new

Configuration File Corrupted Copy Section

If configuration file is corrupted:

# 1. Check configuration file format
cat ~/.claude/settings.json | jq .

# 2. Restore from backup
cp ~/.claude/backup/backup_*/settings.json ~/.claude/

# 3. Or reinitialize
npx zcf init --config-action new

Related Resources Copy Chapter

• Multi-Config and Backup - Multi-configuration system and backup mechanisms
• Internationalization and Languages - Detailed language configuration
• Template System - Template management and customization

💡 Tip: Proper configuration management can improve development efficiency and team collaboration quality. It's recommended to use version control to manage templates and workflows, while properly storing configuration files containing sensitive information. Regularly backup and review configurations to ensure development environment stability.

File: docs/en/advanced/i18n.md Copy Chapter

title: Internationalization and Languages Copy Chapter

Internationalization and Languages

ZCF provides comprehensive internationalization (i18n) support, allowing you to flexibly configure CLI interface language, AI output language, and template language to meet language needs in different scenarios.

Language Configuration Levels Copy Chapter

ZCF's language system is divided into three independent but related levels:

1. CLI Language: Interface language of ZCF tool itself
2. AI Output Language: Language used for AI assistant replies
3. Template Language: Language of workflow templates and prompts

These three levels can be configured independently to meet various mixed scenario needs.

CLI Language Copy Chapter

CLI language controls the interface display language of ZCF command-line tool.

Supported Languages Copy Section

• zh-CN: Simplified Chinese
• en: English

Language Priority Copy Section

CLI language is determined according to the following priority:

1. Command line parameters --all-lang or --lang
2. preferredLang in configuration file
3. Interactive selection
4. System default (en)

Set CLI Language Copy Section

# Through command line parameters
npx zcf --lang zh-CN
npx zcf init --lang zh-CN

# Through unified language parameter (recommended)
npx zcf --all-lang zh-CN

# Switch in main menu
npx zcf
# Enter 0 to switch language

# Configuration file location
cat ~/.ufomiao/zcf/config.toml | grep preferredLang

Language Switch Implementation Copy Section

Language switching is implemented through the following functions:

• changeLanguage: Switch i18n language
• resolveAndSwitchLanguage: Resolve and switch language (considering priority)

AI Output Language Copy Chapter

AI output language controls the language used for AI assistant replies and generated content, which can be different from CLI language.

Supported Language Options Copy Section

• zh-CN: Chinese output
• en: English output
• custom: Custom language instructions

Set AI Output Language Copy Section

# Set during initialization
npx zcf init --ai-output-lang zh-CN

# Or use unified parameter
npx zcf init --all-lang zh-CN

# Configure in main menu
npx zcf
# Select 6 (Configure AI Memory & Output Style)
# Then select AI output language

Custom Language Instructions Copy Section

Using custom option allows input of custom language instructions:

npx zcf init --ai-output-lang custom
# Then enter: Reply in Japanese, maintain professional and polite tone

Custom instructions will be written to CLAUDE.md or AGENTS.md, affecting AI output language and style.

AI Output Language Configuration Location Copy Section

• Claude Code: Language instructions in ~/.claude/CLAUDE.md
• Codex: Language instructions in ~/.codex/AGENTS.md

Template Language Copy Chapter

Template language controls the language version of workflow templates, prompts, and system prompts.

Supported Languages Copy Section

• zh-CN: Chinese templates
• en: English templates

Template Language Independence Copy Section

Template language is independent of CLI language and can be flexibly combined:

# Chinese interface + English templates (suitable for scenarios requiring English documentation)
npx zcf init --lang zh-CN --config-lang en

# English interface + Chinese templates (suitable for international teams)
npx zcf init --lang en --config-lang zh-CN

# Unified language (recommended for most scenarios)
npx zcf init --all-lang zh-CN

Set Template Language Copy Section

# Set during initialization
npx zcf init --config-lang zh-CN

# Set during update
npx zcf update --config-lang zh-CN

# Or use unified parameter
npx zcf init --all-lang zh-CN

Template Language Resolution Copy Section

Template language is determined through resolveTemplateLanguage function:

1. Command line parameter --config-lang
2. templateLang in configuration file
3. Current CLI language (if not specified)
4. System default (en)

Codex Language Configuration Copy Chapter

After switching to Codex, language configuration rules are the same:

# Codex initialization, use Chinese
npx zcf init -T codex --all-lang zh-CN

# Switch language in Codex menu
# Menu in Codex mode will provide language switch options

Usage Scenarios Copy Chapter

Scenario 1: Chinese Environment (Recommended) Copy Section

Suitable for most Chinese users:

npx zcf init --all-lang zh-CN

Result:

• CLI Interface: Chinese
• AI Output: Chinese
• Template Files: Chinese

Scenario 2: Chinese Interface + English Code Copy Section

Suitable for projects requiring English code comments:

npx zcf init --lang zh-CN --ai-output-lang en --config-lang zh-CN

Result:

• CLI Interface: Chinese
• AI Output: English (code comments and documentation)
• Template Files: Chinese

Scenario 3: International Team Copy Section

Suitable for international teams requiring English documentation:

npx zcf init --lang en --config-lang en --ai-output-lang en

Result:

• CLI Interface: English
• AI Output: English
• Template Files: English

Scenario 4: Mixed Configuration Copy Section

Flexibly combine to meet specific needs:

# Chinese interface, Chinese templates, custom AI output
npx zcf init \
  --lang zh-CN \
  --config-lang zh-CN \
  --ai-output-lang custom
# Enter: Use Chinese to reply, code comments use English

Best Practices Copy Chapter

1. Team Unified Configuration Copy Section

In team collaboration, it's recommended to unify language configuration:

# Team uniformly uses Chinese
npx zcf init --all-lang zh-CN

# Or team uniformly uses English
npx zcf init --all-lang en

This ensures:

• Consistent team member experience
• Unified document formats
• Smoother collaboration

2. Project-Specific Configuration Copy Section

Different projects may have different needs:

# Open source projects: Use English
npx zcf init --all-lang en

# Internal projects: Use Chinese
npx zcf init --all-lang zh-CN

# Mixed projects: Chinese interface + English output
npx zcf init --lang zh-CN --ai-output-lang en

3. Multi-Language Documentation Copy Section

If multi-language documentation is needed:

# 1. First generate complete documentation in Chinese
npx zcf init --all-lang zh-CN
# Complete feature development, generate Chinese documentation

# 2. Switch to English, update documentation
npx zcf update --config-lang en
# Generate English version of documentation

# 3. Use GitBook multi-language functionality to manage

4. Configuration File Management Copy Section

Language configuration is saved in ZCF global configuration:

# View current configuration
cat ~/.ufomiao/zcf/config.toml

# Configuration file fields
# preferredLang: CLI language preference
# templateLang: Template language preference
# aiOutputLang: AI output language preference

5. Scripted Configuration Copy Section

Explicitly specify language in automation scripts:

#!/bin/bash
# Deployment script

# Explicitly specify all language parameters
npx zcf init -s \
  --all-lang zh-CN \
  --provider 302ai \
  --api-key "$API_KEY"

Troubleshooting Copy Chapter

Language Configuration Not Effective Copy Section

If language configuration is not effective:

# 1. Check configuration file
cat ~/.ufomiao/zcf/config.toml | grep -E "preferredLang|templateLang|aiOutputLang"

# 2. Reinitialize and explicitly specify
npx zcf init --all-lang zh-CN

# 3. Check environment variables (if set)
echo $LANG

Template Language Doesn't Match Expected Copy Section

If template language doesn't match expected:

# 1. Explicitly specify template language
npx zcf init --config-lang zh-CN

# 2. Update existing configuration
npx zcf update --config-lang zh-CN

# 3. Check template files
ls -la ~/.claude/skills/
# View language version of template files

AI Output Language Incorrect Copy Section

If AI output language is incorrect:

# 1. Check CLAUDE.md or AGENTS.md
cat ~/.claude/CLAUDE.md | grep -i language
cat ~/.codex/AGENTS.md | grep -i language

# 2. Reconfigure AI output language
npx zcf
# Select 6 (Configure AI Memory & Output Style)

# 3. Or directly edit configuration file
vim ~/.claude/CLAUDE.md
# Add language instructions

Related Resources Copy Chapter

• Configuration Management - Detailed configuration management guide
• Template System - Template language and customization
• Quick Start - Initialization process

💡 Tip: Proper language configuration can greatly improve development efficiency and team collaboration experience. It's recommended to choose appropriate language configuration based on project needs and team situation. Most Chinese users are recommended to use --all-lang zh-CN for the best experience.

File: docs/en/advanced/index.md Copy Chapter

title: Advanced Guide Copy Chapter

Advanced Guide

This chapter focuses on advanced configuration, template management, internationalization, and troubleshooting. Suitable for users who need large-scale deployment, team collaboration, or deep customization.

• Configuration Management: Learn about incremental management, backup strategies, and directory structure.
• API Provider Presets: Use presets to quickly configure common service providers.
• Templates and Output Styles: Customize workflows, system prompts, and output styles.
• Internationalization and Languages: Configure CLI and AI output language strategies.
• Troubleshooting: Common errors and troubleshooting procedures.

File: docs/en/advanced/templates.md Copy Chapter

title: Templates and Output Styles Copy Chapter

Templates and Output Styles

ZCF provides a complete template system, including workflow templates, output style templates, and system prompt templates. These templates support multiple languages (Chinese and English) and can be customized to meet team-specific needs.

Template System Overview Copy Chapter

ZCF's template system is divided into the following levels:

1. Workflow Templates: Structured development workflows
2. Output Style Templates: AI assistant personality and output styles
3. System Prompt Templates: Project-level system prompts and standards
4. MCP Service Templates: MCP service usage guides

Template Directory Structure Copy Chapter

Claude Code Templates Copy Section

templates/claude-code/
├── common/                      # Common configuration templates
│   └── settings.json           # Claude settings template
├── zh-CN/                      # Chinese template collection
│   ├── output-styles/         # Output style templates
│   │   ├── engineer-professional.md
│   │   ├── nekomata-engineer.md
│   │   ├── laowang-engineer.md
│   │   └── ojousama-engineer.md
│   └── workflow/              # Workflow templates
│       ├── common/            # Common tools workflow
│       ├── plan/              # Planning workflow
│       ├── sixStep/          # Six-stage workflow
│       ├── bmad/              # BMad enterprise workflow
│       └── git/               # Git workflow
└── en/                         # English template collection
    ├── output-styles/         # Output style templates
    └── workflow/              # Workflow templates (same structure)

Codex Templates Copy Section

templates/codex/
├── common/                     # Common configuration templates
│   └── config.toml            # Codex configuration template
├── zh-CN/                      # Chinese template collection
│   ├── system-prompt/         # System prompt templates
│   └── workflow/              # Workflow templates
│       ├── sixStep/          # Six-stage workflow
│       └── git/              # Git workflow
└── en/                         # English template collection
    ├── system-prompt/         # System prompt templates
    └── workflow/              # Workflow templates (same structure)

Output Style Templates Copy Chapter

Output styles define AI assistant personality and output methods. These templates are stored in the prompts/output-style/ directory.

Pre-configured Output Styles Copy Section

Built-in Output Styles Copy Section

In addition to pre-configured styles, built-in styles are also supported:

• default - Default output style
• explanatory - Explanatory style, focuses on explanation
• learning - Learning style, focuses on teaching

Install Output Styles Copy Section

# Install all output styles
npx zcf init -o all

# Install specific styles
npx zcf init -o engineer-professional,nekomata-engineer

# Set default output style
npx zcf init -o all -d engineer-professional

# Skip output style installation
npx zcf init -o skip

Switch Output Style Copy Section

Claude Code:

/output-style engineer-professional

Codex:
Configure through system prompt or edit systemPromptStyle in config.toml.

Custom Output Styles Copy Section

1. Edit Template File:

# Find template file
cd ~/.claude/prompts/output-style/

# Edit or create new style
vim my-custom-style.md

2. Use During Initialization:

# Initialize first, then manually copy custom style
cp my-custom-style.md ~/.claude/prompts/output-style/

3. Team Sharing:

# Include custom style in version control
git add prompts/output-style/my-custom-style.md
git commit -m "Add custom output style"

Workflow Templates Copy Chapter

Workflow templates define structured development processes. Each workflow includes skill templates and optional agent templates.

Workflow Types Copy Section

1. Common Tools Workflow (`common/`)

Commands:

• init-project.md - Project initialization command

Agents:

• init-architect.md - Initialization architect
• get-current-datetime.md - Time tool

Purpose: Provide project initialization, common tools, and time handling functionality

2. Planning Workflow (`plan/`)

Commands:

• feat.md - Feature development command

Agents:

• planner.md - Planner
• ui-ux-designer.md - UI/UX Designer

Purpose: New feature design and planning

3. Six-Stage Workflow (`sixStep/`)

Commands:

• workflow.md - Six-stage development process (Research→Ideate→Plan→Execute→Optimize→Review)

Purpose: Structured development process

4. BMad Workflow (`bmad/`)

Commands:

• bmad-init.md - BMad initialization

Agents:

• Complete enterprise-level development team simulation (PO, PM, Architect, Developer, QA, etc.)

Purpose: Enterprise-level agile development process

5. Git Workflow (`git/`)

Commands:

• git-commit.md - Smart Git commit
• git-rollback.md - Safe rollback
• git-cleanBranches.md - Clean merged branches
• git-worktree.md - Git worktree management

Purpose: Git operation automation

Workflow Installation Copy Section

# Install all workflows
npx zcf init -w all

# Install specific workflows
npx zcf init -w sixStepsWorkflow,gitWorkflow

# Skip workflow installation
npx zcf init -w skip

Custom Workflows Copy Section

1. Fork Repository and Modify Templates:

# 1. Fork ZCF repository
git clone https://github.com/your-org/zcf.git
cd zcf

# 2. Modify templates
vim templates/claude-code/zh-CN/workflow/custom/my-workflow.md

# 3. Build and test
pnpm build
npm link

2. Use During Initialization:

# Initialize using custom template directory
npx zcf init -w custom

3. Team Publishing Custom Templates:

# Publish npm package containing custom templates
npm publish @your-org/zcf-templates

System Prompt Templates Copy Chapter

System prompt templates define project-level AI behavior standards and guidelines.

CLAUDE.md Copy Section

CLAUDE.md is Claude Code's project memory file, recommended structure:

# Project Configuration

## Language Instructions
Use Chinese to reply

## Coding Standards
- Use TypeScript
- Follow ESLint rules
- Use 2-space indentation

## Workflow Standards
Use six-stage workflow for development

Project Memory Best Practices Copy Section

1. Hierarchical Organization:

Project Root/
├── CLAUDE.md              # Global configuration (concise)
└── .claude/
    ├── plan/              # Plan documents
    ├── memory/            # Project memory
    │   ├── architecture.md
    │   ├── api-design.md
    │   └── coding-standards.md
    └── workflows/         # Workflow templates

2. Avoid Excessive Context:

• Global CLAUDE.md only keeps necessary settings
• Complex standards go into output styles or project memory
• Use /init-project to generate hierarchical structure

3. Regular Updates:

# Update templates and prompts
npx zcf update -g zh-CN

Template Language Support Copy Chapter

ZCF supports templates in two languages:

Chinese Templates (`zh-CN`) Copy Section

• Complete Chinese localization
• Chinese AI interaction mode
• Chinese technical documentation standards
• Chinese workflow descriptions

English Templates (`en`) Copy Section

• Complete English localization
• English AI interaction mode
• English technical documentation standards
• English workflow descriptions

Language Switching Copy Section

# Initialize using Chinese templates
npx zcf init -c zh-CN

# Initialize using English templates
npx zcf init -c en

# Switch language during update
npx zcf update -c en

Template Update Strategy Copy Chapter

Update Methods Copy Section

Preserve Custom Content Copy Section

If you modified templates, it's recommended to:

1. Backup Custom Templates:

# Backup custom templates
tar -czf my-custom-templates.tar.gz ~/.claude/skills/custom/

2. Use Version Control:

# Include custom templates in Git
git add ~/.claude/skills/custom/
git commit -m "Add custom workflow templates"

3. Check During Updates:

# Compare differences before updating
diff -r ~/.claude/skills/ ~/.claude/backup/latest/workflows/

Team Collaboration Copy Chapter

Unified Templates Copy Section

Unify template standards within team:

1. Create Team Template Repository:

# Create template repository
mkdir team-zcf-templates
cd team-zcf-templates
git init

# Add template files
cp -r ~/.claude/skills/team-* ./
git add .
git commit -m "Initial team templates"

2. Team Member Sync:

# Pull team templates
git pull origin main
cp -r team-* ~/.claude/skills/

Template Version Management Copy Section

• Use semantic versioning for template changes
• Provide migration guides for major changes
• Maintain backward compatibility as much as possible
• Test template updates on existing configurations

Troubleshooting Copy Chapter

Templates Not Installed Copy Section

If templates are not correctly installed:

# Reinstall templates
npx zcf init --config-action new

# Check template directories
ls -la ~/.claude/skills/
ls -la ~/.claude/prompts/output-style/

Custom Templates Lost Copy Section

If custom templates are lost after update:

# Restore from backup
cp -r ~/.claude/backup/backup_*/workflows/custom/ ~/.claude/skills/

# Or restore from version control
git checkout HEAD -- ~/.claude/skills/custom/

Language Mismatch Copy Section

If template language doesn't match configuration:

# Reinitialize and specify language
npx zcf init --config-action backup -c zh-CN

# Or only update template language
npx zcf update -c zh-CN

Related Resources Copy Chapter

• Workflow System - Detailed workflow information
• Output Style Strategy - Output style management
• Configuration Management - Configuration management guide

💡 Tip: Proper use of template system can greatly improve development efficiency. It's recommended to unify template standards within teams and regularly update templates to get latest features.

File: docs/en/best-practices/index.md Copy Chapter

title: Best Practices Copy Chapter

Best Practices

This chapter compiles experiences and tips for daily use of ZCF, helping you maximize benefits in team collaboration and multi-project scenarios.

• Usage Tips: Common high-frequency operations and recommendations.
• Worktree Parallel Development: How to efficiently utilize Git Worktree.
• Output Style Strategy: Output style management and team sharing solutions.

File: docs/en/best-practices/output-styles.md Copy Chapter

title: Output Style Strategy Copy Chapter

Output Style Strategy

Output styles are high-priority system prompts, suitable for defining team standards, coding standards, and AI behavior guidelines. By configuring different output styles, you can control AI assistant personality and working methods.

What is Output Style Copy Chapter

Output styles are Markdown files stored in the prompts/output-style/ directory, defining AI assistant's:

• 🎭 Personality Traits: AI's speaking style and behavior
• 📝 Coding Standards: Code style, comment requirements, naming conventions
• ✅ Quality Standards: Code review standards, testing requirements
• 🔍 Working Methods: Problem analysis methods, decision processes

Management Methods Copy Chapter

Install Output Styles Copy Section

Specify styles to install via --output-styles parameter during initialization:

# Install all output styles
npx zcf init -o all

# Install specific styles
npx zcf init -o engineer-professional,nekomata-engineer

# Skip output style installation
npx zcf init -o skip

Switch Output Style Copy Section

Switch in Main Menu

npx zcf
# Select 6 (Configure AI Memory & Output Style)
# Then select output style management

Switch in Project

Claude Code:

/output-style engineer-professional

Codex:
Edit systemPromptStyle in config.toml or use system prompt configuration.

Edit Output Style Copy Section

Output style files are located in prompts/output-style/ directory:

# View installed styles
ls -la ~/.claude/prompts/output-style/

# Edit specific style
vim ~/.claude/prompts/output-style/engineer-professional.md

# Create custom style
vim ~/.claude/prompts/output-style/my-custom-style.md

Pre-configured Output Styles Copy Chapter

ZCF provides the following pre-configured output styles:

Built-in Output Styles Copy Section

In addition to pre-configured styles, the following built-in styles are also supported (always available):

• default: Default output style
• explanatory: Explanatory style, focuses on detailed explanation
• learning: Learning style, focuses on teaching and explanation

Practice Recommendations Copy Chapter

1. Write Team Standards into Output Style Copy Section

Output style is an ideal place to define team development standards:

# ~/.claude/prompts/output-style/team-standards.md

## Coding Standards

- Use TypeScript, strict mode
- Functions no more than 50 lines
- Must write unit tests
- Use ESLint and Prettier
- Follow SOLID principles

## Code Review Requirements

- All PRs must go through code review
- Ensure test coverage > 80%
- Check performance impact
- Verify security

2. Create Multiple Styles for On-Demand Switching Copy Section

Create different output styles for different scenarios:

# During development: Use professional engineer style
/output-style engineer-professional

# During code review: Use review-specific style
/output-style code-review

# During documentation: Use documentation style
/output-style documentation

3. Project-Specific Styles Copy Section

For projects requiring independent styles, use project-level output styles:

# Create in project root directory
Project Root/.claude/output-style/project-specific.md

# Use in conversation
/output-style project-specific

Project-specific styles override global styles but only take effect in that project.

4. Style Priority Copy Section

Output style priority:

1. Project-Specific Style (.claude/output-style/ or .codex/output-style/)
2. Global Default Style (default settings in ~/.claude/prompts/output-style/)
3. Built-in Style (default, explanatory, learning)

5. Version Control Copy Section

Include team output styles in version control:

# Create team style repository
mkdir team-output-styles
cp ~/.claude/prompts/output-style/team-standards.md team-output-styles/

# Include in Git
git add team-output-styles/
git commit -m "Add team output style standards"

# Team member sync
git pull
cp team-output-styles/team-standards.md ~/.claude/prompts/output-style/

Output Style Structure Copy Chapter

Typical output style file structure:

# Output Style Name

## Personality Traits
Describe AI's speaking style and behavior

## Coding Standards
- Code style requirements
- Naming conventions
- Comment requirements

## Quality Standards
- Code review standards
- Testing requirements
- Performance standards

## Working Methods
- Problem analysis methods
- Decision processes
- Collaboration methods

Custom Output Styles Copy Chapter

Create Custom Style Copy Section

1. Create Style File:

vim ~/.claude/prompts/output-style/my-style.md

2. Write Style Content:

# My Custom Style

You are a professional full-stack engineer, focusing on:
- Code quality and maintainability
- Performance optimization
- Security considerations
- User experience

## Coding Standards
- Use TypeScript
- Follow Airbnb code standards
- Write complete type definitions
- Must include error handling

## Working Methods
- Understand requirements before coding
- Write tests for test-driven development
- Focus on code reuse
- Continuous refactoring and optimization

3. Use Custom Style:

# Set default style
npx zcf
# Select 6, then select my-style

# Or use in project
/output-style my-style

Team Shared Styles Copy Section

Share custom styles with team:

# 1. Export style file
cp ~/.claude/prompts/output-style/team-style.md ./team-styles/

# 2. Include in version control
git add team-styles/
git commit -m "Add team output style"

# 3. Team members import
git pull
cp team-styles/team-style.md ~/.claude/prompts/output-style/

Best Practices Copy Chapter

1. Layered Definition of Standards Copy Section

• Global Style: Team-common coding standards and standards
• Project Style: Project-specific requirements and constraints
• Role Style: Styles for different roles (developer, reviewer, document writer)

2. Keep Styles Concise Copy Section

Output styles should be concise and clear, avoid being too verbose:

• ✅ Recommended: Core standards and key requirements
• ❌ Not Recommended: Overly detailed details (should be in project documentation)

3. Regular Style Updates Copy Section

As projects develop and teams grow, regularly update output styles:

# Regular review and update
vim ~/.claude/prompts/output-style/engineer-professional.md

# Update after team discussion
git add prompts/output-style/
git commit -m "Update output style standards"

4. Test Style Effects Copy Section

After creating new style, test its effects:

# 1. Set new style
/output-style my-new-style

# 2. Conduct test conversation
Please help me implement a simple Todo feature

# 3. Evaluate if output meets expectations

# 4. Adjust style based on feedback

5. Document Styles Copy Section

Write documentation for custom styles:

# team-standards.md

## Style Description

This style defines our team's development standards and quality standards.

## Usage Scenarios

- Formal project development
- Code review
- Technical review

## Update History

- 2025-01-15: Initial version
- 2025-02-01: Added performance requirements

Notes Copy Chapter

Claude Code Version Requirements Copy Section

• ⚠️ Version Requirement: Claude Code version must be > 1.0.81 to support output styles
• ✅ Check Version: Use npx zcf check-updates to check and update
• 📝 Migration Note: Global memory rules from old versions have been migrated to engineer-professional style

Style File Locations Copy Section

• Claude Code: ~/.claude/prompts/output-style/
• Codex: ~/.codex/prompts/output-style/ (if supported)
• Project Level: .claude/output-style/ or .codex/output-style/

Style Conflict Handling Copy Section

If multiple styles exist simultaneously:

1. Project-level style takes priority
2. Global default style is next
3. Built-in style as fallback

Related Resources Copy Chapter

• Template System - Detailed templates and output styles
• Configuration Management - Multi-configuration and backup
• Usage Tips - More practical tips

💡 Tip: Proper use of output styles can greatly improve code quality and development efficiency. It's recommended to unify output style standards within teams and customize appropriately based on project characteristics. Output styles should be concise and clear, focusing on core standards and key requirements.

File: docs/en/best-practices/tips.md Copy Chapter

title: Usage Tips Copy Chapter

Usage Tips

This document compiles practical tips and best practices for daily use of ZCF, helping you use ZCF more efficiently in various scenarios.

Core Tips Copy Chapter

1. Make Good Use of Interactive Menu Copy Section

Tip: Get used to starting with npx zcf. All functions have numbered prompts, avoiding the need to remember command details.

# Open interactive menu
npx zcf

# Menu options include:
# 1 - Complete Initialization
# 2 - Import Workflows
# 3 - Configure API or CCR
# 4 - Configure MCP
# 5 - Configure Default Model
# 6 - Configure AI Memory
# 7 - Configure Environment Permissions
# R - CCR Management
# U - ccusage Usage Analysis
# L - CCometixLine Management
# + - Check Updates
# ... etc.

Advantages:

• ✅ No need to remember complex command parameters
• ✅ Can browse all available functions
• ✅ Suitable for users unfamiliar with commands
• ✅ Reduces input errors

2. Regular Updates Copy Section

Tip: Keep workflows and templates up to date, and trigger version checks.

# Update once per week (recommended)
npx zcf update

# Or use abbreviation
npx zcf u

# Non-interactive update
npx zcf u -s -g zh-CN

Best Practices:

• 📅 Update once per week to get latest workflow templates
• 🔔 Pay attention to version update prompts, upgrade tools in time
• 💾 Automatic backup before update, can update with confidence

3. Multi-Language Switching Strategy Copy Section

Tip: Flexibly use language parameters to adapt to different scenario needs.

# Set all languages to Chinese uniformly
npx zcf init -g zh-CN

# Templates Chinese, AI output English (suitable for scenarios requiring English code comments)
npx zcf init -c zh-CN -a en

# Only switch language during update
npx zcf update -c en

Usage Scenarios:

• 🌐 International Projects: Use English templates for team collaboration
• 🇨🇳 Chinese Projects: Use Chinese templates to improve readability
• 🔀 Mixed Scenarios: Templates Chinese, AI output English code comments

4. Multi-Device Configuration Sync Copy Section

Tip: Sync configurations across multiple devices to maintain consistent development environment.

Method 1: Use Git Worktree

# Create worktree in project and migrate configuration
/git-worktree migrate

# Or use command line
git worktree add ../project-config
cp -r ~/.claude/* ../project-config/.claude/

Method 2: Use Cloud Storage Sync

# Use Dropbox, iCloud, OneDrive, etc.
# Link configuration directory to cloud storage

# macOS/iCloud
ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/.zcf-configs ~/.zcf-sync

# Sync configuration
rsync -av ~/.claude/ ~/.zcf-sync/claude/
rsync -av ~/.codex/ ~/.zcf-sync/codex/

Method 3: Use Version Control

# Create configuration repository
mkdir ~/zcf-configs && cd ~/zcf-configs
git init

# Add configuration files (note: exclude sensitive information)
echo "*.key" >> .gitignore
echo "auth.json" >> .gitignore
git add .claude/ .codex/
git commit -m "Initial ZCF configs"

# Pull across multiple devices
git pull origin main

5. Scripted Operations Deployment Copy Section

Tip: Combine --skip-prompt parameter with JSON configuration to achieve automated deployment.

CI/CD Script Example

#!/bin/bash
# deploy-zcf.sh - Automated ZCF configuration deployment

# Read configuration from environment variables
API_KEY=${ZCF_API_KEY}
PROVIDER=${ZCF_PROVIDER:-302ai}
LANG=${ZCF_LANG:-zh-CN}

# Non-interactive initialization
npx zcf init -s \
  --provider "$PROVIDER" \
  --api-key "$API_KEY" \
  --all-lang "$LANG" \
  --mcp-services all \
  --workflows all \
  --output-styles all

echo "ZCF configuration deployment completed"

New Employee Onboarding Script

#!/bin/bash
# onboard-dev.sh - New developer onboarding configuration script

echo "Configuring development environment..."

# 1. Configure ZCF (using configuration file)
npx zcf init -s --api-configs-file ./team-api-configs.json

# 2. Update workflows
npx zcf update -s -g zh-CN

# 3. Check tool versions
npx zcf check-updates

echo "Development environment configuration completed!"

Batch Deployment Script

#!/bin/bash
# batch-deploy.sh - Batch server deployment

SERVERS=("server1" "server2" "server3")

for server in "${SERVERS[@]}"; do
  echo "Deploying to $server..."
  ssh "$server" "npx zcf init -s -p 302ai -k '${API_KEY}' -g zh-CN"
done

6. Monitor Usage Copy Section

Tip: Use ccu command to monitor API usage and prevent excessive calls.

# View usage statistics
npx zcf ccu

# Output JSON format (for integration into monitoring systems)
npx zcf ccu --json > usage.json

# View detailed statistics
npx zcf ccu --verbose

Integration Example:

#!/bin/bash
# monitor-usage.sh - Usage monitoring script

# Get usage
USAGE=$(npx zcf ccu --json)

# Parse JSON (using jq)
TOKENS=$(echo "$USAGE" | jq '.tokens.total')
COST=$(echo "$USAGE" | jq '.cost.total')

# Send alert (if exceeds threshold)
if [ "$TOKENS" -gt 1000000 ]; then
  echo "Warning: Token usage exceeds 1 million!" | mail -s "ZCF Usage Alert" [email protected]
fi

Advanced Tips Copy Chapter

7. Use API Provider Presets Copy Section

Tip: Use provider presets to simplify configuration, reducing from 5+ parameters to just 2.

# Traditional method (requires multiple parameters)
npx zcf init -s \
  -t api_key \
  -k "sk-xxx" \
  -u "https://api.302.ai/v1" \
  -M "claude-sonnet-4-5" \
  -F "claude-haiku-4-5"

# Use preset (only 2 parameters needed)
npx zcf init -s -p 302ai -k "sk-xxx"

Supported Providers: 302ai, z-ai, minimax, kimi, custom

8. Multi-Configuration Management Copy Section

Tip: Use configuration switching to quickly switch between different environments.

# List all configurations
npx zcf config-switch --list

# Switch to work configuration
npx zcf config-switch work

# Switch to personal configuration
npx zcf config-switch personal

# Switch in Codex
npx zcf config-switch work --code-type codex

Naming Suggestions:

• work - Work environment configuration
• personal - Personal environment configuration
• test - Test environment configuration
• demo - Demo environment configuration

9. Workflow Combination Copy Section

Tip: Combine different workflows to improve development efficiency.

# 1. Use feature development workflow to plan features
/feat Add user comment functionality

# 2. Use six-stage workflow to implement details
/workflow Implement comment CRUD operations

# 3. Use Git workflow to commit code
/git-commit

# 4. Use BMad workflow for iteration
/bmad-init

10. Output Style Strategy Copy Section

Tip: Choose appropriate output styles for different scenarios.

# View available styles
npx zcf init -s -o all

# Switch style in conversation
# Claude Code: /output-style engineer-professional
# Codex: Configure through system prompt

Style Selection Recommendations:

• engineer-professional - Professional engineer style, suitable for formal projects
• nekomata-engineer - Nekomata engineer style, suitable for relaxed atmosphere
• laowang-engineer - Laowang engineer style, suitable for Chinese environment
• ojousama-engineer - Ojousama engineer style, suitable for specific scenarios

11. MCP Service Optimization Copy Section

Tip: Select MCP services based on project needs, avoid installing unnecessary services.

# Only install necessary services
npx zcf init -s -m context7,open-websearch

# View all available services
npx zcf
# Select 4 (Configure MCP), view list

Service Selection Recommendations:

• Document Query: context7 - Query library documentation
• Web Search: open-websearch - Multi-engine search
• Requirements Analysis: spec-workflow - Structured requirements
• Code Search: serena - Semantic code search
• Browser Operations: Playwright - Automated testing

12. Backup Strategy Copy Section

Tip: Properly use backup functionality to ensure configuration security.

# Automatic backup (automatically executed during init and update)
npx zcf init  # Automatic backup

# Manual backup of specific configuration
cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d)

# Regularly clean old backups (keep last 7 days)
find ~/.claude/backup -name "*.bak" -mtime +7 -delete

13. Quick Recovery from Failures Copy Section

Tip: Quickly recover configuration when encountering problems.

# 1. Find recent backup
ls -lt ~/.claude/backup/ | head -5

# 2. Restore backup
cp -r ~/.claude/backup/backup_2025-01-15_10-30-45/* ~/.claude/

# 3. Or reinitialize (will create new backup)
npx zcf init --config-action backup

14. Version Control Integration Copy Section

Tip: Include configuration in version control, but exclude sensitive information.

# Create .gitignore
cat > ~/.zcf-configs/.gitignore << EOF
# Exclude sensitive information
*.key
auth.json
settings.json
config.toml

# Include templates and workflows
!templates/
!workflows/
!prompts/
EOF

# Commit configuration
git add .gitignore templates/ workflows/
git commit -m "Add ZCF templates and workflows"

15. Performance Optimization Copy Section

Tip: Optimize configuration to improve response speed.

# 1. Only install needed MCP services
npx zcf init -s -m context7,open-websearch  # Only install necessary services

# 2. Use local cache (if supported)
# Some MCP services support local cache, can speed up response

# 3. Regularly clean backups
npx zcf uninstall --mode custom --items backups

Team Collaboration Tips Copy Chapter

16. Unified Team Configuration Copy Section

Tip: Unify configuration standards within team.

# Create team configuration template
cat > team-config.json << EOF
{
  "provider": "302ai",
  "lang": "zh-CN",
  "mcpServices": ["context7", "open-websearch", "spec-workflow"],
  "workflows": ["sixStepsWorkflow", "gitWorkflow", "featPlanUx"],
  "outputStyle": "engineer-professional"
}
EOF

# Team members use same configuration
npx zcf init -s --api-configs-file team-config.json -k "Personal API Key"

17. Document Sharing Copy Section

Tip: Share workflow templates and configuration templates.

# Export workflow templates
tar -czf team-workflows.tar.gz ~/.claude/skills/

# Team members import
tar -xzf team-workflows.tar.gz -C ~/.claude/

18. Code Review Integration Copy Section

Tip: Integrate ZCF workflows into code review process.

# Use workflow-generated content in PR description
/feat New feature name

# Generated documents can be directly used for PR description

Troubleshooting Tips Copy Chapter

19. Quick Diagnosis Copy Section

Tip: Use built-in commands to quickly diagnose problems.

# Check configuration
cat ~/.claude/settings.json | jq .

# Check MCP services
cat ~/.claude/settings.json | jq .mcpServers

# Check workflows
ls -la ~/.claude/skills/

# Check version
npx zcf check-updates

20. Log Analysis Copy Section

Tip: View ZCF execution logs to locate problems.

# Enable verbose output
npx zcf init --verbose 2>&1 | tee zcf.log

# View logs
cat zcf.log | grep -i error

Related Resources Copy Chapter

• CLI Commands - Detailed descriptions of all commands
• Configuration Management - Multi-configuration and backup system
• Troubleshooting - Common problem solutions
• Worktree Parallel Development - Git Worktree usage tips

💡 Tip: These tips can be flexibly combined according to actual needs. It's recommended to start with basic tips and gradually master advanced tips.