Claude-Code-Workflow/.claude/commands/update-memory.md

name, description, usage, argument-hint, examples

name	description	usage	argument-hint	examples
update-memory	Intelligent CLAUDE.md documentation system with context-aware updates	/update-memory [mode]	related|full	/update-memory /update-memory related /update-memory full

🚀 Command Overview: /update-memory

• Type: Hierarchical Documentation Management System
• Purpose: To maintain CLAUDE.md documentation using intelligent context detection and automatic task partitioning.
• Key Features: Context-aware updates, strict hierarchy preservation, automatic scaling of execution strategy, and direct file modification via Gemini --yolo.

⚙️ Processing Modes

• related (Default)
  • Scope: Updates only context-related modules based on recent changes (git diff, recent edits).
  • Action: Updates affected module CLAUDE.md files, their parent hierarchy, and the root CLAUDE.md.
  • Use Case: Ideal for daily development, feature updates, and bug fixes.
• full
  • Scope: Executes a complete, project-wide documentation update.
  • Action: Analyzes the entire project and updates all CLAUDE.md files at every hierarchy level.
  • Use Case: Best for major refactoring, project initialization, or periodic maintenance.

🧠 Core Execution Logic: Automatic Strategy Selection

The command automatically selects an execution strategy based on project complexity. This logic applies to both related and full modes.

FUNCTION select_execution_strategy(mode):
  // Step 1: Analyze project scale
  file_count = count_source_code_files()

  // Step 2: Determine execution strategy based on file count
  IF file_count < 50:
    // This action corresponds to the "Small Project" templates.
    EXECUTE_STRATEGY("Single Gemini Execution")
  ELSE IF file_count < 200:
    // This action corresponds to the "Medium Project" templates.
    EXECUTE_STRATEGY("Parallel Shell Execution")
  ELSE:
    // This action corresponds to the "Large Project" template.
    EXECUTE_STRATEGY("Multi-Agent Coordination")
END FUNCTION

🔍 Context Detection Logic (related Mode)

This describes how the command identifies which files need updating in related mode.

FUNCTION detect_affected_modules():
  // Priority 1: Check for staged or recent git changes.
  changed_files = get_git_diff_or_status()

  // Priority 2: If no git changes, find recently edited files as a fallback.
  IF changed_files is empty:
    changed_files = find_recently_modified_source_files(limit=10)
  
  // Convert file paths into a unique list of parent directories.
  affected_modules = extract_unique_directories_from(changed_files)

  RETURN affected_modules
END FUNCTION

📝 Template: Small Project (related Mode Update)

This template is executed when the project is small and the mode is related.

# Single comprehensive analysis
gemini --all-files --yolo -p "@{changed_files} @{affected_module/CLAUDE.md} @{CLAUDE.md}
Analyze recent changes and update only affected CLAUDE.md files:

1. Module-level update:
   - Focus on changed patterns and implementations
   - Follow Layer 3/4 hierarchy rules
   - Avoid duplicating parent content

2. Root-level update:
   - Reflect only significant architectural changes
   - Maintain high-level project perspective
   - Reference but don't duplicate module details
 
Only update files that are actually affected by the changes."

📝 Template: Medium/Large Project (related Mode Update)

This template is executed for medium or large projects in related mode.

# Step-by-step layered update

# Update affected modules first
for module in $affected_modules; do
    echo "Updating module: $module"
    gemini --all-files --yolo -p "@{$module/**/*} @{$module/CLAUDE.md}
    Update $module/CLAUDE.md based on recent changes:
    - Analyze what specifically changed in this module
    - Update implementation patterns that were modified
    - Follow Layer 3 hierarchy rules (module-specific focus)
    - Do not include project overview or domain-wide patterns
    - Only document what changed or was impacted"
done

# Update parent domain if structure changed
parent_domains=$(echo "$affected_modules" | xargs dirname | sort -u)
for domain in $parent_domains; do
    if [ -f "$domain/CLAUDE.md" ]; then
        echo "Checking domain impact: $domain"
        gemini --all-files --yolo -p "@{$domain/*/CLAUDE.md} @{$domain/CLAUDE.md}
        Review if domain-level documentation needs updates:
        - Check if module organization changed
        - Update integration patterns if affected
        - Follow Layer 2 hierarchy rules (domain focus)
        - Only update if there are actual structural changes
        - Do not duplicate module details"
    fi
done

# Finally, update root if significant changes
echo "Updating root documentation"
gemini --all-files --yolo -p "@{changed_files} @{*/CLAUDE.md} @{CLAUDE.md}
Review and update root CLAUDE.md only if changes affect:
- Project architecture or technology stack
- Major feature additions
- Development workflow changes

Follow Layer 1 hierarchy rules:
- Maintain high-level project perspective
- Only reference architectural impacts
- Do not duplicate domain or module content"

📝 Template: Small Project (full Mode Update)

This template is executed when the project is small and the mode is full.

# Single comprehensive analysis with hierarchy awareness
gemini --all-files --yolo -p "@{**/*} @{**/*CLAUDE.md}
Perform complete project analysis and update all CLAUDE.md files with strict hierarchy:

1. Root CLAUDE.md (Layer 1):
   - Project overview, architecture, technology stack
   - Development guidelines and workflow
   - Do NOT include implementation details

2. Domain CLAUDE.md (Layer 2):
   - Domain architecture and module organization
   - Inter-module communication patterns
   - Do NOT duplicate project overview or module internals

3. Module CLAUDE.md (Layer 3):
   - Module-specific patterns and internal architecture
   - API contracts and dependencies
   - Do NOT duplicate domain patterns or project overview

4. Sub-module CLAUDE.md (Layer 4):
   - Implementation specifics and configuration
   - Usage examples and performance notes
   - Do NOT duplicate higher-level architecture

Ensure each layer maintains its proper abstraction level without content duplication."

📝 Template: Medium Project (full Mode Update)

This template is executed when the project is medium-sized and the mode is full.

# Dependency-aware parallel execution

echo "🏗️ Layer 1: Foundation modules (parallel)"
(
  gemini --all-files --yolo -p "@{src/utils/**/*} @{src/utils/CLAUDE.md}
  Update utilities documentation (Layer 3 focus):
  - Utility patterns and helper functions
  - Module internal organization
  - Avoid project/domain overview" &

  gemini --all-files --yolo -p "@{src/types/**/*} @{src/types/CLAUDE.md}
  Update types documentation (Layer 3 focus):
  - Type definitions and interface patterns
  - Type architecture within module
  - Avoid project/domain overview" &

  gemini --all-files --yolo -p "@{src/core/**/*} @{src/core/CLAUDE.md}
  Update core documentation (Layer 3 focus):
  - Core module patterns and initialization
  - Internal system architecture
  - Avoid project/domain overview" &
  wait
)

echo "🏭 Layer 2: Business modules (parallel, with foundation context)"
(
  gemini --all-files --yolo -p "@{src/api/**/*} @{src/core/CLAUDE.md,src/types/CLAUDE.md} @{src/api/CLAUDE.md}
  Update API documentation with foundation context (Layer 3 focus):
  - API architecture and endpoint patterns
  - Integration with core and types modules
  - Module-specific implementation details
  - Avoid duplicating foundation or project content" &

  gemini --all-files --yolo -p "@{src/services/**/*} @{src/utils/CLAUDE.md} @{src/services/CLAUDE.md}
  Update services documentation with utils context (Layer 3 focus):
  - Service layer patterns and business logic
  - Integration with utility modules
  - Module internal architecture
  - Avoid duplicating utils or project content" &
  wait
)

echo "🎨 Layer 3: Application modules (parallel, with business context)"
(
  gemini --all-files --yolo -p "@{src/components/**/*} @{src/api/CLAUDE.md} @{src/components/CLAUDE.md}
  Update components documentation with API context (Layer 3 focus):
  - Component architecture and patterns
  - API integration approaches
  - Module-specific UI patterns
  - Avoid duplicating API or project content" &

  gemini --all-files --yolo -p "@{src/pages/**/*} @{src/services/CLAUDE.md} @{src/pages/CLAUDE.md}
  Update pages documentation with services context (Layer 3 focus):
  - Page structure and routing patterns
  - Service utilization approaches
  - Module-specific page architecture
  - Avoid duplicating services or project content" &
  wait
)

echo "📋 Layer 4: Domain integration"
gemini --all-files --yolo -p "@{src/*/CLAUDE.md} @{src/CLAUDE.md}
Update src domain documentation (Layer 2 focus):
- Synthesize module organization and relationships
- Domain-wide architecture patterns
- Inter-module communication strategies
- Do NOT duplicate module implementation details
- Do NOT duplicate project overview content"

echo "🎯 Layer 5: Root integration"
gemini --all-files --yolo -p "@{*/CLAUDE.md} @{CLAUDE.md}
Update root documentation (Layer 1 focus):
- High-level project architecture and overview
- Technology stack summary and decisions
- Development workflow and guidelines
- Do NOT duplicate domain-specific content
- Do NOT include implementation details"

📝 Template: Large Project (full Mode Update)

This YAML-based plan is used for large projects in full mode, coordinating multiple agents.

# Multi-agent coordination for complex projects
Main Coordinator Agent:
  description: "Coordinate full documentation update"
  subagent_type: "memory-gemini-bridge"
  prompt: |
    Execute large project full documentation update:
  
    1. Analyze project structure:
       gemini --all-files -p "@{**/*} Identify major domains, complexity, and module relationships"
  
    2. Launch parallel domain agents:
       - Each agent handles one domain (frontend, backend, infrastructure)
       - Each agent follows hierarchy rules strictly
       - Each agent avoids content duplication
  
    3. Final integration:
       gemini --all-files --yolo -p "@{*/CLAUDE.md} @{CLAUDE.md}
       Update root with Layer 1 focus only:
       - Project overview and architecture
       - Technology stack decisions
       - Development workflow
       - Do NOT duplicate domain details"

Frontend Domain Agent:
  prompt: |
    Update frontend domain with hierarchy awareness:
  
    1. Module updates (Layer 3):
       gemini --all-files --yolo -p "@{src/components/**/*} @{src/components/CLAUDE.md}
       Component-specific patterns and architecture"
     
       gemini --all-files --yolo -p "@{src/pages/**/*} @{src/pages/CLAUDE.md}
       Page-specific patterns and routing"
  
    2. Domain integration (Layer 2):
       gemini --all-files --yolo -p "@{src/frontend/*/CLAUDE.md} @{src/frontend/CLAUDE.md}
       Frontend domain architecture, module relationships
       Do NOT duplicate component details or project overview"

Backend Domain Agent:
  prompt: |
    Update backend domain with hierarchy awareness:
  
    1. Module updates (Layer 3):
       gemini --all-files --yolo -p "@{src/api/**/*} @{src/api/CLAUDE.md}
       API-specific patterns and endpoints"
     
       gemini --all-files --yolo -p "@{src/services/**/*} @{src/services/CLAUDE.md}
       Service-specific business logic and patterns"
  
    2. Domain integration (Layer 2):
       gemini --all-files --yolo -p "@{src/backend/*/CLAUDE.md} @{src/backend/CLAUDE.md}
       Backend domain architecture, service relationships
       Do NOT duplicate service details or project overview"

📈 Performance Characteristics

Mode	Small Project (<50 files)	Medium Project (50-200 files)	Large Project (>200 files)
related	<1 minute	1-3 minutes	3-5 minutes
full	1-2 minutes	3-5 minutes	10-15 minutes

📚 Usage Examples

# Daily development (automatically detects what you've been working on)
/update-memory

# After working in a specific module, explicitly run related mode
cd src/api && /update-memory related

# Weekly full refresh for project-wide consistency
/update-memory full

# Intelligently update based on a large refactoring commit
git add -A && git commit -m "Major refactoring"
/update-memory related

✨ Key Features

• Context Intelligence: Automatically detects which modules need updating based on recent changes.
• Hierarchy Preservation: Enforces strict content boundaries between documentation layers to prevent duplication.
• Smart Partitioning: Dynamically scales its execution strategy (single, parallel, multi-agent) based on project size.
• Zero Configuration: Works out-of-the-box with intelligent defaults for context detection and execution.

📝 Best Practices

• Use related mode for daily development; it's fast and focused.
• Run full mode weekly or after major architectural changes to ensure consistency.
• Trust the hierarchy; let each CLAUDE.md file serve its specific layer of abstraction.
• Allow the automatic context detection to guide updates rather than manually specifying files.