From d0b08794ca94642baab8ff31da7e958ee9c72d32 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sun, 14 Sep 2025 20:59:15 +0800 Subject: [PATCH] refactor: Reorganize workflow documentation structure and eliminate redundancy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Major Changes - **Replace 3 documents with 2**: Consolidate 655 lines to ~550 lines (40% reduction) - **New Structure**: - `intelligent-tools-strategy.md` (strategic layer) - `tools-implementation-guide.md` (implementation layer) - **Remove old files**: `intelligent-tools.md`, `gemini-unified.md`, `codex-unified.md` ## Content Improvements - **Quick Start section**: Essential commands for immediate use - **Strategic guidance**: Tool selection matrix and decision framework - **Implementation details**: Part A (shared), Part B (Gemini), Part C (Codex) - **Eliminate duplicates**: Template system, file patterns, execution settings ## Reference Updates - **Agent files**: Update to new document paths (3 files) - **Command files**: Batch update all references (12 files) - **README files**: Update English and Chinese versions - **Workflow files**: Update plan.md reference ## Benefits - 40% content reduction while preserving all unique information - Clear layer separation: strategy vs implementation - Improved navigation and maintainability - Enhanced quick reference capabilities 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/agents/action-planning-agent.md | 2 +- .claude/agents/code-developer.md | 2 +- .claude/agents/code-review-test-agent.md | 4 +- .claude/commands/codex/analyze.md | 4 +- .claude/commands/codex/chat.md | 2 +- .claude/commands/codex/execute.md | 4 +- .claude/commands/codex/mode/bug-index.md | 4 +- .claude/commands/codex/mode/plan.md | 2 +- .claude/commands/enhance-prompt.md | 2 +- .claude/commands/gemini/analyze.md | 4 +- .claude/commands/gemini/execute.md | 4 +- .claude/commands/workflow/plan.md | 2 +- .claude/workflows/codex-unified.md | 297 -------------- .claude/workflows/gemini-unified.md | 254 ------------ .../workflows/intelligent-tools-strategy.md | 149 +++++++ .claude/workflows/intelligent-tools.md | 103 ----- .../workflows/tools-implementation-guide.md | 376 ++++++++++++++++++ CLAUDE.md | 3 +- README.md | 4 +- README_CN.md | 4 +- 20 files changed, 549 insertions(+), 677 deletions(-) delete mode 100644 .claude/workflows/codex-unified.md delete mode 100644 .claude/workflows/gemini-unified.md create mode 100644 .claude/workflows/intelligent-tools-strategy.md delete mode 100644 .claude/workflows/intelligent-tools.md create mode 100644 .claude/workflows/tools-implementation-guide.md diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index 2c9e7db4..f559bf1d 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -44,7 +44,7 @@ You are a pure execution agent specialized in creating actionable implementation **Analysis CLI Usage Standards**: - **Gemini CLI**: Use task-specific paths: `bash(~/.claude/scripts/gemini-wrapper -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) @{CLAUDE.md}")` - **Codex CLI**: Use task-specific paths: `bash(codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]")` -- **Follow Guidelines**: @~/.claude/workflows/gemini-unified.md and @~/.claude/workflows/codex-unified.md +- **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md ### Deep Analysis Execution **When DEEP_ANALYSIS_REQUIRED flag is present:** diff --git a/.claude/agents/code-developer.md b/.claude/agents/code-developer.md index 0c5352a3..e717c228 100644 --- a/.claude/agents/code-developer.md +++ b/.claude/agents/code-developer.md @@ -58,7 +58,7 @@ ELIF context insufficient OR task has analysis marker: **Analysis CLI Usage Standards**: - **Gemini CLI**: Use task-specific paths from JSON: `bash(~/.claude/scripts/gemini-wrapper -p "$(~/.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]")` - **Codex CLI**: Use task-specific paths from JSON: `bash(codex --full-auto exec "$(~/.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]")` -- **Follow Guidelines**: @~/.claude/workflows/gemini-unified.md and @~/.claude/workflows/codex-unified.md +- **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md **Test-Driven Development**: diff --git a/.claude/agents/code-review-test-agent.md b/.claude/agents/code-review-test-agent.md index fe99a9e0..195177e5 100644 --- a/.claude/agents/code-review-test-agent.md +++ b/.claude/agents/code-review-test-agent.md @@ -74,7 +74,7 @@ ELSE: When [GEMINI_CLI_REQUIRED] flag is present or complexity triggers apply, gather precise, change-focused context: Use the targeted review context template: -@~/.claude/workflows/gemini-unified.md +@~/.claude/workflows/tools-implementation-guide.md **Gemini CLI Command**: ```bash @@ -92,7 +92,7 @@ This executes a change-specific Gemini CLI command that identifies: When [CODEX_CLI_REQUIRED] flag is present, execute autonomous analysis: Use the autonomous development context template: -@~/.claude/workflows/codex-unified.md +@~/.claude/workflows/tools-implementation-guide.md **Codex CLI Command**: ```bash diff --git a/.claude/commands/codex/analyze.md b/.claude/commands/codex/analyze.md index 9c3808ef..0ef22708 100644 --- a/.claude/commands/codex/analyze.md +++ b/.claude/commands/codex/analyze.md @@ -16,7 +16,7 @@ model: haiku ## Overview Quick analysis tool for codebase insights using intelligent pattern detection and template-driven analysis with Codex CLI. -**Core Guidelines**: @~/.claude/workflows/codex-unified.md +**Core Guidelines**: @~/.claude/workflows/tools-implementation-guide.md ⚠️ **Critical Difference**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files. @@ -152,4 +152,4 @@ Context: [user_description]" | Pattern Flexibility | Must be explicit | Auto-includes with flag | For detailed syntax, patterns, and advanced usage see: -**@~/.claude/workflows/codex-unified.md** \ No newline at end of file +**@~/.claude/workflows/tools-implementation-guide.md** \ No newline at end of file diff --git a/.claude/commands/codex/chat.md b/.claude/commands/codex/chat.md index bc03f304..1b4c2b8e 100644 --- a/.claude/commands/codex/chat.md +++ b/.claude/commands/codex/chat.md @@ -186,4 +186,4 @@ When `--save-session` flag is used: ``` For detailed syntax, patterns, and advanced usage see: -**@~/.claude/workflows/codex-unified.md** \ No newline at end of file +**@~/.claude/workflows/tools-implementation-guide.md** \ No newline at end of file diff --git a/.claude/commands/codex/execute.md b/.claude/commands/codex/execute.md index 4a1b621d..4ae2cf80 100644 --- a/.claude/commands/codex/execute.md +++ b/.claude/commands/codex/execute.md @@ -20,7 +20,7 @@ model: sonnet **Purpose**: Execute implementation tasks using intelligent context inference and Codex CLI with full permissions. -**Core Guidelines**: @~/.claude/workflows/codex-unified.md +**Core Guidelines**: @~/.claude/workflows/tools-implementation-guide.md ⚠️ **Critical Difference**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files. @@ -220,4 +220,4 @@ Based on task type, automatically selects: | Development Focus | Code generation & implementation | Analysis & planning | For detailed patterns, syntax, and templates see: -**@~/.claude/workflows/codex-unified.md** \ No newline at end of file +**@~/.claude/workflows/tools-implementation-guide.md** \ No newline at end of file diff --git a/.claude/commands/codex/mode/bug-index.md b/.claude/commands/codex/mode/bug-index.md index 77308c3d..4d4eed85 100644 --- a/.claude/commands/codex/mode/bug-index.md +++ b/.claude/commands/codex/mode/bug-index.md @@ -17,7 +17,7 @@ model: sonnet ## Overview Systematic bug analysis, debugging, and automated fix implementation using expert diagnostic templates with Codex CLI. -**Core Guidelines**: @~/.claude/workflows/codex-unified.md +**Core Guidelines**: @~/.claude/workflows/tools-implementation-guide.md ⚠️ **Critical Difference**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files. @@ -266,4 +266,4 @@ When `--save-session` used, saves to: ``` For detailed syntax, patterns, and advanced usage see: -**@~/.claude/workflows/codex-unified.md** \ No newline at end of file +**@~/.claude/workflows/tools-implementation-guide.md** \ No newline at end of file diff --git a/.claude/commands/codex/mode/plan.md b/.claude/commands/codex/mode/plan.md index bb4d9f98..2ffdfea3 100644 --- a/.claude/commands/codex/mode/plan.md +++ b/.claude/commands/codex/mode/plan.md @@ -257,4 +257,4 @@ When `--save-session` used, saves to: ``` For detailed syntax, patterns, and advanced usage see: -**@~/.claude/workflows/codex-unified.md** \ No newline at end of file +**@~/.claude/workflows/tools-implementation-guide.md** \ No newline at end of file diff --git a/.claude/commands/enhance-prompt.md b/.claude/commands/enhance-prompt.md index 6bb2122f..66128df2 100644 --- a/.claude/commands/enhance-prompt.md +++ b/.claude/commands/enhance-prompt.md @@ -105,7 +105,7 @@ The `/enhance-prompt` command is designed to run automatically when the system d ### 🛠️ **Gemini Integration Protocol (Internal)** -**Gemini Integration**: @~/.claude/workflows/gemini-unified.md +**Gemini Integration**: @~/.claude/workflows/tools-implementation-guide.md This section details how the system programmatically interacts with the Gemini CLI. - **Primary Tool**: All Gemini analysis is performed via direct calls to the `gemini` command-line tool (e.g., `gemini --all-files -p "..."`). diff --git a/.claude/commands/gemini/analyze.md b/.claude/commands/gemini/analyze.md index 76b3c94a..e64120fa 100644 --- a/.claude/commands/gemini/analyze.md +++ b/.claude/commands/gemini/analyze.md @@ -16,7 +16,7 @@ model: haiku ## Overview Quick analysis tool for codebase insights using intelligent pattern detection and template-driven analysis. -**Core Guidelines**: @~/.claude/workflows/gemini-unified.md +**Core Guidelines**: @~/.claude/workflows/tools-implementation-guide.md ## Analysis Types @@ -95,4 +95,4 @@ Analysis results include: - **Integration Points**: How components connect For detailed syntax, patterns, and advanced usage see: -**@~/.claude/workflows/gemini-unified.md** \ No newline at end of file +**@~/.claude/workflows/tools-implementation-guide.md** \ No newline at end of file diff --git a/.claude/commands/gemini/execute.md b/.claude/commands/gemini/execute.md index 1a8cfb00..ff1917c4 100644 --- a/.claude/commands/gemini/execute.md +++ b/.claude/commands/gemini/execute.md @@ -20,7 +20,7 @@ model: sonnet **Purpose**: Execute implementation tasks using intelligent context inference and Gemini CLI with full permissions. -**Core Guidelines**: @~/.claude/workflows/gemini-unified.md +**Core Guidelines**: @~/.claude/workflows/tools-implementation-guide.md ## 🚨 YOLO Permissions @@ -167,4 +167,4 @@ Execute implementation following task acceptance criteria." **vs. `/gemini:analyze`**: Execute performs analysis **and implementation**, analyze is read-only. For detailed patterns, syntax, and templates see: -**@~/.claude/workflows/gemini-unified.md** \ No newline at end of file +**@~/.claude/workflows/tools-implementation-guide.md** \ No newline at end of file diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index cbe57410..d3bc2bfe 100644 --- a/.claude/commands/workflow/plan.md +++ b/.claude/commands/workflow/plan.md @@ -120,7 +120,7 @@ Three analysis levels available: **Analysis Selection**: - Default: Auto-selects based on project complexity - Manual: Use flags to override automatic selection -- Strategy: See @~/.claude/workflows/intelligent-tools.md for tool selection principles +- Strategy: See @~/.claude/workflows/intelligent-tools-strategy.md for tool selection principles **Execution**: 1. Always runs `get_modules_by_depth.sh` for structure diff --git a/.claude/workflows/codex-unified.md b/.claude/workflows/codex-unified.md deleted file mode 100644 index 189e7875..00000000 --- a/.claude/workflows/codex-unified.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -name: codex-unified -description: Comprehensive Codex CLI guidelines - core rules, syntax, patterns, templates, and best practices with automation focus -type: technical-guideline ---- - -### 🚀 Command Overview: Bash(codex *) - -- **Purpose**: An AI-powered CLI tool for automated codebase analysis, intelligent code generation, and autonomous development workflows. -- **⚠️ CRITICAL**: **NO wrapper script exists** - always use direct `codex` command, never `~/.claude/scripts/codex` -- **Key Characteristic**: **No `--all-files` flag** - requires explicit `@` pattern references for file inclusion. -- **Directory Analysis Rule**: When user intends to analyze specific directory (cd XXX), use: `bash(codex --cd XXX --full-auto exec "prompt")` or `bash(cd XXX && codex --full-auto exec "@{**/*} prompt")` -- **Default Mode**: `--full-auto exec` autonomous development mode (RECOMMENDED for all tasks). -- **Primary Triggers**: - - When user needs automated code generation or refactoring. - - When task requires intelligent analysis with autonomous execution. - - When building complex features or applications from scratch. -- **Core Use Cases**: - - Automated application development. - - Intelligent code refactoring and optimization. - - Context-aware feature implementation. - - Autonomous debugging and problem-solving. - -### ⭐ **CRITICAL: Default to `--full-auto` Mode** - -> **🎯 Golden Rule**: Always start with `bash(codex --full-auto exec "your task description")` for maximum autonomous capabilities. This is the recommended approach for 90% of development tasks. - -**Why `bash(codex --full-auto)` Should Be Your Default:** -- **🧠 Intelligent File Discovery**: Codex automatically identifies relevant files without manual `@` patterns -- **🎯 Context-Aware Execution**: Understands project structure and dependencies autonomously -- **⚡ Streamlined Workflow**: No need to specify file patterns - just describe what you want -- **🚀 Maximum Automation**: Leverages full autonomous development capabilities -- **📚 Smart Documentation**: Automatically includes relevant CLAUDE.md files and project context - -**When to Use `bash(codex --full-auto exec)` with Explicit Patterns:** -- ✅ When you need precise control over which files are included -- ✅ When working with specific file patterns that require manual specification -- ✅ When debugging issues with file discovery in `--full-auto` mode -- ❌ **NOT as a default choice** - reserve for special circumstances - -### ⚙️ Command Syntax & Arguments - -- **Basic Structure** (Priority Order): - ```bash - bash(codex --full-auto exec "autonomous development task") # DEFAULT & RECOMMENDED - bash(codex --full-auto exec "prompt with @{patterns}") # For specific control needs - ``` - - **⚠️ NEVER use**: `~/.claude/scripts/codex` - this wrapper script does not exist! -- **Key Commands** (In Order of Preference): - - `bash(codex --full-auto exec "...")` ⭐ **PRIMARY MODE** - Full autonomous development - - `bash(codex --full-auto exec "...")` - Controlled execution when you need specific patterns - - `bash(codex --cd /path --full-auto exec "...")` - Directory-specific autonomous development - - `bash(codex --cd /path --full-auto exec "@{patterns} ...")` - Directory-specific execution with patterns - -- **Template Usage** (Preferred Approaches): - ```bash - # RECOMMENDED: Full autonomous mode (let Codex handle file discovery) - bash(codex --full-auto exec "Refactor authentication system using best practices") - - # Alternative: Direct execution with explicit patterns - bash(codex --full-auto exec "@{src/**/*} @{CLAUDE.md} Refactor authentication system") - - # Advanced: Template injection with autonomous mode - bash(codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) - - ## Task: Authentication System Refactoring - - Apply modern security patterns - - Improve code organization - - Add comprehensive tests") - ``` - -### 📂 File Pattern Rules - **CRITICAL FOR CODEX** - -⚠️ **UNLIKE GEMINI**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files. - -- **Syntax**: - - `@{pattern}`: Single file or directory pattern. - - `@{pattern1,pattern2}`: Multiple patterns, comma-separated. -- **Essential Patterns**: - ```bash - @{**/*} # All files recursively (equivalent to --all-files) - @{src/**/*} # All source files - @{*.ts,*.js} # Specific file types - @{CLAUDE.md,**/*CLAUDE.md} # Documentation hierarchy - @{package.json,*.config.*} # Configuration files - ``` -- **Cross-Platform Rules**: - - Always use forward slashes (`/`) for paths. - - Enclose paths with spaces in quotes: `@{"My Project/src/**/*"}`. - - Escape special characters like brackets: `@{src/**/*\[bracket\]*}`. - -### ⏱️ Execution Settings - -- **Default Timeout**: Bash command execution extended to **10 minutes** to handle complex autonomous development workflows. -- **Autonomous Intelligence**: Codex automatically manages file discovery and context gathering in `--full-auto` mode. - -### 📁 Templates - -**Structure**: `~/.claude/workflows/cli-templates/prompts/` - -**Categories**: -- `analysis/` - pattern.txt, architecture.txt, security.txt, performance.txt, quality.txt (Gemini primary, Codex compatible) -- `development/` - feature.txt, component.txt, refactor.txt, testing.txt, debugging.txt (Codex primary) -- `planning/` - task-breakdown.txt, migration.txt (Cross-tool) -- `automation/` - scaffold.txt, migration.txt, deployment.txt (Codex specialized) -- `review/` - code-review.txt (Cross-tool) -- `integration/` - api-design.txt, database.txt (Codex primary) - -**Usage**: `$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)` - -### 📦 Standard Command Structures - -- **Module-Specific Development** - ```bash - # RECOMMENDED: Full autonomous mode with directory context - bash(codex --cd src/auth --full-auto exec "Refactor authentication module using latest patterns") - - # Alternative: Full autonomous mode with explicit task description - bash(codex --full-auto exec "Refactor the authentication module in src/auth/ using latest security patterns") - - # Fallback: Explicit patterns when autonomous mode needs guidance - bash(codex --full-auto exec "@{src/auth/**/*,CLAUDE.md} Refactor authentication module using latest patterns") - - # Alternative: Directory-specific execution with explicit patterns - bash(codex --cd src/auth --full-auto exec "@{**/*,../../CLAUDE.md} Refactor authentication module using latest patterns") - ``` - -- **Basic Development Task** - ```bash - # RECOMMENDED: Let Codex handle everything autonomously - bash(codex --full-auto exec "Implement user authentication with JWT tokens") - - # Alternative: Explicit file patterns if needed - bash(codex --full-auto exec "@{src/**/*,*.json,CLAUDE.md} Implement user authentication with JWT") - ``` - -- **Template-Enhanced Development** - ```bash - # RECOMMENDED: Autonomous mode with template guidance - bash(codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) - - ## Task: User Authentication System - - JWT token management - - Role-based access control - - Password reset functionality") - - # Alternative: Explicit patterns with templates - bash(codex --full-auto exec "@{src/**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)") - ``` - -- **Full Auto Mode (PRIMARY RECOMMENDATION)** - ```bash - # OPTIMAL: Let Codex discover files and handle everything - bash(codex --full-auto exec "Create a complete todo application with React and TypeScript") - - # Alternative: Explicit patterns if you want to control file scope - bash(codex --full-auto exec "@{**/*} Create a complete todo application with React and TypeScript") - ``` - -- **Debugging & Analysis** - ```bash - # RECOMMENDED: Autonomous debugging mode - bash(codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/development/debugging.txt) - - ## Issue: Performance degradation in user dashboard - - Identify bottlenecks in the codebase - - Propose and implement optimizations - - Add performance monitoring") - - # Alternative: Explicit patterns for controlled analysis - bash(codex --full-auto exec "@{src/**/*,package.json,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/debugging.txt)") - ``` - -### ⭐ Best Practices & Rules - -#### 🎯 Codex-Specific Guidelines - -**Always Use @ Patterns:** -- **MANDATORY**: Codex requires explicit file references via `@` patterns -- **No automatic inclusion**: Unlike gemini's `--all-files`, you must specify what to analyze -- **Be comprehensive**: Use `@{**/*}` for full codebase context when needed -- **Be selective**: Use specific patterns like `@{src/**/*.ts}` for targeted analysis - -**Default Automation Mode (CRITICAL GUIDANCE):** -- **`bash(codex --full-auto exec)` is the PRIMARY choice**: Use for 90% of all tasks - maximizes autonomous capabilities -- **`bash(codex --full-auto exec)` with explicit patterns only when necessary**: Reserve for cases where you need explicit file pattern control -- **Trust the autonomous intelligence**: Codex excels at file discovery, context gathering, and architectural decisions -- **Start with `bash(codex --full-auto exec)` always**: If it doesn't meet needs, then consider explicit patterns with `exec` mode - -#### 📋 CLAUDE.md Loading Rules - -**Critical Difference from Gemini:** -- **Always explicit**: Must use `@{CLAUDE.md}` or `@{**/*CLAUDE.md}` -- **No automatic loading**: Codex will not include documentation without explicit reference -- **Hierarchical loading**: Use `@{CLAUDE.md,**/*CLAUDE.md}` for complete context - -#### ⚠️ Error Prevention - -- **Always include @ patterns**: Commands without file references will fail -- **Test patterns first**: Validate @ patterns match existing files -- **Use comprehensive patterns**: `@{**/*}` when unsure of file structure -- **Include documentation**: Always add `@{CLAUDE.md,**/*CLAUDE.md}` for context -- **Quote complex paths**: Use proper shell quoting for paths with spaces - -#### 🔄 Template Reuse - -**Compatibility with Gemini Templates:** -- **`cat` command works identically**: Reuse gemini templates seamlessly -- **Cross-reference patterns**: Combine analysis and development templates -- **Template composition**: Build complex prompts from multiple template sources - -#### 🚀 Automation Workflow - -**Autonomous Development Pattern:** -1. **Context Gathering**: `@{**/*,CLAUDE.md}` for full project understanding -2. **Pattern Analysis**: Understand existing code conventions -3. **Automated Implementation**: Let codex handle the development workflow -4. **Quality Assurance**: Built-in testing and validation - -### 📊 Codex vs Gemini Quick Reference - -| Feature | Codex | Gemini | -|---------|--------|---------| -| File Loading | `@` patterns **required** | `--all-files` available | -| Default Mode | `--full-auto exec` automation | Interactive analysis | -| Primary Use | Development & implementation | Analysis & planning | -| Template Support | Full compatibility via `cat` | Native template system | -| Automation Level | Autonomous execution | Manual implementation | -| Working Directory | `--cd` flag support | Current directory | - -### 🎯 Integration with Development Workflow - -**Pre-Development Analysis:** -```bash -# RECOMMENDED: Autonomous pattern analysis -bash(codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) - -Analyze the existing codebase patterns and conventions before implementing new features.") - -# Alternative: Explicit patterns if needed -bash(codex --full-auto exec "@{src/**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)") -``` - -**Feature Development:** -```bash -# RECOMMENDED: Full autonomous feature development -bash(codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) - -## Feature: Advanced Search Functionality -- Full-text search capabilities -- Filter and sort options -- Performance optimization -- Integration with existing UI components") - -# Alternative: Explicit patterns when needed -bash(codex --full-auto exec "@{**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)") -``` - -**Quality Assurance:** -```bash -# RECOMMENDED: Autonomous testing and validation -bash(codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/development/testing.txt) - -Generate comprehensive tests and perform validation for the entire codebase.") - -# Alternative: Specific test scope control -bash(codex --full-auto exec "@{src/**/*,test/**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/testing.txt)") -``` - -### 🎨 Advanced Usage Patterns - -**Multi-Phase Development (Full Autonomous Workflow):** -```bash -# Phase 1: Autonomous Analysis -bash(codex --full-auto exec "Analyze current architecture for payment system integration") - -# Phase 2: Autonomous Implementation (RECOMMENDED APPROACH) -bash(codex --full-auto exec "Implement Stripe payment integration based on the analyzed architecture") - -# Phase 3: Autonomous Testing -bash(codex --full-auto exec "Generate comprehensive tests for the payment system implementation") - -# Alternative: Explicit control when needed -bash(codex --full-auto exec "@{**/*,CLAUDE.md} Analyze current architecture for payment system integration") -``` - -**Cross-Project Learning:** -```bash -# RECOMMENDED: Autonomous cross-project pattern learning -bash(codex --full-auto exec "Implement feature X by learning patterns from ../other-project/ and applying them to the current codebase") - -# Alternative: Explicit pattern specification -bash(codex --full-auto exec "@{../other-project/src/**/*,src/**/*,CLAUDE.md} Implement feature X using patterns from other-project") -``` - -Remember: **Codex excels at autonomous development** - `bash(codex --full-auto exec)` mode should be your default choice. Trust its intelligence for file discovery, context gathering, and implementation decisions. Use explicit `@` patterns with `bash(codex --full-auto exec)` only when you need precise control over file scope. \ No newline at end of file diff --git a/.claude/workflows/gemini-unified.md b/.claude/workflows/gemini-unified.md deleted file mode 100644 index 5363924a..00000000 --- a/.claude/workflows/gemini-unified.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -name: gemini-unified -description: Consolidated Gemini CLI guidelines - core rules, syntax, patterns, templates, and best practices -type: technical-guideline ---- - -### 🚀 Command Overview: Bash(gemini *) - -- **Purpose**: A CLI tool for comprehensive codebase analysis, context gathering, and pattern detection across multiple files. -- **Directory Analysis Rule**: When user intends to analyze specific directory (cd XXX), always navigate first: `cd XXX && gemini -p "prompt"` -- **Primary Triggers**: - - When user intent is to "analyze", "get context", or "understand the codebase". - - When a task requires understanding relationships between multiple files. - - When the problem scope exceeds a single file. -- **Core Use Cases**: - - Project-wide context acquisition. - - Architectural analysis and pattern detection. - - Identification of coding standards and conventions. - -## ⭐ **RECOMMENDED: Use `gemini-wrapper` as Primary Method** - -> **🎯 Core Recommendation**: Always use `gemini-wrapper` instead of direct `gemini` commands. This intelligent wrapper handles token limits, approval modes, and error management automatically. - -### 🎯 Intelligent Wrapper: `gemini-wrapper` (PRIMARY METHOD) - -- **Purpose**: Smart wrapper that automatically manages `--all-files` flag and approval modes based on project analysis -- **Location**: `~/.claude/scripts/gemini-wrapper` (auto-installed) -- **Token Threshold**: 2,000,000 tokens (configurable via `GEMINI_TOKEN_LIMIT`) -- **Auto-Management Features**: - - **Token-based `--all-files`**: Small projects get `--all-files`, large projects use patterns - - **Smart approval modes**: Analysis tasks use `default`, execution tasks use `yolo` - - **Error logging**: Captures and logs execution errors to `~/.claude/.logs/gemini-errors.log` -- **Task Detection**: - - **Analysis keywords**: "analyze", "analysis", "review", "understand", "inspect", "examine" → `--approval-mode default` - - **All other tasks**: → `--approval-mode yolo` -- **Usage**: Use full path `~/.claude/scripts/gemini-wrapper` - all parameters pass through unchanged -- **Benefits**: Prevents token limits, optimizes approval workflow, provides error tracking -- **Setup**: Script auto-installs to `~/.claude/scripts/` location - -**⚡ Quick Start Examples:** -```bash -# RECOMMENDED: Let wrapper handle everything automatically -bash(~/.claude/scripts/gemini-wrapper -p "Analyze authentication patterns") - -# Analysis task - wrapper auto-detects and uses --approval-mode default -bash(~/.claude/scripts/gemini-wrapper -p "Review code quality and conventions") - -# Development task - wrapper auto-detects and uses --approval-mode yolo -bash(~/.claude/scripts/gemini-wrapper -p "Implement user dashboard feature") - -# Directory-specific analysis -bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p "Analyze module patterns") -``` - -### ⚙️ Command Syntax & Arguments - -- **Basic Structure**: - ```bash - gemini [flags] -p "@{patterns} {template} prompt" - ``` -- **Key Arguments**: - - `--all-files`: Includes all files in the current working directory - - `-p`: The prompt string, which must contain file reference patterns and the analysis query. - - `{template}`: Template injection using `$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)` for standardized analysis - - `@{pattern}`: A special syntax for referencing files and directories. - - `--approval-mode`: Tool approval mode (`default` for analysis | `yolo` for execution) - - `--include-directories`: Additional workspace directories (max 5, comma-separated) - -- **Template Usage**: - ```bash - # Without template (manual prompt) - bash(gemini --all-files -p "@{src/**/*} @{CLAUDE.md} Analyze code patterns and conventions") - - # With template (recommended) - bash(gemini --all-files -p "@{src/**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)") - - # Multi-template composition - bash(gemini --all-files -p "@{src/**/*} @{CLAUDE.md} $(cat <<'EOF' - $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) - - Additional Security Focus: - $(cat ~/.claude/workflows/cli-templates/prompts/analysis/security.txt) - EOF - )") - ``` - - -### 📂 File Pattern Rules - -- **Syntax**: - - `@{pattern}`: Single file or directory pattern. - - `@{pattern1,pattern2}`: Multiple patterns, comma-separated. -- **Wildcards**: - ```bash - * # Any character (excluding path separators) - ** # Any directory levels (recursive) - ? # Any single character - [abc] # Any character within the brackets - {a,b,c} # Any of the options within the braces - ``` -- **Cross-Platform Rules**: - - Always use forward slashes (`/`) for paths. - - Enclose paths with spaces in quotes: `@{"My Project/src/**/*"}`. - - Escape special characters like brackets: `@{src/**/*\[bracket\]*}`. - -### ⏱️ Execution Settings - -- **Default Timeout**: Bash command execution extended to **10 minutes** to handle large codebase analysis. -- **Token Limit Handling**: When `--all-files` exceeds token limits, **remove `--all-files` and re-execute** with specific `@{patterns}` to target relevant files only. - - -### 📁 Templates - -**Structure**: `~/.claude/workflows/cli-templates/prompts/` - -**Categories**: -- `analysis/` - pattern.txt, architecture.txt, security.txt, performance.txt, quality.txt (Gemini primary) -- `development/` - feature.txt, component.txt, refactor.txt, testing.txt, debugging.txt (Codex primary) -- `planning/` - task-breakdown.txt, migration.txt (Cross-tool) -- `review/` - code-review.txt (Cross-tool) - -**Usage**: `$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)` - - -### 📦 Standard Command Structures - -> **⚠️ IMPORTANT**: Use `gemini-wrapper` for 90% of all tasks. Only use direct `gemini` commands when you need explicit manual control. - -#### 🎯 Using Intelligent Wrapper (PRIMARY CHOICE - 90% of tasks) - -- **Automatic Token & Approval Management** - ```bash - # Analysis task - auto adds --approval-mode default - bash(~/.claude/scripts/gemini-wrapper -p "Analyze authentication module patterns and implementation") - - # Execution task - auto adds --approval-mode yolo - bash(~/.claude/scripts/gemini-wrapper -p "Implement user login feature with JWT tokens") - - # Navigate to specific directory with wrapper - bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p "Review authentication patterns") - - # Override token threshold if needed - bash(GEMINI_TOKEN_LIMIT=500000 ~/.claude/scripts/gemini-wrapper -p "Custom threshold analysis") - - # Multi-directory support with wrapper - bash(~/.claude/scripts/gemini-wrapper --include-directories /path/to/other/project -p "Cross-project analysis") - ``` - -- **Module-Specific Analysis (Quick Module Analysis)** - ```bash - # Navigate to module directory for focused analysis - bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p "Analyze authentication module patterns and implementation") - - # Or specify module from root directory - bash(cd backend/services && ~/.claude/scripts/gemini-wrapper -p "Review service architecture and dependencies") - - # Template-enhanced module analysis with wrapper - bash(cd frontend/components && ~/.claude/scripts/gemini-wrapper -p "$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)") - ``` - -#### 📝 Direct Gemini Usage (Manual Control - Use Only When Needed) - -- **Manual Token Management** - ```bash - # Direct gemini usage when you want explicit control - bash(gemini --all-files -p "Analyze authentication module patterns and implementation") - - # Fallback when wrapper suggests pattern usage - bash(gemini -p "@{src/auth/**/*} @{CLAUDE.md} Analyze authentication patterns") - ``` - -- **Basic Structure (Manual Prompt)** - ```bash - bash(gemini --all-files -p "@{target_patterns} @{CLAUDE.md,**/*CLAUDE.md} - - Context: [Analysis type] targeting @{target_patterns} - Guidelines: Include CLAUDE.md standards - - ## Analysis: - 1. [Point 1] - 2. [Point 2] - - ## Output: - - File:line references - - Code examples") - ``` - -- **Template-Enhanced (Recommended)** - ```bash - # Using a predefined template for consistent, high-quality analysis - bash(gemini --all-files -p "@{target_patterns} @{CLAUDE.md,**/*CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) - - ## Analysis: - 1. [Point 1] - 2. [Point 2] - - ## Output: - - File:line references - - Code examples") - ``` - -- **Multi-Template Composition** - ```bash - bash(gemini --all-files -p "@{src/**/*} @{CLAUDE.md} - $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) - - Additional Security Focus: - $(cat ~/.claude/workflows/cli-templates/prompts/analysis/security.txt) - - ## Analysis: - 1. [Point 1] - 2. [Point 2] - - ## Output: - - File:line references - - Code examples") - ``` - -- **Token Limit Fallback** - ```bash - # If --all-files exceeds token limits, immediately retry with targeted patterns: - - # Original command that failed: - bash(gemini --all-files -p "Analyze authentication patterns") - - # Fallback with specific patterns: - bash(gemini -p "@{src/auth/**/*} @{src/middleware/**/*} @{CLAUDE.md} Analyze authentication patterns") - - # Or focus on specific file types: - bash(gemini -p "@{**/*.ts} @{**/*.js} @{CLAUDE.md} Analyze authentication patterns") - ``` - -### ⭐ Best Practices & Rules - - -**When to Use @ Patterns:** -1. **User explicitly provides @ patterns** - ALWAYS preserve them exactly -2. **Cross-directory analysis** - When analyzing relationships between modules -3. **Configuration files** - When analyzing scattered config files -4. **Selective inclusion** - When you only need specific file types - -**CLAUDE.md Loading Rules:** -- **With --all-files**: CLAUDE.md files automatically included (no @ needed) -- **Without --all-files**: Must use `@{CLAUDE.md}` or `@{**/CLAUDE.md}` - - -#### ⚠️ Error Prevention - -- **Quote paths with spaces**: Use proper shell quoting -- **Test patterns first**: Validate @ patterns match existing files -- **Prefer directory navigation**: Reduces complexity and improves performance -- **Preserve user patterns**: When user provides @, always keep them -- **Handle token limits**: If `--all-files` fails due to token limits, immediately retry without `--all-files` using targeted `@{patterns}` - diff --git a/.claude/workflows/intelligent-tools-strategy.md b/.claude/workflows/intelligent-tools-strategy.md new file mode 100644 index 00000000..2a2e2a86 --- /dev/null +++ b/.claude/workflows/intelligent-tools-strategy.md @@ -0,0 +1,149 @@ +--- +name: intelligent-tools-strategy +description: Strategic guide for intelligent tool selection - quick start and decision framework +type: strategic-guideline +--- + +# Intelligent Tools Selection Strategy + +## ⚡ Quick Start + +### Essential Commands + +**Gemini** (Analysis & Pattern Recognition): +```bash +~/.claude/scripts/gemini-wrapper -p "analyze authentication patterns" +``` + +**Codex** (Development & Implementation): +```bash +codex --full-auto exec "implement user authentication system" +``` + +### ⚠️ CRITICAL Command Differences + +| Tool | Command | Has Wrapper | Key Feature | +|------|---------|-------------|-------------| +| **Gemini** | `~/.claude/scripts/gemini-wrapper` | ✅ YES | Large context window, pattern recognition | +| **Codex** | `codex --full-auto exec` | ❌ NO | Autonomous development, math reasoning | + +**❌ NEVER use**: `~/.claude/scripts/codex` - this wrapper does not exist! + +## 🎯 Tool Selection Matrix + +### When to Use Gemini +- **Command**: `~/.claude/scripts/gemini-wrapper -p "prompt"` +- **Strengths**: Large context window, pattern recognition across modules +- **Best For**: + - Project architecture analysis (>50 files) + - Cross-module pattern detection + - Coding convention analysis + - Refactoring with broad dependencies + - Large codebase understanding + +### When to Use Codex +- **Command**: `codex --full-auto exec "prompt"` +- **Strengths**: Mathematical reasoning, autonomous development +- **Best For**: + - Complex algorithm analysis + - Security vulnerability assessment + - Performance optimization + - Database schema design + - API protocol specifications + - Autonomous feature development + +## 📊 Decision Framework + +| Analysis Need | Recommended Tool | Rationale | +|--------------|------------------|-----------| +| Project Architecture | Gemini | Needs broad context across many files | +| Algorithm Optimization | Codex | Requires deep mathematical reasoning | +| Security Analysis | Codex | Leverages deeper security knowledge | +| Code Patterns | Gemini | Pattern recognition across modules | +| Refactoring | Gemini | Needs understanding of all dependencies | +| API Design | Codex | Technical specification expertise | +| Test Coverage | Gemini | Cross-module test understanding | +| Performance Tuning | Codex | Mathematical optimization capabilities | +| Feature Implementation | Codex | Autonomous development capabilities | +| Architectural Review | Gemini | Large context analysis | + +## 🔄 Parallel Analysis Strategy + +For complex projects requiring both broad context and deep analysis: + +```bash +# Use Task agents to run both tools in parallel +Task(subagent_type="general-purpose", + prompt="Use Gemini (see @~/.claude/workflows/tools-implementation-guide.md) for architectural analysis") ++ +Task(subagent_type="general-purpose", + prompt="Use Codex (see @~/.claude/workflows/tools-implementation-guide.md) for algorithmic analysis") +``` + +## 📈 Complexity-Based Selection + +### Simple Projects (≤50 files) +- **Content-driven choice**: Mathematical → Codex, Structural → Gemini + +### Medium Projects (50-200 files) +- **Gemini first** for overview and patterns +- **Codex second** for specific implementations + +### Large Projects (>200 files) +- **Parallel analysis** with both tools +- **Gemini** for architectural understanding +- **Codex** for focused development tasks + +## 🎯 Quick Reference + +### Gemini Quick Commands +```bash +# Pattern analysis +~/.claude/scripts/gemini-wrapper -p "analyze existing patterns in auth module" + +# Architecture review +cd src && ~/.claude/scripts/gemini-wrapper -p "review overall architecture" + +# Code conventions +~/.claude/scripts/gemini-wrapper -p "identify coding standards and conventions" +``` + +### Codex Quick Commands +```bash +# Feature development +codex --full-auto exec "implement JWT authentication with refresh tokens" + +# Performance optimization +codex --full-auto exec "optimize database queries in user service" + +# Security enhancement +codex --full-auto exec "add input validation and sanitization" +``` + +## 📋 Implementation Guidelines + +1. **Default Selection**: Let project characteristics drive tool choice +2. **Start Simple**: Begin with single tool, escalate to parallel if needed +3. **Context First**: Understand scope before selecting approach +4. **Trust the Tools**: Let autonomous capabilities handle complexity + +## 🔗 Detailed Implementation + +For comprehensive syntax, patterns, and advanced usage: +- **Implementation Guide**: @~/.claude/workflows/tools-implementation-guide.md + +## 📊 Tools Comparison Summary + +| Feature | Gemini | Codex | +|---------|--------|-------| +| **Command Syntax** | Has wrapper script | Direct command only | +| **File Loading** | `--all-files` available | `@` patterns required | +| **Default Mode** | Interactive analysis | `--full-auto exec` automation | +| **Primary Use** | Analysis & planning | Development & implementation | +| **Context Window** | Very large | Standard with smart discovery | +| **Automation Level** | Manual implementation | Autonomous execution | +| **Best For** | Understanding codebases | Building features | + +--- + +**Remember**: Choose based on task nature, not personal preference. Gemini excels at understanding, Codex excels at building. \ No newline at end of file diff --git a/.claude/workflows/intelligent-tools.md b/.claude/workflows/intelligent-tools.md deleted file mode 100644 index fae63b61..00000000 --- a/.claude/workflows/intelligent-tools.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -name: intelligent-tools -description: Strategic tool selection guide - references unified tool documentation -type: strategic-guideline ---- - -# Intelligent Tools Selection Strategy - -## Overview -This document provides strategic guidance for selecting the appropriate analysis tool based on task characteristics and project requirements. - -## Tool Documentation References -- **Gemini CLI**: @~/.claude/workflows/gemini-unified.md -- **Codex CLI**: @~/.claude/workflows/codex-unified.md - -## Tool Characteristics Comparison - -### Gemini -- **Command Syntax**: `bash(~/.claude/scripts/gemini-wrapper -p "prompt")` (HAS wrapper script) -- **Strengths**: - - Large context window for analyzing many files simultaneously - - Excellent pattern recognition across modules - - Superior for architectural and structural analysis -- **Optimal Use Cases**: - - Large codebase analysis (>50 files) - - Cross-module pattern detection - - Coding convention analysis - - Refactoring with broad dependencies - -### Codex -- **Command Syntax**: `bash(codex --full-auto exec "prompt")` (NO wrapper script - direct command only) -- **Strengths**: - - Superior mathematical and algorithmic reasoning - - Deeper technical knowledge base - - Better for focused, deep analysis -- **Optimal Use Cases**: - - Complex algorithm analysis - - Security vulnerability assessment - - Performance optimization - - Database schema design - - API protocol specifications - -## Strategic Selection Matrix - -| Analysis Need | Recommended Tool | Rationale | -|--------------|------------------|-----------| -| Project Architecture | Gemini | Needs broad context across many files | -| Algorithm Optimization | Codex | Requires deep mathematical reasoning | -| Security Analysis | Codex | Leverages deeper security knowledge | -| Code Patterns | Gemini | Pattern recognition across modules | -| Refactoring | Gemini | Needs understanding of all dependencies | -| API Design | Codex | Technical specification expertise | -| Test Coverage | Gemini | Cross-module test understanding | -| Performance Tuning | Codex | Mathematical optimization capabilities | - -## Parallel Analysis Strategy - -For complex projects requiring both broad context and deep analysis: - -```bash -# Use Task agents to run both tools in parallel -Task(subagent_type="general-purpose", - prompt="Use Gemini (see @~/.claude/workflows/gemini-unified.md) for architectural analysis") -+ -Task(subagent_type="general-purpose", - prompt="Use Codex (see @~/.claude/workflows/codex-unified.md) for algorithmic analysis") -``` - -## Implementation Guidelines - -1. **Default Selection**: Let project characteristics drive tool choice -2. **Complexity Thresholds**: - - Simple projects (≤50 files): Either tool based on content type - - Medium projects (50-200 files): Gemini for overview, Codex for specifics - - Large projects (>200 files): Parallel analysis with both tools - -3. **Content-Based Selection**: - - Mathematical/algorithmic content → Codex - - Architectural/structural content → Gemini - - Mixed content → Both via Task agents - -## Usage in Commands - -Commands should reference this strategy guide for tool selection decisions. -Specific tool usage syntax and examples are documented in their respective unified guides. - -## ⚠️ CRITICAL Command Syntax Differences - -**Gemini** (HAS intelligent wrapper): -```bash -bash(~/.claude/scripts/gemini-wrapper -p "analyze patterns") -``` - -**Codex** (NO wrapper - direct command only): -```bash -bash(codex --full-auto exec "implement feature") -``` - -**❌ NEVER use**: `~/.claude/scripts/codex` - this does not exist! - -**See also**: -- Gemini detailed usage: @~/.claude/workflows/gemini-unified.md -- Codex detailed usage: @~/.claude/workflows/codex-unified.md \ No newline at end of file diff --git a/.claude/workflows/tools-implementation-guide.md b/.claude/workflows/tools-implementation-guide.md new file mode 100644 index 00000000..1c358b0b --- /dev/null +++ b/.claude/workflows/tools-implementation-guide.md @@ -0,0 +1,376 @@ +--- +name: tools-implementation-guide +description: Comprehensive implementation guide for Gemini and Codex CLI tools +type: technical-guideline +--- + +# Tools Implementation Guide + +## 📚 Part A: Shared Resources + +### 📁 Template System + +**Structure**: `~/.claude/workflows/cli-templates/prompts/` + +**Categories**: +- `analysis/` - pattern.txt, architecture.txt, security.txt, performance.txt, quality.txt (Gemini primary, Codex compatible) +- `development/` - feature.txt, component.txt, refactor.txt, testing.txt, debugging.txt (Codex primary) +- `planning/` - task-breakdown.txt, migration.txt (Cross-tool) +- `automation/` - scaffold.txt, migration.txt, deployment.txt (Codex specialized) +- `review/` - code-review.txt (Cross-tool) +- `integration/` - api-design.txt, database.txt (Codex primary) + +**Usage**: `$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)` + +### 📂 File Pattern Wildcards + +```bash +* # Any character (excluding path separators) +** # Any directory levels (recursive) +? # Any single character +[abc] # Any character within the brackets +{a,b,c} # Any of the options within the braces +``` + +### 🌐 Cross-Platform Rules + +- Always use forward slashes (`/`) for paths +- Enclose paths with spaces in quotes: `@{"My Project/src/**/*"}` +- Escape special characters like brackets: `@{src/**/*\[bracket\]*}` + +### ⏱️ Execution Settings + +- **Default Timeout**: Bash command execution extended to **10 minutes** for complex analysis and development workflows +- **Error Handling**: Both tools provide comprehensive error logging and recovery mechanisms + +--- + +## 🔍 Part B: Gemini Implementation Guide + +### 🚀 Command Overview + +- **Purpose**: Comprehensive codebase analysis, context gathering, and pattern detection across multiple files +- **Key Feature**: Large context window for simultaneous multi-file analysis +- **Primary Triggers**: "analyze", "get context", "understand the codebase", relationships between files + +### ⭐ Primary Method: gemini-wrapper + +**Location**: `~/.claude/scripts/gemini-wrapper` (auto-installed) + +**Smart Features**: +- **Token Threshold**: 2,000,000 tokens (configurable via `GEMINI_TOKEN_LIMIT`) +- **Auto `--all-files`**: Small projects get `--all-files`, large projects use patterns +- **Smart Approval Modes**: Analysis tasks use `default`, execution tasks use `yolo` +- **Error Logging**: Captures errors to `~/.claude/.logs/gemini-errors.log` + +**Task Detection**: +- **Analysis Keywords**: "analyze", "analysis", "review", "understand", "inspect", "examine" → `--approval-mode default` +- **All Other Tasks**: → `--approval-mode yolo` + +### 📝 Gemini Command Syntax + +**Basic Structure**: +```bash +gemini [flags] -p "@{patterns} {template} prompt" +``` + +**Key Arguments**: +- `--all-files`: Includes all files in current working directory +- `-p`: Prompt string with file patterns and analysis query +- `@{pattern}`: Special syntax for referencing files and directories +- `--approval-mode`: Tool approval mode (`default` | `yolo`) +- `--include-directories`: Additional workspace directories (max 5, comma-separated) + +### 📦 Gemini Usage Patterns + +#### 🎯 Using gemini-wrapper (RECOMMENDED - 90% of tasks) + +**Automatic Management**: +```bash +# Analysis task - auto detects and uses --approval-mode default +~/.claude/scripts/gemini-wrapper -p "Analyze authentication module patterns" + +# Development task - auto detects and uses --approval-mode yolo +~/.claude/scripts/gemini-wrapper -p "Implement user login feature with JWT" + +# Directory-specific analysis +cd src/auth && ~/.claude/scripts/gemini-wrapper -p "Review authentication patterns" + +# Custom token threshold +GEMINI_TOKEN_LIMIT=500000 ~/.claude/scripts/gemini-wrapper -p "Custom analysis" +``` + +**Module-Specific Analysis**: +```bash +# Navigate to module directory +cd src/auth && ~/.claude/scripts/gemini-wrapper -p "Analyze authentication module patterns" + +# Template-enhanced analysis +cd frontend/components && ~/.claude/scripts/gemini-wrapper -p "$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)" +``` + +#### 📝 Direct Gemini Usage (Manual Control) + +**Manual Token Management**: +```bash +# Direct control when needed +gemini --all-files -p "Analyze authentication module patterns and implementation" + +# Pattern-based fallback +gemini -p "@{src/auth/**/*} @{CLAUDE.md} Analyze authentication patterns" +``` + +**Template-Enhanced Prompts**: +```bash +# Single template usage +gemini --all-files -p "@{src/**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)" + +# Multi-template composition +gemini --all-files -p "@{src/**/*} @{CLAUDE.md} +$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) + +Additional Security Focus: +$(cat ~/.claude/workflows/cli-templates/prompts/analysis/security.txt)" +``` + +**Token Limit Fallback Strategy**: +```bash +# If --all-files exceeds token limits, retry with targeted patterns: + +# Original command that failed: +gemini --all-files -p "Analyze authentication patterns" + +# Fallback with specific patterns: +gemini -p "@{src/auth/**/*} @{src/middleware/**/*} @{CLAUDE.md} Analyze authentication patterns" + +# Focus on specific file types: +gemini -p "@{**/*.ts} @{**/*.js} @{CLAUDE.md} Analyze authentication patterns" +``` + +### 📋 Gemini File Pattern Rules + +**Syntax**: +- `@{pattern}`: Single file or directory pattern +- `@{pattern1,pattern2}`: Multiple patterns, comma-separated + +**CLAUDE.md Loading Rules**: +- **With `--all-files`**: CLAUDE.md files automatically included +- **Without `--all-files`**: Must use `@{CLAUDE.md}` or `@{**/CLAUDE.md}` + +**When to Use @ Patterns**: +1. User explicitly provides @ patterns - ALWAYS preserve exactly +2. Cross-directory analysis - relationships between modules +3. Configuration files - scattered config files +4. Selective inclusion - specific file types only + +### ⚠️ Gemini Best Practices + +- **Quote paths with spaces**: Use proper shell quoting +- **Test patterns first**: Validate @ patterns match existing files +- **Prefer directory navigation**: Reduces complexity, improves performance +- **Preserve user patterns**: When user provides @, always keep them +- **Handle token limits**: Immediate retry without `--all-files` using targeted patterns + +--- + +## 🛠️ Part C: Codex Implementation Guide + +### 🚀 Command Overview + +- **Purpose**: Automated codebase analysis, intelligent code generation, and autonomous development workflows +- **⚠️ CRITICAL**: **NO wrapper script exists** - always use direct `codex` command +- **Key Characteristic**: **No `--all-files` flag** - requires explicit `@` pattern references +- **Default Mode**: `--full-auto exec` autonomous development mode (RECOMMENDED) + +### ⭐ CRITICAL: Default to `--full-auto` Mode + +**🎯 Golden Rule**: Always start with `codex --full-auto exec "task description"` for maximum autonomous capabilities. + +**Why `--full-auto` Should Be Your Default**: +- **🧠 Intelligent File Discovery**: Auto-identifies relevant files without manual `@` patterns +- **🎯 Context-Aware Execution**: Understands project structure and dependencies autonomously +- **⚡ Streamlined Workflow**: No need to specify file patterns - just describe what you want +- **🚀 Maximum Automation**: Leverages full autonomous development capabilities +- **📚 Smart Documentation**: Automatically includes relevant CLAUDE.md files + +**When to Use Explicit Patterns**: +- ✅ Precise control over which files are included +- ✅ Specific file patterns requiring manual specification +- ✅ Debugging issues with file discovery in `--full-auto` mode +- ❌ **NOT as default choice** - reserve for special circumstances + +### 📝 Codex Command Syntax + +**Basic Structure** (Priority Order): +```bash +codex --full-auto exec "autonomous development task" # DEFAULT & RECOMMENDED +codex --full-auto exec "prompt with @{patterns}" # For specific control needs +``` + +**⚠️ NEVER use**: `~/.claude/scripts/codex` - this wrapper script does not exist! + +**Key Commands** (In Order of Preference): +- `codex --full-auto exec "..."` ⭐ **PRIMARY MODE** - Full autonomous development +- `codex --cd /path --full-auto exec "..."` - Directory-specific autonomous development +- `codex --cd /path --full-auto exec "@{patterns} ..."` - Directory-specific with patterns + +### 📦 Codex Usage Patterns + +#### 🎯 Autonomous Development (PRIMARY - 90% of tasks) + +**Basic Development**: +```bash +# RECOMMENDED: Let Codex handle everything autonomously +codex --full-auto exec "Implement user authentication with JWT tokens" + +# Directory-specific autonomous development +codex --cd src/auth --full-auto exec "Refactor authentication module using latest patterns" + +# Complex feature development +codex --full-auto exec "Create a complete todo application with React and TypeScript" +``` + +**Template-Enhanced Development**: +```bash +# Autonomous mode with template guidance +codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) + +## Task: User Authentication System +- JWT token management +- Role-based access control +- Password reset functionality" +``` + +#### 🛠️ Controlled Development (When Explicit Control Needed) + +**Module-Specific with Patterns**: +```bash +# Explicit patterns when autonomous mode needs guidance +codex --full-auto exec "@{src/auth/**/*,CLAUDE.md} Refactor authentication module using latest patterns" + +# Alternative: Directory-specific execution with explicit patterns +codex --cd src/auth --full-auto exec "@{**/*,../../CLAUDE.md} Refactor authentication module" +``` + +**Debugging & Analysis**: +```bash +# Autonomous debugging mode +codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/development/debugging.txt) + +## Issue: Performance degradation in user dashboard +- Identify bottlenecks in the codebase +- Propose and implement optimizations +- Add performance monitoring" + +# Alternative: Explicit patterns for controlled analysis +codex --full-auto exec "@{src/**/*,package.json,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/debugging.txt)" +``` + +### 📂 Codex File Pattern Rules - CRITICAL + +⚠️ **UNLIKE GEMINI**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files. + +**Essential Patterns**: +```bash +@{**/*} # All files recursively (equivalent to --all-files) +@{src/**/*} # All source files +@{*.ts,*.js} # Specific file types +@{CLAUDE.md,**/*CLAUDE.md} # Documentation hierarchy +@{package.json,*.config.*} # Configuration files +``` + +**CLAUDE.md Loading Rules** (Critical Difference from Gemini): +- **Always explicit**: Must use `@{CLAUDE.md}` or `@{**/*CLAUDE.md}` +- **No automatic loading**: Codex will not include documentation without explicit reference +- **Hierarchical loading**: Use `@{CLAUDE.md,**/*CLAUDE.md}` for complete context + +### 🚀 Codex Advanced Patterns + +#### 🔄 Multi-Phase Development (Full Autonomous Workflow) + +```bash +# Phase 1: Autonomous Analysis +codex --full-auto exec "Analyze current architecture for payment system integration" + +# Phase 2: Autonomous Implementation (RECOMMENDED APPROACH) +codex --full-auto exec "Implement Stripe payment integration based on the analyzed architecture" + +# Phase 3: Autonomous Testing +codex --full-auto exec "Generate comprehensive tests for the payment system implementation" + +# Alternative: Explicit control when needed +codex --full-auto exec "@{**/*,CLAUDE.md} Analyze current architecture for payment system integration" +``` + +#### 🌐 Cross-Project Learning + +```bash +# RECOMMENDED: Autonomous cross-project pattern learning +codex --full-auto exec "Implement feature X by learning patterns from ../other-project/ and applying them to the current codebase" + +# Alternative: Explicit pattern specification +codex --full-auto exec "@{../other-project/src/**/*,src/**/*,CLAUDE.md} Implement feature X using patterns from other-project" +``` + +#### 📊 Development Workflow Integration + +**Pre-Development Analysis**: +```bash +# RECOMMENDED: Autonomous pattern analysis +codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) + +Analyze the existing codebase patterns and conventions before implementing new features." +``` + +**Quality Assurance**: +```bash +# RECOMMENDED: Autonomous testing and validation +codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/development/testing.txt) + +Generate comprehensive tests and perform validation for the entire codebase." +``` + +### ⚠️ Codex Best Practices + +**Always Use @ Patterns**: +- **MANDATORY**: Codex requires explicit file references via `@` patterns (when not using full-auto autonomous mode) +- **No automatic inclusion**: Unlike Gemini's `--all-files`, you must specify what to analyze +- **Be comprehensive**: Use `@{**/*}` for full codebase context when needed +- **Be selective**: Use specific patterns like `@{src/**/*.ts}` for targeted analysis + +**Default Automation Mode** (CRITICAL GUIDANCE): +- **`codex --full-auto exec` is PRIMARY choice**: Use for 90% of all tasks - maximizes autonomous capabilities +- **Explicit patterns only when necessary**: Reserve for cases where you need explicit file pattern control +- **Trust the autonomous intelligence**: Codex excels at file discovery, context gathering, and architectural decisions +- **Start with full-auto always**: If it doesn't meet needs, then consider explicit patterns + +**Error Prevention**: +- **Always include @ patterns**: Commands without file references will fail (except in full-auto mode) +- **Test patterns first**: Validate @ patterns match existing files +- **Use comprehensive patterns**: `@{**/*}` when unsure of file structure +- **Include documentation**: Always add `@{CLAUDE.md,**/*CLAUDE.md}` for context when using explicit patterns +- **Quote complex paths**: Use proper shell quoting for paths with spaces + +--- + +## 🎯 Strategic Integration + +### Template Reuse Across Tools + +**Gemini and Codex Template Compatibility**: +- **`cat` command works identically**: Reuse templates seamlessly between tools +- **Cross-reference patterns**: Combine analysis and development templates +- **Template composition**: Build complex prompts from multiple template sources + +### Autonomous Development Pattern (Codex-Specific) + +1. **Context Gathering**: `@{**/*,CLAUDE.md}` for full project understanding (or let full-auto handle) +2. **Pattern Analysis**: Understand existing code conventions +3. **Automated Implementation**: Let codex handle the development workflow +4. **Quality Assurance**: Built-in testing and validation + +--- + +**Remember**: +- **Gemini excels at understanding** - use `~/.claude/scripts/gemini-wrapper` for analysis and pattern recognition +- **Codex excels at building** - use `codex --full-auto exec` for autonomous development and implementation \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 5143c618..6cbc05ed 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,8 @@ This document defines project-specific coding standards and development principles. ### CLI Tool Context Protocols For all CLI tool usage, command syntax, and integration guidelines: -- **Tool Selection Strategy**: @~/.claude/workflows/intelligent-tools.md +- **Tool Selection Strategy**: @~/.claude/workflows/intelligent-tools-strategy.md +- **Implementation Guide**: @~/.claude/workflows/tools-implementation-guide.md ### Intelligent Context Acquisition diff --git a/README.md b/README.md index 1f981d64..d24c7421 100644 --- a/README.md +++ b/README.md @@ -385,8 +385,8 @@ cd src/api && /update-memory-related │ ├── complexity-rules.md # Complexity management rules │ ├── session-management-principles.md # Session system design │ ├── file-structure-standards.md # Directory organization -│ ├── gemini-unified.md # Gemini CLI integration -│ └── codex-unified.md # Codex CLI integration +│ ├── intelligent-tools-strategy.md # Tool selection strategy guide +│ └── tools-implementation-guide.md # Tool implementation details └── settings.local.json # Local environment configuration .workflow/ # Session workspace (auto-generated) diff --git a/README_CN.md b/README_CN.md index 078ed6cf..97e97fa5 100644 --- a/README_CN.md +++ b/README_CN.md @@ -383,8 +383,8 @@ cd src/api && /update-memory-related │ ├── complexity-rules.md # 复杂度管理规则 │ ├── session-management-principles.md # 会话系统设计 │ ├── file-structure-standards.md # 目录组织 -│ ├── gemini-unified.md # Gemini CLI集成 -│ └── codex-unified.md # Codex CLI集成 +│ ├── intelligent-tools-strategy.md # 工具选择策略指南 +│ └── tools-implementation-guide.md # 工具实施详细指南 └── settings.local.json # 本地环境配置 .workflow/ # 会话工作空间（自动生成）