mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
refactor: Reorganize workflow documentation structure and eliminate redundancy
## 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 <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -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:**
|
||||
|
||||
@@ -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**:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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**
|
||||
**@~/.claude/workflows/tools-implementation-guide.md**
|
||||
@@ -186,4 +186,4 @@ When `--save-session` flag is used:
|
||||
```
|
||||
|
||||
For detailed syntax, patterns, and advanced usage see:
|
||||
**@~/.claude/workflows/codex-unified.md**
|
||||
**@~/.claude/workflows/tools-implementation-guide.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**
|
||||
**@~/.claude/workflows/tools-implementation-guide.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**
|
||||
**@~/.claude/workflows/tools-implementation-guide.md**
|
||||
@@ -257,4 +257,4 @@ When `--save-session` used, saves to:
|
||||
```
|
||||
|
||||
For detailed syntax, patterns, and advanced usage see:
|
||||
**@~/.claude/workflows/codex-unified.md**
|
||||
**@~/.claude/workflows/tools-implementation-guide.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 "..."`).
|
||||
|
||||
@@ -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**
|
||||
**@~/.claude/workflows/tools-implementation-guide.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**
|
||||
**@~/.claude/workflows/tools-implementation-guide.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
|
||||
|
||||
@@ -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.
|
||||
@@ -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}`
|
||||
|
||||
149
.claude/workflows/intelligent-tools-strategy.md
Normal file
149
.claude/workflows/intelligent-tools-strategy.md
Normal file
@@ -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.
|
||||
@@ -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
|
||||
376
.claude/workflows/tools-implementation-guide.md
Normal file
376
.claude/workflows/tools-implementation-guide.md
Normal file
@@ -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
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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/ # 会话工作空间（自动生成）
|
||||
|
||||
Reference in New Issue
Block a user