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

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
update-single	Update single module CLAUDE.md using Explore agent for deep codebase understanding, producing manual-style documentation (handbook, not API reference)	<path> [--tool gemini|qwen|codex]	Task(*), Bash(*), AskUserQuestion(*)

Single Module Documentation Update (/memory:update-single)

Overview

Generates a manual-style CLAUDE.md for a single target directory using Explore agent for deep semantic codebase understanding. The output reads like a module handbook — explaining what it does, how to use it, and how it integrates — rather than dry API documentation.

Core capabilities:

• Explore agent for semantic codebase exploration (not just file scanning)
• Manual/handbook-style output (usage guide, not reference docs)
• Interactive confirmation with exploration summary preview
• Tool fallback (gemini→qwen→codex)

Usage

/memory:update-single <path> [--tool gemini|qwen|codex]

# Arguments
<path>                         Target directory path (required)

# Options
--tool <gemini|qwen|codex>     Primary CLI tool (default: gemini)

# Examples
/memory:update-single src/auth
/memory:update-single .claude/commands --tool qwen
/memory:update-single ccw/frontend/src/components/issue

Output Artifacts

Artifact	Description
<path>/CLAUDE.md	Manual-style module handbook

CLAUDE.md Style — "说明书" not "文档":

• What this module does (purpose & responsibility)
• How to use it (patterns, conventions, examples)
• How it integrates (dependencies, exports, data flow)
• Important constraints (gotchas, rules, limitations)

Execution Process

Phase 1: Target Validation & Scan
   ├─ Parse arguments (path, --tool)
   ├─ Validate target directory exists
   └─ Quick structure scan (file count, types, depth)

Phase 2: Deep Exploration (Explore Agent)
   ├─ Launch Explore agent with "very thorough" level
   ├─ Analyze purpose, structure, patterns, exports, dependencies
   └─ Build comprehensive module understanding

Phase 3: Confirmation
   ├─ Display exploration summary (key findings)
   └─ AskUserQuestion: Generate / Cancel

Phase 4: Generate CLAUDE.md (CLI Tool)
   ├─ Construct manual-style prompt from exploration results
   ├─ Execute ccw cli with --mode write
   ├─ Tool fallback on failure
   └─ Write to <path>/CLAUDE.md

Phase 5: Verification
   └─ Display generated CLAUDE.md preview + stats

Implementation

Phase 1: Target Validation & Scan

// Parse arguments
const args = $ARGUMENTS.trim()
const parts = args.split(/\s+/)
const toolFlagIdx = parts.indexOf('--tool')
const primaryTool = toolFlagIdx !== -1 ? parts[toolFlagIdx + 1] : 'gemini'
const targetPath = parts.find(p => !p.startsWith('--') && p !== primaryTool)

if (!targetPath) {
  console.log('ERROR: <path> is required. Usage: /memory:update-single <path> [--tool gemini|qwen|codex]')
  return
}

// Validate path exists
Bash({ command: `test -d "${targetPath}" && echo "EXISTS" || echo "NOT_FOUND"`, run_in_background: false })
// → NOT_FOUND: abort with error

// Quick structure scan
Bash({ command: `find "${targetPath}" -maxdepth 3 -type f -not -path "*/node_modules/*" -not -path "*/.git/*" | wc -l`, run_in_background: false })
Bash({ command: `ls "${targetPath}"`, run_in_background: false })

// Check existing CLAUDE.md
const hasExisting = file_exists(`${targetPath}/CLAUDE.md`)

console.log(`
## Target: ${targetPath}

Files: ${fileCount}
Existing CLAUDE.md: ${hasExisting ? 'Yes (will be overwritten)' : 'No (new)'}
Tool: ${primaryTool}

Launching deep exploration...
`)

Phase 2: Deep Exploration (Explore Agent)

⚠️ CRITICAL: Use run_in_background: false — exploration results are REQUIRED before generation.

const explorationResult = Task(
  subagent_type="Explore",
  run_in_background=false,
  description=`Explore: ${targetPath}`,
  prompt=`
Thoroughly explore the module at "${targetPath}" with "very thorough" level. I need comprehensive understanding for generating a manual-style CLAUDE.md (说明书).

## Exploration Focus

Analyze from these 7 dimensions:

1. **Purpose & Responsibility**
   - What problem does this module solve?
   - What is its core responsibility in the larger system?
   - One-sentence summary a developer would use to describe it

2. **Directory Structure & Key Files**
   - Map directory layout and file organization
   - Identify entry points, core logic files, utilities, types
   - Note any naming conventions or organizational patterns

3. **Code Patterns & Conventions**
   - Common patterns used (factory, observer, middleware, hooks, etc.)
   - Import/export conventions
   - Error handling patterns
   - State management approach (if applicable)

4. **Public API / Exports**
   - What does this module expose to the outside?
   - Key functions, classes, components, types exported
   - How do consumers typically import from this module?

5. **Dependencies & Integration**
   - External packages this module depends on
   - Internal modules it imports from
   - Modules that depend on this one (reverse dependencies)
   - Data flow: how data enters and exits this module

6. **Constraints & Gotchas**
   - Non-obvious rules a developer must follow
   - Performance considerations
   - Security-sensitive areas
   - Common pitfalls or mistakes

7. **Development Workflow**
   - How to add new functionality to this module
   - Testing approach used
   - Build/compilation specifics (if any)

## Output Format

Return a structured summary covering all 7 dimensions above. Include specific file:line references where relevant. Focus on **actionable knowledge** — what a developer needs to know to work with this module effectively.
`
)

Phase 3: Confirmation

console.log(`
## Exploration Summary

${explorationResult}

---

**Will generate**: ${targetPath}/CLAUDE.md
**Style**: Manual/handbook (说明书)
**Tool**: ${primaryTool}
`)

AskUserQuestion({
  questions: [{
    question: `Generate manual-style CLAUDE.md for "${targetPath}"?`,
    header: "Confirm",
    multiSelect: false,
    options: [
      { label: "Generate", description: "Write CLAUDE.md based on exploration" },
      { label: "Cancel", description: "Abort without changes" }
    ]
  }]
})

// Cancel → abort

Phase 4: Generate CLAUDE.md (CLI Tool)

Tool fallback hierarchy:

const toolOrder = {
  'gemini': ['gemini', 'qwen', 'codex'],
  'qwen':   ['qwen', 'gemini', 'codex'],
  'codex':  ['codex', 'gemini', 'qwen']
}[primaryTool]

Generation via ccw cli:

for (let tool of toolOrder) {
  Bash({
    command: `ccw cli -p "PURPOSE: Generate a manual-style CLAUDE.md (说明书) for the module at current directory.
This CLAUDE.md should read like a developer handbook — practical, actionable, concise.

## Exploration Context (use as primary source)

${explorationResult}

## CLAUDE.md Structure Requirements

Generate CLAUDE.md following this exact structure:

### 1. Title & Summary
\`# <Module Name>\`
> One-line description of purpose

### 2. Responsibilities
- Bullet list of what this module owns
- Keep to 3-7 items, each one sentence

### 3. Structure
\`\`\`
directory-tree/
├── key-files-only
└── with-brief-annotations
\`\`\`

### 4. Key Patterns
- Code conventions specific to THIS module
- Import patterns, naming rules, style decisions
- NOT generic best practices — only module-specific patterns

### 5. Usage
- How other modules use this one
- Common import/usage examples (real code, not pseudo-code)

### 6. Integration Points
- **Depends on**: modules/packages this uses (with purpose)
- **Used by**: modules that import from here

### 7. Constraints & Gotchas
- Non-obvious rules developers MUST follow
- Common mistakes to avoid
- Performance or security notes

## Style Rules
- Be CONCISE: each section 3-10 lines max
- Be PRACTICAL: actionable knowledge only, no boilerplate
- Be SPECIFIC: reference actual files and patterns, not generic advice
- No API reference listings — this is a handbook, not a reference doc
- Total length: 50-150 lines of markdown
- Language: Match the project's primary language (check existing CLAUDE.md files)

MODE: write
CONTEXT: @**/*
EXPECTED: Single CLAUDE.md file at ./CLAUDE.md following the structure above
CONSTRAINTS: Only write CLAUDE.md, no other files" --tool ${tool} --mode write --cd "${targetPath}"`,
    run_in_background: false
  })

  if (exit_code === 0) {
    console.log(`✅ ${targetPath}/CLAUDE.md generated with ${tool}`)
    break
  }
  console.log(`⚠️ ${tool} failed, trying next...`)
}

Phase 5: Verification

// Check file was created/updated
Bash({ command: `test -f "${targetPath}/CLAUDE.md" && echo "EXISTS" || echo "MISSING"`, run_in_background: false })

// Show stats
Bash({ command: `wc -l "${targetPath}/CLAUDE.md"`, run_in_background: false })

// Preview first 30 lines
Read(`${targetPath}/CLAUDE.md`, { limit: 30 })

console.log(`
## Result

✅ Generated: ${targetPath}/CLAUDE.md
   Lines: ${lineCount}
   Style: Manual/handbook format
   Tool: ${usedTool}
`)

CLAUDE.md Output Style Guide

The generated CLAUDE.md is a 说明书 (handbook), NOT a reference doc:

Aspect	Handbook Style ✅	Reference Doc Style ❌
Purpose	"This module handles user auth"	"Authentication module"
Content	How to work with it	What every function does
Patterns	"Always use createAuthMiddleware()"	"List of all exports"
Constraints	"Never store tokens in localStorage"	"Token storage API"
Length	50-150 lines	300+ lines
Audience	Developer joining the team	API consumer

Error Handling

Error	Resolution
Path not found	Abort with clear error message
Explore agent failure	Fallback to basic ls + head file scan, continue
All CLI tools fail	Report failure with last error, suggest --tool override
Empty directory	Abort — nothing to document
Existing CLAUDE.md	Overwrite entirely (full regeneration)

Usage Examples

# Generate handbook for a module
/memory:update-single src/auth

# Use specific tool
/memory:update-single .claude/commands --tool qwen

# Deep nested module
/memory:update-single ccw/frontend/src/components/issue

# Root-level documentation
/memory:update-single .