catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-11 02:33:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: 更新文档更新脚本，添加策略参数以支持单层和多层更新

Browse Source
This commit is contained in:
catlog22
2025-10-22 10:35:30 +08:00
parent 7783ee0ac5
commit b6c1880abf
4 changed files with 451 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
.claude/agents/memory-bridge.md
View File

@@ -41,9 +41,13 @@ TodoWrite([
# 2. Extract module paths for current depth # 2. Extract module paths for current depth
# 3. Launch parallel jobs (max 4) # 3. Launch parallel jobs (max 4)
# Depth 5 example: # Depth 5 example (Layer 3 - use multi-layer):
~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/analysis" "gemini" & ~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/analysis" "gemini" &
~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/development" "gemini" & ~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/development" "gemini" &
# Depth 1 example (Layer 2 - use single-layer):
~/.claude/scripts/update_module_claude.sh "single-layer" "./src/auth" "gemini" &
~/.claude/scripts/update_module_claude.sh "single-layer" "./src/api" "gemini" &
# ... up to 4 concurrent jobs # ... up to 4 concurrent jobs
# 4. Wait for all depth jobs to complete # 4. Wait for all depth jobs to complete
@@ -62,21 +66,24 @@ git status --short
## Tool Parameter Flow ## Tool Parameter Flow
**Command Format**: `update_module_claude.sh <path> <tool>` **Command Format**: `update_module_claude.sh <strategy> <path> <tool>`
Examples: Examples:
- Gemini: `update_module_claude.sh "./.claude/agents" "gemini" &` - Layer 3 (depth ≥3): `update_module_claude.sh "multi-layer" "./.claude/agents" "gemini" &`
- Qwen: `update_module_claude.sh "./src/api" "qwen" &` - Layer 2 (depth 1-2): `update_module_claude.sh "single-layer" "./src/api" "qwen" &`
- Codex: `update_module_claude.sh "./tests" "codex" &` - Layer 1 (depth 0): `update_module_claude.sh "single-layer" "./tests" "codex" &`
## Execution Rules ## Execution Rules
1. **Task Tracking**: Create TodoWrite entry for each depth before execution 1. **Task Tracking**: Create TodoWrite entry for each depth before execution
2. **Parallelism**: Max 4 jobs per depth, sequential across depths 2. **Parallelism**: Max 4 jobs per depth, sequential across depths
3. **Tool Passing**: Always pass tool parameter as 2nd argument 3. **Strategy Assignment**: Assign strategy based on depth:
4. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format - Depth ≥3 (Layer 3): Use "multi-layer" strategy
5. **Completion**: Mark todo completed only after all depth jobs finish - Depth 0-2 (Layers 1-2): Use "single-layer" strategy
6. **No Skipping**: Process every module from input list 4. **Tool Passing**: Always pass tool parameter as 3rd argument
5. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format
6. **Completion**: Mark todo completed only after all depth jobs finish
7. **No Skipping**: Process every module from input list
## Concise Output ## Concise Output

331
.claude/commands/memory/update-full.md
View File

@@ -1,32 +1,114 @@
--- ---
name: update-full name: update-full
description: Complete project-wide CLAUDE.md documentation update with agent-based parallel execution and tool fallback description: Complete project-wide CLAUDE.md documentation update with agent-based parallel execution and tool fallback
argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]" argument-hint: "[--tool gemini|qwen|codex] [--path <directory>] [--strategy single-layer|multi-layer]"
--- ---
# Full Documentation Update (/memory:update-full) # Full Documentation Update (/memory:update-full)
## Overview ## Overview
Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback (gemini→qwen→codex). Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback (gemini→qwen→codex) and 3-layer architecture support.
**Parameters**: **Parameters**:
- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini) - `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
- `--path <directory>`: Target specific directory (default: entire project) - `--path <directory>`: Target specific directory (default: entire project)
- `--strategy <single-layer|multi-layer>`: Update strategy (default: single-layer)
**Execution Flow**: **Execution Flow**:
1. Discovery & Analysis → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification 1. Discovery & Analysis → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification
## 3-Layer Architecture
**Layer Definition**:
- **Layer 3 (Bottom/Deepest)**: depth ≥ 3 - Use multi-layer strategy (generate CLAUDE.md for all subdirectories)
- **Layer 2 (Middle)**: depth 1-2 - Use single-layer strategy (aggregate from children)
- **Layer 1 (Top)**: depth 0 - Use single-layer strategy (aggregate from children)
**Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up)
## Update Strategies
### Strategy 1: single-layer (For Layers 1-2)
**Use Case**: Upper layers that aggregate from existing child CLAUDE.md files
**Context Configuration**:
- **Layer 2** (depth 1-2): `@*/CLAUDE.md @*.{ts,tsx,js,jsx,py,sh,md,json,yaml,yml}` - Direct children CLAUDE.md + current layer code
- **Layer 1** (depth 0): `@*/CLAUDE.md @*.{ts,tsx,js,jsx,py,sh,md,json,yaml,yml}` - Direct children CLAUDE.md + current layer code
**Benefits**:
- Minimal context consumption
- Clear layer separation
- Each layer reads only immediate children summaries
- Ideal for structured projects with defined hierarchy
**Example Execution Flow**:
```
src/auth/handlers/ (depth 3) - MULTI-LAYER STRATEGY
CONTEXT: @**/* (all files in handlers/ and subdirs)
GENERATES: ./CLAUDE.md + CLAUDE.md in each subdir with files
↓
src/auth/ (depth 2) - SINGLE-LAYER STRATEGY
CONTEXT: @*/CLAUDE.md @*.ts (handlers/CLAUDE.md, middleware/CLAUDE.md, index.ts)
GENERATES: ./CLAUDE.md only
↓
src/ (depth 1) - SINGLE-LAYER STRATEGY
CONTEXT: @*/CLAUDE.md (auth/CLAUDE.md, utils/CLAUDE.md)
GENERATES: ./CLAUDE.md only
↓
./ (depth 0) - SINGLE-LAYER STRATEGY
CONTEXT: @*/CLAUDE.md (src/CLAUDE.md, tests/CLAUDE.md)
GENERATES: ./CLAUDE.md only
```
### Strategy 2: multi-layer (For Layer 3 only)
**Use Case**: Deepest layer with unstructured files, initial documentation generation
**Context Configuration**:
- **Layer 3** (depth ≥3): `@**/*` - All files in current directory and generate CLAUDE.md for each subdirectory
**Benefits**:
- Handles unstructured file layouts
- Generates documentation for all directories with files
- Creates the foundation layer for upper layers to reference
- Ideal for leaf directories that haven't been documented yet
**Example Execution Flow**:
```
src/auth/handlers/ (depth 3) - MULTI-LAYER STRATEGY
CONTEXT: @**/* (all files: login.ts, logout.ts, validation/)
GENERATES: ./CLAUDE.md + validation/CLAUDE.md (if validation/ has files)
```
### Strategy Selection Guidelines
**Strategy Assignment by Layer**:
| Layer | Depth | Strategy | Purpose |
|-------|-------|----------|---------|
| Layer 3 (Deepest) | ≥3 | multi-layer | Generate docs for unstructured directories |
| Layer 2 (Middle) | 1-2 | single-layer | Aggregate from children + current code |
| Layer 1 (Top) | 0 | single-layer | Aggregate from children + current code |
**Layer 3 Processing**:
- Use multi-layer strategy to handle unstructured file layouts
- Generate CLAUDE.md for each directory containing files
- Create foundation for upper layers to reference
## Core Rules ## Core Rules
1. **Analyze First**: Git cache + module discovery before updates 1. **Analyze First**: Git cache + module discovery before updates
2. **Wait for Approval**: Present plan, no execution without user confirmation 2. **Wait for Approval**: Present plan, no execution without user confirmation
3. **Execution Strategy**: 3. **Execution Strategy**:
- <20 modules: Direct parallel execution (max 4 concurrent per depth, no agent overhead) - <20 modules: Direct parallel execution (max 4 concurrent per layer, no agent overhead)
- ≥20 modules: Agent batch processing (4 modules/agent, 73% overhead reduction) - ≥20 modules: Agent batch processing (4 modules/agent, 73% overhead reduction)
4. **Tool Fallback**: Auto-retry with fallback tools on failure 4. **Tool Fallback**: Auto-retry with fallback tools on failure
5. **Depth Sequential**: Process depths N→0, parallel batches within depth (both modes) 5. **Layer Sequential**: Process layers 3→2→1 (bottom-up), parallel batches within layer
6. **Safety Check**: Verify only CLAUDE.md files modified 6. **Safety Check**: Verify only CLAUDE.md files modified
7. **Strategy Parameter**: Pass `--strategy` to update script for correct context selection
8. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
## Tool Fallback Hierarchy ## Tool Fallback Hierarchy
@@ -60,17 +142,22 @@ bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
``` ```
Update Plan: Update Plan:
Tool: gemini (fallback: qwen → codex) Tool: gemini (fallback: qwen → codex)
Strategy: recursive-read
Total: 7 modules Total: 7 modules
Execution: Direct sequential (< 20 modules threshold) Execution: Direct sequential (< 20 modules threshold)
Will update: Will update:
- ./core/interfaces (12 files) - depth 2 - ./core/interfaces (12 files) - depth 2 [Layer 2]
- ./core (22 files) - depth 1 - ./core (22 files) - depth 1 [Layer 2]
- ./models (9 files) - depth 1 - ./models (9 files) - depth 1 [Layer 2]
- ./parametric (6 files) - depth 1 - ./parametric (6 files) - depth 1 [Layer 2]
- ./results (7 files) - depth 1 - ./results (7 files) - depth 1 [Layer 2]
- ./utils (12 files) - depth 1 - ./utils (12 files) - depth 1 [Layer 2]
- . (5 files) - depth 0 - . (5 files) - depth 0 [Layer 1]
Context Strategy:
- Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
- Layer 1 (depth 0): @*/CLAUDE.md + current code files
Auto-skipped (15 paths): Auto-skipped (15 paths):
- Tests: ./tests, **/*_test.py (8 paths) - Tests: ./tests, **/*_test.py (8 paths)
@@ -91,15 +178,21 @@ Update Plan:
``` ```
Update Plan: Update Plan:
Tool: gemini (fallback: qwen → codex) Tool: gemini (fallback: qwen → codex)
Strategy: multi-layer
Total: 31 modules Total: 31 modules
Execution: Agent batch processing (4 modules/agent) Execution: Agent batch processing (4 modules/agent)
Will update: Will update:
- ./src/features/auth (12 files) - ./src/features/auth (12 files) - depth 3 [Layer 3]
- ./.claude/commands/cli (6 files) - ./.claude/commands/cli (6 files) - depth 3 [Layer 3]
- ./src/utils (8 files) - ./src/utils (8 files) - depth 2 [Layer 2]
... ...
Context Strategy:
- Layer 3 (depth ≥3): @**/* (all files)
- Layer 2 (depth 1-2): @**/CLAUDE.md + @**/* (all CLAUDE.md + all files)
- Layer 1 (depth 0): @**/CLAUDE.md + @**/* (all CLAUDE.md + all files)
Auto-skipped (45 paths): Auto-skipped (45 paths):
- Tests: ./tests, ./src/**/*.test.ts (18 paths) - Tests: ./tests, ./src/**/*.test.ts (18 paths)
- Config: package.json, tsconfig.json, vite.config.ts (12 paths) - Config: package.json, tsconfig.json, vite.config.ts (12 paths)
@@ -107,10 +200,10 @@ Update Plan:
- Docs: ./README.md, ./docs (5 paths) - Docs: ./README.md, ./docs (5 paths)
- Other: .git, .vscode, coverage (2 paths) - Other: .git, .vscode, coverage (2 paths)
Agent allocation: Agent allocation (by LAYER):
- Depth 5 (8 modules): 2 agents [4, 4] - Layer 3 (14 modules, depth ≥3): 4 agents [4, 4, 4, 2]
- Depth 4 (7 modules): 2 agents [4, 3] - Layer 2 (15 modules, depth 1-2): 4 agents [4, 4, 4, 3]
- Depth 3 (6 modules): 2 agents [3, 3] - Layer 1 (2 modules, depth 0): 1 agent [2]
Estimated time: ~15-25 minutes Estimated time: ~15-25 minutes
@@ -125,15 +218,39 @@ Update Plan:
## Phase 3A: Direct Execution (<20 modules) ## Phase 3A: Direct Execution (<20 modules)
**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead, tool fallback per module. **Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead, tool fallback per module.
```javascript ```javascript
let modules_by_depth = group_by_depth(module_list); // Group modules by LAYER (not depth)
let tool_order = construct_tool_order(primary_tool); function group_by_layer(modules) {
let layers = {
3: [], // Layer 3: depth ≥3
2: [], // Layer 2: depth 1-2
1: [] // Layer 1: depth 0
};
for (let depth of sorted_depths.reverse()) { // N → 0 modules.forEach(module => {
let modules = modules_by_depth[depth]; if (module.depth >= 3) {
let batches = batch_modules(modules, 4); // Split into groups of 4 layers[3].push(module);
} else if (module.depth >= 1) {
layers[2].push(module);
} else {
layers[1].push(module);
}
});
return layers;
}
let modules_by_layer = group_by_layer(module_list);
let tool_order = construct_tool_order(primary_tool);
let strategy = get_strategy_parameter(); // single-layer or multi-layer
// Process by LAYER (3 → 2 → 1), not by depth
for (let layer of [3, 2, 1]) {
if (modules_by_layer[layer].length === 0) continue;
let batches = batch_modules(modules_by_layer[layer], 4); // Split into groups of 4
for (let batch of batches) { for (let batch of batches) {
// Execute batch in parallel (max 4 concurrent) // Execute batch in parallel (max 4 concurrent)
@@ -141,15 +258,15 @@ for (let depth of sorted_depths.reverse()) { // N → 0
return async () => { return async () => {
let success = false; let success = false;
for (let tool of tool_order) { for (let tool of tool_order) {
let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "." "${tool}"); let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}");
if (exit_code === 0) { if (exit_code === 0) {
report("${module.path} updated with ${tool}"); report("✅ ${module.path} (Layer ${layer}) updated with ${tool}");
success = true; success = true;
break; break;
} }
} }
if (!success) { if (!success) {
report("FAILED: ${module.path} failed all tools"); report("❌ FAILED: ${module.path} (Layer ${layer}) failed all tools");
} }
}; };
}); });
@@ -159,26 +276,28 @@ for (let depth of sorted_depths.reverse()) { // N → 0
} }
``` ```
**Example execution (7 modules)**: **Example execution (7 modules, recursive-read)**:
```bash ```bash
# Depth 2 (1 module) # Layer 2 (1 module: depth 2)
bash(cd ./core/interfaces && ~/.claude/scripts/update_module_claude.sh "." "gemini") bash(cd ./core/interfaces && ~/.claude/scripts/update_module_claude.sh "multi-layer" "." "gemini")
# → CONTEXT: @*/CLAUDE.md @*.ts @*.tsx... (direct children + current code)
# → Success with gemini # → Success with gemini
# Depth 1 (5 modules → 2 batches: [4, 1]) # Layer 2 (5 modules: depth 1 → 2 batches: [4, 1])
# Batch 1 (4 modules in parallel): # Batch 1 (4 modules in parallel):
bash(cd ./core && ~/.claude/scripts/update_module_claude.sh "." "gemini") & bash(cd ./core && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
bash(cd ./models && ~/.claude/scripts/update_module_claude.sh "." "gemini") & bash(cd ./models && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
bash(cd ./parametric && ~/.claude/scripts/update_module_claude.sh "." "gemini") & bash(cd ./parametric && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
bash(cd ./results && ~/.claude/scripts/update_module_claude.sh "." "gemini") & bash(cd ./results && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
wait # Wait for batch 1 to complete wait # Wait for batch 1 to complete
# Batch 2 (1 module): # Batch 2 (1 module):
bash(cd ./utils && ~/.claude/scripts/update_module_claude.sh "." "gemini") bash(cd ./utils && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini")
# → Success with gemini # → Success with gemini
# Depth 0 (1 module) # Layer 1 (1 module: depth 0)
bash(cd . && ~/.claude/scripts/update_module_claude.sh "." "gemini") bash(cd . && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini")
# → CONTEXT: @*/CLAUDE.md @*.ts... (direct children + current code)
# → Success with gemini # → Success with gemini
``` ```
@@ -210,40 +329,67 @@ function batch_modules(modules, batch_size = 4) {
### Coordinator Orchestration ### Coordinator Orchestration
```javascript ```javascript
let modules_by_depth = group_by_depth(module_list); // Group modules by LAYER (not depth)
function group_by_layer(modules) {
let layers = {
3: [], // Layer 3: depth ≥3
2: [], // Layer 2: depth 1-2
1: [] // Layer 1: depth 0
};
modules.forEach(module => {
if (module.depth >= 3) {
layers[3].push(module);
} else if (module.depth >= 1) {
layers[2].push(module);
} else {
layers[1].push(module);
}
});
return layers;
}
let modules_by_layer = group_by_layer(module_list);
let tool_order = construct_tool_order(primary_tool); let tool_order = construct_tool_order(primary_tool);
for (let depth of sorted_depths.reverse()) { // N → 0 // Process by LAYER (3 → 2 → 1), not by depth
let batches = batch_modules(modules_by_depth[depth], 4); for (let layer of [3, 2, 1]) {
if (modules_by_layer[layer].length === 0) continue;
let batches = batch_modules(modules_by_layer[layer], 4);
let worker_tasks = []; let worker_tasks = [];
for (let batch of batches) { for (let batch of batches) {
worker_tasks.push( worker_tasks.push(
Task( Task(
subagent_type="memory-bridge", subagent_type="memory-bridge",
description=`Update ${batch.length} modules at depth ${depth}`, description=`Update ${batch.length} modules in Layer ${layer}`,
prompt=generate_batch_worker_prompt(batch, tool_order) prompt=generate_batch_worker_prompt(batch, tool_order, strategy, layer)
) )
); );
} }
await parallel_execute(worker_tasks); // Batches run in parallel await parallel_execute(worker_tasks); // Batches run in parallel within layer
} }
``` ```
### Batch Worker Prompt Template ### Batch Worker Prompt Template
``` ```
PURPOSE: Update CLAUDE.md for assigned modules with tool fallback PURPOSE: Update CLAUDE.md for assigned modules with tool fallback and 3-layer architecture
TASK: TASK:
Update documentation for the following modules. For each module, try tools in order until success. Update documentation for the following modules. For each module, try tools in order until success.
Use the specified strategy for context selection.
STRATEGY: {{strategy}} # single-layer or multi-layer
MODULES: MODULES:
{{module_path_1}} {{module_path_1}} (depth: {{depth_1}}, layer: {{layer_1}})
{{module_path_2}} {{module_path_2}} (depth: {{depth_2}}, layer: {{layer_2}})
{{module_path_3}} {{module_path_3}} (depth: {{depth_3}}, layer: {{layer_3}})
{{module_path_4}} {{module_path_4}} (depth: {{depth_4}}, layer: {{layer_4}})
TOOLS (try in order): TOOLS (try in order):
1. {{tool_1}} 1. {{tool_1}}
@@ -254,17 +400,26 @@ EXECUTION:
For each module above: For each module above:
1. cd "{{module_path}}" 1. cd "{{module_path}}"
2. Try tool 1: 2. Try tool 1:
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "{{tool_1}}") bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "{{tool_1}}")
→ Success: Report " {{module_path}} updated with {{tool_1}}", proceed to next module → Success: Report "✅ {{module_path}} updated with {{tool_1}}", proceed to next module
→ Failure: Try tool 2 → Failure: Try tool 2
3. Try tool 2: 3. Try tool 2:
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "{{tool_2}}") bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "{{tool_2}}")
→ Success: Report " {{module_path}} updated with {{tool_2}}", proceed to next module → Success: Report "✅ {{module_path}} updated with {{tool_2}}", proceed to next module
→ Failure: Try tool 3 → Failure: Try tool 3
4. Try tool 3: 4. Try tool 3:
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "{{tool_3}}") bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "{{tool_3}}")
→ Success: Report " {{module_path}} updated with {{tool_3}}", proceed to next module → Success: Report "✅ {{module_path}} updated with {{tool_3}}", proceed to next module
→ Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module → Failure: Report "❌ FAILED: {{module_path}} failed all tools", proceed to next module
CONTEXT SELECTION (automated by script):
- Layer 3 (depth ≥3): @**/* (all files)
- Layer 2 (depth 1-2):
* recursive-read: @*/CLAUDE.md + current code files
* multi-layer: @**/CLAUDE.md + @**/*
- Layer 1 (depth 0):
* recursive-read: @*/CLAUDE.md + current code files
* multi-layer: @**/CLAUDE.md + @**/*
REPORTING: REPORTING:
Report final summary with: Report final summary with:
@@ -272,22 +427,36 @@ Report final summary with:
- Successful: Y modules - Successful: Y modules
- Failed: Z modules - Failed: Z modules
- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z - Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z
- Detailed results for each module - Detailed results for each module with layer information
``` ```
### Example Execution ### Example Execution
**Depth 5 (8 modules → 2 batches)**: **Layer-based allocation (31 modules total)**:
```javascript ```javascript
// Layer 3: 14 modules (depth ≥3) → 4 agents
Task(subagent_type="memory-bridge", batch=[mod1, mod2, mod3, mod4]) // Agent 1 Task(subagent_type="memory-bridge", batch=[mod1, mod2, mod3, mod4]) // Agent 1
Task(subagent_type="memory-bridge", batch=[mod5, mod6, mod7, mod8]) // Agent 2 Task(subagent_type="memory-bridge", batch=[mod5, mod6, mod7, mod8]) // Agent 2
// Both run in parallel Task(subagent_type="memory-bridge", batch=[mod9, mod10, mod11, mod12]) // Agent 3
Task(subagent_type="memory-bridge", batch=[mod13, mod14]) // Agent 4
// All 4 agents run in parallel
// Layer 2: 15 modules (depth 1-2) → 4 agents
Task(subagent_type="memory-bridge", batch=[mod15, mod16, mod17, mod18]) // Agent 5
Task(subagent_type="memory-bridge", batch=[mod19, mod20, mod21, mod22]) // Agent 6
Task(subagent_type="memory-bridge", batch=[mod23, mod24, mod25, mod26]) // Agent 7
Task(subagent_type="memory-bridge", batch=[mod27, mod28, mod29]) // Agent 8
// All 4 agents run in parallel
// Layer 1: 2 modules (depth 0) → 1 agent
Task(subagent_type="memory-bridge", batch=[mod30, mod31]) // Agent 9
``` ```
**Benefits**: **Benefits**:
- 8 modules → 2 agents (75% reduction) - 31 modules → 9 agents (71% reduction from sequential)
- Parallel batches, sequential within batch - Parallel execution within each layer
- Each module gets full fallback chain - Each module gets full fallback chain
- Layer isolation ensures proper dependency order
## Phase 4: Safety Verification ## Phase 4: Safety Verification
@@ -351,15 +520,22 @@ Update Summary:
## Path Parameter Examples ## Path Parameter Examples
```bash ```bash
# Full project update # Full project update with default strategy (single-layer)
/memory:update-full /memory:update-full
# Target specific directory # Full project update with multi-layer strategy
/memory:update-full --path .claude /memory:update-full --strategy multi-layer
# Target specific directory with single-layer
/memory:update-full --path .claude --strategy single-layer
/memory:update-full --path src/features/auth /memory:update-full --path src/features/auth
# Combine with tool selection # Combine all parameters
/memory:update-full --path .claude --tool qwen /memory:update-full --path .claude --tool qwen --strategy multi-layer
# Strategy selection based on project size
/memory:update-full --strategy single-layer # Large projects (>50 modules)
/memory:update-full --strategy multi-layer # Small projects (<20 modules)
``` ```
## Key Advantages ## Key Advantages
@@ -371,18 +547,29 @@ Update Summary:
## Coordinator Checklist ## Coordinator Checklist
- Parse `--tool` (default: gemini) and `--path` (default: current dir) - Parse `--tool` (default: gemini), `--path` (default: current dir), and `--strategy` (default: recursive-read)
- Git cache + module discovery - Git cache + module discovery
- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs) - **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs)
- **Group modules by LAYER** (not depth):
- Layer 3: depth ≥3
- Layer 2: depth 1-2
- Layer 1: depth 0
- Construct tool fallback order - Construct tool fallback order
- **Present filtered plan** with execution strategy (<20: direct, ≥20: agent batch) - **Determine strategy** based on project size or user specification:
- <20 modules: Use depth-based strategy assignment (multi-layer for depth ≥3, single-layer for depth 0-2)
- ≥20 modules: Use depth-based strategy assignment (multi-layer for depth ≥3, single-layer for depth 0-2)
- **Present filtered plan** with:
- Execution strategy (<20: direct, ≥20: agent batch)
- Layer groupings (not depth groupings)
- Context strategy per layer
- Agent allocation by LAYER
- **Wait for y/n confirmation** - **Wait for y/n confirmation**
- Determine execution mode: - Determine execution mode:
- **<20 modules**: Direct execution (Phase 3A) - **<20 modules**: Direct execution (Phase 3A)
- For each depth (N→0): Sequential module updates with tool fallback - For each layer (3→2→1): Parallel module updates within layer (max 4 concurrent) with tool fallback and strategy parameter
- **≥20 modules**: Agent batch execution (Phase 3B) - **≥20 modules**: Agent batch execution (Phase 3B)
- For each depth (N→0): Batch modules (4 per batch), spawn batch workers in parallel - For each layer (3→2→1): Batch modules (4 per batch), spawn batch workers in parallel with strategy parameter
- Wait for depth/batch completion - Wait for layer completion before moving to next layer
- Aggregate results - Aggregate results
- Safety check (only CLAUDE.md modified) - Safety check (only CLAUDE.md modified)
- Display git status + summary - Display git status + summary with layer statistics

8
.claude/commands/memory/update-related.md
View File

@@ -108,7 +108,7 @@ for (let depth of sorted_depths.reverse()) { // N → 0
return async () => { return async () => {
let success = false; let success = false;
for (let tool of tool_order) { for (let tool of tool_order) {
let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "." "${tool}"); let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "${tool}");
if (exit_code === 0) { if (exit_code === 0) {
report("${module.path} updated with ${tool}"); report("${module.path} updated with ${tool}");
success = true; success = true;
@@ -198,15 +198,15 @@ EXECUTION:
For each module above: For each module above:
1. cd "{{module_path}}" 1. cd "{{module_path}}"
2. Try tool 1: 2. Try tool 1:
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "{{tool_1}}") bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_1}}")
→ Success: Report "{{module_path}} updated with {{tool_1}}", proceed to next module → Success: Report "{{module_path}} updated with {{tool_1}}", proceed to next module
→ Failure: Try tool 2 → Failure: Try tool 2
3. Try tool 2: 3. Try tool 2:
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "{{tool_2}}") bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_2}}")
→ Success: Report "{{module_path}} updated with {{tool_2}}", proceed to next module → Success: Report "{{module_path}} updated with {{tool_2}}", proceed to next module
→ Failure: Try tool 3 → Failure: Try tool 3
4. Try tool 3: 4. Try tool 3:
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "." "{{tool_3}}") bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_3}}")
→ Success: Report "{{module_path}} updated with {{tool_3}}", proceed to next module → Success: Report "{{module_path}} updated with {{tool_3}}", proceed to next module
→ Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module → Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module

211
.claude/scripts/update_module_claude.sh
View File

@@ -1,20 +1,32 @@
#!/bin/bash #!/bin/bash
# Update CLAUDE.md for a specific module with unified template # Update CLAUDE.md for modules with two strategies
# Usage: update_module_claude.sh <module_path> [tool] [model] # Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]
# strategy: single-layer|multi-layer
# module_path: Path to the module directory # module_path: Path to the module directory
# tool: gemini|qwen|codex (default: gemini) # tool: gemini|qwen|codex (default: gemini)
# model: Model name (optional, uses tool defaults if not specified) # model: Model name (optional, uses tool defaults)
# #
# Default Models: # Default Models:
# gemini: gemini-2.5-flash # gemini: gemini-2.5-flash
# qwen: coder-model (default, -m optional) # qwen: coder-model
# codex: gpt5-codex # codex: gpt5-codex
# #
# Strategies:
# single-layer: Upward aggregation
# - Read: Current directory code + child CLAUDE.md files
# - Generate: Single ./CLAUDE.md in current directory
# - Use: Large projects, incremental bottom-up updates
#
# multi-layer: Downward distribution
# - Read: All files in current and subdirectories
# - Generate: CLAUDE.md for each directory containing files
# - Use: Small projects, full documentation generation
#
# Features: # Features:
# - Respects .gitignore patterns (current directory or git root) # - Minimal prompts based on unified template
# - Unified template for all modules (folders and files) # - Respects .gitignore patterns
# - Template-based documentation generation # - Path-focused processing (script only cares about paths)
# - Configurable model selection per tool # - Template-driven generation
# Build exclusion filters from .gitignore # Build exclusion filters from .gitignore
build_exclusion_filters() { build_exclusion_filters() {
@@ -65,15 +77,84 @@ build_exclusion_filters() {
echo "$filters" echo "$filters"
} }
# Scan directory structure and generate structured information
scan_directory_structure() {
local target_path="$1"
local strategy="$2"
if [ ! -d "$target_path" ]; then
echo "Directory not found: $target_path"
return 1
fi
local exclusion_filters=$(build_exclusion_filters)
local structure_info=""
# Get basic directory info
local dir_name=$(basename "$target_path")
local total_files=$(eval "find \"$target_path\" -type f $exclusion_filters 2>/dev/null" | wc -l)
local total_dirs=$(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null" | wc -l)
structure_info+="Directory: $dir_name\n"
structure_info+="Total files: $total_files\n"
structure_info+="Total directories: $total_dirs\n\n"
if [ "$strategy" = "multi-layer" ]; then
# For multi-layer: show all subdirectories with file counts
structure_info+="Subdirectories with files:\n"
while IFS= read -r dir; do
if [ -n "$dir" ] && [ "$dir" != "$target_path" ]; then
local rel_path=${dir#$target_path/}
local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
if [ $file_count -gt 0 ]; then
structure_info+=" - $rel_path/ ($file_count files)\n"
fi
fi
done < <(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null")
else
# For single-layer: show direct children only
structure_info+="Direct subdirectories:\n"
while IFS= read -r dir; do
if [ -n "$dir" ]; then
local dir_name=$(basename "$dir")
local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
local has_claude=$([ -f "$dir/CLAUDE.md" ] && echo " [has CLAUDE.md]" || echo "")
structure_info+=" - $dir_name/ ($file_count files)$has_claude\n"
fi
done < <(eval "find \"$target_path\" -maxdepth 1 -type d $exclusion_filters 2>/dev/null" | grep -v "^$target_path$")
fi
# Show main file types in current directory
structure_info+="\nCurrent directory files:\n"
local code_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.sh' \\) $exclusion_filters 2>/dev/null" | wc -l)
local config_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.toml' \\) $exclusion_filters 2>/dev/null" | wc -l)
local doc_files=$(eval "find \"$target_path\" -maxdepth 1 -type f -name '*.md' $exclusion_filters 2>/dev/null" | wc -l)
structure_info+=" - Code files: $code_files\n"
structure_info+=" - Config files: $config_files\n"
structure_info+=" - Documentation: $doc_files\n"
printf "%b" "$structure_info"
}
update_module_claude() { update_module_claude() {
local module_path="$1" local strategy="$1"
local tool="${2:-gemini}" local module_path="$2"
local model="$3" local tool="${3:-gemini}"
local model="$4"
# Validate parameters # Validate parameters
if [ -z "$module_path" ]; then if [ -z "$strategy" ] || [ -z "$module_path" ]; then
echo "❌ Error: Module path is required" echo "❌ Error: Strategy and module path are required"
echo "Usage: update_module_claude.sh <module_path> [tool] [model]" echo "Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]"
echo "Strategies: single-layer|multi-layer"
return 1
fi
# Validate strategy
if [ "$strategy" != "single-layer" ] && [ "$strategy" != "multi-layer" ]; then
echo "❌ Error: Invalid strategy '$strategy'"
echo "Valid strategies: single-layer, multi-layer"
return 1 return 1
fi fi
@@ -113,46 +194,77 @@ update_module_claude() {
# Use unified template for all modules # Use unified template for all modules
local template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt" local template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt"
# Read template content directly
local template_content=""
if [ -f "$template_path" ]; then
template_content=$(cat "$template_path")
echo " 📋 Loaded template: $(wc -l < "$template_path") lines"
else
echo " ⚠️ Template not found: $template_path"
echo " Using fallback template..."
template_content="Create comprehensive CLAUDE.md documentation following standard structure with Purpose, Structure, Components, Dependencies, Integration, and Implementation sections."
fi
# Scan directory structure first
echo " 🔍 Scanning directory structure..."
local structure_info=$(scan_directory_structure "$module_path" "$strategy")
# Prepare logging info # Prepare logging info
local module_name=$(basename "$module_path") local module_name=$(basename "$module_path")
echo "⚡ Updating: $module_path" echo "⚡ Updating: $module_path"
echo " Tool: $tool | Model: $model | Files: $file_count" echo " Strategy: $strategy | Tool: $tool | Model: $model | Files: $file_count"
echo " Template: $(basename "$template_path")" echo " Template: $(basename "$template_path") ($(echo "$template_content" | wc -l) lines)"
echo " Structure: Scanned $(echo "$structure_info" | wc -l) lines of structure info"
# Generate prompt with template injection # Build minimal strategy-specific prompt with explicit paths and structure info
local template_content="" local final_prompt=""
if [ -f "$template_path" ]; then
template_content=$(cat "$template_path") if [ "$strategy" = "multi-layer" ]; then
# multi-layer strategy: read all, generate for each directory
final_prompt="Directory Structure Analysis:
$structure_info
Read: @**/*
Generate CLAUDE.md files:
- Primary: ./CLAUDE.md (current directory)
- Additional: CLAUDE.md in each subdirectory containing files
Template Guidelines:
$template_content
Instructions:
- Work bottom-up: deepest directories first
- Parent directories reference children
- Each CLAUDE.md file must be in its respective directory
- Follow the template guidelines above for consistent structure
- Use the structure analysis to understand directory hierarchy"
else else
echo " ⚠️ Template not found: $template_path, using fallback" # single-layer strategy: read current + child CLAUDE.md, generate current only
template_content="Update CLAUDE.md documentation for this module: document structure, key components, dependencies, and integration points." final_prompt="Directory Structure Analysis:
$structure_info
Read: @*/CLAUDE.md @*.ts @*.tsx @*.js @*.jsx @*.py @*.sh @*.md @*.json @*.yaml @*.yml
Generate single file: ./CLAUDE.md
Template Guidelines:
$template_content
Instructions:
- Create exactly one CLAUDE.md file in the current directory
- Reference child CLAUDE.md files, do not duplicate their content
- Follow the template guidelines above for consistent structure
- Use the structure analysis to understand the current directory context"
fi fi
local base_prompt="
⚠️ CRITICAL RULES - MUST FOLLOW:
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
CONTEXT: @**/*"
# Execute update # Execute update
local start_time=$(date +%s) local start_time=$(date +%s)
echo " 🔄 Starting update..." echo " 🔄 Starting update..."
if cd "$module_path" 2>/dev/null; then if cd "$module_path" 2>/dev/null; then
local tool_result=0 local tool_result=0
local final_prompt="$base_prompt
Module Information:
- Name: $module_name
- Path: $module_path
- Tool: $tool"
# Execute with selected tool # Execute with selected tool
# NOTE: Model parameter (-m) is placed AFTER the prompt # NOTE: Model parameter (-m) is placed AFTER the prompt
@@ -200,5 +312,22 @@ update_module_claude() {
# Execute function if script is run directly # Execute function if script is run directly
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
# Show help if no arguments or help requested
if [ $# -eq 0 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
echo "Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]"
echo ""
echo "Strategies:"
echo " single-layer - Read current dir code + child CLAUDE.md, generate ./CLAUDE.md"
echo " multi-layer - Read all files, generate CLAUDE.md for each directory"
echo ""
echo "Tools: gemini (default), qwen, codex"
echo "Models: Use tool defaults if not specified"
echo ""
echo "Examples:"
echo " ./update_module_claude.sh single-layer ./src/auth"
echo " ./update_module_claude.sh multi-layer ./components gemini gemini-2.5-flash"
exit 0
fi
update_module_claude "$@" update_module_claude "$@"
fi fi