From 51bd51ea60d4338c27686d1f55abea9c9f40647c Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 6 Oct 2025 12:19:18 +0800 Subject: [PATCH] refactor: optimize docs workflow with lightweight planning strategy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Core Changes**: - Shift from heavy analysis in planning to targeted analysis in execution - Reduce main process context by collecting only metadata (paths, structure) - Simplify pre_analysis steps to be more declarative **docs.md optimizations**: - Phase 2: Lightweight metadata collection (get_modules_by_depth.sh + Code Index MCP) - Planning phase now collects only paths and structure, not file content - IMPL-001: Simplified to 2 pre_analysis steps (structure + tech stack from config files only) - IMPL-002: Removed system_context loading, single focused analysis step - IMPL-N (API): Replace rg with mcp__code-index__search_code_advanced for better structure **doc-generator.md optimizations**: - Add "Scope-Limited Analysis" philosophy - Add "Optimized Execution Model" section - Emphasize analysis is always limited to focus_paths to prevent context explosion **Benefits**: - Main process context stays minimal (no risk of overflow) - Each task has controlled, scoped context - Better separation: planning = metadata, execution = deep analysis - More maintainable pre_analysis steps (less nested commands) - Better use of MCP tools for structured data 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/agents/doc-generator.md | 9 +++ .claude/commands/workflow/tools/docs.md | 84 ++++++++++++------------- 2 files changed, 51 insertions(+), 42 deletions(-) diff --git a/.claude/agents/doc-generator.md b/.claude/agents/doc-generator.md index 6c3910d2..59473359 100644 --- a/.claude/agents/doc-generator.md +++ b/.claude/agents/doc-generator.md @@ -22,9 +22,18 @@ You are an expert technical documentation specialist. Your responsibility is to - **Autonomous Execution**: You are not a script runner; you are a goal-oriented worker that understands and executes a plan. - **Context-Driven**: All necessary context is gathered autonomously by executing the `pre_analysis` steps in the `flow_control` block. +- **Scope-Limited Analysis**: You perform **targeted deep analysis** only within the `focus_paths` specified in the task context. - **Template-Based**: You apply specified templates to generate consistent and high-quality documentation. - **Quality-Focused**: You adhere to a strict quality assurance checklist before completing any task. +## Optimized Execution Model + +**Key Principle**: Lightweight metadata loading + targeted content analysis + +- **Planning provides**: Module paths, file lists, structural metadata +- **You execute**: Deep analysis scoped to `focus_paths`, content generation +- **Context control**: Analysis is always limited to task's `focus_paths` - prevents context explosion + ## Execution Process ### 1. Task Ingestion diff --git a/.claude/commands/workflow/tools/docs.md b/.claude/commands/workflow/tools/docs.md index b1a530bb..8b16473a 100644 --- a/.claude/commands/workflow/tools/docs.md +++ b/.claude/commands/workflow/tools/docs.md @@ -14,11 +14,16 @@ examples: ## Purpose -**`/workflow:docs` is a pure planner/orchestrator** - it analyzes project structure, decomposes documentation work into tasks, and generates execution plans. It does **NOT** generate any documentation content itself. +**`/workflow:docs` is a lightweight planner/orchestrator** - it analyzes project structure using metadata tools, decomposes documentation work into tasks, and generates execution plans. It does **NOT** generate any documentation content itself. -**Key Principle**: Separation of Concerns -- **docs.md** → Planning, session creation, task generation -- **doc-generator.md** → Execution, content generation, quality assurance +**Key Principle**: Lightweight Planning + Targeted Execution +- **docs.md** → Collect metadata (paths, structure), generate task JSONs with path references +- **doc-generator.md** → Execute targeted analysis on focus_paths, generate content + +**Optimization Philosophy**: +- **Planning phase**: Minimal context - only metadata (module paths, file lists via `get_modules_by_depth.sh` and Code Index MCP) +- **Task JSON**: Store path references, not content +- **Execution phase**: Targeted deep analysis within focus_paths scope ## Usage @@ -75,11 +80,18 @@ mkdir -p "${session_dir}"/{.task,.process,.summaries} touch ".workflow/.active-WFS-docs-${timestamp}" ``` -#### Phase 2: Project Structure Analysis (MANDATORY) +#### Phase 2: Lightweight Metadata Collection (MANDATORY) ```bash -# Run get_modules_by_depth.sh for module hierarchy +# Step 1: Run get_modules_by_depth.sh for module hierarchy (metadata only) module_data=$(~/.claude/scripts/get_modules_by_depth.sh) # Format: depth:N|path:|files:N|size:N|has_claude:yes/no + +# Step 2: Use Code Index MCP for file discovery (optional, for better precision) +# Example: mcp__code-index__find_files(pattern="src/**/") +# This finds directories without loading content + +# IMPORTANT: Do NOT read file contents in planning phase +# Only collect: paths, file counts, module structure ``` #### Phase 3: Quick Documentation Assessment @@ -172,32 +184,27 @@ fi "pre_analysis": [ { "step": "discover_project_structure", - "action": "Analyze project structure and modules", + "action": "Get project module hierarchy metadata", "command": "bash(~/.claude/scripts/get_modules_by_depth.sh)", - "output_to": "system_structure" - }, - { - "step": "discover_project_files", - "action": "Identify key project files", - "command": "bash(find . -maxdepth 2 -type f \\( -name '*.json' -o -name '*.md' -o -name '*.yml' -o -name '*.yaml' \\) | head -30)", - "output_to": "project_files" + "output_to": "system_structure", + "on_error": "fail", + "note": "Lightweight metadata only - no file content" }, { "step": "analyze_tech_stack", - "action": "Analyze technology stack and dependencies", - "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project technology stack\\nTASK: Extract tech stack, architecture patterns, design principles\\nMODE: analysis\\nCONTEXT: System structure: [system_structure]\\n Project files: [project_files]\\nEXPECTED: Technology analysis with architecture style\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt)\")", - "output_to": "tech_analysis", - "on_error": "fail", - "note": "Command is built at planning time based on $tool variable (gemini/qwen/codex)" + "action": "Analyze technology stack from key config files", + "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project technology stack\\nTASK: Extract tech stack from key config files\\nMODE: analysis\\nCONTEXT: @{package.json,pom.xml,build.gradle,requirements.txt,go.mod,Cargo.toml,CLAUDE.md}\\nEXPECTED: Technology list and architecture style\\nRULES: Be concise, focus on stack only\")", + "output_to": "tech_stack_analysis", + "on_error": "skip_optional", + "note": "Only analyze config files - small, controlled context" } ], "implementation_approach": { - "task_description": "Use tech_analysis to populate Project-Level Documentation Template", + "task_description": "Use system_structure and tech_stack_analysis to populate Project Overview Template", "logic_flow": [ "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt", - "Parse tech_analysis for: purpose, architecture, tech stack, design principles", - "Fill template sections with extracted information", - "Generate navigation links to module/API docs", + "Fill sections using [system_structure] and [tech_stack_analysis]", + "Generate navigation links based on module paths", "Format output as Markdown" ] }, @@ -239,27 +246,19 @@ fi "flow_control": { "pre_analysis": [ { - "step": "load_system_context", - "action": "Load system architecture from IMPL-001", - "command": "bash(cat .workflow/WFS-docs-*/IMPL-001-system_structure.output 2>/dev/null || ~/.claude/scripts/get_modules_by_depth.sh)", - "output_to": "system_context", - "on_error": "skip_optional" - }, - { - "step": "analyze_module_structure", - "action": "Deep analysis of module structure and API", - "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module comprehensively\\nTASK: Extract module purpose, architecture, public API, dependencies\\nMODE: analysis\\nCONTEXT: @{**/*}\\n System: [system_context]\\nEXPECTED: Complete module analysis for documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")", + "step": "analyze_module_content", + "action": "Perform deep analysis of the specific module's content", + "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document 'auth' module comprehensively\\nTASK: Extract module purpose, architecture, public API, dependencies\\nMODE: analysis\\nCONTEXT: @{**/*}\\nEXPECTED: Structured analysis of module content\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")", "output_to": "module_analysis", "on_error": "fail", - "note": "For qwen: qwen-wrapper | For codex: codex -C src/auth --full-auto exec \"...\" --skip-git-repo-check" + "note": "Analysis strictly limited to focus_paths ('src/auth') - controlled context" } ], "implementation_approach": { - "task_description": "Use module_analysis to populate Module-Level Documentation Template", + "task_description": "Use the detailed [module_analysis] to populate the Module-Level Documentation Template", "logic_flow": [ "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt", - "Parse module_analysis for: purpose, components, API, dependencies", - "Fill template sections with extracted information", + "Fill sections using [module_analysis]", "Generate code examples from actual usage", "Format output as Markdown" ] @@ -369,18 +368,19 @@ fi "pre_analysis": [ { "step": "discover_api_endpoints", - "action": "Find all API routes and endpoints", - "command": "bash(rg -t ts -t js '(router\\.|app\\.|@(Get|Post|Put|Delete|Patch))' src/ --no-heading | head -100)", + "action": "Find all API routes and endpoints using MCP", + "command": "mcp__code-index__search_code_advanced(pattern='router\\.|app\\.|@(Get|Post|Put|Delete|Patch)', file_pattern='*.{ts,js}', output_mode='content', head_limit=100)", "output_to": "endpoint_discovery", - "on_error": "skip_optional" + "on_error": "skip_optional", + "note": "Use MCP instead of rg for better structure" }, { "step": "analyze_api_structure", "action": "Analyze API structure and patterns", - "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document API comprehensively\\nTASK: Extract endpoints, auth, request/response formats\\nMODE: analysis\\nCONTEXT: @{src/api/**/*,src/routes/**/*,src/controllers/**/*}\\n Endpoints: [endpoint_discovery]\\nEXPECTED: Complete API documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt)\")", + "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document API comprehensively\\nTASK: Extract endpoints, auth, request/response formats\\nMODE: analysis\\nCONTEXT: @{src/api/**/*,src/routes/**/*,src/controllers/**/*}\\nEXPECTED: Complete API documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt)\")", "output_to": "api_analysis", "on_error": "fail", - "note": "Tool-specific: gemini-wrapper | qwen-wrapper | codex -C src/api exec" + "note": "Analysis limited to API-related paths - controlled context" } ], "implementation_approach": {