From 51a0cb3a3c2423af6c4bb3b9e59950cbe6b45db2 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 20 Oct 2025 10:58:31 +0800 Subject: [PATCH] docs: release v4.6.2 - documentation optimization and /memory:load refinement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### Documentation Optimization **Optimized `/memory:load` Command Specification**: - Reduced documentation from 273 to 240 lines (12% reduction) - Merged redundant sections for better information flow - Removed unnecessary internal implementation details - Simplified usage examples while preserving clarity - Maintained all critical information (parameters, workflow, JSON structure) ### Documentation Updates **CHANGELOG.md**: - Added v4.6.2 release entry with documentation improvements **COMMAND_SPEC.md**: - Updated `/memory:load` specification to match actual implementation - Corrected syntax: `[--tool gemini|qwen]` instead of outdated `[--agent] [--json]` flags - Added agent-driven execution details **GETTING_STARTED.md**: - Added "Quick Context Loading for Specific Tasks" section - Positioned between "Full Project Index Rebuild" and "Incremental Related Module Updates" - Includes practical examples and use case guidance **README.md**: - Updated version badge to v4.6.2 - Updated latest release description **COMMAND_REFERENCE.md**: - Added `/memory:load` command reference entry 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/commands/memory/load.md | 240 ++++++++++++++++++++++++++++++++ CHANGELOG.md | 27 ++++ COMMAND_REFERENCE.md | 1 + COMMAND_SPEC.md | 21 +++ GETTING_STARTED.md | 25 ++++ README.md | 4 +- 6 files changed, 316 insertions(+), 2 deletions(-) create mode 100644 .claude/commands/memory/load.md diff --git a/.claude/commands/memory/load.md b/.claude/commands/memory/load.md new file mode 100644 index 00000000..32eca9b2 --- /dev/null +++ b/.claude/commands/memory/load.md @@ -0,0 +1,240 @@ +--- +name: load +description: Load project memory by delegating to agent, returns structured core content package for subsequent operations +argument-hint: "[--tool gemini|qwen] \"task context description\"" +allowed-tools: Task(*), Bash(*) +examples: + - /memory:load "在当前前端基础上开发用户认证功能" + - /memory:load --tool qwen "重构支付模块API" +--- + +# Memory Load Command (/memory:load) + +## 1. Overview + +The `memory:load` command **delegates to a general-purpose agent** to analyze the project and return a structured "Core Content Pack". This pack is loaded into the main thread's memory, providing essential context for subsequent agent operations while minimizing token consumption. + +**Core Philosophy**: +- **Agent-Driven**: Fully delegates execution to general-purpose agent +- **Read-Only Analysis**: Does not modify code, only extracts context +- **Structured Output**: Returns standardized JSON content package +- **Memory Optimization**: Package loaded directly into main thread memory +- **Token Efficiency**: CLI analysis executed within agent to save tokens + +## 2. Parameters + +- `"task context description"` (Required): Task description to guide context extraction + - Example: "在当前前端基础上开发用户认证功能" + - Example: "重构支付模块API" + - Example: "修复数据库查询性能问题" + +- `--tool ` (Optional): Specify CLI tool for agent to use (default: gemini) + - gemini: Large context window, suitable for complex project analysis + - qwen: Alternative to Gemini with similar capabilities + +## 3. Agent-Driven Execution Flow + +The command fully delegates to **general-purpose agent**, which autonomously: + +1. **Analyzes Project Structure**: Executes `get_modules_by_depth.sh` to understand architecture +2. **Loads Documentation**: Reads CLAUDE.md, README.md and other key docs +3. **Extracts Keywords**: Derives core keywords from task description +4. **Discovers Files**: Uses MCP code-index or rg/find to locate relevant files +5. **CLI Deep Analysis**: Executes Gemini/Qwen CLI for deep context analysis +6. **Generates Content Package**: Returns structured JSON core content package + +## 4. Core Content Package Structure + +**Output Format** - Loaded into main thread memory for subsequent use: + +```json +{ + "task_context": "在当前前端基础上开发用户认证功能", + "keywords": ["前端", "用户", "认证", "auth", "login"], + "project_summary": { + "architecture": "TypeScript + React frontend with Vite build system", + "tech_stack": ["React", "TypeScript", "Vite", "TailwindCSS"], + "key_patterns": [ + "State management via Context API", + "Functional components with Hooks pattern", + "API calls encapsulated in custom hooks" + ] + }, + "relevant_files": [ + { + "path": "src/components/Auth/LoginForm.tsx", + "relevance": "Existing login form component", + "priority": "high" + }, + { + "path": "src/contexts/AuthContext.tsx", + "relevance": "Authentication state management context", + "priority": "high" + }, + { + "path": "CLAUDE.md", + "relevance": "Project development standards", + "priority": "high" + } + ], + "integration_points": [ + "Must integrate with existing AuthContext", + "Follow component organization pattern: src/components/[Feature]/", + "API calls should use src/hooks/useApi.ts wrapper" + ], + "constraints": [ + "Maintain backward compatibility", + "Follow TypeScript strict mode", + "Use existing UI component library" + ] +} +``` + +## 5. Agent Invocation + +```javascript +Task( + subagent_type="general-purpose", + description="Load project memory: ${task_description}", + prompt=` +## Mission: Load Project Memory Context + +**Task Context**: "${task_description}" +**Mode**: Read-only analysis +**Tool**: ${tool || 'gemini'} + +## Execution Steps + +### Step 1: Foundation Analysis + +1. **Project Structure** + \`\`\`bash + bash(~/.claude/scripts/get_modules_by_depth.sh) + \`\`\` + +2. **Core Documentation** + \`\`\`javascript + Read(CLAUDE.md) + Read(README.md) + \`\`\` + +### Step 2: Keyword Extraction & File Discovery + +1. Extract core keywords from task description +2. Discover relevant files using MCP code-index or rg: + \`\`\`javascript + // Prefer MCP tools + mcp__code-index__find_files(pattern="*{keyword}*") + mcp__code-index__search_code_advanced(pattern="{keyword}", context_lines=2) + + // Fallback: use rg + bash(rg -l "{keyword}" --type ts --type md) + \`\`\` + +### Step 3: Deep Analysis via CLI + +Execute Gemini/Qwen CLI for deep analysis (saves main thread tokens): + +\`\`\`bash +cd . && ~/.claude/scripts/${tool}-wrapper -p " +PURPOSE: Extract project core context for task: ${task_description} +TASK: Analyze project architecture, tech stack, key patterns, relevant files +MODE: analysis +CONTEXT: @{CLAUDE.md,README.md,${discovered_files}} +EXPECTED: Structured project summary and integration point analysis +RULES: +- Focus on task-relevant core information +- Identify key architecture patterns and technical constraints +- Extract integration points and development standards +- Output concise, structured format +" +\`\`\` + +### Step 4: Generate Core Content Package + +Generate structured JSON content package (format shown above) + +**Required Fields**: +- task_context: Original task description +- keywords: Extracted keyword array +- project_summary: Architecture, tech stack, key patterns +- relevant_files: File list with path, relevance, priority +- integration_points: Integration guidance +- constraints: Development constraints + +### Step 5: Return Content Package + +Return JSON content package as final output for main thread to load into memory. + +## Quality Checklist + +Before returning: +- [ ] Valid JSON format +- [ ] All required fields complete +- [ ] relevant_files contains 3-10 files minimum +- [ ] project_summary accurately reflects architecture +- [ ] integration_points clearly specify integration paths +- [ ] keywords accurately extracted (3-8 keywords) +- [ ] Content concise, avoiding redundancy (< 5KB total) + + ` +) +``` + +## 6. Usage Examples + +### Example 1: Load Context for New Feature + +```bash +/memory:load "在当前前端基础上开发用户认证功能" +``` + +**Agent Execution**: +1. Analyzes project structure (`get_modules_by_depth.sh`) +2. Reads CLAUDE.md, README.md +3. Extracts keywords: ["前端", "用户", "认证", "auth"] +4. Uses MCP to search relevant files +5. Executes Gemini CLI for deep analysis +6. Returns core content package + +**Returned Package** (loaded into memory): +```json +{ + "task_context": "在当前前端基础上开发用户认证功能", + "keywords": ["前端", "认证", "auth", "login"], + "project_summary": { ... }, + "relevant_files": [ ... ], + "integration_points": [ ... ], + "constraints": [ ... ] +} +``` + +### Example 2: Using Qwen Tool + +```bash +/memory:load --tool qwen "重构支付模块API" +``` + +Agent uses Qwen CLI for analysis, returns same structured package. + +### Example 3: Bug Fix Context + +```bash +/memory:load "修复登录验证错误" +``` + +Returns core context related to login validation, including test files and validation logic. + +### Memory Persistence + +- **Session-Scoped**: Content package valid for current session +- **Subsequent Reference**: All subsequent agents/commands can access +- **Reload Required**: New sessions need to re-execute /memory:load + +## 8. Notes + +- **Read-Only**: Does not modify any code, pure analysis +- **Token Optimization**: CLI analysis executed within agent, saves main thread tokens +- **Memory Loading**: Returned JSON loaded directly into main thread memory +- **Subsequent Use**: Other commands/agents can reference this package for development +- **Session-Level**: Content package valid for current session diff --git a/CHANGELOG.md b/CHANGELOG.md index 998ed8aa..82a69d15 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,33 @@ All notable changes to Claude Code Workflow (CCW) will be documented in this fil The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +n## [4.6.2] - 2025-10-20 + +### 📝 Documentation Optimization + +#### Improved + +**`/memory:load` Command Documentation**: Optimized command specification from 273 to 240 lines (12% reduction) +- Merged redundant sections for better information flow +- Removed unnecessary internal implementation details +- Simplified usage examples while preserving clarity +- Maintained all critical information (parameters, workflow, JSON structure) +- Improved user-centric documentation structure + +#### Updated + +**COMMAND_SPEC.md**: Updated `/memory:load` specification to match actual implementation +- Corrected syntax: `[--tool gemini|qwen]` instead of outdated `[--agent] [--json]` flags +- Added agent-driven execution details +- Clarified core philosophy and token-efficiency benefits + +**GETTING_STARTED.md**: Added "Quick Context Loading for Specific Tasks" section +- Positioned between "Full Project Index Rebuild" and "Incremental Related Module Updates" +- Includes practical examples and use case guidance +- Explains how `/memory:load` works and when to use it + +--- + ## [4.6.0] - 2025-10-18 ### 🎯 Concept Clarification & Agent-Driven Analysis diff --git a/COMMAND_REFERENCE.md b/COMMAND_REFERENCE.md index f4cafbab..109cf5d9 100644 --- a/COMMAND_REFERENCE.md +++ b/COMMAND_REFERENCE.md @@ -127,6 +127,7 @@ Commands for managing individual tasks within a workflow session. | Command | Description | |---|---| | `/memory:update-full` | Complete project-wide CLAUDE.md documentation update. | +| `/memory:load` | Quickly load key project context into memory based on a task description. | | `/memory:update-related` | Context-aware CLAUDE.md documentation updates based on recent changes. | | `/version` | Display version information and check for updates. | | `/enhance-prompt` | Context-aware prompt enhancement using session memory and codebase analysis. | diff --git a/COMMAND_SPEC.md b/COMMAND_SPEC.md index 3051f451..bfb3e1b9 100644 --- a/COMMAND_SPEC.md +++ b/COMMAND_SPEC.md @@ -299,6 +299,27 @@ Commands for managing individual tasks within a workflow session. /memory:update-full ``` +### **/memory:load** +- **Syntax**: `/memory:load [--tool gemini|qwen] "task context description"` +- **Parameters**: + - `"task context description"` (Required, String): Task description to guide context extraction. + - `--tool ` (Optional): Specify CLI tool for agent to use (default: gemini). +- **Responsibilities**: Delegates to `@general-purpose` agent to analyze the project and return a structured "Core Content Pack". This pack is loaded into the main thread's memory, providing essential context for subsequent operations. +- **Agent-Driven Execution**: Fully delegates to general-purpose agent which autonomously: + 1. Analyzes project structure and documentation + 2. Extracts keywords from task description + 3. Discovers relevant files using MCP code-index or search tools + 4. Executes Gemini/Qwen CLI for deep analysis + 5. Generates structured JSON content package +- **Core Philosophy**: Read-only analysis, token-efficient (CLI analysis in agent), structured output +- **Agent Calls**: `@general-purpose` agent. +- **Integration**: Provides quick, task-relevant context for subsequent agent operations while minimizing token consumption. +- **Example**: + ```bash + /memory:load "在当前前端基础上开发用户认证功能" + /memory:load --tool qwen "重构支付模块API" + ``` + ### **/memory:update-related** - **Syntax**: `/memory:update-related [--tool gemini|qwen|codex]` - **Responsibilities**: Performs a context-aware update of `CLAUDE.md` files for modules affected by recent git changes. diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index a5507ee6..56cceafb 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -226,6 +226,31 @@ Suitable for large-scale refactoring, architectural changes, or first-time CCW u - Weekly routine maintenance - When AI output drift is detected +#### Quick Context Loading for Specific Tasks + +When you need immediate, task-specific context without updating documentation: + +```bash +# Load context for a specific task into memory +/memory:load "在当前前端基础上开发用户认证功能" + +# Use alternative CLI tool for analysis +/memory:load --tool qwen "重构支付模块API" +``` + +**How It Works**: +- Delegates to an AI agent for autonomous project analysis +- Discovers relevant files and extracts task-specific keywords +- Uses CLI tools (Gemini/Qwen) for deep analysis to save tokens +- Returns a structured "Core Content Pack" loaded into memory +- Provides context for subsequent agent operations + +**When to Use**: +- Before starting a new feature or task +- When you need quick context without full documentation rebuild +- For task-specific architectural or pattern discovery +- As preparation for agent-based development workflows + #### Incremental Related Module Updates Suitable for daily development, updating only modules affected by changes: diff --git a/README.md b/README.md index ed6473d5..602fef80 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@
-[![Version](https://img.shields.io/badge/version-v4.6.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) +[![Version](https://img.shields.io/badge/version-v4.6.2-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]() [![MCP Tools](https://img.shields.io/badge/🔧_MCP_Tools-Experimental-orange.svg)](https://github.com/modelcontextprotocol) @@ -15,7 +15,7 @@ **Claude Code Workflow (CCW)** transforms AI development from simple prompt chaining into a robust, context-first orchestration system. It solves execution uncertainty and error accumulation through structured planning, deterministic execution, and intelligent multi-model orchestration. -> **🎉 Latest: v4.6.0** - Concept Clarification & Agent-Driven Analysis. See [CHANGELOG.md](CHANGELOG.md) for details. +> **🎉 Latest: v4.6.2** - Documentation Optimization & `/memory:load` Command Refinement. See [CHANGELOG.md](CHANGELOG.md) for details. > 📚 **New to CCW?** Check out the [**Getting Started Guide**](GETTING_STARTED.md) for a beginner-friendly 5-minute tutorial!