From de3dc35c5be98fbf9f8d20f913373e0fae83ce29 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Tue, 21 Oct 2025 20:28:11 +0800 Subject: [PATCH] refactor: improve memory update commands with parallel execution and fix file naming MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Renamed update-memory-full.md -> update-full.md for consistency - Renamed update-memory-related.md -> update-related.md for consistency - Added parallel execution support (max 4 concurrent) for both direct and agent modes - Fixed execution strategy: <20 modules direct parallel, β‰₯20 modules agent batch - Removed misleading "orchestrator agent" section that caused hierarchy confusion - Clarified coordinator always executes, agents only for batching β‰₯20 modules - Added explicit file naming rules to prevent ToolSidebar.CLAUDE.md errors - Updated template and script with CRITICAL file naming constraints - Removed all emoji symbols from documentation for clean text format - Added smart filtering strategy to docs.md for auto-skip patterns Key improvements: - Phase 3A: Direct parallel execution (max 4 concurrent per depth) - Phase 3B: Agent batch execution (4 modules/agent) - Both modes use same batching strategy, differ only in agent layer - Explicit CLAUDE.md file naming in 3 locations (script, template, checklist) πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/commands/memory/docs.md | 10 +- .claude/commands/memory/update-full.md | 388 ++++++++++++++++++ .claude/commands/memory/update-memory-full.md | 330 --------------- .../commands/memory/update-memory-related.md | 306 -------------- .claude/commands/memory/update-related.md | 352 ++++++++++++++++ .claude/scripts/update_module_claude.sh | 9 +- .../prompts/memory/claude-module-unified.txt | 12 + 7 files changed, 766 insertions(+), 641 deletions(-) create mode 100644 .claude/commands/memory/update-full.md delete mode 100644 .claude/commands/memory/update-memory-full.md delete mode 100644 .claude/commands/memory/update-memory-related.md create mode 100644 .claude/commands/memory/update-related.md diff --git a/.claude/commands/memory/docs.md b/.claude/commands/memory/docs.md index c8875ec2..a95163d1 100644 --- a/.claude/commands/memory/docs.md +++ b/.claude/commands/memory/docs.md @@ -129,9 +129,11 @@ EOF ### Phase 2: Analyze Structure +**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack (Node.js/Python/Go/Rust/etc). + #### Step 1: Discover and Classify Folders ```bash -# Run analysis pipeline (module discovery + folder classification) +# Run analysis pipeline (module discovery + folder classification + smart filtering) bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh > .workflow/WFS-docs-20240120/.process/folder-analysis.txt) ``` @@ -142,6 +144,12 @@ bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-fold ./src/utils|navigation|code:0|dirs:4 ``` +**Auto-skipped**: +- Tests: `**/test/**`, `**/*.test.*`, `**/__tests__/**` +- Build: `**/node_modules/**`, `**/dist/**`, `**/build/**` +- Config: Root-level config files (package.json, tsconfig.json, etc) +- Vendor: Language-specific dependency directories + #### Step 2: Extract Top-Level Directories ```bash # Group folders by top-level directory diff --git a/.claude/commands/memory/update-full.md b/.claude/commands/memory/update-full.md new file mode 100644 index 00000000..a3459187 --- /dev/null +++ b/.claude/commands/memory/update-full.md @@ -0,0 +1,388 @@ +--- +name: update-full +description: Complete project-wide CLAUDE.md documentation update with agent-based parallel execution and tool fallback +argument-hint: "[--tool gemini|qwen|codex] [--path ]" +--- + +# Full Documentation Update (/memory:update-full) + +## Overview + +Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback (geminiβ†’qwenβ†’codex). + +**Parameters**: +- `--tool `: Primary tool (default: gemini) +- `--path `: Target specific directory (default: entire project) + +**Execution Flow**: +1. Discovery & Analysis β†’ 2. Plan Presentation β†’ 3. Batched Agent Execution β†’ 4. Safety Verification + +## Core Rules + +1. **Analyze First**: Git cache + module discovery before updates +2. **Wait for Approval**: Present plan, no execution without user confirmation +3. **Execution Strategy**: + - <20 modules: Direct parallel execution (max 4 concurrent per depth, no agent overhead) + - β‰₯20 modules: Agent batch processing (4 modules/agent, 73% overhead reduction) +4. **Tool Fallback**: Auto-retry with fallback tools on failure +5. **Depth Sequential**: Process depths Nβ†’0, parallel batches within depth (both modes) +6. **Safety Check**: Verify only CLAUDE.md files modified + +## Tool Fallback Hierarchy + +```javascript +--tool gemini β†’ [gemini, qwen, codex] // default +--tool qwen β†’ [qwen, gemini, codex] +--tool codex β†’ [codex, gemini, qwen] +``` + +**Trigger**: Non-zero exit code from update script + +## Phase 1: Discovery & Analysis + +```bash +# Cache git changes +bash(git add -A 2>/dev/null || true) + +# Get module structure +bash(~/.claude/scripts/get_modules_by_depth.sh list) +# OR with --path +bash(cd && ~/.claude/scripts/get_modules_by_depth.sh list) +``` + +**Parse output** `depth:N|path:|...` to extract module paths and count. + +**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack (Node.js/Python/Go/Rust/etc). + +## Phase 2: Plan Presentation + +**Present filtered plan**: +``` +Update Plan: + Tool: gemini (fallback: qwen β†’ codex) + Total: 7 modules + Execution: Direct sequential (< 20 modules threshold) + + Will update: + - ./core/interfaces (12 files) - depth 2 + - ./core (22 files) - depth 1 + - ./models (9 files) - depth 1 + - ./parametric (6 files) - depth 1 + - ./results (7 files) - depth 1 + - ./utils (12 files) - depth 1 + - . (5 files) - depth 0 + + Auto-skipped (15 paths): + - Tests: ./tests, **/*_test.py (8 paths) + - Build: __pycache__, dist, *.egg-info (5 paths) + - Config: setup.py, requirements.txt (2 paths) + + Execution order (by depth): + 1. Depth 2: ./core/interfaces + 2. Depth 1: ./core, ./models, ./parametric, ./results, ./utils + 3. Depth 0: . + + Estimated time: ~5-10 minutes + + Confirm execution? (y/n) +``` + +**For β‰₯20 modules**: +``` +Update Plan: + Tool: gemini (fallback: qwen β†’ codex) + Total: 31 modules + Execution: Agent batch processing (4 modules/agent) + + Will update: + - ./src/features/auth (12 files) + - ./.claude/commands/cli (6 files) + - ./src/utils (8 files) + ... + + Auto-skipped (45 paths): + - Tests: ./tests, ./src/**/*.test.ts (18 paths) + - Config: package.json, tsconfig.json, vite.config.ts (12 paths) + - Build: ./dist, ./node_modules, ./.next (8 paths) + - Docs: ./README.md, ./docs (5 paths) + - Other: .git, .vscode, coverage (2 paths) + + Agent allocation: + - Depth 5 (8 modules): 2 agents [4, 4] + - Depth 4 (7 modules): 2 agents [4, 3] + - Depth 3 (6 modules): 2 agents [3, 3] + + Estimated time: ~15-25 minutes + + Confirm execution? (y/n) +``` + +**Decision logic**: +- User confirms "y": Proceed with execution +- User declines "n": Abort, no changes +- <20 modules: Direct execution (Phase 3A) +- β‰₯20 modules: Agent batch execution (Phase 3B) + +## Phase 3A: Direct Execution (<20 modules) + +**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead, tool fallback per module. + +```javascript +let modules_by_depth = group_by_depth(module_list); +let tool_order = construct_tool_order(primary_tool); + +for (let depth of sorted_depths.reverse()) { // N β†’ 0 + let modules = modules_by_depth[depth]; + let batches = batch_modules(modules, 4); // Split into groups of 4 + + for (let batch of batches) { + // Execute batch in parallel (max 4 concurrent) + let parallel_tasks = batch.map(module => { + return async () => { + let success = false; + for (let tool of tool_order) { + let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "." "full" "${tool}"); + if (exit_code === 0) { + report("${module.path} updated with ${tool}"); + success = true; + break; + } + } + if (!success) { + report("FAILED: ${module.path} failed all tools"); + } + }; + }); + + await Promise.all(parallel_tasks.map(task => task())); // Run batch in parallel + } +} +``` + +**Example execution (7 modules)**: +```bash +# Depth 2 (1 module) +bash(cd ./core/interfaces && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") +# β†’ Success with gemini + +# Depth 1 (5 modules β†’ 2 batches: [4, 1]) +# Batch 1 (4 modules in parallel): +bash(cd ./core && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") & +bash(cd ./models && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") & +bash(cd ./parametric && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") & +bash(cd ./results && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") & +wait # Wait for batch 1 to complete + +# Batch 2 (1 module): +bash(cd ./utils && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") +# β†’ Success with gemini + +# Depth 0 (1 module) +bash(cd . && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") +# β†’ Success with gemini +``` + +**Benefits**: +- No agent startup overhead +- Parallel execution within depth (max 4 concurrent) +- Tool fallback still applies per module +- Faster for small projects (<20 modules) +- Same batching strategy as Phase 3B but without agent layer + +--- + +## Phase 3B: Agent Batch Execution (β‰₯20 modules) + +### Batching Strategy + +```javascript +// Batch modules into groups of 4 +function batch_modules(modules, batch_size = 4) { + let batches = []; + for (let i = 0; i < modules.length; i += batch_size) { + batches.push(modules.slice(i, i + batch_size)); + } + return batches; +} +// Examples: 10β†’[4,4,2] | 8β†’[4,4] | 3β†’[3] +``` + +### Coordinator Orchestration + +```javascript +let modules_by_depth = group_by_depth(module_list); +let tool_order = construct_tool_order(primary_tool); + +for (let depth of sorted_depths.reverse()) { // N β†’ 0 + let batches = batch_modules(modules_by_depth[depth], 4); + let worker_tasks = []; + + for (let batch of batches) { + worker_tasks.push( + Task( + subagent_type="memory-bridge", + description=`Update ${batch.length} modules at depth ${depth}`, + prompt=generate_batch_worker_prompt(batch, tool_order) + ) + ); + } + + await parallel_execute(worker_tasks); // Batches run in parallel +} +``` + +### Batch Worker Prompt Template + +``` +PURPOSE: Update CLAUDE.md for assigned modules with tool fallback + +TASK: +Update documentation for the following modules. For each module, try tools in order until success. + +MODULES: +{{module_path_1}} +{{module_path_2}} +{{module_path_3}} +{{module_path_4}} + +TOOLS (try in order): +1. {{tool_1}} +2. {{tool_2}} +3. {{tool_3}} + +EXECUTION: +For each module above: + 1. cd "{{module_path}}" + 2. Try tool 1: + bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "full" "{{tool_1}}") + β†’ Success: Report " {{module_path}} updated with {{tool_1}}", proceed to next module + β†’ Failure: Try tool 2 + 3. Try tool 2: + bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "full" "{{tool_2}}") + β†’ Success: Report " {{module_path}} updated with {{tool_2}}", proceed to next module + β†’ Failure: Try tool 3 + 4. Try tool 3: + bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "full" "{{tool_3}}") + β†’ Success: Report " {{module_path}} updated with {{tool_3}}", proceed to next module + β†’ Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module + +REPORTING: +Report final summary with: +- Total processed: X modules +- Successful: Y modules +- Failed: Z modules +- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z +- Detailed results for each module +``` + +### Example Execution + +**Depth 5 (8 modules β†’ 2 batches)**: +```javascript +Task(subagent_type="memory-bridge", batch=[mod1, mod2, mod3, mod4]) // Agent 1 +Task(subagent_type="memory-bridge", batch=[mod5, mod6, mod7, mod8]) // Agent 2 +// Both run in parallel +``` + +**Benefits**: +- 8 modules β†’ 2 agents (75% reduction) +- Parallel batches, sequential within batch +- Each module gets full fallback chain + +## Phase 4: Safety Verification + +```bash +# Check only CLAUDE.md modified +bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified") + +# Display status +bash(git status --short) +``` + +**Aggregate results**: +``` +Update Summary: + Total: 31 | Success: 29 | Failed: 2 + + Tool usage: + - gemini: 25 modules + - qwen: 4 modules (fallback) + - codex: 0 modules + + Failed: FAILED: path1, path2 +``` + +## Execution Summary + +**Module Count Threshold**: +- **<20 modules**: Coordinator executes Phase 3A (Direct Execution) +- **β‰₯20 modules**: Coordinator executes Phase 3B (Agent Batch Execution) + +**Agent Hierarchy** (for β‰₯20 modules): +- **Coordinator**: Handles batch division, spawns worker agents per depth +- **Worker Agents**: Each processes 4 modules with tool fallback + +## Error Handling + +**Batch Worker**: +- Tool fallback per module (auto-retry) +- Batch isolation (failures don't propagate) +- Clear per-module status reporting + +**Coordinator**: +- Invalid path: Abort with error +- User decline: No execution +- Safety check fail: Auto-revert staging +- Partial failures: Continue execution, report failed modules + +**Fallback Triggers**: +- Non-zero exit code +- Script timeout +- Unexpected output + +## Tool Reference + +| Tool | Best For | Fallback To | +|--------|--------------------------------|----------------| +| gemini | Documentation, patterns | qwen β†’ codex | +| qwen | Architecture, system design | gemini β†’ codex | +| codex | Implementation, code quality | gemini β†’ qwen | + +## Path Parameter Examples + +```bash +# Full project update +/memory:update-full + +# Target specific directory +/memory:update-full --path .claude +/memory:update-full --path src/features/auth + +# Combine with tool selection +/memory:update-full --path .claude --tool qwen +``` + +## Key Advantages + +**Efficiency**: 30 modules β†’ 8 agents (73% reduction) +**Resilience**: 3-tier fallback per module +**Performance**: Parallel batches, no concurrency limits +**Observability**: Per-module tool usage, batch-level metrics + +## Coordinator Checklist + +- Parse `--tool` (default: gemini) and `--path` (default: current dir) +- Git cache + module discovery +- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs) +- Construct tool fallback order +- **Present filtered plan** with execution strategy (<20: direct, β‰₯20: agent batch) +- **Wait for y/n confirmation** +- Determine execution mode: + - **<20 modules**: Direct execution (Phase 3A) + - For each depth (Nβ†’0): Sequential module updates with tool fallback + - **β‰₯20 modules**: Agent batch execution (Phase 3B) + - For each depth (Nβ†’0): Batch modules (4 per batch), spawn batch workers in parallel +- Wait for depth/batch completion +- Aggregate results +- Safety check (only CLAUDE.md modified) +- Display git status + summary diff --git a/.claude/commands/memory/update-memory-full.md b/.claude/commands/memory/update-memory-full.md deleted file mode 100644 index 292f29b9..00000000 --- a/.claude/commands/memory/update-memory-full.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -name: update-full -description: Complete project-wide CLAUDE.md documentation update -argument-hint: "[--tool gemini|qwen|codex] [--path ]" ---- - -# Full Documentation Update (/memory:update-full) - -## Coordinator Role - -**This command orchestrates project-wide CLAUDE.md updates** using depth-parallel execution strategy with intelligent complexity detection. - -**Execution Model**: - -1. **Initial Analysis**: Cache git changes, discover module structure -2. **Complexity Detection**: Analyze module count, determine strategy -3. **Plan Presentation**: Show user exactly what will be updated -4. **Depth-Parallel Execution**: Update modules by depth (highest to lowest) -5. **Safety Verification**: Ensure only CLAUDE.md files modified - -**Tool Selection**: -- `--tool gemini` (default): Documentation generation, pattern recognition -- `--tool qwen`: Architecture analysis, system design docs -- `--tool codex`: Implementation validation, code quality analysis - -**Path Parameter**: -- `--path ` (optional): Target specific directory for updates -- If not specified: Updates entire project from current directory -- If specified: Changes to target directory before discovery - -## Core Rules - -1. **Analyze First**: Run git cache and module discovery before any updates -2. **Scope Control**: Use --path to target specific directories, default is entire project -3. **Wait for Approval**: Present plan, no execution without user confirmation -4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential -5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched -6. **Independent Commands**: Each update is a separate bash() call -7. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism - -## Execution Workflow - -### Phase 1: Discovery & Analysis - -**Cache git changes:** -```bash -bash(git add -A 2>/dev/null || true) -``` - -**Get module structure:** - -*If no --path parameter:* -```bash -bash(~/.claude/scripts/get_modules_by_depth.sh list) -``` - -*If --path parameter specified:* -```bash -bash(cd && ~/.claude/scripts/get_modules_by_depth.sh list) -``` - -**Example with path:** -```bash -# Update only .claude directory -bash(cd .claude && ~/.claude/scripts/get_modules_by_depth.sh list) - -# Update specific feature directory -bash(cd src/features/auth && ~/.claude/scripts/get_modules_by_depth.sh list) -``` - -**Parse Output**: -- Extract module paths from `depth:N|path:|...` format -- Count total modules -- Identify which modules have/need CLAUDE.md - -**Example output:** -``` -depth:5|path:./.claude/workflows/cli-templates/prompts/analysis|files:5|has_claude:no -depth:4|path:./.claude/commands/cli/mode|files:3|has_claude:no -depth:3|path:./.claude/commands/cli|files:6|has_claude:no -depth:0|path:.|files:14|has_claude:yes -``` - -**Validation**: -- If --path specified, directory exists and is accessible -- Module list contains depth and path information -- At least one module exists -- All paths are relative to target directory (if --path used) - ---- - -### Phase 2: Plan Presentation - -**Decision Logic**: -- **Simple projects (≀20 modules)**: Present plan to user, wait for approval -- **Complex projects (>20 modules)**: Delegate to memory-bridge agent - -**Plan format:** -``` -πŸ“‹ Update Plan: - Tool: gemini - Total modules: 31 - - NEW CLAUDE.md files (30): - - ./.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md - - ./.claude/commands/cli/mode/CLAUDE.md - - ... (28 more) - - UPDATE existing CLAUDE.md files (1): - - ./CLAUDE.md - - ⚠️ Confirm execution? (y/n) -``` - -**User Confirmation Required**: No execution without explicit approval - ---- - -### Phase 3: Depth-Parallel Execution - -**Pattern**: Process highest depth first, parallel within depth, sequential across depths. - -**Command structure:** -```bash -bash(cd && ~/.claude/scripts/update_module_claude.sh "." "full" "" &) -``` - -**Example - Depth 5 (8 modules):** -```bash -bash(cd ./.claude/workflows/cli-templates/prompts/analysis && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &) -``` -```bash -bash(cd ./.claude/workflows/cli-templates/prompts/development && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &) -``` -```bash -bash(cd ./.claude/workflows/cli-templates/prompts/documentation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &) -``` -```bash -bash(cd ./.claude/workflows/cli-templates/prompts/implementation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &) -``` - -*Wait for depth 5 completion...* - -**Example - Depth 4 (7 modules):** -```bash -bash(cd ./.claude/commands/cli/mode && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &) -``` -```bash -bash(cd ./.claude/commands/workflow/brainstorm && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &) -``` - -*Continue for remaining depths (3 β†’ 2 β†’ 1 β†’ 0)...* - -**Execution Rules**: -- Each command is separate bash() call -- Up to 4 concurrent jobs per depth -- Wait for all jobs in current depth before proceeding -- Extract path from `depth:N|path:|...` format -- All paths relative to target directory (current dir or --path value) - -**Path Context**: -- Without --path: Paths relative to current directory -- With --path: Paths relative to specified target directory -- Module discovery runs in target directory context - ---- - -### Phase 4: Safety Verification - -**Check modified files:** -```bash -bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "βœ… Only CLAUDE.md files modified") -``` - -**Expected output:** -``` -βœ… Only CLAUDE.md files modified -``` - -**If non-CLAUDE.md files detected:** -``` -⚠️ Warning: Non-CLAUDE.md files were modified -Modified files: src/index.ts, package.json -β†’ Run: git restore --staged . -``` - -**Display final status:** -```bash -bash(git status --short) -``` - -**Example output:** -``` -A .claude/workflows/cli-templates/prompts/analysis/CLAUDE.md -A .claude/commands/cli/mode/CLAUDE.md -M CLAUDE.md -... (30 more files) -``` - -## Command Pattern Reference - -**Single module update:** -```bash -bash(cd && ~/.claude/scripts/update_module_claude.sh "." "full" "" &) -``` - -**Components**: -- `cd ` - Navigate to module (from `path:` field) -- `&&` - Ensure cd succeeds -- `update_module_claude.sh` - Update script -- `"."` - Current directory -- `"full"` - Full update mode -- `""` - gemini/qwen/codex -- `&` - Background execution - -**Path extraction:** -```bash -# From: depth:5|path:./src/auth|files:10|has_claude:no -# Extract: ./src/auth -# Command: bash(cd ./src/auth && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &) -``` - -## Complex Projects Strategy - -For projects >20 modules, delegate to memory-bridge agent: - -```javascript -Task( - subagent_type="memory-bridge", - description="Complex project full update", - prompt=` -CONTEXT: -- Total modules: ${module_count} -- Tool: ${tool} -- Mode: full - -MODULE LIST: -${modules_output} - -REQUIREMENTS: -1. Use TodoWrite to track each depth level -2. Process depths Nβ†’0 sequentially, max 4 parallel per depth -3. Command: cd "" && update_module_claude.sh "." "full" "${tool}" & -4. Extract path from "depth:N|path:|..." format -5. Verify all modules processed -6. Run safety check -7. Display git status -` -) -``` - -## Error Handling - -- **Invalid path parameter**: Report error if --path directory doesn't exist, abort execution -- **Module discovery failure**: Report error, abort execution -- **User declines approval**: Abort execution, no changes made -- **Safety check failure**: Automatic staging revert, report modified files -- **Update script failure**: Report failed modules, continue with remaining - -## Coordinator Checklist - -βœ… Parse `--tool` parameter (default: gemini) -βœ… Parse `--path` parameter (optional, default: current directory) -βœ… Execute git cache in current directory -βœ… Execute module discovery (with cd if --path specified) -βœ… Parse module list, count total modules -βœ… Determine strategy based on module count (≀20 vs >20) -βœ… Present plan with exact file paths -βœ… **Wait for user confirmation** (simple projects only) -βœ… Organize modules by depth -βœ… For each depth (highest to lowest): - - Launch up to 5 parallel updates - - Wait for depth completion - - Proceed to next depth -βœ… Run safety check after all updates -βœ… Display git status -βœ… Report completion summary - - - -## Tool Parameter Reference - -**Gemini** (default): -- Best for: Documentation generation, pattern recognition, architecture review -- Context window: Large, handles complex codebases -- Output style: Comprehensive, detailed explanations - -**Qwen**: -- Best for: Architecture analysis, system design documentation -- Context window: Large, similar to Gemini -- Output style: Structured, systematic analysis - -**Codex**: -- Best for: Implementation validation, code quality analysis -- Capabilities: Mathematical reasoning, autonomous development -- Output style: Technical, implementation-focused - -## Path Parameter Reference - -**Use Cases**: - -**Update configuration directory only:** -```bash -/memory:update-full --path .claude -``` -- Updates only .claude directory and subdirectories -- Useful after workflow or command modifications -- Faster than full project update - -**Update specific feature module:** -```bash -/memory:update-full --path src/features/auth -``` -- Updates authentication feature and sub-modules -- Ideal for feature-specific documentation -- Isolates scope for targeted updates - -**Update nested structure:** -```bash -/memory:update-full --path .claude/workflows/cli-templates -``` -- Updates deeply nested directory tree -- Maintains relative path structure in output -- All module paths relative to specified directory - -**Best Practices**: -- Use `--path` when working on specific features/modules -- Omit `--path` for project-wide architectural changes -- Combine with `--tool` for specialized documentation needs -- Verify directory exists before execution (automatic validation) diff --git a/.claude/commands/memory/update-memory-related.md b/.claude/commands/memory/update-memory-related.md deleted file mode 100644 index d4c6fe25..00000000 --- a/.claude/commands/memory/update-memory-related.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -name: update-related -description: Context-aware CLAUDE.md documentation updates based on recent changes -argument-hint: "[--tool gemini|qwen|codex]" ---- - -# Related Documentation Update (/memory:update-related) - -## Coordinator Role - -**This command orchestrates context-aware CLAUDE.md updates** for modules affected by recent changes using intelligent change detection. - -**Execution Model**: - -1. **Change Detection**: Analyze git changes to identify affected modules -2. **Complexity Analysis**: Evaluate change count and determine strategy -3. **Plan Presentation**: Show user which modules need updates -4. **Depth-Parallel Execution**: Update affected modules by depth (highest to lowest) -5. **Safety Verification**: Ensure only CLAUDE.md files modified - -**Tool Selection**: -- `--tool gemini` (default): Documentation generation, pattern recognition -- `--tool qwen`: Architecture analysis, system design docs -- `--tool codex`: Implementation validation, code quality analysis - -## Core Rules - -1. **Detect Changes First**: Use git diff to identify affected modules before updates -2. **Wait for Approval**: Present plan, no execution without user confirmation -3. **Related Mode**: Update only changed modules and their parent contexts -4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential -5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched -6. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism - -## Execution Workflow - -### Phase 1: Change Detection & Analysis - -**Refresh code index:** -```bash -bash(mcp__code-index__refresh_index) -``` - -**Detect changed modules:** -```bash -bash(~/.claude/scripts/detect_changed_modules.sh list) -``` - -**Cache git changes:** -```bash -bash(git add -A 2>/dev/null || true) -``` - -**Parse Output**: -- Extract changed module paths from `depth:N|path:|...` format -- Count affected modules -- Identify which modules have/need CLAUDE.md updates - -**Example output:** -``` -depth:3|path:./src/api/auth|files:5|types:[ts]|has_claude:no|change:new -depth:2|path:./src/api|files:12|types:[ts]|has_claude:yes|change:modified -depth:1|path:./src|files:8|types:[ts]|has_claude:yes|change:parent -depth:0|path:.|files:14|has_claude:yes|change:parent -``` - -**Fallback behavior**: -- If no git changes detected, use recent modules (first 10 by depth) - -**Validation**: -- Changed module list contains valid paths -- At least one affected module exists - ---- - -### Phase 2: Plan Presentation - -**Decision Logic**: -- **Simple changes (≀15 modules)**: Present plan to user, wait for approval -- **Complex changes (>15 modules)**: Delegate to memory-bridge agent - -**Plan format:** -``` -πŸ“‹ Related Update Plan: - Tool: gemini - Changed modules: 4 - - NEW CLAUDE.md files (1): - - ./src/api/auth/CLAUDE.md [new module] - - UPDATE existing CLAUDE.md files (3): - - ./src/api/CLAUDE.md [parent of changed auth/] - - ./src/CLAUDE.md [parent context] - - ./CLAUDE.md [root level] - - ⚠️ Confirm execution? (y/n) -``` - -**User Confirmation Required**: No execution without explicit approval - ---- - -### Phase 3: Depth-Parallel Execution - -**Pattern**: Process highest depth first, parallel within depth, sequential across depths. - -**Command structure:** -```bash -bash(cd && ~/.claude/scripts/update_module_claude.sh "." "related" "" &) -``` - -**Example - Depth 3 (new module):** -```bash -bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &) -``` - -*Wait for depth 3 completion...* - -**Example - Depth 2 (modified parent):** -```bash -bash(cd ./src/api && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &) -``` - -*Wait for depth 2 completion...* - -**Example - Depth 1 & 0 (parent contexts):** -```bash -bash(cd ./src && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &) -``` -```bash -bash(cd . && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &) -``` - -*Wait for all depths completion...* - -**Execution Rules**: -- Each command is separate bash() call -- Up to 4 concurrent jobs per depth -- Wait for all jobs in current depth before proceeding -- Use "related" mode (not "full") for context-aware updates -- Extract path from `depth:N|path:|...` format - -**Related Mode Behavior**: -- Updates module based on recent git changes -- Includes parent context for better documentation coherence -- More efficient than full updates for iterative development - ---- - -### Phase 4: Safety Verification - -**Check modified files:** -```bash -bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "βœ… Only CLAUDE.md files modified") -``` - -**Expected output:** -``` -βœ… Only CLAUDE.md files modified -``` - -**If non-CLAUDE.md files detected:** -``` -⚠️ Warning: Non-CLAUDE.md files were modified -Modified files: src/api/auth/index.ts, package.json -β†’ Run: git restore --staged . -``` - -**Display final statistics:** -```bash -bash(git diff --stat) -``` - -**Example output:** -``` -.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md | 45 +++++++++++++++++++++ -src/api/CLAUDE.md | 23 +++++++++-- -src/CLAUDE.md | 12 ++++-- -CLAUDE.md | 8 ++-- -4 files changed, 82 insertions(+), 6 deletions(-) -``` - -## Command Pattern Reference - -**Single module update:** -```bash -bash(cd && ~/.claude/scripts/update_module_claude.sh "." "related" "" &) -``` - -**Components**: -- `cd ` - Navigate to module (from `path:` field) -- `&&` - Ensure cd succeeds -- `update_module_claude.sh` - Update script -- `"."` - Current directory -- `"related"` - Related mode (context-aware, change-based) -- `""` - gemini/qwen/codex -- `&` - Background execution - -**Path extraction:** -```bash -# From: depth:3|path:./src/api/auth|files:5|change:new|has_claude:no -# Extract: ./src/api/auth -# Command: bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &) -``` - -**Mode comparison:** -- `"full"` - Complete module documentation regeneration -- `"related"` - Context-aware update based on recent changes (faster) - -## Complex Changes Strategy - -For changes affecting >15 modules, delegate to memory-bridge agent: - -```javascript -Task( - subagent_type="memory-bridge", - description="Complex project related update", - prompt=` -CONTEXT: -- Total modules: ${change_count} -- Tool: ${tool} -- Mode: related - -MODULE LIST: -${changed_modules_output} - -REQUIREMENTS: -1. Use TodoWrite to track each depth level -2. Process depths Nβ†’0 sequentially, max 4 parallel per depth -3. Command: cd "" && update_module_claude.sh "." "related" "${tool}" & -4. Extract path from "depth:N|path:|..." format -5. Verify all ${change_count} modules processed -6. Run safety check -7. Display git diff --stat -` -) -``` - -## Error Handling - -- **No changes detected**: Use fallback mode (recent 10 modules) -- **Change detection failure**: Report error, abort execution -- **User declines approval**: Abort execution, no changes made -- **Safety check failure**: Automatic staging revert, report modified files -- **Update script failure**: Report failed modules, continue with remaining - -## Coordinator Checklist - -βœ… Parse `--tool` parameter (default: gemini) -βœ… Refresh code index for accurate change detection -βœ… Detect changed modules via detect_changed_modules.sh -βœ… Cache git changes to protect current state -βœ… Parse changed module list, count affected modules -βœ… Apply fallback if no changes detected (recent 10 modules) -βœ… Determine strategy based on change count (≀15 vs >15) -βœ… Present plan with exact file paths and change types -βœ… **Wait for user confirmation** (simple changes only) -βœ… Organize modules by depth -βœ… For each depth (highest to lowest): - - Launch up to 4 parallel updates with "related" mode - - Wait for depth completion - - Proceed to next depth -βœ… Run safety check after all updates -βœ… Display git diff statistics -βœ… Report completion summary - -## Usage Examples - -```bash -# Daily development update (default: gemini) -/memory:update-related - -# After feature work with specific tool -/memory:update-related --tool qwen - -# Code quality review after implementation -/memory:update-related --tool codex -``` - -## Tool Parameter Reference - -**Gemini** (default): -- Best for: Documentation generation, pattern recognition -- Use case: Daily development updates, feature documentation -- Output style: Comprehensive, contextual explanations - -**Qwen**: -- Best for: Architecture analysis, system design -- Use case: Structural changes, API design updates -- Output style: Structured, systematic documentation - -**Codex**: -- Best for: Implementation validation, code quality -- Use case: After implementation, refactoring work -- Output style: Technical, implementation-focused - -## Comparison with Full Update - -| Aspect | Related Update | Full Update | -|--------|----------------|-------------| -| **Scope** | Changed modules only | All project modules | -| **Speed** | Fast (minutes) | Slower (10-30 min) | -| **Use case** | Daily development | Major refactoring | -| **Mode** | `"related"` | `"full"` | -| **Trigger** | After commits | After major changes | -| **Complexity threshold** | ≀15 modules | ≀20 modules | diff --git a/.claude/commands/memory/update-related.md b/.claude/commands/memory/update-related.md new file mode 100644 index 00000000..67757154 --- /dev/null +++ b/.claude/commands/memory/update-related.md @@ -0,0 +1,352 @@ +--- +name: update-related +description: Context-aware CLAUDE.md documentation updates based on recent changes with agent-based execution and tool fallback +argument-hint: "[--tool gemini|qwen|codex]" +--- + +# Related Documentation Update (/memory:update-related) + +## Overview + +Orchestrates context-aware CLAUDE.md updates for changed modules using batched agent execution with automatic tool fallback (geminiβ†’qwenβ†’codex). + +**Parameters**: +- `--tool `: Primary tool (default: gemini) + +**Execution Flow**: +1. Change Detection β†’ 2. Plan Presentation β†’ 3. Batched Agent Execution β†’ 4. Safety Verification + +## Core Rules + +1. **Detect Changes First**: Use git diff to identify affected modules +2. **Wait for Approval**: Present plan, no execution without user confirmation +3. **Execution Strategy**: + - <15 modules: Direct parallel execution (max 4 concurrent per depth, no agent overhead) + - β‰₯15 modules: Agent batch processing (4 modules/agent, 73% overhead reduction) +4. **Tool Fallback**: Auto-retry with fallback tools on failure +5. **Depth Sequential**: Process depths Nβ†’0, parallel batches within depth (both modes) +6. **Related Mode**: Update only changed modules and their parent contexts + +## Tool Fallback Hierarchy + +```javascript +--tool gemini β†’ [gemini, qwen, codex] // default +--tool qwen β†’ [qwen, gemini, codex] +--tool codex β†’ [codex, gemini, qwen] +``` + +**Trigger**: Non-zero exit code from update script + +## Phase 1: Change Detection & Analysis + +```bash +# Refresh code index +bash(mcp__code-index__refresh_index) + +# Detect changed modules +bash(~/.claude/scripts/detect_changed_modules.sh list) + +# Cache git changes +bash(git add -A 2>/dev/null || true) +``` + +**Parse output** `depth:N|path:|change:` to extract affected modules. + +**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack (Node.js/Python/Go/Rust/etc). + +**Fallback**: If no changes detected, use recent modules (first 10 by depth). + +## Phase 2: Plan Presentation + +**Present filtered plan**: +``` +Related Update Plan: + Tool: gemini (fallback: qwen β†’ codex) + Changed: 4 modules | Batching: 4 modules/agent + + Will update: + - ./src/api/auth (5 files) [new module] + - ./src/api (12 files) [parent of changed auth/] + - ./src (8 files) [parent context] + - . (14 files) [root level] + + Auto-skipped (12 paths): + - Tests: ./src/api/auth.test.ts (8 paths) + - Config: tsconfig.json (3 paths) + - Other: node_modules (1 path) + + Agent allocation: + - Depth 3 (1 module): 1 agent [1] + - Depth 2 (1 module): 1 agent [1] + - Depth 1 (1 module): 1 agent [1] + - Depth 0 (1 module): 1 agent [1] + + Confirm execution? (y/n) +``` + +**Decision logic**: +- User confirms "y": Proceed with execution +- User declines "n": Abort, no changes +- <15 modules: Direct execution +- β‰₯15 modules: Agent batch execution + +## Phase 3A: Direct Execution (<15 modules) + +**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead, tool fallback per module. + +```javascript +let modules_by_depth = group_by_depth(changed_modules); +let tool_order = construct_tool_order(primary_tool); + +for (let depth of sorted_depths.reverse()) { // N β†’ 0 + let modules = modules_by_depth[depth]; + let batches = batch_modules(modules, 4); // Split into groups of 4 + + for (let batch of batches) { + // Execute batch in parallel (max 4 concurrent) + let parallel_tasks = batch.map(module => { + return async () => { + let success = false; + for (let tool of tool_order) { + let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "." "related" "${tool}"); + if (exit_code === 0) { + report("${module.path} updated with ${tool}"); + success = true; + break; + } + } + if (!success) { + report("FAILED: ${module.path} failed all tools"); + } + }; + }); + + await Promise.all(parallel_tasks.map(task => task())); // Run batch in parallel + } +} +``` + +**Benefits**: +- No agent startup overhead +- Parallel execution within depth (max 4 concurrent) +- Tool fallback still applies per module +- Faster for small changesets (<15 modules) +- Same batching strategy as Phase 3B but without agent layer + +--- + +## Phase 3B: Agent Batch Execution (β‰₯15 modules) + +### Batching Strategy + +```javascript +// Batch modules into groups of 4 +function batch_modules(modules, batch_size = 4) { + let batches = []; + for (let i = 0; i < modules.length; i += batch_size) { + batches.push(modules.slice(i, i + batch_size)); + } + return batches; +} +// Examples: 10β†’[4,4,2] | 8β†’[4,4] | 3β†’[3] +``` + +### Coordinator Orchestration + +```javascript +let modules_by_depth = group_by_depth(changed_modules); +let tool_order = construct_tool_order(primary_tool); + +for (let depth of sorted_depths.reverse()) { // N β†’ 0 + let batches = batch_modules(modules_by_depth[depth], 4); + let worker_tasks = []; + + for (let batch of batches) { + worker_tasks.push( + Task( + subagent_type="memory-bridge", + description=`Update ${batch.length} modules at depth ${depth}`, + prompt=generate_batch_worker_prompt(batch, tool_order, "related") + ) + ); + } + + await parallel_execute(worker_tasks); // Batches run in parallel +} +``` + +### Batch Worker Prompt Template + +``` +PURPOSE: Update CLAUDE.md for assigned modules with tool fallback (related mode) + +TASK: +Update documentation for the following modules based on recent changes. For each module, try tools in order until success. + +MODULES: +{{module_path_1}} +{{module_path_2}} +{{module_path_3}} +{{module_path_4}} + +TOOLS (try in order): +1. {{tool_1}} +2. {{tool_2}} +3. {{tool_3}} + +EXECUTION: +For each module above: + 1. cd "{{module_path}}" + 2. Try tool 1: + bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "related" "{{tool_1}}") + β†’ Success: Report "{{module_path}} updated with {{tool_1}}", proceed to next module + β†’ Failure: Try tool 2 + 3. Try tool 2: + bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "related" "{{tool_2}}") + β†’ Success: Report "{{module_path}} updated with {{tool_2}}", proceed to next module + β†’ Failure: Try tool 3 + 4. Try tool 3: + bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "related" "{{tool_3}}") + β†’ Success: Report "{{module_path}} updated with {{tool_3}}", proceed to next module + β†’ Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module + +REPORTING: +Report final summary with: +- Total processed: X modules +- Successful: Y modules +- Failed: Z modules +- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z +- Detailed results for each module +``` + +### Example Execution + +**Depth 3 (new module)**: +```javascript +Task(subagent_type="memory-bridge", batch=[./src/api/auth], mode="related") +``` + +**Benefits**: +- 4 modules β†’ 1 agent (75% reduction) +- Parallel batches, sequential within batch +- Each module gets full fallback chain +- Context-aware updates based on git changes + +## Phase 4: Safety Verification + +```bash +# Check only CLAUDE.md modified +bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified") + +# Display statistics +bash(git diff --stat) +``` + +**Aggregate results**: +``` +Update Summary: + Total: 4 | Success: 4 | Failed: 0 + + Tool usage: + - gemini: 4 modules + - qwen: 0 modules (fallback) + - codex: 0 modules + + Changes: + src/api/auth/CLAUDE.md | 45 +++++++++++++++++++++ + src/api/CLAUDE.md | 23 +++++++++-- + src/CLAUDE.md | 12 ++++-- + CLAUDE.md | 8 ++-- + 4 files changed, 82 insertions(+), 6 deletions(-) +``` + +## Execution Summary + +**Module Count Threshold**: +- **<15 modules**: Coordinator executes Phase 3A (Direct Execution) +- **β‰₯15 modules**: Coordinator executes Phase 3B (Agent Batch Execution) + +**Agent Hierarchy** (for β‰₯15 modules): +- **Coordinator**: Handles batch division, spawns worker agents per depth +- **Worker Agents**: Each processes 4 modules with tool fallback (related mode) + +## Error Handling + +**Batch Worker**: +- Tool fallback per module (auto-retry) +- Batch isolation (failures don't propagate) +- Clear per-module status reporting + +**Coordinator**: +- No changes: Use fallback (recent 10 modules) +- User decline: No execution +- Safety check fail: Auto-revert staging +- Partial failures: Continue execution, report failed modules + +**Fallback Triggers**: +- Non-zero exit code +- Script timeout +- Unexpected output + +## Tool Reference + +| Tool | Best For | Fallback To | +|--------|--------------------------------|----------------| +| gemini | Documentation, patterns | qwen β†’ codex | +| qwen | Architecture, system design | gemini β†’ codex | +| codex | Implementation, code quality | gemini β†’ qwen | + +## Usage Examples + +```bash +# Daily development update +/memory:update-related + +# After feature work with specific tool +/memory:update-related --tool qwen + +# Code quality review after implementation +/memory:update-related --tool codex +``` + +## Key Advantages + +**Efficiency**: 30 modules β†’ 8 agents (73% reduction) +**Resilience**: 3-tier fallback per module +**Performance**: Parallel batches, no concurrency limits +**Context-aware**: Updates based on actual git changes +**Fast**: Only affected modules, not entire project + +## Coordinator Checklist + +- Parse `--tool` (default: gemini) +- Refresh code index for accurate change detection +- Detect changed modules via detect_changed_modules.sh +- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs) +- Cache git changes +- Apply fallback if no changes (recent 10 modules) +- Construct tool fallback order +- **Present filtered plan** with skip reasons and change types +- **Wait for y/n confirmation** +- Determine execution mode: + - **<15 modules**: Direct execution (Phase 3A) + - For each depth (Nβ†’0): Sequential module updates with tool fallback + - **β‰₯15 modules**: Agent batch execution (Phase 3B) + - For each depth (Nβ†’0): Batch modules (4 per batch), spawn batch workers in parallel +- Wait for depth/batch completion +- Aggregate results +- Safety check (only CLAUDE.md modified) +- Display git diff statistics + summary + +## Comparison with Full Update + +| Aspect | Related Update | Full Update | +|--------|----------------|-------------| +| **Scope** | Changed modules only | All project modules | +| **Speed** | Fast (minutes) | Slower (10-30 min) | +| **Use case** | Daily development | Major refactoring | +| **Mode** | `"related"` | `"full"` | +| **Trigger** | After commits | After major changes | +| **Batching** | 4 modules/agent | 4 modules/agent | +| **Fallback** | geminiβ†’qwenβ†’codex | geminiβ†’qwenβ†’codex | +| **Complexity threshold** | ≀15 modules | ≀20 modules | diff --git a/.claude/scripts/update_module_claude.sh b/.claude/scripts/update_module_claude.sh index e0a26ae0..bf952583 100644 --- a/.claude/scripts/update_module_claude.sh +++ b/.claude/scripts/update_module_claude.sh @@ -123,10 +123,11 @@ update_module_claude() { local base_prompt=" ⚠️ CRITICAL RULES - MUST FOLLOW: - 1. ONLY modify CLAUDE.md files - 2. NEVER modify source code files - 3. Focus exclusively on updating documentation - 4. Follow the template guidelines exactly + 1. Target file: ONLY create/update the file named 'CLAUDE.md' in current directory + 2. File name: MUST be exactly 'CLAUDE.md' (not ToolSidebar.CLAUDE.md or any variant) + 3. NEVER modify source code files + 4. Focus exclusively on updating documentation + 5. Follow the template guidelines exactly $template_content diff --git a/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt b/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt index 2e9d5f32..a50133f4 100644 --- a/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt +++ b/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt @@ -1,6 +1,12 @@ Create or update CLAUDE.md documentation using unified module/file template. +## ⚠️ FILE NAMING RULE (CRITICAL) +- Target file: MUST be named exactly `CLAUDE.md` in the current directory +- NEVER create files like `ToolSidebar.CLAUDE.md` or `[filename].CLAUDE.md` +- ALWAYS use the fixed name: `CLAUDE.md` + ## CORE CHECKLIST ⚑ +β–‘ MUST create/update file named exactly 'CLAUDE.md' (not variants) β–‘ MUST include all 6 sections: Purpose, Structure, Components, Dependencies, Integration, Implementation β–‘ For code files: Document all public/exported APIs with complete parameter details β–‘ For folders: Reference subdirectory CLAUDE.md files instead of duplicating @@ -64,6 +70,11 @@ Create or update CLAUDE.md documentation using unified module/file template. ## OUTPUT REQUIREMENTS +### File Naming (CRITICAL) +- **Output file**: MUST be named exactly `CLAUDE.md` in the current directory +- **Examples of WRONG naming**: `ToolSidebar.CLAUDE.md`, `index.CLAUDE.md`, `utils.CLAUDE.md` +- **Correct naming**: `CLAUDE.md` (always, for all directories) + ### Template Structure ```markdown # [Module/File Name] @@ -143,6 +154,7 @@ Create or update CLAUDE.md documentation using unified module/file template. - Update existing CLAUDE.md files rather than creating duplicate sections ## VERIFICATION CHECKLIST βœ“ +β–‘ Output file is named exactly 'CLAUDE.md' (not [filename].CLAUDE.md) β–‘ All 6 required sections included (Purpose, Structure, Components, Dependencies, Integration, Implementation) β–‘ All public/exported APIs documented with complete signatures β–‘ Parameters documented with types, descriptions, and defaults