docs: enhance documentation with examples and fix package names

- Fix incorrect package names (@ccw/cli, @anthropic/claude-code-workflow) to claude-code-workflow
- Add workflow examples page with 8 practical artifact samples
- Optimize sidebar navigation with emoji icons and second-level grouping
- Add usage examples to commands and skills documentation
- Update qa/issues.md with current status
- Sync Chinese documentation changes
This commit is contained in:
catlog22
2026-02-28 17:20:37 +08:00
parent 84610661ca
commit 5e35da32e8
8 changed files with 633 additions and 8 deletions

View File

@@ -207,6 +207,7 @@ export default defineConfig({
items: [
{ text: 'Overview', link: '/workflows/' },
{ text: '4-Level System', link: '/workflows/4-level' },
{ text: 'Examples', link: '/workflows/examples' },
{ text: 'Best Practices', link: '/workflows/best-practices' },
{ text: 'Teams', link: '/workflows/teams' }
]

View File

@@ -5,6 +5,7 @@ import DarkModeToggle from './components/DarkModeToggle.vue'
import CopyCodeButton from './components/CopyCodeButton.vue'
import Breadcrumb from './components/Breadcrumb.vue'
import PageToc from './components/PageToc.vue'
import ProfessionalHome from './components/ProfessionalHome.vue'
import Layout from './layouts/Layout.vue'
import './styles/variables.css'
import './styles/custom.css'
@@ -21,5 +22,6 @@ export default {
app.component('CopyCodeButton', CopyCodeButton)
app.component('Breadcrumb', Breadcrumb)
app.component('PageToc', PageToc)
app.component('ProfessionalHome', ProfessionalHome)
}
}

View File

@@ -111,6 +111,110 @@ Most commands support the `--yes` or `-y` flag to enable auto mode and skip conf
/ccw "implement user authentication" --yes
```
## Usage Examples
### Quick Analysis
```bash
# Analyze codebase structure
/ccw "Analyze the authentication module architecture"
# Quick bug diagnosis
/ccw "Diagnose why the login timeout issue occurs"
```
### Planning & Implementation
```bash
# Create implementation plan
/workflow:plan "Add OAuth2 authentication with Google and GitHub providers"
# Execute with auto mode
/workflow:execute --yes
```
### Code Review
```bash
# Review current changes
/cli:codex-review
# Focus on specific area
/cli:codex-review "Focus on security vulnerabilities in auth module"
```
### Session Management
```bash
# List all sessions
/workflow:session:list
# Resume a paused session
/workflow:session:resume "WFS-001"
# Mark session as complete
/workflow:session:complete "WFS-001"
```
### Issue Workflow
```bash
# Discover issues from codebase
/issue:discover
# Create plan for specific issue
/issue:plan "ISSUE-001"
# Execute the fix
/issue:execute --commit
```
### Memory Management
```bash
# Capture current session learnings
/memory:capture "Key insights from authentication refactoring"
# List all memories
/memory:list
# Search memories
/memory:search "authentication patterns"
```
### CLI Tool Invocation
```bash
# Initialize CLI configuration
/cli:cli-init
# Run Gemini analysis
ccw cli -p "Analyze code patterns in src/auth" --tool gemini --mode analysis
# Run with specific rule template
ccw cli -p "Review code quality" --tool gemini --mode analysis --rule analysis-review-code-quality
```
### UI Design Workflow
```bash
# Extract styles from reference image
/workflow:ui-design:style-extract --input "path/to/reference.png"
# Generate prototype
/workflow:ui-design:generate --layout "dashboard" --tokens "design-tokens.json"
```
## Tips
1. **Use Auto Mode Sparingly**: Only use `--yes` or `-y` for routine tasks. Keep manual confirmation for complex decisions.
2. **Session Persistence**: Always complete sessions with `/workflow:session:complete` to preserve learnings.
3. **Memory Capture**: Regularly capture important insights with `/memory:capture` to build project knowledge.
4. **CLI Tool Selection**: Let `/ccw` auto-select the appropriate tool, or explicitly specify with `--tool gemini|qwen|codex`.
## Related Documentation
- [Skills Reference](../skills/)

View File

@@ -144,3 +144,48 @@ echo 'set -gx PATH (npm config get prefix)/bin $PATH' >> ~/.config/fish/config.f
::: info Next Steps
After installation, check out the [First Workflow](./first-workflow.md) guide.
:::
## Quick Start Example
After installation, try these commands to verify everything works:
```bash
# 1. Initialize in your project
cd your-project
ccw init
# 2. Try a simple analysis
ccw cli -p "Analyze the project structure" --tool gemini --mode analysis
# 3. Run the main orchestrator
/ccw "Summarize the codebase architecture"
# 4. Check available commands
ccw --help
```
### Expected Output
```
$ ccw --version
CCW v7.0.5
$ ccw init
✔ Created .claude/CLAUDE.md
✔ Created .ccw/workflows/
✔ Configuration complete
$ ccw cli -p "Analyze project" --tool gemini --mode analysis
Analyzing with Gemini...
✔ Analysis complete
```
### Common First-Time Issues
| Issue | Solution |
|-------|----------|
| `ccw: command not found` | Add npm global bin to PATH, or reinstall |
| `Permission denied` | Use `sudo` or fix npm permissions |
| `API key not found` | Configure API keys in `~/.claude/cli-tools.json` |
| `Node version mismatch` | Update to Node.js >= 18.0.0 |

View File

@@ -4,8 +4,4 @@ title: CCW Documentation
titleTemplate: Claude Code Workspace
---
<script setup>
import ProfessionalHome from './.vitepress/theme/components/ProfessionalHome.vue'
</script>
<ProfessionalHome lang="en" />

View File

@@ -165,6 +165,96 @@ Skill(skill="my-custom-skill", args="input")
4. **Compact Recovery**: Use TodoWrite for progress tracking
5. **Documentation**: Include usage examples and expected outputs
## Practical Examples
### Example 1: Feature Development
**Scenario**: Implement a new user dashboard feature
```bash
# Step 1: Brainstorm the feature
ccw brainstorm
# Follow prompts to define:
# - Dashboard widgets (stats, charts, recent activity)
# - Layout preferences
# - Data refresh intervals
# Step 2: Plan implementation
ccw workflow:plan "Build user dashboard with configurable widgets"
# Outputs: IMPL-001.json with task breakdown
# Step 3: Execute with team
ccw team lifecycle
# Or use quick iteration:
ccw workflow:lite-plan && ccw workflow:execute
# Step 4: Review and refine
ccw review-code
# Fix any issues found
```
### Example 2: Bug Investigation
**Scenario**: Debug performance issue in API endpoint
```bash
# Step 1: Quick analysis
ccw cli -p "Analyze /api/users endpoint for N+1 query issues" --tool gemini --mode analysis
# Step 2: Deep dive if needed
ccw workflow:debug-with-file
# Creates hypothesis, instruments code, analyzes logs
# Step 3: Apply fix
ccw workflow:execute --task "Fix N+1 query in user endpoint"
```
### Example 3: Code Migration
**Scenario**: Migrate from JavaScript to TypeScript
```bash
# Step 1: Analyze codebase
ccw workflow:refactor-cycle
# Identifies tech debt and creates migration plan
# Step 2: Execute migration in phases
ccw team roadmap-dev --epic "ts-migration"
# Progressively migrates modules with tests
```
### Example 4: Documentation Generation
**Scenario**: Generate API documentation
```bash
# Step 1: Capture existing patterns
ccw memory:capture "API patterns: REST, versioning, error handling"
# Step 2: Generate docs
ccw software-manual --output ./docs/api/
```
### Example 5: Code Review Pipeline
**Scenario**: Review PR changes
```bash
# Comprehensive review
ccw review-code --focus security,performance
# Or use cycle for auto-fix
ccw review-cycle --max-iterations 3
```
### Tips for Best Results
1. **Start Small**: Begin with `workflow:lite-plan` for simple tasks
2. **Use Memory**: Capture insights with `memory:capture` for future reference
3. **Verify Plans**: Always review generated plans before execution
4. **Iterate**: Use `review-cycle` for continuous improvement
5. **Check Sessions**: Use `workflow:session:list` to track progress
## Design Patterns
Skills use these proven patterns:

391
docs/workflows/examples.md Normal file
View File

@@ -0,0 +1,391 @@
# Workflow Examples
This page provides practical examples of CCW workflow artifacts with sensitive information redacted.
## Example 1: Lite Plan Output
### plan.json
This is an output from `workflow:lite-plan` command.
```json
{
"title": "Add user authentication with OAuth2",
"description": "Implement OAuth2 authentication with GitHub provider",
"entryPoint": "/api/auth/oauth2/callback",
"outputPath": "src/auth/oauth2/callback.ts",
"tasks": [
{
"id": "TASK-001",
"title": "Define OAuth2 types",
"description": "Create TypeScript interfaces",
"type": "new file",
"file_path": "src/types/oauth2.ts",
"priority": 1,
"dependencies": []
},
{
"id": "TASK-002",
"title": "Implement GitHub provider",
"description": "Implement GitHubProvider class",
"type": "new file",
"file_path": "src/providers/github.ts",
"priority": 2,
"dependencies": ["TASK-001"]
},
{
"id": "TASK-003",
"title": "Create auth routes",
"description": "Set up Express routes",
"type": "new file",
"file_path": "src/routes/auth.ts",
"priority": 3,
"dependencies": ["TASK-001", "TASK-002"]
}
],
"generatedAt": "2026-02-28T10:30:00",
"version": "1.0.0"
}
```
### Execution Steps
```bash
# Execute the plan
ccw workflow:execute --session WFS-001
```
---
## Example 2: Team Session Output
### team-session.json
This is an output from `team-coordinate` with a team of specialists.
```json
{
"session_id": "TLS-frontend-team-2026-02-27",
"team_name": "creative-spark",
"mode": "full-lifecycle-fe",
"scope": "Build React dashboard with real-time visualization",
"requirements": {
"location": "~/projects/dashboard",
"features": [
"Responsive grid layout",
"Interactive charts with D3.js",
"Real-time data via WebSocket",
"Dark mode support",
"Accessibility compliance"
]
},
"status": "completed",
"created_at": "2026-02-27",
"completed_at": "2026-02-28",
"tasks_total": 12,
"tasks_completed": 12,
"members": [
{
"name": "architect",
"type": "team-worker",
"role_spec": ".claude/skills/team-lifecycle-v5/role-specs/architect.md"
},
{
"name": "frontend-dev",
"type": "team-worker",
"role_spec": ".claude/skills/team-lifecycle-v5/role-specs/frontend-dev.md"
},
{
"name": "backend-dev",
"type": "team-worker",
"role_spec": ".claude/skills/team-lifecycle-v5/role-specs/backend-dev.md"
},
{
"name": "qa-engineer",
"type": "team-worker",
"role_spec": ".claude/skills/team-lifecycle-v5/role-specs/qa.md"
}
],
"deliverables": [
{
"type": "code",
"path": "~/projects/dashboard/src/",
"description": "Complete dashboard implementation"
},
{
"type": "documentation",
"path": "~/projects/dashboard/README.md",
"description": "Setup and usage guide"
}
]
}
```
---
## Example 3: Memory Capture Output
### memory.json
This is an output from `memory:capture` command.
```json
{
"id": "CMEM-20260228-001",
"type": "core_memory",
"source_type": "workflow",
"source_id": "WFS-dashboard-001",
"content": "Dashboard Implementation Insights",
"key_learnings": [
{
"topic": "WebSocket Integration",
"challenge": "Connection drops during high traffic",
"solution": "Implemented exponential backoff with reconnection",
"benefit": "99.9% uptime achieved"
},
{
"topic": "D3.js Performance",
"challenge": "5000+ data points caused lag",
"solution": "Switched to SVG rendering with virtual scrolling",
"benefit": "60% performance improvement"
}
],
"code_pattern": "useWebSocket hook for real-time data"
}
```
---
## Example 4: CLI Analysis Output
### analysis-result.json
This is an output from `ccw cli` with `--tool gemini`.
```json
{
"summary": "Code quality analysis for authentication module",
"tool": "gemini",
"timestamp": "2026-02-27T14:30:00",
"findings": [
{
"severity": "high",
"category": "security",
"title": "Missing CSRF token validation",
"file": "src/routes/auth.ts",
"line": 45,
"description": "OAuth2 callback missing CSRF token validation",
"recommendation": "Add CSRF token validation in validateCSRFToken method"
},
{
"severity": "medium",
"category": "performance",
"title": "Inefficient user profile query",
"file": "src/models/user.ts",
"line": 78,
"description": "Query fetches all fields including unused ones",
"recommendation": "Select only necessary fields"
},
{
"severity": "low",
"category": "style",
"title": "Inconsistent error handling",
"file": "src/providers/github.ts",
"line": 89,
"description": "Error messages vary in format",
"recommendation": "Standardize error codes"
}
],
"recommendations": [
"Immediate: Add CSRF token validation",
"Short-term: Optimize database queries",
"Optional: Standardize error handling"
]
}
```
---
## Example 5: Issue Solution Output
### issue-solution.json
This is an output from `issue:execute` command.
```json
{
"issue_id": "ISSUE-001",
"title": "Memory leak in WebSocket connection handler",
"status": "resolved",
"priority": "high",
"created_at": "2026-02-26",
"resolved_at": "2026-02-26",
"resolution": "Fixed by adding proper cleanup in onClose handler",
"affected_files": ["src/services/websocket.ts"],
"root_cause": "Event listeners not removed when connections close",
"fix_steps": [
{
"step": 1,
"description": "Add cleanup logic to onClose handler",
"changes": [
"Add connection.removeListener call",
"Add connection.on close handler",
"Add cleanup interval in constructor"
]
},
{
"step": 2,
"description": "Add unit test for cleanup logic",
"changes": ["Add test case for event listener removal"]
},
{
"step": 3,
"description": "Update documentation",
"changes": ["Add note about proper connection cleanup"]
}
],
"verifications": [
{
"type": "unit_test",
"status": "passed",
"details": "All listeners properly removed on close"
},
{
"type": "integration_test",
"status": "passed",
"details": "No memory leaks after 1000 connections"
}
]
}
```
---
## Example 6: Code Review Output
### review-report.md
This is an output from `review-code` skill.
```markdown
## Code Review Report
### Summary
- **Review Type**: 6-Dimensional code review
- **Scope**: All files changed in PR #42
- **Timestamp**: 2026-02-28
### 1. Correctness
| Aspect | Score | Issues |
|--------|-------|--------|
| Logic correctness | 9/10 | No issues |
| Edge case handling | 8/10 | 1 issue |
### 2. Security
| Aspect | Score | Issues |
|--------|-------|--------|
| Input validation | 10/10 | No issues |
| XSS prevention | 10/10 | No issues |
| CSRF protection | 10/10 | No issues |
### 3. Performance
| Aspect | Score | Issues |
|--------|-------|--------|
| Bundle size | 7/10 | 1 issue |
| Database queries | 6/10 | 2 issues |
### Overall Score: 8.4/10
### Recommendations
1. **Performance**: Review bundle size
2. **Performance**: Optimize database queries
3. **Maintainability**: Add JSDoc comments
```
---
## Example 7: Spec Document Output
### spec-section.md
This is an output from `spec-generator` skill.
```markdown
## API: User Authentication
### Endpoint: POST /api/auth/login
- **Description**: Authenticate user with email and password
- **Request**: { "email": "string", "password": "string" }
- **Response**: { "success": true, "token": "jwt_token", "user": {...} }
### Endpoint: POST /api/auth/oauth2/callback
- **Description**: Handle OAuth2 provider callback
- **Request**: { "code": "string", "provider": "string", "state": "string" }
- **Response**: { "success": true, "token": "jwt_token", "user": {...} }
### Endpoint: POST /api/auth/logout
- **Description**: Logout user and invalidate token
- **Headers**: Authorization: Bearer token
- **Response**: { "success": true, "message": "Logged out" }
### Error Codes
| Code | Description |
|------|-------------|
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 429 | Rate Limited |
| 500 | Server Error |
```
---
## Example 8: Skill Definition Output
### skill-definition.yaml
This is a skill file for creating new custom skills.
```yaml
name: api-documentation-generator
description: Generate API documentation from code annotations
version: 1.0.0
triggers:
- generate api docs
- create documentation
- document api
phases:
- name: Analyze Code
description: Scan codebase for API endpoints
tools:
- glob
- read_file
- grep
- name: Generate Documentation
description: Create markdown files
tools:
- write_file
- name: Review Output
description: Validate documentation
tools:
- read_file
- edit_file
output:
format: markdown
template: docs/api-template.md
examples:
- input: "Generate docs for /api/auth endpoints"
output: "Created auth-api.md with 5 endpoints"
```
---
## Using These Examples
To use these examples in your own projects:
1. **Copy the structure** that matches your needs
2. **Modify fields** to fit your requirements
3. **Remove sensitive information**
4. **Test the output** with `ccw workflow:execute`
::: tip
These examples are generated by CCW workflow tools. Run relevant commands to generate similar outputs for your projects.
:::

View File

@@ -4,8 +4,4 @@ title: CCW 文档
titleTemplate: Claude Code Workspace
---
<script setup>
import ProfessionalHome from '../.vitepress/theme/components/ProfessionalHome.vue'
</script>
<ProfessionalHome lang="zh" />