From 2301f263cd8c06f956ecccbc68f8f0a6845e0f3a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 20 Nov 2025 11:53:40 +0000 Subject: [PATCH] docs: cleanup unnecessary root directory documentation Remove 7 unnecessary documentation files from root directory: - COMMAND_DOCS_AUDIT_REPORT.md (temporary audit report) - PLANNING_GAP_ANALYSIS.md (temporary analysis document) - PROJECT_INTRODUCTION.md (duplicate of README) - COMMAND_FLOW_STANDARD.md (internal standard) - COMMAND_TEMPLATE_EXECUTOR.md (internal design) - COMMAND_TEMPLATE_ORCHESTRATOR.md (internal design) - LITE_FIX_DESIGN.md (internal design) Retained essential documentation: - User guides (README, GETTING_STARTED, FAQ, EXAMPLES) - Developer docs (CLAUDE.md, CONTRIBUTING, ARCHITECTURE) - Command references (COMMAND_REFERENCE, COMMAND_SPEC) - Workflow guides (WORKFLOW_DECISION_GUIDE, WORKFLOW_DIAGRAMS) --- COMMAND_DOCS_AUDIT_REPORT.md | 278 -------- COMMAND_FLOW_STANDARD.md | 274 -------- COMMAND_TEMPLATE_EXECUTOR.md | 126 ---- COMMAND_TEMPLATE_ORCHESTRATOR.md | 140 ---- LITE_FIX_DESIGN.md | 620 ------------------ PLANNING_GAP_ANALYSIS.md | 1016 ------------------------------ PROJECT_INTRODUCTION.md | 401 ------------ 7 files changed, 2855 deletions(-) delete mode 100644 COMMAND_DOCS_AUDIT_REPORT.md delete mode 100644 COMMAND_FLOW_STANDARD.md delete mode 100644 COMMAND_TEMPLATE_EXECUTOR.md delete mode 100644 COMMAND_TEMPLATE_ORCHESTRATOR.md delete mode 100644 LITE_FIX_DESIGN.md delete mode 100644 PLANNING_GAP_ANALYSIS.md delete mode 100644 PROJECT_INTRODUCTION.md diff --git a/COMMAND_DOCS_AUDIT_REPORT.md b/COMMAND_DOCS_AUDIT_REPORT.md deleted file mode 100644 index cd2fa633..00000000 --- a/COMMAND_DOCS_AUDIT_REPORT.md +++ /dev/null @@ -1,278 +0,0 @@ -# 命令文档审计报告 - -**审计日期**: 2025-11-20 -**审计范围**: 73个命令文档文件 -**审计方法**: 自动化扫描 + 手动内容分析 - ---- - -## 发现的问题 - -### 1. 包含版本信息的文件 - -#### [CRITICAL] version.md -**文件路径**: `/home/user/Claude-Code-Workflow/.claude/commands/version.md` - -**问题位置**: -- 第1-3行：包含在YAML头中 -- 第96-102行：示例中包含完整版本号和发布日期（如"v3.2.2"、"2025-10-03"） -- 第127-130行：包含开发版本号和日期 -- 第155-172行：版本比较和升级建议 - -**内容摘要**: -``` -Latest Stable: v3.2.2 -Release: v3.2.2: Independent Test-Gen Workflow with Cross-Session Context -Published: 2025-10-03T04:10:08Z - -Latest Dev: a03415b -Message: feat: Add version tracking and upgrade check system -Date: 2025-10-03T04:46:44Z -``` - -**严重程度**: ⚠️ 高 - 文件本质上是版本管理命令，但包含具体版本号、发布日期和完整版本历史 - ---- - -### 2. 包含额外无关内容的文件 - -#### [HIGH] tdd-plan.md -**文件路径**: `/home/user/Claude-Code-Workflow/.claude/commands/workflow/tdd-plan.md` - -**问题位置**: 第420-523行 - -**部分内容**: -```markdown -## TDD Workflow Enhancements - -### Overview -The TDD workflow has been significantly enhanced by integrating best practices -from both traditional `plan --agent` and `test-gen` workflows... - -### Key Improvements - -#### 1. Test Coverage Analysis (Phase 3) -**Adopted from test-gen workflow** - -#### 2. Iterative Green Phase with Test-Fix Cycle -**Adopted from test-gen workflow** - -#### 3. Agent-Driven Planning -**From plan --agent workflow** - -### Workflow Comparison -| Aspect | Previous | Current (Optimized) | -| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) | -| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) | - -### Migration Notes -**Backward Compatibility**: Fully compatible -- Existing TDD workflows continue to work -- New features are additive, not breaking -``` - -**问题分析**: -- 包含"增强"、"改进"、"演进"等版本历史相关内容 -- 包含"工作流比较"部分，对比了"之前"和"现在"的版本 -- 包含"迁移说明"，描述了从旧版本的升级路径 -- 约100行内容（第420-523行）不是关于命令如何使用，而是关于如何改进的 - -**严重程度**: ⚠️ 中-高 - 约18%的文件内容（100/543行）是版本演进相关，而不是核心功能说明 - ---- - -### 3. 任务不够专注的文件 - -#### [MEDIUM] tdd-plan.md (继续) -**问题**: 文件中包含过多关于与其他命令（plan、test-gen）集成的说明 - -**相关部分**: -- 第475-488行：与"plan --agent"工作流的比较 -- 第427-441行：描述从test-gen工作流"采纳"的特性 -- 第466-473行：描述从plan --agent工作流"采纳"的特性 - -**问题分析**: 虽然这些集成说明可能有用，但在命令文档中过度强调其他命令的关系，使文档的焦点分散。建议这类内容应放在项目级文档或架构文档中，而不是在具体命令文档中。 - -**严重程度**: ⚠️ 中 - 降低了文档的焦点，但不是严重问题 - ---- - -## 合规文件统计 - -### 审计结果汇总 - -| 类别 | 计数 | 百分比 | -|------|------|--------| -| **完全合规的文件** | 70 | 95.9% | -| **有版本信息的文件** | 1 | 1.4% | -| **包含额外无关内容的文件** | 1 | 1.4% | -| **任务不够专注的文件** | 1* | 1.4% | -| **总计** | 73 | 100% | - -*注: tdd-plan.md 同时出现在"额外无关内容"和"任务不专注"两个类别中 - -### 问题严重程度分布 - -| 严重程度 | 文件数 | 说明 | -|---------|--------|------| -| CRITICAL | 0 | 没有需要立即阻止执行的问题 | -| HIGH | 1 | version.md - 包含完整版本号和发布信息 | -| MEDIUM | 1 | tdd-plan.md - 包含过度的版本演进说明和工作流对比 | -| LOW | 0 | 无其他问题 | - ---- - -## 详细发现 - -### version.md - 完整分析 - -**问题本质**: version.md命令的存在目的就是管理和报告版本信息。文件中包含版本号、发布日期、更新日志等内容不仅是合理的，而是必需的。 - -**但审计角度**: 根据用户的审计标准： -- ✓ "包含版本号、版本历史、changelog等内容" - **是的，明确包含** - - 示例版本号: v3.2.1, v3.2.2, 3.4.0-dev - - 发布日期: 2025-10-03T12:00:00Z - - 版本历史信息和升级路径 - -**结论**: 该文件符合审计标准中的"版本信息"类别，应被标记为有问题（尽管这是功能需求） - ---- - -### tdd-plan.md - 完整分析 - -**第一个问题 - 额外的版本演进信息**: -``` -## TDD Workflow Enhancements (行420) -### Overview -The TDD workflow has been **significantly enhanced** by integrating best practices -from **both traditional `plan --agent` and `test-gen` workflows** - -### Key Improvements -#### 1. Test Coverage Analysis (Phase 3) -**Adopted from test-gen workflow** (行428) - -#### 2. Iterative Green Phase with Test-Fix Cycle -**Adopted from test-gen workflow** (行443) - -#### 3. Agent-Driven Planning -**From plan --agent workflow** (行467) -``` - -这部分内容完全是关于命令的历史演变和改进，不是关于如何使用该命令。 - -**第二个问题 - 工作流对比表**: -``` -### Workflow Comparison (行475) -| Aspect | Previous | Current (Optimized) | -| **Phases** | 6 | 7 | -| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) | -``` - -直接对比了"之前"和"现在"的实现，这是版本历史相关内容。 - -**第三个问题 - 迁移说明**: -``` -### Migration Notes (行490) -**Backward Compatibility**: Fully compatible -- Existing TDD workflows continue to work -- New features are additive, not breaking -``` - -这是版本升级路径说明，不是命令核心功能文档的一部分。 - -**统计**: -- 总行数: 543行 -- 有问题的行: ~103行（第420-523行） -- 占比: ~19% - -**结论**: tdd-plan.md 同时违反了两个审计标准： -1. 包含版本演进历史相关内容 -2. 过度描述与其他命令的关系（缺乏任务专注度） - ---- - -## 建议 - -### 高优先级 - -1. **移除 version.md 中的具体版本号** - - 当前做法: 包含硬编码的版本号、日期等 - - 建议: 使用变量或运行时获取版本信息，文档中只描述版本命令的功能 - - 理由: 版本号应该由版本控制系统管理，而不是在文档中硬编码 - -2. **从 tdd-plan.md 中移除第420-523行（版本演进部分）** - - 当前: ~103行关于"增强"、"改进"、"迁移"的内容 - - 建议: 移到单独的"CHANGELOG.md"或项目级文档 - - 理由: 这是历史演变信息，不是使用指南 - -### 中优先级 - -3. **重构 tdd-plan.md 中的工作流关系** - - 当前: 第475-495行详细对比与其他命令的区别 - - 建议: 简化对其他命令的引用，保留"Related Commands"部分即可 - - 理由: 过度关注与其他命令的关系分散了文档焦点 - -4. **统一版本信息管理策略** - - 建议: 建立项目级文档规范，明确哪些信息应在命令文档中出现 - - 范围: 适用于所有命令文档 - ---- - -## 合规性评定 - -### 总体评分: 96/100 - -- ✓ **整体质量高**: 95.9%的文件完全合规 -- ⚠️ **两个文件需要整改**: - - version.md: 版本信息管理需要优化 - - tdd-plan.md: 版本演进内容需要分离 - -### 推荐行动 - -| 优先级 | 行动 | 预期影响 | -|--------|------|---------| -| **高** | 清理 version.md 的硬编码版本号 | 提高版本管理的可维护性 | -| **高** | 从 tdd-plan.md 移除第420-523行 | 提高文档专注度，减少19% | -| **中** | 建立版本信息管理规范 | 防止未来重复问题 | -| **低** | 简化 tdd-plan.md 中的工作流关系说明 | 进一步改善文档清晰度 | - ---- - -## 附录 - -### 审计方法论 - -1. **自动扫描**: 使用grep搜索关键词（version, changelog, release, history等） -2. **内容分析**: 手动读取匹配文件的完整内容 -3. **结构分析**: 检查是否包含与核心功能无关的内容 -4. **统计分析**: 计算问题内容占比 - -### 数据来源 - -- 总文件数: 73 -- 详细分析文件: 15 -- 快速扫描文件: 58 - -### 文件列表（完整性检查） - -已审计的所有命令文档: -- ✓ version.md (有问题) -- ✓ enhance-prompt.md -- ✓ test-fix-gen.md -- ✓ test-gen.md -- ✓ test-cycle-execute.md -- ✓ tdd-plan.md (有问题) -- ✓ tdd-verify.md -- ✓ status.md -- ✓ review.md -- ✓ plan.md -- ✓ lite-plan.md -- ✓ lite-execute.md -- ✓ init.md -- ✓ execute.md -- ✓ action-plan-verify.md -- ... 以及其他58个文件 (全部合规) - ---- - -**审计完成** - 生成时间: 2025-11-20 diff --git a/COMMAND_FLOW_STANDARD.md b/COMMAND_FLOW_STANDARD.md deleted file mode 100644 index 648343b6..00000000 --- a/COMMAND_FLOW_STANDARD.md +++ /dev/null @@ -1,274 +0,0 @@ -# Command Flow Expression Standard - -**用途**：规范命令文档中Task、SlashCommand、Skill和Bash调用的标准表达方式 - -**版本**：v2.1.0 - ---- - -## 核心原则 - -1. **统一格式** - 所有调用使用标准化格式 -2. **清晰参数** - 必需参数明确标注，可选参数加方括号 -3. **减少冗余** - 避免不必要的echo命令和管道操作 -4. **工具优先** - 优先使用专用工具（Write/Read/Edit）而非Bash变通 -5. **可读性** - 保持缩进和换行的一致性 - ---- - -## 1. Task调用标准（Agent启动） - -### 标准格式 - -```javascript -Task( - subagent_type="agent-type", - description="Brief description", - prompt=` -FULL TASK PROMPT HERE - ` -) -``` - -### 规范要求 - -- `subagent_type`: Agent类型（字符串） -- `description`: 简短描述（5-10词，动词开头） -- `prompt`: 完整任务提示（使用反引号包裹多行内容） -- 参数字段缩进2空格 - -### 正确示例 - -```javascript -// CLI执行agent -Task( - subagent_type="cli-execution-agent", - description="Analyze codebase patterns", - prompt=` -PURPOSE: Identify code patterns for refactoring -TASK: Scan project files and extract common patterns -MODE: analysis -CONTEXT: @src/**/* -EXPECTED: Pattern list with usage examples - ` -) - -// 代码开发agent -Task( - subagent_type="code-developer", - description="Implement authentication module", - prompt=` -GOAL: Build JWT-based authentication -SCOPE: User login, token validation, session management -CONTEXT: @src/auth/**/* @CLAUDE.md - ` -) -``` - ---- - -## 2. SlashCommand调用标准 - -### 标准格式 - -```javascript -SlashCommand(command="/category:command-name [flags] arguments") -``` - -### 规范要求 - -单行调用 | 双引号包裹 | 完整路径`/category:command-name` | 参数顺序: 标志→参数值 - -### 正确示例 - -```javascript -// 无参数 -SlashCommand(command="/workflow:status") - -// 带标志和参数 -SlashCommand(command="/workflow:session:start --auto \"task description\"") - -// 变量替换 -SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"description\"") - -// 多个标志 -SlashCommand(command="/workflow:plan --agent --cli-execute \"feature description\"") -``` - ---- - -## 3. Skill调用标准 - -### 标准格式 - -```javascript -Skill(command: "skill-name") -``` - -### 规范要求 - -单行调用 | 冒号语法`command:` | 双引号包裹skill-name - -### 正确示例 - -```javascript -// 项目SKILL -Skill(command: "claude_dms3") - -// 技术栈SKILL -Skill(command: "react-dev") - -// 工作流SKILL -Skill(command: "workflow-progress") - -// 变量替换 -Skill(command: "${skill_name}") -``` - ---- - -## 4. Bash命令标准 - -### 核心原则：优先使用专用工具 - -**工具优先级**: -1. **Write工具** → 创建/覆盖文件内容 -2. **Edit工具** → 修改现有文件内容 -3. **Read工具** → 读取文件内容 -4. **Bash命令** → 仅用于真正的系统操作（git, npm, test等） - -### 标准格式 - -```javascript -bash(command args) -``` - -### 合理使用Bash的场景 - -```javascript -// ✅ Git操作 -bash(git status --short) -bash(git commit -m "commit message") - -// ✅ 包管理器和测试 -bash(npm install) -bash(npm test) - -// ✅ 文件系统查询和文本处理 -bash(find .workflow -name "*.json" -type f) -bash(rg "pattern" --type js --files-with-matches) -``` - -### 避免Bash的场景 - -```javascript -// ❌ 文件创建/写入 → 使用Write工具 -bash(echo "content" > file.txt) // 错误 -Write({file_path: "file.txt", content: "content"}) // 正确 - -// ❌ 文件读取 → 使用Read工具 -bash(cat file.txt) // 错误 -Read({file_path: "file.txt"}) // 正确 - -// ❌ 简单字符串处理 → 在代码中处理 -bash(echo "text" | tr '[:upper:]' '[:lower:]') // 错误 -"text".toLowerCase() // 正确 -``` - ---- - -## 5. 组合调用模式（伪代码准则） - -### 核心准则 - -直接写执行逻辑（无FUNCTION/END包裹）| 用`#`注释分段 | 变量赋值`variable = value` | 条件`IF/ELSE` | 循环`FOR` | 验证`VALIDATE` | 错误`ERROR + EXIT 1` - -### 顺序调用（依赖关系） - -```pseudo -# Phase 1-2: Session and Context -sessionId = SlashCommand(command="/workflow:session:start --auto \"description\"") -PARSE sessionId from output -VALIDATE: bash(test -d .workflow/{sessionId}) - -contextPath = SlashCommand(command="/workflow:tools:context-gather --session {sessionId} \"desc\"") -context_json = READ(contextPath) - -# Phase 3-4: Conditional and Agent -IF context_json.conflict_risk IN ["medium", "high"]: - SlashCommand(command="/workflow:tools:conflict-resolution --session {sessionId}") - -Task(subagent_type="action-planning-agent", description="Generate tasks", prompt=`SESSION: {sessionId}`) - -VALIDATE: bash(test -f .workflow/{sessionId}/IMPL_PLAN.md) -RETURN summary -``` - -### 并行调用（无依赖） - -```pseudo -PARALLEL_START: - check_git = bash(git status) - check_count = bash(find .workflow -name "*.json" | wc -l) - check_skill = Skill(command: "project-name") -WAIT_ALL_COMPLETE -VALIDATE results -RETURN summary -``` - -### 条件分支调用 - -```pseudo -IF task_type CONTAINS "test": agent = "test-fix-agent" -ELSE IF task_type CONTAINS "implement": agent = "code-developer" -ELSE: agent = "universal-executor" - -Skill(command: "project-name") -Task(subagent_type=agent, description="Execute task", prompt=build_prompt(task_type)) -VALIDATE output -RETURN result -``` - ---- - -## 6. 变量和占位符规范 - -| 上下文 | 格式 | 示例 | -|--------|------|------| -| **Markdown说明** | `[variableName]` | `[sessionId]`, `[contextPath]` | -| **JavaScript代码** | `${variableName}` | `${sessionId}`, `${contextPath}` | -| **Bash命令** | `$variable` | `$session_id`, `$context_path` | - ---- - -## 7. 快速检查清单 - -**Task**: subagent_type已指定 | description≤10词 | prompt用反引号 | 缩进2空格 - -**SlashCommand**: 完整路径 `/category:command` | 标志在前 | 变量用`[var]` | 双引号包裹 - -**Skill**: 冒号语法 `command:` | 双引号包裹 | 单行格式 - -**Bash**: 能用Write/Edit/Read工具吗？| 避免不必要echo | 真正的系统操作 - ---- - -## 8. 常见错误及修复 - -```javascript -// ❌ 错误1: Bash中不必要的echo -bash(echo '{"status":"active"}' > status.json) -// ✅ 正确: 使用Write工具 -Write({file_path: "status.json", content: '{"status":"active"}'}) - -// ❌ 错误2: Task单行格式 -Task(subagent_type="agent", description="Do task", prompt=`...`) -// ✅ 正确: 多行格式 -Task(subagent_type="agent", description="Do task", prompt=`...`) - -// ❌ 错误3: Skill使用等号 -Skill(command="skill-name") -// ✅ 正确: 使用冒号 -Skill(command: "skill-name") -``` - diff --git a/COMMAND_TEMPLATE_EXECUTOR.md b/COMMAND_TEMPLATE_EXECUTOR.md deleted file mode 100644 index ec7a1210..00000000 --- a/COMMAND_TEMPLATE_EXECUTOR.md +++ /dev/null @@ -1,126 +0,0 @@ -# Command Template: Executor - -**用途**：直接执行特定功能的执行器命令模板 - -**特征**：专注于自身功能实现，移除 Related Commands 段落 - ---- - -## 模板结构 - -```markdown ---- -name: command-name -description: Brief description of what this command does -argument-hint: "[flags] arguments" -allowed-tools: Read(*), Edit(*), Write(*), Bash(*), TodoWrite(*) ---- - -# Command Name (/category:command-name) - -## Overview -Clear description of what this command does and its purpose. - -**Key Characteristics**: -- Executes specific functionality directly -- Does NOT orchestrate other commands -- Focuses on single responsibility -- Returns concrete results - -## Core Functionality -- Function 1: Description -- Function 2: Description -- Function 3: Description - -## Usage - -### Command Syntax -```bash -/category:command-name [FLAGS] - -# Flags ---flag1 Description ---flag2 Description - -# Arguments - Description - Description (optional) -``` - -## Execution Process - -### Step 1: Step Name -Description of what happens in this step - -**Operations**: -- Operation 1 -- Operation 2 - -**Validation**: -- Check 1 -- Check 2 - ---- - -### Step 2: Step Name -[Repeat for each step] - ---- - -## Input/Output - -### Input Requirements -- Input 1: Description and format -- Input 2: Description and format - -### Output Format -``` -Output description and structure -``` - -## Error Handling - -### Common Errors -| Error | Cause | Resolution | -|-------|-------|------------| -| Error message 1 | Root cause | How to fix | -| Error message 2 | Root cause | How to fix | - -## Best Practices - -1. **Practice 1**: Description and rationale -2. **Practice 2**: Description and rationale -3. **Practice 3**: Description and rationale -``` - ---- - -## 使用规则 - -### 核心原则 -1. **移除 Related Commands** - 执行器不协调其他命令 -2. **专注单一职责** - 每个执行器只做一件事 -3. **清晰的步骤划分** - 明确执行流程 -4. **完整的错误处理** - 列出常见错误和解决方案 - -### 可选段落 -根据命令特性，以下段落可选： -- **Configuration**: 有配置参数时使用 -- **Output Files**: 生成文件时使用 -- **Exit Codes**: 有明确退出码时使用 -- **Environment Variables**: 依赖环境变量时使用 - -### 格式要求 -- 无 emoji/图标装饰 -- 纯文本状态指示器 -- 使用表格组织错误信息 -- 提供实用的示例代码 - -## 示例参考 - -参考已重构的执行器命令： -- `.claude/commands/task/create.md` -- `.claude/commands/task/breakdown.md` -- `.claude/commands/task/execute.md` -- `.claude/commands/cli/execute.md` -- `.claude/commands/version.md` diff --git a/COMMAND_TEMPLATE_ORCHESTRATOR.md b/COMMAND_TEMPLATE_ORCHESTRATOR.md deleted file mode 100644 index cc8beabe..00000000 --- a/COMMAND_TEMPLATE_ORCHESTRATOR.md +++ /dev/null @@ -1,140 +0,0 @@ -# Command Template: Orchestrator - -**用途**：协调多个子命令的编排器命令模板 - -**特征**：保留 Related Commands 段落，明确说明调用的命令链 - ---- - -## 模板结构 - -```markdown ---- -name: command-name -description: Brief description of what this command orchestrates -argument-hint: "[flags] arguments" -allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*) ---- - -# Command Name (/category:command-name) - -## Overview -Clear description of what this command orchestrates and its role. - -**Key Characteristics**: -- Orchestrates X phases/commands -- Coordinates between multiple slash commands -- Does NOT execute directly - delegates to specialized commands -- Manages workflow state and progress tracking - -## Core Responsibilities -- Responsibility 1: Description -- Responsibility 2: Description -- Responsibility 3: Description - -## Execution Flow - -### Phase 1: Phase Name -**Command**: `SlashCommand(command="/command:name args")` - -**Input**: Description of inputs - -**Expected Behavior**: -- Behavior 1 -- Behavior 2 - -**Parse Output**: -- Extract: variable name (pattern description) - -**Validation**: -- Validation rule 1 -- Validation rule 2 - -**TodoWrite**: Mark phase 1 completed, phase 2 in_progress - ---- - -### Phase 2: Phase Name -[Repeat structure for each phase] - ---- - -## TodoWrite Pattern - -Track progress through all phases: - -```javascript -TodoWrite({todos: [ - {"content": "Execute phase 1", "status": "in_progress|completed", "activeForm": "Executing phase 1"}, - {"content": "Execute phase 2", "status": "pending|in_progress|completed", "activeForm": "Executing phase 2"}, - {"content": "Execute phase 3", "status": "pending|in_progress|completed", "activeForm": "Executing phase 3"} -]}) -``` - -## Data Flow - -``` -Phase 1: command-1 → output-1 - ↓ -Phase 2: command-2 (input: output-1) → output-2 - ↓ -Phase 3: command-3 (input: output-2) → final-result -``` - -## Error Handling - -| Phase | Error | Action | -|-------|-------|--------| -| 1 | Error description | Recovery action | -| 2 | Error description | Recovery action | - -## Usage Examples - -### Basic Usage -```bash -/category:command-name -/category:command-name --flag "argument" -``` - -## Related Commands - -**Prerequisite Commands**: -- `/command:prerequisite` - Description of when to use before this - -**Called by This Command**: -- `/command:phase1` - Description (Phase 1) -- `/command:phase2` - Description (Phase 2) -- `/command:phase3` - Description (Phase 3) - -**Follow-up Commands**: -- `/command:next` - Description of what to do after this -``` - ---- - -## 使用规则 - -### 核心原则 -1. **保留 Related Commands** - 明确说明命令调用链 -2. **清晰的阶段划分** - 每个Phase独立可追踪 -3. **数据流可视化** - 展示Phase间的数据传递 -4. **TodoWrite追踪** - 实时更新执行进度 - -### Related Commands 分类 -- **Prerequisite Commands**: 执行本命令前需要先运行的命令 -- **Called by This Command**: 本命令会调用的子命令（按阶段分组） -- **Follow-up Commands**: 执行本命令后的推荐下一步 - -### 格式要求 -- 无 emoji/图标装饰 -- 纯文本状态指示器 -- 使用表格组织错误信息 -- 清晰的数据流图 - -## 示例参考 - -参考已重构的编排器命令： -- `.claude/commands/workflow/plan.md` -- `.claude/commands/workflow/execute.md` -- `.claude/commands/workflow/session/complete.md` -- `.claude/commands/workflow/session/start.md` diff --git a/LITE_FIX_DESIGN.md b/LITE_FIX_DESIGN.md deleted file mode 100644 index cbc6e6bd..00000000 --- a/LITE_FIX_DESIGN.md +++ /dev/null @@ -1,620 +0,0 @@ -# Lite-Fix Command Design Document - -**Date**: 2025-11-20 -**Version**: 2.0.0 (Simplified Design) -**Status**: Design Complete -**Related**: PLANNING_GAP_ANALYSIS.md (Scenario #8: Emergency Fix Scenario) - ---- - -## Design Overview - -`/workflow:lite-fix` is a lightweight bug diagnosis and fix workflow command that fills the gap in emergency fix scenarios in the current planning system. Designed with reference to the successful `/workflow:lite-plan` pattern, optimized for bug fixing scenarios. - -### Core Design Principles - -1. **Rapid Response** - Supports 15 minutes to 4 hours fix cycles -2. **Intelligent Adaptation** - Automatically adjusts workflow complexity based on risk assessment -3. **Progressive Verification** - Flexible testing strategy from smoke tests to full suite -4. **Automated Follow-up** - Hotfix mode auto-generates comprehensive fix tasks - -### Key Innovation: **Intelligent Self-Adaptation** - -Unlike traditional fixed-mode commands, lite-fix uses **Phase 2 Impact Assessment** to automatically determine severity and adapt the entire workflow: - -```javascript -// Phase 2 auto-determines severity -risk_score = (user_impact × 0.4) + (system_risk × 0.3) + (business_impact × 0.3) - -// Workflow auto-adapts -if (risk_score < 3.0) → Full test suite, comprehensive diagnosis -else if (risk_score < 5.0) → Focused integration, moderate diagnosis -else if (risk_score < 8.0) → Smoke+critical, focused diagnosis -else → Smoke only, minimal diagnosis -``` - -**Result**: Users don't need to manually select severity modes - the system intelligently adapts. - ---- - -## Design Comparison: lite-fix vs lite-plan - -| Dimension | lite-plan | lite-fix (v2.0) | Design Rationale | -|-----------|-----------|-----------------|------------------| -| **Target Scenario** | New feature development | Bug fixes | Different development intent | -| **Time Budget** | 1-6 hours | Auto-adapt (15min-4h) | Bug fixes more urgent | -| **Exploration Phase** | Optional (`-e` flag) | Adaptive depth | Bug needs diagnosis | -| **Output Type** | Implementation plan | Diagnosis + fix plan | Bug needs root cause | -| **Verification Strategy** | Full test suite | Auto-adaptive (Smoke→Full) | Risk vs speed tradeoff | -| **Branch Strategy** | Feature branch | Feature/Hotfix branch | Production needs special handling | -| **Follow-up Mechanism** | None | Hotfix auto-generates tasks | Technical debt management | -| **Intelligence Level** | Manual | **Auto-adaptive** | **Key innovation** | - ---- - -## Two-Mode Design (Simplified from Three) - -### Mode 1: Default (Intelligent Auto-Adaptive) - -**Use Cases**: -- All standard bugs (90% of scenarios) -- Automatic severity assessment -- Workflow adapts to risk score - -**Workflow Characteristics**: -``` -Adaptive diagnosis → Impact assessment → Auto-severity detection - ↓ - Strategy selection (count based on risk) → Adaptive testing - ↓ - Confirmation (dimensions based on risk) → Execution -``` - -**Example Use Cases**: -```bash -# Low severity (auto-detected) -/workflow:lite-fix "User profile bio field shows HTML tags" -# → Full test suite, multiple strategy options, 3-4 hour budget - -# Medium severity (auto-detected) -/workflow:lite-fix "Shopping cart occasionally loses items" -# → Focused integration tests, best strategy, 1-2 hour budget - -# High severity (auto-detected) -/workflow:lite-fix "Login fails for all users after deployment" -# → Smoke+critical tests, single strategy, 30-60 min budget -``` - -### Mode 2: Hotfix (`--hotfix`) - -**Use Cases**: -- Production outage only -- 100% user impact or business interruption -- Requires 15-30 minute fix - -**Workflow Characteristics**: -``` -Minimal diagnosis → Skip assessment (assume critical) - ↓ - Surgical fix → Production smoke tests - ↓ - Hotfix branch (from production tag) → Auto follow-up tasks -``` - -**Example Use Case**: -```bash -/workflow:lite-fix --hotfix "Payment gateway 5xx errors" -# → Hotfix branch from v2.3.1 tag, smoke tests only, follow-up tasks auto-generated -``` - ---- - -## Command Syntax (Simplified) - -### Before (v1.0 - Complex) - -```bash -/workflow:lite-fix [--critical|--hotfix] [--incident ID] "bug description" - -# 3 modes, 3 parameters ---critical, -c Critical bug mode ---hotfix, -h Production hotfix mode ---incident Incident tracking ID -``` - -**Problems**: -- Users need to manually determine severity (Regular vs Critical) -- Too many parameters (3 flags) -- Incident ID as separate parameter adds complexity - -### After (v2.0 - Simplified) - -```bash -/workflow:lite-fix [--hotfix] "bug description" - -# 2 modes, 1 parameter ---hotfix, -h Production hotfix mode only -``` - -**Improvements**: -- ✅ Automatic severity detection (no manual selection) -- ✅ Single optional flag (67% reduction) -- ✅ Incident info can be in bug description -- ✅ Matches lite-plan simplicity - ---- - -## Intelligent Adaptive Workflow - -### Phase 1: Diagnosis - Adaptive Search Depth - -**Confidence-based Strategy Selection**: - -```javascript -// High confidence (specific error message provided) -if (has_specific_error_message || has_file_path_hint) { - strategy = "direct_grep" - time_budget = "5 minutes" - grep -r '${error_message}' src/ --include='*.ts' -n | head -10 -} -// Medium confidence (module or feature mentioned) -else if (has_module_hint) { - strategy = "cli-explore-agent_focused" - time_budget = "10-15 minutes" - Task(subagent="cli-explore-agent", scope="focused") -} -// Low confidence (vague symptoms) -else { - strategy = "cli-explore-agent_broad" - time_budget = "20 minutes" - Task(subagent="cli-explore-agent", scope="comprehensive") -} -``` - -**Output**: -- Root cause (file:line, issue, introduced_by) -- Reproduction steps -- Affected scope -- **Confidence level** (used in Phase 2) - -### Phase 2: Impact Assessment - Auto-Severity Detection - -**Risk Score Calculation**: - -```javascript -risk_score = (user_impact × 0.4) + (system_risk × 0.3) + (business_impact × 0.3) - -// Examples: -// - UI typo: user_impact=1, system_risk=0, business_impact=0 → risk_score=0.4 (LOW) -// - Cart bug: user_impact=5, system_risk=3, business_impact=4 → risk_score=4.1 (MEDIUM) -// - Login failure: user_impact=9, system_risk=7, business_impact=8 → risk_score=8.1 (CRITICAL) -``` - -**Workflow Adaptation Table**: - -| Risk Score | Severity | Diagnosis | Test Strategy | Review | Time Budget | -|------------|----------|-----------|---------------|--------|-------------| -| **< 3.0** | Low | Comprehensive | Full test suite | Optional | 3-4 hours | -| **3.0-5.0** | Medium | Moderate | Focused integration | Optional | 1-2 hours | -| **5.0-8.0** | High | Focused | Smoke + critical | Skip | 30-60 min | -| **≥ 8.0** | Critical | Minimal | Smoke only | Skip | 15-30 min | - -**Output**: -```javascript -{ - risk_score: 6.5, - severity: "high", - workflow_adaptation: { - diagnosis_depth: "focused", - test_strategy: "smoke_and_critical", - review_optional: true, - time_budget: "45_minutes" - } -} -``` - -### Phase 3: Fix Planning - Adaptive Strategy Count - -**Before Phase 2 adaptation**: -- Always generate 1-3 strategy options -- User manually selects - -**After Phase 2 adaptation**: -```javascript -if (risk_score < 5.0) { - // Low-medium risk: User has time to choose - strategies = generateMultipleStrategies() // 2-3 options - user_selection = true -} -else { - // High-critical risk: Speed is priority - strategies = [selectBestStrategy()] // Single option - user_selection = false -} -``` - -**Example**: -```javascript -// Low risk (risk_score=2.5) → Multiple options -[ - { strategy: "immediate_patch", time: "15min", pros: ["Quick"], cons: ["Not comprehensive"] }, - { strategy: "comprehensive_fix", time: "2h", pros: ["Root cause"], cons: ["Longer"] } -] - -// High risk (risk_score=6.5) → Single best -{ strategy: "surgical_fix", time: "5min", risk: "minimal" } -``` - -### Phase 4: Verification - Auto-Test Level Selection - -**Test strategy determined by Phase 2 risk_score**: - -```javascript -// Already determined in Phase 2 -test_strategy = workflow_adaptation.test_strategy - -// Map to specific test commands -test_commands = { - "full_test_suite": "npm test", - "focused_integration": "npm test -- affected-module.test.ts", - "smoke_and_critical": "npm test -- critical.smoke.test.ts", - "smoke_only": "npm test -- smoke.test.ts" -} -``` - -**Auto-suggested to user** (can override if needed) - -### Phase 5: User Confirmation - Adaptive Dimensions - -**Dimension count adapts to risk score**: - -```javascript -dimensions = [ - "Fix approach confirmation", // Always present - "Execution method", // Always present - "Verification level" // Always present (auto-suggested) -] - -// Optional 4th dimension for low-risk bugs -if (risk_score < 5.0) { - dimensions.push("Post-fix review") // Only for low-medium severity -} -``` - -**Result**: -- High-risk bugs: 3 dimensions (faster confirmation) -- Low-risk bugs: 4 dimensions (includes review) - -### Phase 6: Execution - Same as Before - -Dispatch to lite-execute with adapted context. - ---- - -## Six-Phase Execution Flow Design - -### Phase Summary Comparison - -| Phase | v1.0 (3 modes) | v2.0 (Adaptive) | -|-------|----------------|-----------------| -| 1. Diagnosis | Manual mode selection → Fixed depth | Confidence detection → Adaptive depth | -| 2. Impact | Assessment only | **Assessment + Auto-severity + Workflow adaptation** | -| 3. Planning | Fixed strategy count | **Risk-based strategy count** | -| 4. Verification | Manual test selection | **Auto-suggested test level** | -| 5. Confirmation | Fixed dimensions | **Adaptive dimensions (3 or 4)** | -| 6. Execution | Same | Same | - -**Key Difference**: Phases 2-5 now adapt based on Phase 2 risk score. - ---- - -## Data Structure Extensions - -### diagnosisContext (Extended) - -```javascript -{ - symptom: string, - error_message: string | null, - keywords: string[], - confidence_level: "high" | "medium" | "low", // ← NEW: Search confidence - root_cause: { - file: string, - line_range: string, - issue: string, - introduced_by: string - }, - reproduction_steps: string[], - affected_scope: {...} -} -``` - -### impactContext (Extended) - -```javascript -{ - affected_users: {...}, - system_risk: {...}, - business_impact: {...}, - risk_score: number, // 0-10 - severity: "low" | "medium" | "high" | "critical", - workflow_adaptation: { // ← NEW: Adaptation decisions - diagnosis_depth: string, - test_strategy: string, - review_optional: boolean, - time_budget: string - } -} -``` - ---- - -## Implementation Roadmap - -### Phase 1: Core Functionality (Sprint 1) - 5-8 days - -**Completed** ✅: -- [x] Command specification (lite-fix.md - 652 lines) -- [x] Design document (this document) -- [x] Mode simplification (3→2) -- [x] Parameter reduction (3→1) - -**Remaining**: -- [ ] Implement 6-phase workflow -- [ ] Implement intelligent adaptation logic -- [ ] Integrate with lite-execute - -### Phase 2: Advanced Features (Sprint 2) - 3-5 days - -- [ ] Diagnosis caching mechanism -- [ ] Auto-severity keyword detection -- [ ] Hotfix branch management scripts -- [ ] Follow-up task auto-generation - -### Phase 3: Optimization (Sprint 3) - 2-3 days - -- [ ] Performance optimization (diagnosis speed) -- [ ] Error handling refinement -- [ ] Documentation and examples -- [ ] User feedback iteration - ---- - -## Success Metrics - -### Efficiency Improvements - -| Mode | v1.0 Manual Selection | v2.0 Auto-Adaptive | Improvement | -|------|----------------------|-------------------|-------------| -| Low severity | 4-6 hours (manual Regular) | <3 hours (auto-detected) | 50% faster | -| Medium severity | 2-3 hours (need to select Critical) | <1.5 hours (auto-detected) | 40% faster | -| High severity | 1-2 hours (if user selects Critical correctly) | <1 hour (auto-detected) | 50% faster | - -**Key**: Users no longer waste time deciding which mode to use. - -### Quality Metrics - -- **Diagnosis Accuracy**: >85% (structured root cause analysis) -- **First-time Fix Success Rate**: >90% (comprehensive impact assessment) -- **Regression Rate**: <5% (adaptive verification strategy) -- **Mode Selection Accuracy**: 100% (automatic, no human error) - -### User Experience - -**v1.0 User Flow**: -``` -User: "Is this bug Regular or Critical? Not sure..." -User: "Let me read the mode descriptions again..." -User: "OK I'll try --critical" -System: "Executing critical mode..." (might be wrong choice) -``` - -**v2.0 User Flow**: -``` -User: "/workflow:lite-fix 'Shopping cart loses items'" -System: "Analyzing impact... Risk score: 6.5 (High severity detected)" -System: "Adapting workflow: Focused diagnosis, Smoke+critical tests" -User: "Perfect, proceed" (no mode selection needed) -``` - ---- - -## Comparison with Other Commands - -| Command | Modes | Parameters | Adaptation | Complexity | -|---------|-------|------------|------------|------------| -| `/workflow:lite-fix` (v2.0) | 2 | 1 | **Auto** | Low ✅ | -| `/workflow:lite-plan` | 1 + explore flag | 1 | Manual | Low ✅ | -| `/workflow:plan` | Multiple | Multiple | Manual | High | -| `/workflow:lite-fix` (v1.0) | 3 | 3 | Manual | Medium ❌ | - -**Conclusion**: v2.0 matches lite-plan's simplicity while adding intelligence. - ---- - -## Architecture Decision Records (ADRs) - -### ADR-001: Why Remove Critical Mode? - -**Decision**: Remove `--critical` flag, use automatic severity detection - -**Rationale**: -1. Users often misjudge bug severity (too conservative or too aggressive) -2. Phase 2 impact assessment provides objective risk scoring -3. Automatic adaptation eliminates mode selection overhead -4. Aligns with "lite" philosophy - simpler is better - -**Alternatives Rejected**: -- Keep 3 modes: Too complex, user confusion -- Use continuous severity slider (0-10): Still requires manual input - -**Result**: 90% of users can use default mode without thinking about severity. - -### ADR-002: Why Keep Hotfix as Separate Mode? - -**Decision**: Keep `--hotfix` as explicit flag (not auto-detect) - -**Rationale**: -1. Production incidents require explicit user intent (safety measure) -2. Hotfix has special workflow (branch from production tag, follow-up tasks) -3. Clear distinction: "Is this a production incident?" → Yes/No decision -4. Prevents accidental hotfix branch creation - -**Alternatives Rejected**: -- Auto-detect hotfix based on keywords: Too risky, false positives -- Merge into default mode with risk_score≥9.0: Loses explicit intent - -**Result**: Users explicitly choose when to trigger hotfix workflow. - -### ADR-003: Why Adaptive Confirmation Dimensions? - -**Decision**: Use 3 or 4 confirmation dimensions based on risk score - -**Rationale**: -1. High-risk bugs need speed → Skip optional code review -2. Low-risk bugs have time → Add code review dimension for quality -3. Adaptive UX provides best of both worlds - -**Alternatives Rejected**: -- Always 4 dimensions: Slows down high-risk fixes -- Always 3 dimensions: Misses quality improvement opportunities for low-risk bugs - -**Result**: Workflow adapts to urgency while maintaining quality. - -### ADR-004: Why Remove --incident Parameter? - -**Decision**: Remove `--incident ` parameter - -**Rationale**: -1. Incident ID can be included in bug description string -2. Or tracked separately in follow-up task metadata -3. Reduces command-line parameter count (simplification goal) -4. Matches lite-plan's simple syntax - -**Alternatives Rejected**: -- Keep as optional parameter: Adds complexity for rare use case -- Auto-extract from description: Over-engineering - -**Result**: Simpler command syntax, incident tracking handled elsewhere. - ---- - -## Risk Assessment and Mitigation - -### Risk 1: Auto-Severity Detection Errors - -**Risk**: System incorrectly assesses severity (e.g., critical bug marked as low) - -**Mitigation**: -1. User can see risk score and severity in Phase 2 output -2. User can escalate to `/workflow:plan` if automated assessment seems wrong -3. Provide clear explanation of risk score calculation -4. Phase 5 confirmation allows user to override test strategy - -**Likelihood**: Low (risk score formula well-tested) - -### Risk 2: Users Miss --hotfix Flag - -**Risk**: Production incident handled as default mode (slower process) - -**Mitigation**: -1. Auto-suggest `--hotfix` if keywords detected ("production", "outage", "down") -2. If risk_score ≥ 9.0, prompt: "Consider using --hotfix for production incidents" -3. Documentation clearly explains when to use hotfix - -**Likelihood**: Medium → Mitigation reduces to Low - -### Risk 3: Adaptive Workflow Confusion - -**Risk**: Users confused by different workflows for different bugs - -**Mitigation**: -1. Clear output explaining why workflow adapted ("Risk score: 6.5 → Using focused diagnosis") -2. Consistent 6-phase structure (only depth/complexity changes) -3. Documentation with examples for each risk level - -**Likelihood**: Low (transparency in adaptation decisions) - ---- - -## Gap Coverage from PLANNING_GAP_ANALYSIS.md - -This design addresses **Scenario #8: Emergency Fix Scenario** from the gap analysis: - -| Gap Item | Coverage | Implementation | -|----------|----------|----------------| -| Workflow simplification | ✅ 100% | 2 modes vs 3, 1 parameter vs 3 | -| Fast verification | ✅ 100% | Adaptive test strategy (smoke to full) | -| Hotfix branch management | ✅ 100% | Branch from production tag, dual merge | -| Comprehensive fix follow-up | ✅ 100% | Auto-generated follow-up tasks | - -**Additional Enhancements** (beyond original gap): -- ✅ Intelligent auto-adaptation (not in original gap) -- ✅ Risk score calculation (quantitative severity) -- ✅ Diagnosis caching (performance optimization) - ---- - -## Design Evolution Summary - -### v1.0 → v2.0 Changes - -| Aspect | v1.0 | v2.0 | Impact | -|--------|------|------|--------| -| **Modes** | 3 (Regular, Critical, Hotfix) | **2 (Default, Hotfix)** | -33% complexity | -| **Parameters** | 3 (--critical, --hotfix, --incident) | **1 (--hotfix)** | -67% parameters | -| **Adaptation** | Manual mode selection | **Intelligent auto-adaptation** | 🚀 Key innovation | -| **User Decision Points** | 3 (mode + incident + confirmation) | **1 (hotfix or not)** | -67% decisions | -| **Documentation** | 707 lines | **652 lines** | -8% length | -| **Workflow Intelligence** | Low | **High** | Major upgrade | - -### Philosophy Shift - -**v1.0**: "Provide multiple modes for different scenarios" -- User selects mode based on perceived severity -- Fixed workflows for each mode - -**v2.0**: "Intelligent single mode that adapts to reality" -- System assesses actual severity -- Workflow automatically optimizes for risk level -- User only decides: "Is this a production incident?" (Yes → --hotfix) - -**Result**: Simpler to use, smarter behavior, same powerful capabilities. - ---- - -## Conclusion - -`/workflow:lite-fix` v2.0 represents a significant simplification while maintaining (and enhancing) full functionality: - -**Core Achievements**: -1. ⚡ **Simplified Interface**: 2 modes, 1 parameter (vs 3 modes, 3 parameters) -2. 🧠 **Intelligent Adaptation**: Auto-severity detection with risk score -3. 🎯 **Optimized Workflows**: Each bug gets appropriate process depth -4. 🛡️ **Quality Assurance**: Adaptive verification strategy -5. 📋 **Tech Debt Management**: Hotfix auto-generates follow-up tasks - -**Competitive Advantages**: -- Matches lite-plan's simplicity (1 optional flag) -- Exceeds lite-plan's intelligence (auto-adaptation) -- Solves 90% of bug scenarios without mode selection -- Explicit hotfix mode for safety-critical production fixes - -**Expected Impact**: -- Reduce bug fix time by 50-70% -- Eliminate mode selection errors (100% accuracy) -- Improve diagnosis accuracy to 85%+ -- Systematize technical debt from hotfixes - -**Next Steps**: -1. Review this design document -2. Approve v2.0 simplified approach -3. Implement Phase 1 core functionality (estimated 5-8 days) -4. Iterate based on user feedback - ---- - -**Document Version**: 2.0.0 -**Author**: Claude (Sonnet 4.5) -**Review Status**: Pending Approval -**Implementation Status**: Design Complete, Development Pending diff --git a/PLANNING_GAP_ANALYSIS.md b/PLANNING_GAP_ANALYSIS.md deleted file mode 100644 index aa6bb5f6..00000000 --- a/PLANNING_GAP_ANALYSIS.md +++ /dev/null @@ -1,1016 +0,0 @@ -# Planning环节未考虑场景深度分析 - -**分析日期**: 2025-11-20 -**分析范围**: `/workflow:plan`, `/workflow:lite-plan`, `/workflow:tdd-plan`, `/workflow:replan`, `/cli:discuss-plan` -**分析目的**: 识别软件开发生命周期中当前planning流程未充分支持的场景 - ---- - -## 执行摘要 - -当前planning系统设计完善，覆盖了标准软件开发流程的核心场景（新功能开发、TDD、重构、测试）。然而，通过对15类特殊开发场景的深入分析，发现以下关键空白： - -**高优先级缺失**： -1. 遗留代码重构（无测试覆盖的安全重构） -2. 紧急修复流程（生产问题hotfix） -3. 数据迁移（需要回滚计划和验证） -4. 依赖升级（breaking changes处理） - -**中优先级缺失**： -5. 增量式开发/Feature Flags -6. 多团队协作同步 -7. 技术债务系统化管理 -8. 性能优化专项（需要baseline和profiling） - ---- - -## 1. 增量式开发/渐进式增强场景 - -### 场景描述 -在现有功能基础上逐步增加复杂性，通过feature flags控制渐进式发布。 - -### 当前Planning的局限性 - -**现有流程假设**： -- `/workflow:plan` 生成的任务是完整的、独立的功能单元 -- `IMPL_PLAN.md` 描述的是"一次性交付"的实现方案 -- 验收标准(`context.acceptance`)是二元的（完成/未完成） - -**实际需求**： -```json -{ - "feature_strategy": "incremental", - "phases": [ - { - "phase": 1, - "scope": "basic_functionality", - "feature_flag": "new_auth_v1", - "rollout_percentage": 5, - "metrics": ["error_rate < 1%", "latency_p99 < 200ms"] - }, - { - "phase": 2, - "scope": "advanced_features", - "feature_flag": "new_auth_v2", - "dependency": "phase_1_metrics_green", - "rollout_percentage": 25 - } - ], - "rollback_trigger": "automated_on_metric_threshold" -} -``` - -### Gap分析 - -| 维度 | 当前支持 | 缺失功能 | -|------|---------|---------| -| **任务分解** | 单阶段完整交付 | ❌ 多阶段渐进式任务链 | -| **验收标准** | 功能完成度 | ❌ 按阶段的指标监控 | -| **回滚计划** | 无 | ❌ Feature flag回滚策略 | -| **A/B测试** | 无 | ❌ 实验组/对照组配置 | - -### 影响范围 -- **action-planning-agent.md**: 需要支持`phased_rollout`策略 -- **workflow-architecture.md**: `flow_control.implementation_approach`需要增加`rollout_config`字段 -- **Enhanced Task JSON Schema**: 需要新字段`deployment_strategy` - -### 建议改进 - -**新增Planning模式**: `/workflow:plan --mode incremental` - -```json -{ - "deployment_strategy": { - "type": "feature_flag_rollout", - "phases": [ - { - "id": "alpha", - "flag_config": { - "name": "feature_x_alpha", - "enabled_for": "internal_users" - }, - "success_criteria": [ - "zero_critical_bugs", - "positive_user_feedback > 80%" - ], - "duration": "1_week", - "rollback_on": ["critical_bug", "negative_feedback > 30%"] - } - ], - "monitoring": { - "dashboards": ["feature_x_health"], - "alerts": ["feature_x_error_rate"] - } - } -} -``` - ---- - -## 2. 遗留代码重构场景 - -### 场景描述 -重构缺少测试覆盖的遗留代码，需要在不破坏现有功能的前提下逐步改进。 - -### 当前Planning的局限性 - -**现有流程假设**： -- Context gathering (`/workflow:tools:context-gather`) 假设代码库有良好的文档和测试 -- TDD planning (`/workflow:tdd-plan`) 假设可以先写测试 -- 验收标准假设可以通过测试验证 - -**遗留代码现实**： -``` -Legacy System Characteristics: -├── No existing tests (coverage = 0%) -├── No documentation (last update: 5 years ago) -├── Original developers left -├── Critical business logic (cannot break) -├── Tightly coupled architecture -└── Unknown edge cases (production behavior is spec) -``` - -### Gap分析 - -| 维度 | 当前支持 | 缺失功能 | -|------|---------|---------| -| **安全网构建** | 假设有测试 | ❌ Characterization tests生成 | -| **风险评估** | 基于代码分析 | ❌ 生产流量分析/影响范围评估 | -| **重构策略** | 直接重写 | ❌ Strangler Pattern/Branch by Abstraction | -| **验证方法** | 单元测试 | ❌ 影子模式(Shadow Mode)/流量回放 | - -### 影响范围 -- **test-context-gather**: 当前假设tests/目录存在，需要处理coverage=0场景 -- **tdd-plan**: Red-Green-Refactor不适用，需要Golden Master Testing -- **conflict-resolution**: 需要识别"遗留代码约束"类型的冲突 - -### 建议改进 - -**新增Planning模式**: `/workflow:plan --legacy-refactor` - -**Phase 1: 安全网构建** -```bash -# 1. 生成Characterization Tests（捕获当前行为） -/workflow:tools:legacy-safety-net --session WFS-refactor - → 分析生产日志提取真实输入 - → 录制当前输出作为Golden Master - → 生成快照测试覆盖关键路径 - -# Output: Approval Tests for critical workflows -``` - -**Phase 2: Strangler Pattern规划** -```json -{ - "refactor_strategy": "strangler_pattern", - "steps": [ - { - "step": 1, - "action": "Create abstraction layer", - "legacy_code_untouched": true, - "new_interface": "PaymentGateway", - "routing_logic": "feature_flag_controlled" - }, - { - "step": 2, - "action": "Implement new module behind abstraction", - "parallel_run": true, - "comparison": "assert_output_parity(legacy, new)" - }, - { - "step": 3, - "action": "Gradual traffic migration", - "rollout": [1, 5, 25, 50, 100], - "rollback_automatic": true - } - ] -} -``` - ---- - -## 3. 多团队协作场景 - -### 场景描述 -跨团队开发，存在API依赖、共享代码库、并行开发同步等协作需求。 - -### 当前Planning的局限性 - -**现有session管理假设**： -``` -.workflow/active/WFS-feature/ # 单团队单功能 -``` - -**多团队现实**： -``` -Teams: -├── Team A (Frontend) → 依赖 Team B的API -├── Team B (Backend) → 依赖 Team C的数据模型 -└── Team C (Data) → 依赖 Team A的UI需求 - -Coordination Points: -├── API Contract定义 (需要提前锁定) -├── 集成测试环境 (需要协调部署窗口) -├── 共享组件库 (需要版本兼容性管理) -└── 代码review (需要跨团队审查) -``` - -### Gap分析 - -| 维度 | 当前支持 | 缺失功能 | -|------|---------|---------| -| **依赖表达** | `task.depends_on` (同session内) | ❌ 跨session/跨团队依赖 | -| **API契约** | 代码实现后确定 | ❌ Contract-first设计 | -| **同步点** | 无 | ❌ Integration milestones | -| **冲突预防** | 同一代码库检测 | ❌ 共享模块版本协调 | - -### 影响范围 -- **workflow-session.json**: 需要`external_dependencies`字段 -- **conflict-resolution**: 需要检测跨session的模块冲突 -- **IMPL_PLAN.md**: 需要"Coordination Points"章节 - -### 建议改进 - -**新增命令**: `/workflow:plan --multi-team` - -```json -{ - "session_id": "WFS-checkout-flow", - "team": "frontend", - "external_dependencies": [ - { - "team": "backend", - "session_id": "WFS-payment-api", - "contract": { - "type": "OpenAPI", - "spec_path": "shared/contracts/payment-api-v2.yaml", - "locked_at": "2025-10-15", - "status": "approved" - }, - "blocking_tasks": ["IMPL-1", "IMPL-2"], - "ready_by": "2025-10-20" - } - ], - "coordination_points": [ - { - "milestone": "API Contract Freeze", - "date": "2025-10-15", - "attendees": ["frontend", "backend"], - "deliverable": "OpenAPI spec v2 approved" - }, - { - "milestone": "Integration Test", - "date": "2025-10-25", - "environment": "staging", - "cross_team_test_suite": "e2e/checkout_flow.spec.ts" - } - ] -} -``` - ---- - -## 4. 技术债务偿还场景 - -### 场景描述 -系统化管理技术债务，在功能开发中平衡债务偿还，评估ROI和风险。 - -### 当前Planning的局限性 - -**现有任务类型**： -```json -{ - "meta": { - "type": "feature|bugfix|refactor|test|docs" - } -} -``` - -**技术债务特性**： -- 非紧急但长期累积会造成严重影响 -- 需要量化（利息成本、偿还成本） -- 需要优先级排序 -- 可能跨越多个模块 - -### Gap分析 - -| 维度 | 当前支持 | 缺失功能 | -|------|---------|---------| -| **债务识别** | 手动发现 | ❌ 自动检测（复杂度、重复代码、过时依赖） | -| **债务量化** | 无 | ❌ 技术债务指标（利息成本、偿还工时） | -| **优先级评估** | 主观判断 | ❌ ROI评分（影响×紧迫度/偿还成本） | -| **穿插策略** | 无 | ❌ 在功能开发中配额式偿还债务 | - -### 影响范围 -- **workflow:plan**: 需要`--tech-debt-mode`识别债务 -- **action-planning-agent**: 需要债务优先级算法 -- **Enhanced Task JSON**: 需要`debt_metrics`字段 - -### 建议改进 - -**新增命令**: `/workflow:debt:assess` - -```bash -/workflow:debt:assess --session WFS-feature - → Scan codebase for debt indicators: - - Cyclomatic complexity > 15 - - Duplicated code blocks > 50 lines - - Dependencies with CVEs - - TODO/FIXME comments > 6 months old - → Generate debt inventory with ROI scores - → Recommend debt paydown tasks -``` - -**Debt Task JSON Schema**: -```json -{ - "id": "DEBT-001", - "title": "Refactor UserService god class", - "meta": { - "type": "tech_debt", - "debt_category": "complexity" - }, - "debt_metrics": { - "interest_cost": { - "description": "每次修改需要额外30%时间理解代码", - "monthly_cost_hours": 8 - }, - "paydown_cost": { - "estimated_hours": 16, - "risk_level": "medium" - }, - "roi_score": 6.0, - "priority": "high" - }, - "bundled_with_feature": "IMPL-003" -} -``` - ---- - -## 5. 性能优化专项场景 - -### 场景描述 -系统性能优化需要baseline建立、profiling分析、多次迭代实验，与常规功能开发流程不同。 - -### 当前Planning的局限性 - -**现有验收标准**： -```json -{ - "acceptance": [ - "功能X实现完成", - "测试覆盖率>80%" - ] -} -``` - -**性能优化验收标准**： -```json -{ - "acceptance": [ - "P95延迟从500ms降低到100ms", - "CPU使用率从80%降低到40%", - "内存占用减少30%", - "QPS提升至10000" - ], - "measurement_method": "load_test_with_k6", - "baseline": "current_production_metrics", - "confidence_interval": "99%", - "sample_size": "10000_requests" -} -``` - -### Gap分析 - -| 维度 | 当前支持 | 缺失功能 | -|------|---------|---------| -| **Baseline建立** | 无 | ❌ 自动收集当前性能指标 | -| **Profiling集成** | 无 | ❌ 集成profiling工具（flamegraph, perf） | -| **实验流程** | 无 | ❌ 优化→测量→对比→迭代循环 | -| **A/B对比** | 无 | ❌ 性能回归检测 | - -### 影响范围 -- **flow_control.pre_analysis**: 需要`establish_baseline`步骤 -- **flow_control.implementation_approach**: 需要支持迭代式优化 -- **verification**: 需要性能测试集成 - -### 建议改进 - -**新增Planning模式**: `/workflow:plan --performance-optimization` - -```json -{ - "performance_optimization": { - "phase_0_baseline": { - "steps": [ - { - "action": "Capture current metrics", - "tools": ["k6_load_test", "flamegraph_profiling"], - "output": "baseline_report.json" - }, - { - "action": "Identify bottlenecks", - "analysis": "flamegraph analysis shows DB query N+1 problem", - "target": "reduce_db_roundtrips" - } - ] - }, - "phase_1_optimization": { - "hypothesis": "Batch DB queries to reduce roundtrips", - "implementation": "IMPL-001", - "verification": { - "load_test": "k6 run scenarios/checkout.js", - "success_criteria": "p95_latency < 200ms", - "comparison": "baseline vs optimized" - } - }, - "phase_2_iteration": { - "condition": "if p95_latency still > 150ms", - "next_hypothesis": "Add Redis caching layer", - "max_iterations": 3 - } - } -} -``` - ---- - -## 6. 安全加固专项场景 - -### 场景描述 -安全审计发现的修复、威胁建模、合规性要求（GDPR、SOC2）等安全相关工作。 - -### 当前Planning的局限性 - -**现有风险检测**： -```json -{ - "conflict_detection": { - "risk_level": "medium", - "risk_factors": ["architecture_complexity"] - } -} -``` - -**安全专项需求**： -- 威胁建模（STRIDE框架） -- 安全审计清单 -- 合规性检查点 -- 渗透测试后的修复优先级 - -### Gap分析 - -| 维度 | 当前支持 | 缺失功能 | -|------|---------|---------| -| **威胁建模** | 无 | ❌ STRIDE/DREAD框架集成 | -| **漏洞优先级** | 无 | ❌ CVSS评分、利用难度评估 | -| **合规检查** | 无 | ❌ GDPR/HIPAA/SOC2检查清单 | -| **攻击面分析** | 无 | ❌ 入口点识别、数据流追踪 | - -### 建议改进 - -**新增Planning模式**: `/workflow:plan --security-hardening` - -```json -{ - "security_hardening": { - "threat_model": { - "framework": "STRIDE", - "assets": ["user_credentials", "payment_data"], - "threats": [ - { - "id": "T-001", - "type": "Spoofing", - "scenario": "攻击者伪造JWT token", - "likelihood": "high", - "impact": "critical", - "mitigation_task": "IMPL-001" - } - ] - }, - "audit_findings": [ - { - "id": "CVE-2024-1234", - "severity": "high", - "cvss_score": 8.5, - "affected_component": "express@4.17.1", - "remediation": "IMPL-002" - } - ], - "compliance": { - "framework": "GDPR", - "requirements": [ - { - "article": "Article 17 (Right to erasure)", - "current_status": "non_compliant", - "gap": "用户数据删除功能缺失", - "implementation": "IMPL-003" - } - ] - } - } -} -``` - ---- - -## 7. 数据迁移场景 - -### 场景描述 -数据库schema变更、数据格式转换、系统迁移等需要数据迁移的场景。 - -### 当前Planning的局限性 - -**现有flow_control**： -```json -{ - "implementation_approach": [ - {"step": 1, "title": "实现功能"}, - {"step": 2, "title": "编写测试"} - ] -} -``` - -**数据迁移流程**： -``` -1. 备份生产数据 -2. 在staging环境验证迁移脚本 -3. 准备回滚脚本 -4. 制定停机时间窗口 -5. 执行迁移 -6. 验证数据一致性 -7. 监控应用健康 -8. 必要时执行回滚 -``` - -### Gap分析 - -| 维度 | 当前支持 | 缺失功能 | -|------|---------|---------| -| **回滚计划** | 无 | ❌ 强制要求回滚脚本 | -| **数据验证** | 无 | ❌ 一致性检查、数据抽样对比 | -| **分阶段迁移** | 无 | ❌ 增量迁移、双写策略 | -| **停机窗口** | 无 | ❌ 时间预估、通知机制 | - -### 建议改进 - -**新增Planning模式**: `/workflow:plan --data-migration` - -```json -{ - "data_migration": { - "migration_type": "schema_change", - "estimated_downtime": "30_minutes", - "affected_tables": ["users", "orders"], - "record_count": 10000000, - "strategy": "online_migration", - "phases": [ - { - "phase": "pre_migration", - "tasks": [ - "IMPL-001: 创建新schema", - "IMPL-002: 实现双写逻辑（写旧表+新表）", - "IMPL-003: 编写验证脚本" - ] - }, - { - "phase": "migration", - "tasks": [ - "IMPL-004: 批量迁移历史数据", - "verification": "每1000条记录对比checksum" - ] - }, - { - "phase": "post_migration", - "tasks": [ - "IMPL-005: 切换读取到新表", - "IMPL-006: 停止双写，删除旧表" - ] - } - ], - "rollback_plan": { - "trigger": "data_inconsistency_detected", - "steps": [ - "停止应用", - "从备份恢复", - "验证数据完整性" - ], - "script": "scripts/rollback_migration_001.sql" - } - } -} -``` - ---- - -## 8. 紧急修复场景 - -### 场景描述 -生产环境严重问题需要立即修复，时间压力下简化流程。 - -### 当前Planning的局限性 - -**现有最快流程**: `/workflow:lite-plan` -- 仍然包含完整的exploration和planning阶段 -- 没有"紧急模式"的流程简化 -- 缺少hotfix分支管理 - -**紧急修复实际需求**： -``` -时间线: -├── T+0: 生产故障告警 -├── T+5min: 确认问题根因 -├── T+15min: 代码修复完成 -├── T+20min: 快速验证（非完整测试） -├── T+25min: 部署到生产 -└── T+30min: 监控确认修复 -``` - -### Gap分析 - -| 维度 | 当前支持 | 缺失功能 | -|------|---------|---------| -| **流程简化** | 标准流程 | ❌ 紧急模式跳过非关键步骤 | -| **快速验证** | 完整测试套件 | ❌ Smoke test快速验证 | -| **Hotfix分支** | 标准分支策略 | ❌ 从production tag创建hotfix分支 | -| **事后补充** | 无 | ❌ 生成"技术债务"任务补充完整修复 | - -### 建议改进 - -**新增命令**: `/workflow:hotfix` - -```bash -/workflow:hotfix --critical "修复支付失败问题" --incident INC-2024-1015 -``` - -**简化流程**： -```json -{ - "hotfix_mode": true, - "incident_id": "INC-2024-1015", - "severity": "critical", - "phases": [ - { - "phase": "diagnosis", - "max_duration": "10_minutes", - "action": "快速根因分析", - "skip": ["deep_code_exploration"] - }, - { - "phase": "fix", - "branch_strategy": "hotfix_from_production_tag", - "implementation": "IMPL-HOTFIX-001", - "skip": ["comprehensive_testing", "code_review"] - }, - { - "phase": "verification", - "test_level": "smoke_test_only", - "acceptance": ["关键路径验证通过"] - }, - { - "phase": "deployment", - "approval": "incident_commander", - "monitoring": "real_time_error_rate" - } - ], - "follow_up_tasks": [ - { - "id": "IMPL-001", - "title": "补充完整测试覆盖", - "type": "tech_debt", - "due_date": "within_3_days" - }, - { - "id": "IMPL-002", - "title": "根因分析报告", - "type": "docs", - "due_date": "within_1_week" - } - ] -} -``` - ---- - -## 9. 依赖升级场景 - -### 场景描述 -升级第三方库、框架或运行时版本，处理breaking changes和兼容性问题。 - -### 当前Planning的局限性 - -**现有依赖处理**： -```json -{ - "dependencies": { - "internal": [...], - "external": [...] - } -} -``` -仅列出依赖，不处理升级策略。 - -**依赖升级实际需求**： -``` -Example: React 17 → React 18 -├── Breaking Changes识别 -│ ├── 自动批处理行为变更 -│ └── Suspense API变化 -├── 兼容性测试 -│ ├── 运行完整测试套件 -│ └── 手动测试关键流程 -├── 渐进式升级 -│ ├── 先升级dev dependencies -│ └── 再升级production dependencies -└── 降级回退方案 - └── package.json.backup -``` - -### Gap分析 - -| 维度 | 当前支持 | 缺失功能 | -|------|---------|---------| -| **Breaking Changes分析** | 无 | ❌ 自动扫描changelog | -| **兼容性测试** | 标准测试 | ❌ 依赖升级专项测试策略 | -| **降级方案** | 无 | ❌ 快速回退到旧版本 | -| **分阶段升级** | 无 | ❌ dev → staging → production策略 | - -### 建议改进 - -**新增Planning模式**: `/workflow:plan --dependency-upgrade` - -```bash -/workflow:plan --dependency-upgrade "React 17 → 18" -``` - -```json -{ - "dependency_upgrade": { - "package": "react", - "from_version": "17.0.2", - "to_version": "18.2.0", - "breaking_changes": [ - { - "change": "Automatic batching", - "impact": "setState调用行为变更", - "affected_files": ["src/components/Form.tsx"], - "mitigation": "IMPL-001: 审查状态更新逻辑" - } - ], - "testing_strategy": { - "unit_tests": "全量运行", - "integration_tests": "全量运行", - "e2e_tests": "关键路径", - "manual_testing": "regression_test_checklist.md" - }, - "rollout_plan": { - "stage_1": "dev_environment", - "stage_2": "staging_environment", - "stage_3": "production_canary_10%", - "stage_4": "production_full_rollout" - }, - "rollback_plan": { - "backup": "package.json + package-lock.json", - "quick_revert": "git revert && npm install" - } - } -} -``` - ---- - -## 10. 实验性探索场景 (Spike/POC) - -### 场景描述 -技术可行性验证、原型开发、快速失败的研究性工作。 - -### 当前Planning的局限性 - -**现有验收标准**： -- 假设任务有明确的成功标准 -- 假设所有任务都会"完成" - -**Spike任务特点**： -- 时间盒限制（固定时间后必须停止） -- 可能结论是"不可行"（这也是成功） -- 输出是"学习成果"而非"生产代码" - -### Gap分析 - -| 维度 | 当前支持 | 缺失功能 | -|------|---------|---------| -| **时间盒** | 无 | ❌ 固定时间预算（探索2天后必须决策） | -| **成功定义** | 功能完成 | ❌ "获得足够信息做决策"即成功 | -| **输出形式** | 代码 | ❌ ADR (Architecture Decision Record) | -| **并行探索** | 无 | ❌ 同时探索多个技术方案 | - -### 建议改进 - -**新增Planning模式**: `/workflow:spike` - -```bash -/workflow:spike --timebox 2days "评估三种状态管理方案" -``` - -```json -{ - "spike_config": { - "research_question": "选择合适的状态管理方案", - "timebox": "2_days", - "parallel_explorations": [ - { - "id": "SPIKE-001", - "approach": "Redux Toolkit", - "success_criteria": "实现一个代表性功能，评估开发体验" - }, - { - "id": "SPIKE-002", - "approach": "Zustand", - "success_criteria": "同样功能对比代码量和性能" - }, - { - "id": "SPIKE-003", - "approach": "Jotai", - "success_criteria": "评估学习曲线和文档质量" - } - ], - "decision_criteria": [ - "开发体验 (权重40%)", - "性能 (权重30%)", - "生态系统 (权重20%)", - "团队熟悉度 (权重10%)" - ], - "output": { - "type": "ADR", - "path": "docs/adr/0005-state-management-choice.md", - "includes": [ - "各方案优缺点对比", - "推荐方案和理由", - "POC代码链接" - ] - }, - "post_spike": { - "decision": "proceed_with_zustand", - "follow_up_task": "IMPL-001: 迁移到Zustand" - } - } -} -``` - ---- - -## 11-15. 其他场景简要分析 - -### 11. 多版本并行维护场景 -**Gap**: 当前session管理假设单版本开发 -**需求**: 需要支持`version_branch`字段，安全补丁向多版本移植 -**建议**: `/workflow:plan --version v2.x --backport-to v1.x,v1.y` - -### 12. 监控和可观测性增强场景 -**Gap**: 当前planning关注业务功能，忽略运维需求 -**需求**: SLI/SLO定义、日志/指标/追踪规划、告警规则设计 -**建议**: `/workflow:plan --observability` 生成包含监控配置的任务 - -### 13. 文档补充场景 -**Gap**: 文档任务缺少模板和验证标准 -**需求**: API文档自动生成、ADR模板、代码注释覆盖率 -**建议**: `/workflow:plan --docs-type api|adr|inline` 根据类型生成结构化任务 - -### 14. DevOps流程改进场景 -**Gap**: Planning聚焦应用代码，忽略基础设施代码 -**需求**: Terraform/Ansible代码规划、CI/CD pipeline优化 -**建议**: `/workflow:plan --infra-as-code` 支持IaC任务规划 - -### 15. 可访问性(A11y)改进场景 -**Gap**: 缺少WCAG标准合规检查 -**需求**: 屏幕阅读器测试、键盘导航、ARIA标签审计 -**建议**: `/workflow:plan --a11y` 生成可访问性测试任务 - ---- - -## 优先级建议 - -### 🔴 高优先级（建议立即实现） - -1. **遗留代码重构支持** (`/workflow:plan --legacy-refactor`) - - **理由**: 大量实际项目面临遗留代码维护 - - **实现成本**: 中等（新增safety-net工具 + strangler pattern模板） - - **影响范围**: test-context-gather, tdd-plan - -2. **紧急修复流程** (`/workflow:hotfix`) - - **理由**: 生产问题需要快速响应 - - **实现成本**: 低（简化现有流程 + hotfix分支策略） - - **影响范围**: 新增独立命令 - -3. **数据迁移专项** (`/workflow:plan --data-migration`) - - **理由**: 数据迁移风险高，需要强制回滚计划 - - **实现成本**: 中等（新增migration-specific验证步骤） - - **影响范围**: flow_control schema, verification phase - -### 🟡 中优先级（建议3个月内实现） - -4. **依赖升级管理** (`/workflow:plan --dependency-upgrade`) -5. **增量式发布** (`/workflow:plan --mode incremental`) -6. **技术债务管理** (`/workflow:debt:assess`) -7. **性能优化专项** (`/workflow:plan --performance-optimization`) - -### 🟢 低优先级（可选增强） - -8-15. 其他场景 - ---- - -## 实现路线图 - -### Phase 1: 核心场景支持（Sprint 1-2） -- [ ] `/workflow:hotfix` - 紧急修复快速通道 -- [ ] `/workflow:plan --legacy-refactor` - 遗留代码安全重构 -- [ ] Enhanced Task JSON Schema扩展（支持新场景字段） - -### Phase 2: 高级场景支持（Sprint 3-4） -- [ ] `/workflow:plan --data-migration` - 数据迁移规划 -- [ ] `/workflow:plan --dependency-upgrade` - 依赖升级管理 -- [ ] `/workflow:debt:assess` - 技术债务评估 - -### Phase 3: 专项优化（Sprint 5-6） -- [ ] `/workflow:plan --performance-optimization` - 性能优化流程 -- [ ] `/workflow:plan --security-hardening` - 安全加固 -- [ ] `/workflow:plan --multi-team` - 多团队协作 - -### Phase 4: 长尾场景（按需实现） -- [ ] `/workflow:spike` - 实验性探索 -- [ ] 其他场景 - ---- - -## 技术实现建议 - -### 1. 扩展Enhanced Task JSON Schema - -**当前schema** (5个核心字段): -```json -{ - "id": "...", - "title": "...", - "status": "...", - "meta": {...}, - "context": {...}, - "flow_control": {...} -} -``` - -**扩展字段建议**: -```json -{ - "scenario_type": "legacy_refactor|data_migration|hotfix|...", - "scenario_config": { - // 场景特定配置，根据scenario_type动态验证 - } -} -``` - -### 2. 命令层扩展 - -**新增参数**: `--scenario ` 或 `--mode ` - -```bash -/workflow:plan --scenario legacy-refactor "重构支付模块" -/workflow:plan --scenario data-migration "迁移用户表schema" -/workflow:hotfix --critical "修复内存泄漏" -``` - -### 3. Agent增强 - -**action-planning-agent.md** 需要支持: -- 场景识别逻辑 -- 场景特定的pre_analysis步骤 -- 场景特定的验收标准模板 - ---- - -## 结论 - -当前Planning系统在标准软件开发流程上设计优秀，但在以下15类特殊场景存在支持空白： - -**关键发现**: -1. **遗留代码**、**紧急修复**、**数据迁移**是最紧迫的缺失场景 -2. 当前系统架构具备良好扩展性，可通过scenario_type字段扩展 -3. 建议采用渐进式实现策略，优先支持高影响场景 - -**影响评估**: -- **高**: 遗留代码重构、紧急修复、数据迁移（影响50%+实际项目） -- **中**: 依赖升级、技术债务、性能优化（影响30%项目） -- **低**: 其他场景（影响<20%项目，但对特定领域关键） - -**下一步行动**: -1. 评审本分析报告，确认优先级 -2. 设计Enhanced Task JSON Schema扩展方案 -3. 实现Phase 1高优先级场景（预计2个sprint） -4. 迭代收集用户反馈，调整后续优先级 - ---- - -**文档版本**: 1.0 -**作者**: Claude (Sonnet 4.5) -**审阅状态**: 待审阅 diff --git a/PROJECT_INTRODUCTION.md b/PROJECT_INTRODUCTION.md deleted file mode 100644 index bf994510..00000000 --- a/PROJECT_INTRODUCTION.md +++ /dev/null @@ -1,401 +0,0 @@ -# 🚀 Claude Code Workflow (CCW): 下一代多智能体软件开发自动化框架 - -[![Version](https://img.shields.io/badge/version-v3.2.1-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) -[![MCP工具](https://img.shields.io/badge/🔧_MCP工具-实验性-orange.svg)](https://github.com/modelcontextprotocol) -[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) - ---- - -## 📋 项目概述 - -**Claude Code Workflow (CCW)** 是一个革命性的多智能体自动化开发框架，它通过智能工作流管理和自主执行来协调复杂的软件开发任务。CCW 不仅仅是一个工具，它是一个完整的开发生态系统，将人工智能的强大能力与结构化的开发流程相结合。 - -## 🎯 概念设计与核心理念 - -### 设计哲学 - -CCW 的设计基于几个核心理念： - -1. **🧠 智能协作而非替代**: 不是完全取代开发者，而是作为智能助手协同工作 -2. **📊 JSON 优先架构**: 以 JSON 作为单一数据源，消除同步复杂性 -3. **🔄 完整的开发生命周期**: 覆盖从构思到部署的每一个环节 -4. **🤖 多智能体协调**: 专门的智能体处理不同类型的开发任务 -5. **⚡ 原子化会话管理**: 超快速的上下文切换和并行工作 - -### 架构创新 - -```mermaid -graph TD - A[🖥️ CLI 接口层] --> B[📋 会话管理层] - B --> C[📊 JSON 任务数据层] - C --> D[🤖 多智能体编排层] - - A --> A1[Gemini CLI - 分析探索] - A --> A2[Codex CLI - 自主开发] - A --> A3[Qwen CLI - 架构生成] - - B --> B1[.active-session 标记] - B --> B2[工作流会话状态] - - C --> C1[IMPL-*.json 任务定义] - C --> C2[动态任务分解] - C --> C3[依赖关系映射] - - D --> D1[概念规划智能体] - D --> D2[代码开发智能体] - D --> D3[测试审查智能体] - D --> D4[记忆桥接智能体] -``` - -## 🔥 解决的核心问题 - -### 1. **项目上下文丢失问题** -**传统痛点**: 在复杂项目中，开发者经常在不同任务间切换时丢失上下文，需要重新理解代码结构和业务逻辑。 - -**CCW 解决方案**: -- 📚 **智能内存更新系统**: 自动维护 `CLAUDE.md` 文档，实时跟踪代码库变化 -- 🔄 **会话持久化**: 完整保存工作流状态，支持无缝恢复 -- 📊 **上下文继承**: 任务间自动传递相关上下文信息 - -### 2. **开发流程不统一问题** -**传统痛点**: 团队成员使用不同的开发流程，导致代码质量不一致，难以协作。 - -**CCW 解决方案**: -- 🔄 **标准化工作流**: 强制执行 Brainstorm → Plan → Verify → Execute → Test → Review 流程 -- ✅ **质量门禁**: 每个阶段都有验证机制确保质量 -- 📋 **可追溯性**: 完整记录决策过程和实现细节 - -### 3. **重复性任务自动化不足** -**传统痛点**: 大量重复性的代码生成、测试编写、文档更新工作消耗开发者精力。 - -**CCW 解决方案**: -- 🤖 **多智能体自动化**: 不同类型任务分配给专门的智能体 -- 🧪 **自动测试生成**: 根据实现自动生成全面的测试套件 -- 📝 **文档自动更新**: 代码变更时自动更新相关文档 - -### 4. **代码库理解困难** -**传统痛点**: 在大型项目中，理解现有代码结构和模式需要大量时间。 - -**CCW 解决方案**: -- 🔧 **MCP 工具集成**: 通过 Model Context Protocol 实现高级代码分析 -- 🔍 **模式识别**: 自动识别代码库中的设计模式和架构约定 -- 🌐 **外部最佳实践**: 集成外部 API 模式和行业最佳实践 - -## 🛠️ 核心工作流介绍 - -### 📊 JSON 优先数据模型 - -CCW 采用独特的 JSON 优先架构，所有工作流状态都存储在结构化的 JSON 文件中： - -```json -{ - "id": "IMPL-1.2", - "title": "实现 JWT 认证系统", - "status": "pending", - "meta": { - "type": "feature", - "agent": "code-developer" - }, - "context": { - "requirements": ["JWT 认证", "OAuth2 支持"], - "focus_paths": ["src/auth", "tests/auth"], - "acceptance": ["JWT 验证工作", "OAuth 流程完整"] - }, - "flow_control": { - "pre_analysis": [...], - "implementation_approach": {...} - } -} -``` - -### 🧠 智能内存管理系统 - -#### 自动内存更新 -CCW 的内存更新系统是其核心特色之一： - -```bash -# 日常开发后的自动更新 -/update-memory-related # 智能分析最近变更，只更新相关模块 - -# 重大变更后的全面更新 -/update-memory-full # 完整扫描项目，重建所有文档 - -# 模块特定更新 -cd src/auth && /update-memory-related # 针对特定模块的精准更新 -``` - -#### CLAUDE.md 四层架构 -``` -CLAUDE.md (项目级总览) -├── src/CLAUDE.md (源码层文档) -├── src/auth/CLAUDE.md (模块层文档) -└── src/auth/jwt/CLAUDE.md (组件层文档) -``` - -### 🔧 Flow Control 与 CLI 工具集成 - -#### 预分析阶段 (pre_analysis) -```json -"pre_analysis": [ - { - "step": "mcp_codebase_exploration", - "action": "使用 MCP 工具探索代码库结构", - "command": "mcp__code-index__find_files(pattern=\"[task_focus_patterns]\")", - "output_to": "codebase_structure" - }, - { - "step": "mcp_external_context", - "action": "获取外部 API 示例和最佳实践", - "command": "mcp__exa__get_code_context_exa(query=\"[task_technology] [task_patterns]\")", - "output_to": "external_context" - }, - { - "step": "gather_task_context", - "action": "分析任务上下文，不进行实现", - "command": "gemini-wrapper -p \"分析 [task_title] 的现有模式和依赖\"", - "output_to": "task_context" - } -] -``` - -#### 实现方法定义 (implementation_approach) -```json -"implementation_approach": { - "task_description": "基于 [design] 分析结果实现 JWT 认证", - "modification_points": [ - "使用 [parent] 模式添加 JWT 生成", - "基于 [context] 实现验证中间件" - ], - "logic_flow": [ - "用户登录 → 使用 [inherited] 验证 → 生成 JWT", - "受保护路由 → 提取 JWT → 使用 [shared] 规则验证" - ], - "target_files": [ - "src/auth/login.ts:handleLogin:75-120", - "src/middleware/auth.ts:validateToken" - ] -} -``` - -### 🚀 CLI 工具协同工作 - -#### 三大 CLI 工具分工 -```mermaid -graph LR - A[Gemini CLI] --> A1[深度分析] - A --> A2[模式识别] - A --> A3[架构理解] - - B[Qwen CLI] --> B1[架构设计] - B --> B2[代码生成] - B --> B3[系统规划] - - C[Codex CLI] --> C1[自主开发] - C --> C2[错误修复] - C --> C3[测试生成] -``` - -#### 智能工具选择策略 -CCW 基于任务类型自动选择最适合的工具： - -```bash -# 探索和理解阶段 -/cli:analyze --tool gemini "认证系统架构模式" - -# 设计和规划阶段 -/cli:mode:plan --tool qwen "微服务认证架构设计" - -# 实现和开发阶段 -/cli:execute --tool codex "实现 JWT 认证系统" -``` - -### 🔄 完整开发生命周期 - -#### 1. 头脑风暴阶段 -```bash -# 多角色专家视角分析 -/workflow:brainstorm:system-architect "用户认证系统" -/workflow:brainstorm:security-expert "认证安全考虑" -/workflow:brainstorm:ui-designer "认证用户体验" - -# 综合所有视角 -/workflow:brainstorm:synthesis -``` - -#### 2. 规划与验证 -```bash -# 创建实现计划 -/workflow:plan "用户认证系统与 JWT 支持" - -# 双重验证机制 -/workflow:plan-verify # Gemini 战略 + Codex 技术双重验证 -``` - -#### 3. 执行与测试 -```bash -# 智能体协调执行 -/workflow:execute - -# 自动生成测试工作流 -/workflow:test-gen WFS-user-auth-system -``` - -#### 4. 审查与文档 -```bash -# 质量审查 -/workflow:review - -# 分层文档生成 -/workflow:docs "all" -``` - -## 🔧 技术创新亮点 - -### 1. **MCP 工具集成** *(实验性)* -- **Exa MCP Server**: 获取真实世界的 API 模式和最佳实践 -- **Code Index MCP**: 高级内部代码库搜索和索引 -- **自动回退**: MCP 不可用时无缝切换到传统工具 - -### 2. **原子化会话管理** -```bash -# 超快速会话切换 (<10ms) -.workflow/.active-user-auth-system # 简单的文件标记 - -# 并行会话支持 -.workflow/WFS-user-auth/ # 认证系统会话 -.workflow/WFS-payment/ # 支付系统会话 -.workflow/WFS-dashboard/ # 仪表板会话 -``` - -### 3. **智能上下文传递** -- **依赖上下文**: 任务完成后自动传递关键信息给依赖任务 -- **继承上下文**: 子任务自动继承父任务的设计决策 -- **共享上下文**: 会话级别的全局规则和模式 - -### 4. **动态任务分解** -```json -// 主任务自动分解为子任务 -"IMPL-1": "用户认证系统", -"IMPL-1.1": "JWT 令牌生成", -"IMPL-1.2": "认证中间件", -"IMPL-1.3": "用户登录接口" -``` - -## 🎯 使用场景示例 - -### 场景 1: 新功能开发 -```bash -# 1. 启动专门会话 -/workflow:session:start "OAuth2 集成" - -# 2. 多视角头脑风暴 -/workflow:brainstorm:system-architect "OAuth2 架构设计" -/workflow:brainstorm:security-expert "OAuth2 安全考虑" - -# 3. 执行完整开发流程 -/workflow:plan "OAuth2 与现有认证系统集成" -/workflow:plan-verify -/workflow:execute -/workflow:test-gen WFS-oauth2-integration -/workflow:review -``` - -### 场景 2: 紧急错误修复 -```bash -# 快速错误解决工作流 -/workflow:session:start "支付验证修复" -/cli:mode:bug-diagnosis --tool gemini "并发请求时支付验证失败" -/cli:execute --tool codex "修复支付验证竞态条件" -/workflow:review -``` - -### 场景 3: 架构重构 -```bash -# 深度架构分析和重构 -/workflow:session:start "微服务重构" -/cli:analyze --tool gemini "当前单体架构的技术债务" -/workflow:plan "单体到微服务的迁移策略" -/workflow:execute -/workflow:test-gen WFS-microservice-refactoring -``` - -## 🌟 核心优势 - -### 1. **提升开发效率** -- ⚡ **10x 上下文切换速度**: 原子化会话管理 -- 🤖 **自动化重复任务**: 90% 的样板代码和测试自动生成 -- 📊 **智能决策支持**: 基于历史模式的建议 - -### 2. **保证代码质量** -- ✅ **强制质量门禁**: 每个阶段的验证机制 -- 🔍 **自动模式检测**: 识别并遵循现有代码约定 -- 📝 **完整可追溯性**: 从需求到实现的完整记录 - -### 3. **降低学习成本** -- 📚 **智能文档系统**: 自动维护的项目知识库 -- 🔄 **标准化流程**: 统一的开发工作流 -- 💡 **最佳实践集成**: 外部优秀模式的自动引入 - -### 4. **支持团队协作** -- 🔀 **并行会话支持**: 多人同时工作不冲突 -- 📊 **透明的进度跟踪**: 实时可见的任务状态 -- 🤝 **知识共享**: 决策过程和实现细节的完整记录 - -## 🚀 开始使用 - -### 快速安装 -```powershell -# Windows 一键安装 -Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content - -# 验证安装 -/workflow:session:list -``` - -### 可选 MCP 工具增强 -```bash -# 安装 Exa MCP Server (外部 API 模式) -# 安装指南: https://github.com/exa-labs/exa-mcp-server - -# 安装 Code Index MCP (高级代码搜索) -# 安装指南: https://github.com/johnhuang316/code-index-mcp -``` - -## 📈 项目状态与路线图 - -### 当前状态 (v2.1.0-experimental) -- ✅ 核心多智能体系统完成 -- ✅ JSON 优先架构稳定 -- ✅ 完整工作流生命周期支持 -- 🧪 MCP 工具集成 (实验性) -- ✅ 智能内存管理系统 - -### 即将推出 -- 🔮 **AI 辅助代码审查**: 更智能的质量检测 -- 🌐 **云端协作支持**: 团队级工作流共享 -- 📊 **性能分析集成**: 自动性能优化建议 -- 🔧 **更多 MCP 工具**: 扩展外部工具生态 - -## 🤝 社区与支持 - -- 📚 **文档**: [项目 Wiki](https://github.com/catlog22/Claude-Code-Workflow/wiki) -- 🐛 **问题反馈**: [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues) -- 💬 **社区讨论**: [讨论区](https://github.com/catlog22/Claude-Code-Workflow/discussions) -- 📋 **更新日志**: [发布历史](CHANGELOG.md) - ---- - -## 💡 结语 - -**Claude Code Workflow** 不仅仅是一个开发工具，它代表了软件开发工作流的未来趋势。通过智能化的多智能体协作、结构化的开发流程和先进的上下文管理，CCW 让开发者能够专注于创造性工作，而将重复性和机械性任务交给 AI 助手。 - -我们相信，未来的软件开发将是人机协作的典范，CCW 正是这一愿景的先锋实践。 - -🌟 **立即体验 CCW，开启您的智能化开发之旅！** - -[![⭐ Star on GitHub](https://img.shields.io/badge/⭐-Star%20on%20GitHub-yellow.svg)](https://github.com/catlog22/Claude-Code-Workflow) -[![🚀 Latest Release](https://img.shields.io/badge/🚀-Download%20Latest-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases/latest) - ---- - -*本文档由 Claude Code Workflow 的智能文档系统自动生成和维护* \ No newline at end of file