mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-09 02:24:11 +08:00
29dfd49c90
- Added validation for --style-variants in generate command to ensure it matches actual style directories, preventing errors during prototype generation. - Updated ui-instantiate-prototypes.sh script to validate style variants against existing directories, providing warnings and auto-correcting when necessary. - Improved clarity in generate.md documentation regarding parameters, default values, and auto-detection mechanisms. - Created a comprehensive UI Design Workflow Parameter Clarity Report to address inconsistencies in parameter naming and documentation across extract, consolidate, and generate commands. - Unified parameter naming conventions to reduce confusion and improve user experience. - Enhanced user guidance with a new README.md for the UI Design Workflow, outlining best practices and common mistakes.
426 lines
12 KiB
Markdown
426 lines
12 KiB
Markdown
# UI设计工作流参数清晰度分析报告
|
||
|
||
## 📋 执行摘要
|
||
|
||
**问题来源**：用户手动调用 `/workflow:ui-design:generate` 时传入了 `--style-variants 4`，但实际只有3个样式目录存在，导致生成了引用不存在CSS文件的 `style-4` 原型。
|
||
|
||
**根本原因**：工作流命令链中参数命名不一致、验证缺失、文档说明不清晰。
|
||
|
||
## 🔍 关键发现
|
||
|
||
### 1. 参数命名不一致
|
||
|
||
| 命令 | 参数名称 | 默认值 | 说明 |
|
||
|------|---------|--------|------|
|
||
| `extract` | `--variants` | 1 | ⚠️ 未在文档中明确说明默认值 |
|
||
| `consolidate` | `--variants` | 所有变体 | ⚠️ 与extract同名但语义不同 |
|
||
| `generate` | `--style-variants` | 3 | ⚠️ 名称不一致，默认值说明不清晰 |
|
||
|
||
**问题**：
|
||
- `extract` 和 `consolidate` 使用 `--variants`，但 `generate` 使用 `--style-variants`
|
||
- `--variants` 在两个命令中含义不同：
|
||
- `extract`：生成多少个变体
|
||
- `consolidate`：处理多少个变体
|
||
|
||
### 2. 命名转换混淆
|
||
|
||
```
|
||
extract 输出 → consolidate 处理 → generate 使用
|
||
variant-1 → style-1/ → login-style-1-layout-1.html
|
||
variant-2 → style-2/ → login-style-2-layout-1.html
|
||
variant-3 → style-3/ → login-style-3-layout-1.html
|
||
```
|
||
|
||
**问题**：
|
||
- `variant-N` 到 `style-N` 的转换没有文档说明
|
||
- 增加了用户的认知负担
|
||
- 容易造成混淆和错误
|
||
|
||
### 3. 验证缺失
|
||
|
||
#### ❌ 当前状态（generate.md 第79-82行）
|
||
|
||
```bash
|
||
# Phase 1: Path Resolution & Context Loading
|
||
style_variants = --style-variants OR 3 # Default to 3
|
||
VALIDATE: 1 <= style_variants <= 5
|
||
```
|
||
|
||
**问题**：
|
||
- ✅ 验证范围（1-5）
|
||
- ❌ 不验证是否匹配实际目录数量
|
||
- ❌ 允许传入 `4` 但实际只有 `3` 个目录
|
||
|
||
#### ✅ 应有的验证
|
||
|
||
```bash
|
||
style_variants = --style-variants OR 3
|
||
actual_styles = count_directories({base_path}/style-consolidation/style-*)
|
||
|
||
IF style_variants > actual_styles:
|
||
WARN: "Requested {style_variants} styles, but only {actual_styles} exist"
|
||
REPORT: "Auto-correcting to {actual_styles} style variants"
|
||
style_variants = actual_styles
|
||
|
||
VALIDATE: 1 <= style_variants <= actual_styles
|
||
```
|
||
|
||
### 4. 文档清晰度问题
|
||
|
||
#### extract.md
|
||
|
||
**问题点**：
|
||
- ⚠️ 默认值 `1` 未在 `usage` 或 `argument-hint` 中说明
|
||
- ⚠️ 输出的 `variant-N` 命名未解释后续转换为 `style-N`
|
||
|
||
**当前文档**（第580行附近）：
|
||
```
|
||
"id": "variant-2" # 缺少说明这会成为 style-2 目录
|
||
```
|
||
|
||
#### consolidate.md
|
||
|
||
**问题点**：
|
||
- ⚠️ `--variants` 与 `extract` 同名但语义不同
|
||
- ⚠️ 默认行为（处理所有变体）不够突出
|
||
- ⚠️ `variant-N` → `style-N` 转换未文档化
|
||
|
||
#### generate.md
|
||
|
||
**问题点**：
|
||
- ⚠️ `--style-variants` 名称与前置命令不一致
|
||
- ⚠️ 默认值 `3` 的来源和意义不清晰
|
||
- ⚠️ 自动检测机制未说明
|
||
- ❌ 手动覆盖无验证
|
||
|
||
**当前文档**（第79-82行）：
|
||
```bash
|
||
style_variants = --style-variants OR 3 # Default to 3
|
||
VALIDATE: 1 <= style_variants <= 5
|
||
```
|
||
|
||
## 💡 改进方案
|
||
|
||
### 方案1：代码层面改进（推荐）
|
||
|
||
#### 1.1 统一参数命名
|
||
|
||
```diff
|
||
# extract.md
|
||
- usage: /workflow:ui-design:extract [--variants <count>]
|
||
+ usage: /workflow:ui-design:extract [--style-variants <count>]
|
||
|
||
# consolidate.md
|
||
- usage: /workflow:ui-design:consolidate [--variants <count>]
|
||
+ usage: /workflow:ui-design:consolidate [--style-variants <count>]
|
||
|
||
# generate.md (保持不变)
|
||
usage: /workflow:ui-design:generate [--style-variants <count>]
|
||
```
|
||
|
||
**优点**：
|
||
- ✅ 全链路参数名称统一
|
||
- ✅ 语义清晰（style-variants）
|
||
- ✅ 降低混淆风险
|
||
|
||
#### 1.2 添加验证逻辑（关键）
|
||
|
||
##### generate.md 改进
|
||
|
||
```bash
|
||
# Phase 1: Path Resolution & Context Loading
|
||
style_variants = --style-variants OR 3 # Default to 3
|
||
|
||
# 🆕 添加验证逻辑
|
||
actual_styles = count_directories({base_path}/style-consolidation/style-*)
|
||
|
||
IF actual_styles == 0:
|
||
ERROR: "No style directories found in {base_path}/style-consolidation/"
|
||
SUGGEST: "Run /workflow:ui-design:consolidate first"
|
||
EXIT 1
|
||
|
||
IF style_variants > actual_styles:
|
||
WARN: "⚠️ Requested {style_variants} style variants, but only {actual_styles} directories exist"
|
||
REPORT: " Auto-correcting to {actual_styles} style variants"
|
||
REPORT: " Available styles: {list_directories(style-consolidation/style-*)}"
|
||
style_variants = actual_styles
|
||
|
||
VALIDATE: 1 <= style_variants <= actual_styles
|
||
```
|
||
|
||
##### ui-instantiate-prototypes.sh 改进
|
||
|
||
在脚本第239行之后添加：
|
||
|
||
```bash
|
||
# Validate STYLE_VARIANTS matches actual directories
|
||
if [ "$STYLE_VARIANTS" -gt 0 ]; then
|
||
actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" 2>/dev/null | wc -l)
|
||
|
||
if [ "$actual_styles" -eq 0 ]; then
|
||
log_error "No style directories found in style-consolidation/"
|
||
log_info "Run /workflow:ui-design:consolidate first"
|
||
exit 1
|
||
fi
|
||
|
||
if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
|
||
log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
|
||
log_info "Auto-correcting to $actual_styles style variants"
|
||
STYLE_VARIANTS=$actual_styles
|
||
fi
|
||
fi
|
||
```
|
||
|
||
#### 1.3 统一命名约定
|
||
|
||
##### extract.md 改进
|
||
|
||
修改输出格式（第580行附近）：
|
||
|
||
```diff
|
||
# style-cards.json 格式
|
||
{
|
||
"style_cards": [
|
||
{
|
||
- "id": "variant-1",
|
||
+ "id": "style-1",
|
||
"name": "Modern Minimalist",
|
||
...
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 方案2：文档层面改进
|
||
|
||
#### 2.1 extract.md 文档改进
|
||
|
||
```markdown
|
||
## Parameters
|
||
|
||
- `--style-variants <count>`: Number of style variants to extract. **Default: 1**
|
||
- Range: 1-5
|
||
- Each variant will become an independent design system (style-1, style-2, etc.)
|
||
- Output IDs use `style-N` format for consistency across the workflow
|
||
|
||
## Output Format
|
||
|
||
style-cards.json uses `style-N` IDs that directly correspond to directory names
|
||
created by the consolidate command:
|
||
|
||
- `style-1` → `style-consolidation/style-1/`
|
||
- `style-2` → `style-consolidation/style-2/`
|
||
```
|
||
|
||
#### 2.2 consolidate.md 文档改进
|
||
|
||
```markdown
|
||
## Parameters
|
||
|
||
- `--style-variants <count>`: Number of style variants to process from style-cards.json.
|
||
**Default: all available variants**
|
||
- Processes the first N variants from the style-cards array
|
||
- Creates separate `style-{n}` directories for each variant
|
||
- Range: 1 to count available in style-cards.json
|
||
|
||
## Naming Convention
|
||
|
||
Variants from extraction are materialized into style directories:
|
||
- Input: `style-cards.json` with `style-1`, `style-2`, `style-3`
|
||
- Output: `style-consolidation/style-1/`, `style-2/`, `style-3/` directories
|
||
```
|
||
|
||
#### 2.3 generate.md 文档改进
|
||
|
||
```markdown
|
||
## Parameters
|
||
|
||
- `--style-variants <count>`: Number of style variants to generate prototypes for.
|
||
**Default: 3** (can be overridden)
|
||
- Range: 1-5
|
||
- ⚠️ **IMPORTANT**: This value MUST match the number of style-* directories in style-consolidation/
|
||
- If mismatched, the command will auto-correct to the actual directory count
|
||
- Use auto-detection (omit parameter) for safety
|
||
|
||
## Auto-Detection vs Manual Override
|
||
|
||
The command uses intelligent auto-detection:
|
||
|
||
1. **Auto-Detection** (Recommended):
|
||
```bash
|
||
/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
|
||
# Automatically counts style-1/, style-2/, style-3/ → uses 3
|
||
```
|
||
|
||
2. **Manual Override** (Use with caution):
|
||
```bash
|
||
/workflow:ui-design:generate --style-variants 4
|
||
# If only 3 styles exist, auto-corrects to 3 with warning
|
||
```
|
||
|
||
3. **Safety Check**:
|
||
- Command validates against actual `style-consolidation/style-*` directories
|
||
- Prevents generation of prototypes referencing non-existent styles
|
||
- Displays warning and auto-corrects if mismatch detected
|
||
```
|
||
|
||
### 方案3：用户指南改进
|
||
|
||
创建 `.claude/commands/workflow/ui-design/README.md`：
|
||
|
||
```markdown
|
||
# UI Design Workflow Parameter Guide
|
||
|
||
## Style Variant Count Flow
|
||
|
||
### 1. Extract Phase
|
||
```bash
|
||
/workflow:ui-design:extract --style-variants 3
|
||
# Generates: style-cards.json with 3 style variants (style-1, style-2, style-3)
|
||
```
|
||
|
||
### 2. Consolidate Phase
|
||
```bash
|
||
/workflow:ui-design:consolidate --style-variants 3
|
||
# Creates: style-consolidation/style-1/, style-2/, style-3/
|
||
```
|
||
|
||
### 3. Generate Phase
|
||
```bash
|
||
# ✅ Recommended: Let it auto-detect
|
||
/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
|
||
|
||
# ⚠️ Manual: Must match consolidation output
|
||
/workflow:ui-design:generate --style-variants 3
|
||
```
|
||
|
||
## ⚠️ Common Mistakes
|
||
|
||
### Mistake 1: Mismatched Counts
|
||
```bash
|
||
# ❌ Wrong: Request 4 styles when only 3 exist
|
||
/workflow:ui-design:generate --style-variants 4
|
||
# Only 3 directories in style-consolidation/ → ERROR
|
||
|
||
# ✅ Correct: Omit parameter for auto-detection
|
||
/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
|
||
```
|
||
|
||
### Mistake 2: Naming Confusion
|
||
```bash
|
||
# ❌ Don't confuse variant-N with style-N
|
||
# variant-N was old naming in style-cards.json
|
||
# style-N is the current standard across all commands
|
||
```
|
||
|
||
## 🎯 Best Practices
|
||
|
||
1. **Use auto-detection**: Omit `--style-variants` in generate command
|
||
2. **Verify consolidation**: Check `consolidation-report.json` before generating
|
||
3. **Use explore-auto**: Automated workflow prevents parameter mismatches
|
||
4. **Check directories**: `ls .workflow/.design/run-xxx/style-consolidation/`
|
||
```
|
||
|
||
## 🎯 实施优先级
|
||
|
||
### 🔴 高优先级（立即实施）
|
||
|
||
1. **generate.md 添加验证逻辑**
|
||
- 防止参数不匹配问题再次发生
|
||
- 影响范围：所有手动调用 generate 命令的场景
|
||
|
||
2. **ui-instantiate-prototypes.sh 添加验证**
|
||
- 脚本层面的最后防线
|
||
- 影响范围：所有原型生成操作
|
||
|
||
3. **文档说明默认值和验证机制**
|
||
- 降低用户误用风险
|
||
- 影响范围：所有新用户和手动操作场景
|
||
|
||
### 🟡 中优先级（短期改进）
|
||
|
||
4. **统一参数命名为 --style-variants**
|
||
- 提高一致性，减少混淆
|
||
- 影响范围：需要更新多个命令文件
|
||
|
||
5. **extract.md 统一使用 style-N 命名**
|
||
- 消除命名转换混淆
|
||
- 影响范围：需要更新 style-cards.json 格式
|
||
|
||
### 🟢 低优先级（长期优化）
|
||
|
||
6. **创建用户指南 README.md**
|
||
- 提供完整的参数使用指南
|
||
- 影响范围：文档层面，不影响功能
|
||
|
||
## 📊 改进效果预测
|
||
|
||
### 实施前
|
||
|
||
```
|
||
用户手动调用: /workflow:ui-design:generate --style-variants 4
|
||
实际目录数: 3
|
||
结果: ❌ 生成 login-style-4-layout-1.html 引用不存在的 CSS
|
||
```
|
||
|
||
### 实施后
|
||
|
||
```
|
||
用户手动调用: /workflow:ui-design:generate --style-variants 4
|
||
实际目录数: 3
|
||
|
||
验证检查:
|
||
⚠️ Requested 4 style variants, but only 3 directories exist
|
||
Available: style-1, style-2, style-3
|
||
Auto-correcting to 3 style variants
|
||
|
||
结果: ✅ 生成正确的 style-1, style-2, style-3 原型，避免错误
|
||
```
|
||
|
||
## 🔧 快速修复指南（针对当前问题）
|
||
|
||
### 立即修复生成的错误文件
|
||
|
||
```bash
|
||
cd .workflow/.design/run-20251009-210559/prototypes
|
||
|
||
# 删除错误的 style-4 文件
|
||
rm -f *-style-4-*
|
||
|
||
# 重新生成（使用自动检测）
|
||
~/.claude/scripts/ui-instantiate-prototypes.sh . --session-id run-20251009-210559
|
||
```
|
||
|
||
### 预防未来错误
|
||
|
||
```bash
|
||
# ✅ 推荐：使用自动检测
|
||
/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
|
||
|
||
# ⚠️ 如果必须手动指定，先验证
|
||
jq '.variant_count' .workflow/.design/run-xxx/style-consolidation/consolidation-report.json
|
||
# 输出: 3
|
||
# 然后使用该数字
|
||
/workflow:ui-design:generate --style-variants 3
|
||
```
|
||
|
||
## 📝 总结
|
||
|
||
**核心问题**：
|
||
- 参数命名不统一（`--variants` vs `--style-variants`）
|
||
- 命名转换混淆（`variant-N` → `style-N`）
|
||
- 验证缺失（不检查参数是否匹配实际目录）
|
||
- 文档不清晰（默认值、自动检测机制说明不足）
|
||
|
||
**关键改进**：
|
||
1. ✅ 添加参数验证逻辑（防止不匹配）
|
||
2. ✅ 统一参数命名（提高一致性）
|
||
3. ✅ 完善文档说明（降低误用风险）
|
||
4. ✅ 提供清晰的用户指南
|
||
|
||
**预期效果**：
|
||
- 🔒 杜绝参数不匹配问题
|
||
- 📈 提高工作流鲁棒性
|
||
- 🎓 降低用户学习成本
|
||
- 🚀 提升整体用户体验
|