catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
ca6677149ab883accd4d80a27147b0e56b455e6a
Claude-Code-Workflow/FAQ.md

19 KiB
Raw Blame History

❓ Frequently Asked Questions (FAQ)

This document answers common questions about Claude Code Workflow (CCW).

📋 Table of Contents

🌟 General Questions

What is Claude Code Workflow (CCW)?

CCW is an advanced AI-powered development automation framework for Claude Code. It transforms AI development from simple prompt chaining into a robust, context-first orchestration system with structured planning, deterministic execution, and intelligent multi-model orchestration.

How is CCW different from using Claude Code directly?

Claude Code (Vanilla) Claude Code with CCW
Manual task management Automated workflow orchestration
No context preservation Hierarchical memory system (CLAUDE.md)
Single conversation context Session-based project isolation
Manual planning Automated multi-phase planning
One model/approach Multi-model strategy (Gemini, Qwen, Codex)
No quality gates Built-in verification and review

Do I need external CLI tools (Gemini, Qwen, Codex)?

No, they're optional. CCW can work with Claude Code alone. External CLI tools enhance CCW's capabilities by:

  • Providing specialized analysis (Gemini)
  • Enabling autonomous development (Codex)
  • Supporting architectural planning (Qwen)

But all core workflows function without them.

Is CCW suitable for beginners?

Yes! CCW provides:

  • Simple commands like /workflow:plan and /workflow:execute
  • Interactive command guide (CCW-help)
  • Comprehensive documentation
  • Built-in examples and tutorials

Start with the 5-minute Quick Start to get a feel for it.

What languages/frameworks does CCW support?

CCW is language-agnostic. It works with any programming language or framework that Claude Code supports:

  • JavaScript/TypeScript (Node.js, React, Vue, etc.)
  • Python (Django, Flask, FastAPI, etc.)
  • Java/Kotlin (Spring Boot, etc.)
  • Go, Rust, C++, C#, Ruby, PHP, etc.

Is CCW free?

Yes! CCW is open-source under the MIT License. However, you need:

  • Claude Code subscription (for the base platform)
  • Optional: API keys for external CLI tools (Gemini, Qwen, Codex)

🔧 Installation & Setup

How do I install CCW?

NPM Global Install (Recommended):

npm install -g claude-code-workflow

Verify Installation:

ccw --version
ccw dashboard   # Start Dashboard
ccw view        # Start View interface

See INSTALL.md for detailed instructions.

How do I verify CCW is installed correctly?

Open Claude Code and run:

/workflow:session:list

If the command is recognized, installation succeeded.

Where are CCW files installed?

CCW installs to your home directory:

~/.claude/
├── agents/       # Agent definitions
├── commands/     # Slash commands
├── skills/       # Agent skills
└── workflows/    # Workflow documentation

Can I customize CCW after installation?

Yes! All files in ~/.claude/ can be customized:

  • Modify agent prompts in agents/
  • Add custom commands in commands/
  • Adjust workflow templates in workflows/

How do I update CCW to the latest version?

Update via npm:

npm update -g claude-code-workflow

Note: Custom modifications in ~/.claude/ will be preserved. The npm package only updates core CCW files.

Do I need to install CLI tools?

Optional. To use CLI tools:

  1. Gemini CLI: Follow setup instructions
  2. Qwen CLI: Follow setup instructions
  3. Codex CLI: Follow setup instructions

Then initialize with:

/cli:cli-init

🚀 Usage & Workflows

What's the simplest way to use CCW?

Two-command workflow:

/workflow:plan "Your feature description"
/workflow:execute

That's it! CCW handles planning, task generation, and implementation.

What's the difference between /workflow:plan and /workflow:lite-plan?

/workflow:plan /workflow:lite-plan
Full 5-phase planning Lightweight interactive planning
Creates persistent artifacts In-memory planning
Best for complex projects Best for quick tasks
Includes verification phase Streamlined flow
Suitable for team collaboration Suitable for solo development

Use /workflow:plan for: Complex features, team projects, when you need detailed documentation

Use /workflow:lite-plan for: Quick fixes, small features, rapid prototyping

When should I use brainstorming workflows?

Use /workflow:brainstorm:auto-parallel when you know WHAT to build, but NOT HOW to build it.

Brainstorming scenarios:

  • 🤔 Unclear solution approach - Multiple ways to solve the problem, need expert analysis
  • 🏗️ Architectural exploration - Need to explore different architectural patterns
  • 📋 Requirements clarification - High-level goal is clear, but technical details are not
  • 🔀 Multiple trade-offs - Need to analyze pros/cons of different approaches
  • 🆕 Unfamiliar domain - Building something new without clear implementation path

Skip brainstorming, use /workflow:plan directly when:

  • ✅ Clear implementation approach - You already know how to build it
  • ✅ Similar to existing code - Following established patterns in your codebase
  • ✅ Well-defined requirements - Technical specs are clear from the start
  • ✅ Simple features - Straightforward implementation, no architectural decisions

Workflow comparison:

Know what + Know how Know what, NOT how
/workflow:plan "Add JWT auth" /workflow:brainstorm:auto-parallel "Design auth system" → /workflow:plan
Plan generates tasks directly Brainstorm explores solutions → Plan generates tasks

Example:

# When you DON'T know how to build it
/workflow:brainstorm:auto-parallel "Build real-time collaborative document editing system"
/workflow:plan
/workflow:execute

How do I check the status of my workflow?

/workflow:status

Shows:

  • Current session
  • Task completion status
  • Currently executing task
  • Next steps

Can I run multiple workflows simultaneously?

Yes! CCW supports parallel sessions:

# Session 1: Authentication
/workflow:session:start "User Authentication"
/workflow:plan "JWT-based authentication"

# Session 2: Payment
/workflow:session:start "Payment Integration"
/workflow:plan "Stripe payment integration"

# Execute each session independently
/workflow:execute --session WFS-user-authentication
/workflow:execute --session WFS-payment-integration

How do I resume a paused workflow?

/workflow:session:resume

Automatically detects and resumes the most recent paused session.

💬 Commands & Syntax

Where can I find all available commands?

See COMMAND_REFERENCE.md for a complete list.

Or use the interactive guide:

CCW-help

What's the difference between /cli:* and /workflow:* commands?

/cli:* commands:

  • CLI tool configuration
  • Example: /cli:cli-init (initialize Gemini/Qwen configurations)

/workflow:* commands:

  • Multi-phase orchestration
  • Session-based
  • Complex development workflows
  • Examples: /workflow:plan, /workflow:lite-plan, /workflow:lite-fix

Note

: Most CLI commands have been replaced by semantic invocation. Simply describe your needs in natural language, and Claude will automatically use the appropriate tools.

How do I use command flags?

Most commands support flags for customization:

# Basic usage
/workflow:plan "Feature description"

# With CLI execution flag
/workflow:plan --cli-execute "Feature description"

# With multiple flags
/workflow:ui-design:explore-auto --prompt "Login page" --style-variants 3 --layout-variants 2

Can I use natural language instead of commands?

Yes! Claude understands semantic invocation:

Instead of using specific commands, you can say:

"Use Gemini to analyze the authentication module architecture"

Claude will automatically select and execute the appropriate CLI tools (Gemini/Qwen/Codex) with optimized templates.

What does the -e or --enhance flag do?

The -e flag triggers the prompt-enhancer skill in natural conversation:

User: "Analyze authentication module -e"

Claude will expand and enhance your request for better results.

📦 Sessions & Tasks

What is a workflow session?

A workflow session is an isolated workspace for a specific feature or project. It contains:

  • Task definitions (JSON files)
  • Brainstorming artifacts
  • Generated plans
  • Chat logs
  • Session state

Location: .workflow/active/WFS-<session-name>/

How are sessions created?

Sessions are created automatically when you run:

/workflow:session:start "Feature name"
/workflow:plan "Feature description"
/workflow:brainstorm:auto-parallel "Topic"

How do I list all sessions?

/workflow:session:list

Shows all sessions with their status (active, paused, completed).

What happens when I complete a session?

/workflow:session:complete

CCW will:

  1. Archive session to .workflow/archives/
  2. Remove active flag
  3. Generate lessons learned
  4. Update session manifest

What are tasks in CCW?

Tasks are atomic units of work stored as JSON files in .task/ directory:

.workflow/active/WFS-feature/.task/
├── IMPL-1.json       # Main task
├── IMPL-1.1.json     # Subtask
└── IMPL-2.json       # Another task

Each task contains:

  • Title and description
  • Requirements and acceptance criteria
  • Context and focus paths
  • Implementation approach
  • Status (pending, in_progress, completed)

How deep can task hierarchies go?

Maximum 2 levels:

  • IMPL-1 - Main task
  • IMPL-1.1, IMPL-1.2 - Subtasks
  • No further nesting (no IMPL-1.1.1)

Can I manually edit task JSON files?

Yes, but:

  • ⚠️ JSON files are the source of truth
  • ⚠️ Markdown documents are read-only views
  • ✅ Edit JSON directly for fine-grained control
  • ✅ Validate JSON syntax after editing
  • ✅ Use /workflow:status to regenerate views

🤖 Agents & Tools

What agents are available in CCW?

Agent Purpose
@code-developer Code implementation
@test-fix-agent Test generation and fixing
@ui-design-agent UI design and prototyping
@action-planning-agent Task planning and decomposition
@cli-execution-agent Autonomous CLI task handling
@cli-explore-agent Codebase exploration
@context-search-agent Context gathering
@doc-generator Documentation generation
@memory-bridge Memory system updates

See ARCHITECTURE.md for details.

How do agents get selected for tasks?

Automatic selection based on task type defined in JSON:

{
  "meta": {
    "agent": "code-developer"
  }
}

CCW automatically invokes the appropriate agent during /workflow:execute.

What's the difference between Gemini, Qwen, and Codex?

Tool Strengths Best For
Gemini Deep analysis, pattern recognition Code exploration, architecture analysis
Qwen System design, planning Architectural planning, system design
Codex Autonomous implementation Feature development, bug fixes

CCW auto-selects the best tool for each task, but you can override with --tool flag.

Can I create custom agents?

Yes! Create a new file in .claude/agents/:

# My Custom Agent

## Role
Agent description

## Tools Available
- Tool 1
- Tool 2

## Prompt
Agent instructions...

Then reference it in task JSON:

{
  "meta": {
    "agent": "my-custom-agent"
  }
}

💾 Memory System

What is the CLAUDE.md memory system?

A hierarchical documentation system that maintains project knowledge across 4 layers:

CLAUDE.md (Project root)
└── src/CLAUDE.md (Source layer)
    └── auth/CLAUDE.md (Module layer)
        └── jwt/CLAUDE.md (Component layer)

Each layer provides context at the appropriate abstraction level.

When should I update memory?

Update memory when:

  • After completing a feature
  • After refactoring modules
  • After changing architecture
  • Before starting complex tasks
  • Weekly maintenance

What's the difference between memory update commands?

Command Scope When to Use
/memory:update-full Entire project Major changes, first-time setup, monthly maintenance
/memory:update-related Changed modules only Daily development, after feature completion
/memory:load Task-specific, no files Quick context for immediate task

How long does memory update take?

  • /memory:update-full: 5-20 minutes (depends on project size)
  • /memory:update-related: 1-5 minutes (only changed modules)
  • /memory:load: <1 minute (no file updates)

Do I need to update memory manually?

Recommended but not required. Benefits of regular updates:

  • ✅ Higher quality AI outputs
  • ✅ Accurate pattern recognition
  • ✅ Better context understanding
  • ✅ Reduced hallucinations

Without updates:

  • ⚠️ AI may reference outdated code
  • ⚠️ Incorrect architectural assumptions
  • ⚠️ Lower output quality

Can I exclude files from memory?

Yes! Use ignore files:

  • .geminiignore - For Gemini CLI
  • .qwenignore - For Qwen CLI
  • .gitignore - Automatically respected

Example .geminiignore:

node_modules/
dist/
*.log
*.test.js

🔧 Troubleshooting

"No active session found" error

Cause: No workflow session is currently active.

Solution:

# Option 1: Start new session
/workflow:session:start "Feature name"

# Option 2: Resume existing session
/workflow:session:resume

Command execution fails or hangs

Troubleshooting steps:

  1. Check status:

    /workflow:status

  2. Review logs:

    # Session logs location
.workflow/active/WFS-<session>/.chat/

  3. Simplify task: Break complex requests into smaller tasks

  4. Check CLI tools: Ensure external tools (if used) are properly configured

Task execution produces errors

Common causes:

  1. Outdated memory: Run /memory:update-related
  2. Insufficient context: Add more details to task requirements
  3. Tool misconfiguration: Check CLI tool setup with /cli:cli-init

Memory update fails

Solutions:

  1. Check file permissions: Ensure write access to project
  2. Try different tool: 
    /memory:update-full --tool qwen
  3. Update incrementally: 
    /memory:update-related

Workflow gets stuck in a phase

Steps:

  1. Check current phase:

    /workflow:status

  2. Review session JSON:

    cat .workflow/active/WFS-<session>/workflow-session.json

  3. Manually advance (if needed): Edit session JSON to update phase

  4. Restart session:

    /workflow:session:complete
/workflow:session:start "New attempt"

CLI tools not working

Checklist:

  1. ✅ Tools installed correctly?
  2. ✅ API keys configured?
  3. ✅ .gemini/ or .qwen/ directories exist?
  4. ✅ Configuration files valid?

Re-initialize:

/cli:cli-init --tool gemini

Performance is slow

Optimization tips:

  1. Use incremental updates:

    /memory:update-related  # Instead of update-full

  2. Exclude unnecessary files: Add to .geminiignore or .qwenignore

  3. Break down large tasks: Smaller tasks = faster execution

  4. Use lite workflows:

    /workflow:lite-plan  # Instead of full workflow:plan

🚀 Advanced Topics

How does CCW handle dependencies between tasks?

Tasks can reference dependencies in their JSON:

{
  "id": "IMPL-2",
  "dependencies": ["IMPL-1"],
  "context": {
    "inherited_from": "IMPL-1"
  }
}

CCW ensures dependencies are completed before dependent tasks execute.

Can I integrate CCW with CI/CD pipelines?

Yes! CCW can be used in automated workflows:

  1. Generate tests:

    /workflow:test-gen WFS-feature
/workflow:execute

  2. Run verification:

    /workflow:action-plan-verify

  3. Automated reviews:

    /workflow:review --type security

How do I create custom workflows?

Combine existing commands:

# Custom TDD workflow
/workflow:tdd-plan "Feature"
/workflow:execute
/workflow:tdd-verify
/workflow:review --type quality

Or create custom command in .claude/commands/.

What's the JSON-first architecture?

Principle: JSON files are the single source of truth for all task state.

  • ✅ JSON files contain actual state
  • ❌ Markdown documents are read-only generated views
  • ✅ Edit JSON to change state
  • ❌ Never edit markdown documents

Benefits:

  • No synchronization complexity
  • Programmatic access
  • Clear data model
  • Deterministic state

How does context flow between agents?

Agents share context through:

  1. Session JSON: Shared session state
  2. Task JSON: Task-specific context
  3. CLAUDE.md: Project knowledge base
  4. Flow Control: Pre-analysis and implementation approach

Can I use CCW for non-code projects?

Yes! CCW can manage any structured project:

  • Documentation writing
  • Content creation
  • Data analysis
  • Research projects
  • Process automation

How do I migrate from one CCW version to another?

  1. Backup customizations: Save .claude/ modifications
  2. Run installation: Install new version
  3. Restore customizations: Reapply your changes
  4. Check changelog: Review breaking changes in CHANGELOG.md
  5. Test workflows: Verify existing workflows work

Where can I get more help?

📚 Additional Resources

Last Updated: 2025-11-20 Version: 5.8.1

Didn't find your question? Ask in GitHub Discussions!

Reference in New Issue View Git Blame Copy Permalink