mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-14 02:42:04 +08:00
feat: Add global relationships management to GlobalSymbolIndex
- Introduced a new schema version (v2) with a global_relationships table. - Implemented CRUD operations for file relationships, including update and delete functionalities. - Added query capabilities for relationships by target and symbols. - Created migration logic from v1 to v2 schema. - Enhanced tests for global relationships, covering various scenarios including insertion, querying, and deletion. docs: Add update-single command for generating module documentation - Created a new command to generate manual-style documentation (CLAUDE.md) for a single module. - Detailed execution process and implementation phases for the command. - Included usage examples and error handling guidelines. feat: Implement team command for CLI interface - Added a new team command for logging and retrieving messages in a team message bus. - Supported subcommands for logging, reading, listing, and checking status of messages. - Included error handling and JSON output options. test: Add comprehensive tests for global relationships - Developed extensive tests for the global_relationships table in GlobalSymbolIndex. - Covered schema creation, migration, CRUD operations, and performance benchmarks. - Ensured project isolation and validated query functionalities for relationships.
This commit is contained in:
catlog22
347
.claude/commands/memory/update-single.md
Normal file
347
.claude/commands/memory/update-single.md
Normal file
@@ -0,0 +1,347 @@
|
||||
---
|
||||
name: update-single
|
||||
description: Update single module CLAUDE.md using Explore agent for deep codebase understanding, producing manual-style documentation (handbook, not API reference)
|
||||
argument-hint: "<path> [--tool gemini|qwen|codex]"
|
||||
allowed-tools: 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
|
||||
|
||||
```bash
|
||||
/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
|
||||
|
||||
```javascript
|
||||
// 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.
|
||||
|
||||
```javascript
|
||||
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
|
||||
|
||||
```javascript
|
||||
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**:
|
||||
```javascript
|
||||
const toolOrder = {
|
||||
'gemini': ['gemini', 'qwen', 'codex'],
|
||||
'qwen': ['qwen', 'gemini', 'codex'],
|
||||
'codex': ['codex', 'gemini', 'qwen']
|
||||
}[primaryTool]
|
||||
```
|
||||
|
||||
**Generation via ccw cli**:
|
||||
```javascript
|
||||
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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```bash
|
||||
# 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 .
|
||||
```
|
||||
Reference in New Issue
Block a user