feat: Add task-specific path management system for precise CLI analysis

- Add 'paths' field to task JSON schema with semicolon-separated concrete paths - Create read-task-paths.sh script to convert paths to Gemini @ format - Update all agents to use task-specific paths instead of --all-files - Integrate get_modules_by_depth.sh for project structure discovery - Update workflow planning to populate paths field automatically - Enhance execute command to pass task-specific paths to agents - Update documentation for new path management system 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-05 01:50:27 +08:00 · 2025-09-13 11:28:16 +08:00
parent e8de626387
commit 9a4003deda
10 changed files with 146 additions and 7 deletions
--- a/.claude/agents/action-planning-agent.md
+++ b/.claude/agents/action-planning-agent.md
@@ -42,8 +42,9 @@ You are a pure execution agent specialized in creating actionable implementation
 ```

 **Analysis CLI Usage Standards**:
- **Gemini CLI**: Follow unified guidelines: `@~/.claude/workflows/gemini-unified.md`
- **Codex CLI**: Follow unified guidelines: `@~/.claude/workflows/codex-unified.md`
+- **Gemini CLI**: Use task-specific paths: `gemini -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) @{CLAUDE.md}" `
+- **Codex CLI**: Use task-specific paths: `codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]"`
+- **Follow Guidelines**: @~/.claude/workflows/gemini-unified.md and @~/.claude/workflows/codex-unified.md

 ### Deep Analysis Execution
 **When DEEP_ANALYSIS_REQUIRED flag is present:**
--- a/.claude/agents/code-developer.md
+++ b/.claude/agents/code-developer.md
@@ -56,8 +56,10 @@ ELIF context insufficient OR task has analysis marker:
  - **Purpose**: Enables autonomous development with intelligent file discovery and code generation

 **Analysis CLI Usage Standards**:
- **Gemini CLI**: Follow unified guidelines: @~/.claude/workflows/gemini-unified.md
- **Codex CLI**: Follow unified guidelines: @~/.claude/workflows/codex-unified.md
+- **Gemini CLI**: Use task-specific paths from JSON: `gemini -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]" `
+- **Codex CLI**: Use task-specific paths from JSON: `codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]"`
+- **Follow Guidelines**: @~/.claude/workflows/gemini-unified.md and @~/.claude/workflows/codex-unified.md
+

 **Test-Driven Development**:
 - Write tests first (red → green → refactor)
--- a/.claude/agents/code-review-test-agent.md
+++ b/.claude/agents/code-review-test-agent.md
@@ -76,6 +76,11 @@ When [GEMINI_CLI_REQUIRED] flag is present or complexity triggers apply, gather
 Use the targeted review context template:
@~/.claude/workflows/gemini-unified.md

+**Gemini CLI Command**:
+```bash
+gemini -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) @{CLAUDE.md} [review-analysis-prompt]"
+```
+
 This executes a change-specific Gemini CLI command that identifies:
 - **Change understanding**: What specific task was being implemented
 - **Repository conventions**: Standards used in similar files and functions
@@ -89,6 +94,11 @@ When [CODEX_CLI_REQUIRED] flag is present, execute autonomous analysis:
 Use the autonomous development context template:
@~/.claude/workflows/codex-unified.md

+**Codex CLI Command**:
+```bash
+codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [autonomous-review-prompt]"
+```
+
 This executes autonomous Codex CLI analysis that provides:
 - **Autonomous understanding**: Intelligent discovery of implementation context
 - **Code generation insights**: Autonomous development recommendations
--- a/.claude/agents/conceptual-planning-agent.md
+++ b/.claude/agents/conceptual-planning-agent.md
@@ -53,6 +53,7 @@ def handle_analysis_markers(prompt):
    if "[GEMINI_CLI_REQUIRED]" in prompt:
        for dimension in dimensions:
            result = execute_gemini_cli(
+                command=f"gemini -p \"$(.claude/scripts/read-task-paths.sh [task-json-file]) @{{CLAUDE.md}} {dimension}\"",
                dimension=dimension,
                role_context=role,
                topic=topic
@@ -61,6 +62,7 @@ def handle_analysis_markers(prompt):
    
    elif "[CODEX_CLI_REQUIRED]" in prompt:
        result = execute_codex_cli(
+            command=f"codex --full-auto exec \"$(.claude/scripts/read-task-paths.sh [task-json-file]) {topic}\"",
            autonomous_analysis=True,
            role_context=role, 
            topic=topic
--- a/.claude/commands/workflow/execute.md
+++ b/.claude/commands/workflow/execute.md
@@ -168,6 +168,9 @@ Task(subagent_type="code-developer",
     - Risks: Schema changes require database migration, Existing user data compatibility
     - Performance: Index JWT fields for faster lookups
     
+     Focus Paths (from task JSON): $(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
+     Gemini Command: gemini -p "$(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}"
+     
     IMPORTANT: Update TODO_LIST.md and create summary in provided directories upon completion.
     Use implementation details above for precise, targeted development.",
     description="Execute impl-1.2 with full workflow context and implementation details")
@@ -237,10 +240,14 @@ Task(subagent_type="code-developer",
     - Workflow Directory: .workflow/WFS-user-auth/
     - TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md
     - Summaries Directory: .workflow/WFS-user-auth/.summaries/
+     - Task JSON: .workflow/WFS-user-auth/.task/impl-1.2.json
     
-     CRITICAL: Update TODO_LIST.md and create completion summary using provided paths.",
+     Focus Paths: $(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
+     Analysis Command: Use gemini -p \"$(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\"
     
-     description="Agent executes with full discovered context")
+     CRITICAL: Use task-specific paths for focused analysis. Update TODO_LIST.md and create completion summary using provided paths.",
+     
+     description="Agent executes with task-specific paths and full discovered context")
 ```

 ### Status Tracking Integration
--- a/.claude/commands/workflow/plan.md
+++ b/.claude/commands/workflow/plan.md
@@ -91,6 +91,7 @@ The command automatically detects input type:
 - Automatically creates .task/ files when complexity warrants
 - Generates hierarchical task structure (max 3 levels)
 - Updates session state with task references
+- Runs project structure analysis to populate paths field

 ### Implementation Field Requirements
 ⚠️ **CRITICAL**: All generated tasks must include detailed implementation guidance
@@ -132,6 +133,31 @@ The command automatically detects input type:
 - **context_notes**: Dependencies, risks, performance considerations
 - **analysis_source**: manual|gemini|codex|auto-detected

+**Paths Field Population Process**:
+1. **Project Structure Analysis**: Run `get_modules_by_depth.sh` to discover project structure
+2. **Relevance Filtering**: Match discovered modules to task requirements
+3. **Path Selection**: Choose concrete directories/files (avoid wildcards)
+4. **Format**: Semicolon-separated list (e.g., `"src/auth;tests/auth;config/auth.json"`)
+
+**Path Selection Strategy**:
+```pseudo
+# Step 1: Analyze project structure
+modules = Bash(.claude/scripts/get_modules_by_depth.sh list)
+
+# Step 2: Extract relevant modules based on task scope
+relevant_paths = []
+for module in modules:
+    if matches_task_scope(module.path, task_requirements):
+        relevant_paths.append(module.path)
+
+# Step 3: Add specific files mentioned in requirements
+specific_files = extract_file_mentions(task_requirements)
+relevant_paths.extend(specific_files)
+
+# Step 4: Format as semicolon-separated string
+task.paths = join(relevant_paths, ";")
+```
+
 **Quality Standards**:
 - logic_flow must use specified symbols (───►, ◊───, ◄───)
 - Each file must have specific location (function name or line range)
--- a/.claude/scripts/read-task-paths.sh
+++ b/.claude/scripts/read-task-paths.sh
@@ -0,0 +1,56 @@
+#!/bin/bash
+# Read paths field from task JSON and convert to Gemini @ format
+# Usage: read-task-paths.sh [task-json-file]
+
+TASK_FILE="$1"
+
+if [ -z "$TASK_FILE" ]; then
+    echo "Usage: read-task-paths.sh [task-json-file]" >&2
+    exit 1
+fi
+
+if [ ! -f "$TASK_FILE" ]; then
+    echo "Error: Task file '$TASK_FILE' not found" >&2
+    exit 1
+fi
+
+# Extract paths field from JSON
+paths=$(grep -o '"paths":[[:space:]]*"[^"]*"' "$TASK_FILE" | sed 's/"paths":[[:space:]]*"\([^"]*\)"/\1/')
+
+if [ -z "$paths" ]; then
+    # No paths field found, return empty @ format
+    echo "@{}"
+    exit 0
+fi
+
+# Convert semicolon-separated paths to comma-separated @ format
+formatted_paths=$(echo "$paths" | sed 's/;/,/g')
+
+# For directories, append /**/* to get all files
+# For files (containing .), keep as-is
+IFS=',' read -ra path_array <<< "$formatted_paths"
+result_paths=()
+
+for path in "${path_array[@]}"; do
+    # Trim whitespace
+    path=$(echo "$path" | xargs)
+    
+    if [ -n "$path" ]; then
+        # Check if path is a directory (no extension) or file (has extension)
+        if [[ "$path" == *.* ]]; then
+            # File path - keep as is
+            result_paths+=("$path")
+        else
+            # Directory path - add wildcard expansion
+            result_paths+=("$path/**/*")
+        fi
+    fi
+done
+
+# Output Gemini @ format
+printf "@{"
+printf "%s" "${result_paths[0]}"
+for i in "${result_paths[@]:1}"; do
+    printf ",%s" "$i"
+done
+printf "}"
--- a/.claude/workflows/workflow-architecture.md
+++ b/.claude/workflows/workflow-architecture.md
@@ -75,7 +75,7 @@ Each session directory contains `workflow-session.json`:
 - **Performance**: Direct JSON access without parsing overhead

 ### Task JSON Schema
-All task files use this 9-field schema:
+All task files use this 10-field schema:

 ```json
 {
@@ -84,6 +84,7 @@ All task files use this 9-field schema:
  "status": "pending|active|completed|blocked|container",
  "type": "feature|bugfix|refactor|test|docs", 
  "agent": "code-developer|planning-agent|code-review-test-agent",
+  "paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts",
  
  "context": {
    "requirements": ["JWT authentication", "OAuth2 support"],
@@ -147,6 +148,34 @@ All task files use this 9-field schema:
 }
 ```

+### Paths Field Details
+
+The **paths** field specifies concrete project paths (folders and files) relevant to the task implementation:
+
+#### Path Format
+- **Semicolon-separated list**: `"folder1;folder2;specific_file.ts"`
+- **Concrete paths**: Use actual directory/file names without wildcards
+- **Mixed types**: Can include both directories and specific files
+- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
+
+#### Path Selection Strategy
+- **Directories**: Include relevant module directories (e.g., `src/auth`, `tests/auth`)
+- **Specific files**: Include files explicitly mentioned in requirements (e.g., `config/auth.json`)
+- **Avoid wildcards**: Use concrete paths discovered via `get_modules_by_depth.sh`
+- **Focus scope**: Only include paths directly related to task implementation
+
+#### Examples
+```json
+// Authentication system task
+"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts"
+
+// UI component task
+"paths": "src/components/Button;src/styles;tests/components"
+
+// Database migration task  
+"paths": "migrations;src/models;config/database.json"
+```
+
 ### Implementation Field Details

 The **implementation** field provides detailed code implementation guidance with 4 core components:
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@ Claude Code Workflow (CCW) is built on three core architectural principles:

 ### **JSON-First Data Model**
 - **Single Source of Truth**: All workflow states and task definitions stored in structured `.task/impl-*.json` files
+- **Task-Specific Paths**: New `paths` field enables precise CLI analysis targeting concrete project paths
 - **Generated Views**: Markdown documents created on-demand from JSON data sources
 - **Data Consistency**: Eliminates synchronization issues through centralized data management
 - **Performance**: Direct JSON operations with sub-millisecond query response times
@@ -47,6 +48,7 @@ CCW automatically adjusts workflow structure based on project complexity:
 ### Dual CLI Integration
 - **Gemini CLI**: Deep codebase analysis, pattern recognition, and investigation workflows
 - **Codex CLI**: Autonomous development, code generation, and implementation automation
+- **Task-Specific Targeting**: Precise path management for focused analysis (replaces `--all-files`)
 - **Template System**: Unified template library for consistent workflow execution
 - **Cross-Platform Support**: Windows and Linux compatibility with unified path handling

@@ -238,6 +240,8 @@ cd src/api && /update-memory-related
 ├── planning-templates/    # Role-specific planning approaches
 ├── prompt-templates/      # AI interaction templates
 ├── scripts/              # Automation and utility scripts
+│   ├── read-task-paths.sh        # Convert task JSON paths to @ format
+│   └── get_modules_by_depth.sh   # Project structure analysis
 ├── tech-stack-templates/ # Technology-specific configurations
 ├── workflows/            # Core workflow documentation
 │   ├── system-architecture.md         # Architecture specifications
--- a/README_CN.md
+++ b/README_CN.md
@@ -16,6 +16,7 @@ Claude Code Workflow (CCW) 建立在三个核心架构原则之上：

 ### **JSON优先数据模型**
 - **单一数据源**: 所有工作流状态和任务定义存储在结构化的 `.task/impl-*.json` 文件中
+- **任务特定路径**: 新增 `paths` 字段实现针对具体项目路径的精准CLI分析
 - **生成视图**: 从JSON数据源按需创建Markdown文档
 - **数据一致性**: 通过集中式数据管理消除同步问题
 - **性能**: 直接JSON操作，亚毫秒级查询响应时间
@@ -47,6 +48,7 @@ CCW根据项目复杂度自动调整工作流结构：
 ### 双CLI集成
 - **Gemini CLI**: 深度代码库分析，模式识别和调查工作流
 - **Codex CLI**: 自主开发，代码生成和实现自动化
+- **任务特定定位**: 精准路径管理实现聚焦分析（替代 `--all-files`）
 - **模板系统**: 统一模板库确保一致的工作流执行
 - **跨平台支持**: Windows和Linux兼容性，统一路径处理