From ff1ca34c2e515c1786a2d7d3b3589fdc01129cd6 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Wed, 17 Sep 2025 23:17:31 +0800 Subject: [PATCH] refactor: Streamline intelligent tools strategy with unified template system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Major Changes: - Merge tools-implementation-guide.md into intelligent-tools-strategy.md - Consolidate TEMPLATE and RULES fields into single RULES field - Standardize template references using $(cat ...) format - Reduce document length by 66% (520→177 lines) while preserving core functionality Template System Improvements: - Universal 4-field command format: PURPOSE | TASK | EXPECTED | RULES - Unified rules format: $(cat template.txt) | constraints - Comprehensive template directory structure with examples - Cross-tool template compatibility and reuse patterns Content Optimization: - Remove redundant examples and duplicate content - Focus on universal command templates and common scenarios - Simplify tool selection matrix with clear task-to-tool mapping - Streamline workflow integration with essential best practices 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/agents/action-planning-agent.md | 2 +- .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 +- .../workflows/intelligent-tools-strategy.md | 252 +++++------ .../workflows/tools-implementation-guide.md | 402 ------------------ CLAUDE.md | 1 - 8 files changed, 123 insertions(+), 546 deletions(-) delete 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 edf50585..1a249b51 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -56,7 +56,7 @@ You are a pure execution agent specialized in creating actionable implementation - **CLI Commands**: - **Gemini**: `bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [expanded_action]")` - **Codex**: `bash(codex --full-auto exec "$(cat template_path) [expanded_action]" -s danger-full-access)` -- **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md +- **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md ### Pre-Execution Analysis **When [MULTI_STEP_ANALYSIS] marker is present:** diff --git a/.claude/commands/codex/mode/plan.md b/.claude/commands/codex/mode/plan.md index 3cab402c..5e4b1c16 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/tools-implementation-guide.md** \ No newline at end of file +**@~/.claude/workflows/intelligent-tools-strategy.md** \ No newline at end of file diff --git a/.claude/commands/enhance-prompt.md b/.claude/commands/enhance-prompt.md index 66128df2..ffdcf8e9 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/tools-implementation-guide.md +**Gemini Integration**: @~/.claude/workflows/intelligent-tools-strategy.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 e64120fa..06624888 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/tools-implementation-guide.md +**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md ## Analysis Types @@ -94,5 +94,3 @@ Analysis results include: - **Recommendations**: Actionable improvements - **Integration Points**: How components connect -For detailed syntax, patterns, and advanced usage see: -**@~/.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 abbf0354..0369c099 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/tools-implementation-guide.md +**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md ## 🚨 YOLO Permissions @@ -166,5 +166,3 @@ 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/tools-implementation-guide.md** \ No newline at end of file diff --git a/.claude/workflows/intelligent-tools-strategy.md b/.claude/workflows/intelligent-tools-strategy.md index fd77c4fa..79c7c3c9 100644 --- a/.claude/workflows/intelligent-tools-strategy.md +++ b/.claude/workflows/intelligent-tools-strategy.md @@ -23,57 +23,16 @@ type: strategic-guideline 3. **Not sure?** → Use both in parallel 4. **Small task?** → Still use tools - they're faster than manual work -## 🎯 Tool Specifications +## 🎯 Universal Command Template -### Gemini (Analysis & Understanding) -**Command**: `~/.claude/scripts/gemini-wrapper -p "PURPOSE: [analysis goal] | TASK: [what to do] | EXPECTED: [expected results]"` - -**Strengths**: Large context window, pattern recognition across modules - -**Use Cases**: -- Any project analysis (≥5 files) -- Quick code exploration and familiarization -- Cross-module pattern detection and consistency checks -- Coding convention analysis and standardization -- Refactoring planning with dependency mapping -- Legacy code understanding and modernization paths -- API surface analysis and integration points -- Test coverage gaps and quality assessment -- Configuration file analysis and optimization -- Dependency audit and relationship mapping -- Code review preparation and checklist generation -- Documentation generation from existing code - -### Codex (Development & Implementation) -**Command**: `codex --full-auto exec "PURPOSE: [development goal] | TASK: [what to implement] | EXPECTED: [expected code/features]" -s danger-full-access` - -**Strengths**: Mathematical reasoning, autonomous development - -**Use Cases**: -- Any feature development (simple to complex) -- Quick prototyping and proof-of-concepts -- Bug fixes and issue resolution -- Test generation and validation -- Code scaffolding and boilerplate creation -- Configuration setup and environment preparation -- Algorithm implementation and optimization -- Security vulnerability assessment and fixes -- Performance optimization and profiling -- Database schema design and migration -- API development and integration -- DevOps automation and deployment scripts -- Documentation automation and generation -- Code modernization and refactoring execution -- Dependency management and updates -- Build system optimization and tooling - -### Structured Prompt Templates +### Standard Format (REQUIRED) ```bash # Gemini Analysis ~/.claude/scripts/gemini-wrapper -p " PURPOSE: [clear analysis goal] TASK: [specific analysis task] EXPECTED: [expected output] +RULES: [template reference and constraints] " # Codex Development @@ -81,113 +40,138 @@ codex --full-auto exec " PURPOSE: [clear development goal] TASK: [specific development task] EXPECTED: [expected deliverables] +RULES: [template reference and constraints] " -s danger-full-access ``` -**Prompt Checklist**: +### Template Structure - [ ] **PURPOSE** - Clear goal and intent - [ ] **TASK** - Specific execution task - [ ] **EXPECTED** - Clear expected results +- [ ] **RULES** - Template reference and constraints -## 📊 Decision Matrix - -| Task Category | Tool | Rationale | Frequency | -|--------------|------|-----------|-----------| -| **Understanding & Analysis** | -| Project Architecture | Gemini | Broad context across files | Weekly/Monthly | -| Code Exploration | Gemini | Quick module familiarization | Daily | -| Legacy Code Analysis | Gemini | Pattern recognition across systems | As needed | -| Dependency Mapping | Gemini | Cross-module relationship analysis | Sprint planning | -| Code Review Prep | Gemini | Comprehensive context understanding | Before reviews | -| **Development & Implementation** | -| Feature Development | Codex | Autonomous implementation capabilities | Daily | -| Bug Fixes | Codex | Targeted problem resolution | As issues arise | -| Prototyping | Codex | Rapid development and iteration | Weekly | -| Test Generation | Codex | Automated test creation | After feature work | -| Configuration Setup | Codex | Environment and tooling setup | Project setup | -| **Optimization & Maintenance** | -| Algorithm Optimization | Codex | Mathematical reasoning capabilities | Performance sprints | -| Security Analysis | Codex | Security knowledge and fixes | Security reviews | -| Performance Tuning | Codex | Mathematical optimization | Performance reviews | -| Code Modernization | Both | Gemini for planning, Codex for execution | Quarterly | -| **Documentation & Quality** | -| Documentation Generation | Both | Gemini for analysis, Codex for automation | Continuous | -| Coding Standards | Gemini | Pattern recognition and consistency | Code reviews | -| Test Coverage Analysis | Gemini | Cross-module test understanding | Sprint retrospectives | - -## 📋 Workflow Integration - -### Mandatory Planning Process -When planning any coding task, **ALWAYS** integrate CLI tools: - -#### 1. Understanding Phase (Required) -- **Gemini Analysis**: Understand existing patterns, architecture, dependencies -- **Context Discovery**: Map related modules and integration points -- **Pattern Recognition**: Identify existing conventions and standards - -#### 2. Development Strategy -- **Understanding/Analysis**: Gemini (primary), Codex (occasional) -- **Implementation**: Codex (occasional), manual development (primary) -- **Complex Tasks**: Both tools in sequence - -#### 3. Workflow Pattern -``` -Planning → Gemini Analysis → Manual Development → Codex Assistance (as needed) +### Rules Field Format +```bash +RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints] ``` -### Tool Usage Guidelines +**Examples**: +- Single template: `$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) | Focus on security` +- Multiple templates: `$(cat template1.txt) $(cat template2.txt) | Enterprise standards` +- No template: `Focus on security patterns, include dependency analysis` +- File patterns: `@{src/**/*.ts,CLAUDE.md} - Stay within scope` -#### Gemini (Primary for Understanding) -- Always use for initial codebase analysis -- Pattern discovery and convention mapping -- Architecture understanding before implementation -- Dependency analysis and impact assessment -- Code review preparation +## 📊 Tool Selection Matrix -#### Codex (Occasional for Development) -- Selective use for complex algorithms -- Prototype generation for proof-of-concepts -- Boilerplate creation when patterns are clear -- Test generation and validation -- Performance optimization tasks +| Task Type | Tool | Use Case | Template | +|-----------|------|----------|-----------| +| **Analysis** | Gemini | Code exploration, architecture review, patterns | `analysis/pattern.txt` | +| **Development** | Codex | Feature implementation, bug fixes, testing | `development/feature.txt` | +| **Planning** | Both | Task breakdown, migration planning | `planning/task-breakdown.txt` | +| **Documentation** | Both | Code docs, API specs, guides | `analysis/quality.txt` | +| **Security** | Codex | Vulnerability assessment, fixes | `analysis/security.txt` | +| **Refactoring** | Both | Gemini for analysis, Codex for execution | `development/refactor.txt` | -### Planning Checklist -For every development task: -- [ ] **Gemini analysis** completed for understanding -- [ ] **Existing patterns** identified and documented -- [ ] **Dependencies mapped** and integration points clear -- [ ] **CLI tool usage points** identified in workflow -- [ ] **Manual development approach** defined -- [ ] **Codex assistance triggers** identified (if applicable) +## 📁 Template System + +**Base Structure**: `~/.claude/workflows/cli-templates/` + +### Available Templates +``` +prompts/ +├── analysis/ +│ ├── pattern.txt - Code pattern analysis +│ ├── architecture.txt - System architecture review +│ ├── security.txt - Security assessment +│ └── quality.txt - Code quality review +├── development/ +│ ├── feature.txt - Feature implementation +│ ├── refactor.txt - Refactoring tasks +│ └── testing.txt - Test generation +└── planning/ + └── task-breakdown.txt - Task decomposition + +planning-roles/ +├── system-architect.md - System design perspective +├── security-expert.md - Security architecture +└── feature-planner.md - Feature specification + +tech-stacks/ +├── typescript-dev.md - TypeScript guidelines +├── python-dev.md - Python conventions +└── react-dev.md - React architecture +``` ## 🚀 Usage Patterns -### Immediate Engagement Triggers -- **New codebase**: Use Gemini to understand structure before changes -- **Bug reports**: Use Codex to investigate and propose fixes -- **Feature requests**: Use Codex for rapid prototyping and implementation -- **Code reviews**: Use Gemini to prepare comprehensive analysis -- **Refactoring needs**: Use Gemini for impact analysis, Codex for execution +### Workflow Integration (REQUIRED) +When planning any coding task, **ALWAYS** integrate CLI tools: -### Daily Integration Points -- **Morning standup prep**: Gemini for codebase overview -- **Sprint planning**: Both tools for effort estimation -- **Development tasks**: Codex for implementation -- **Testing**: Codex for test generation and coverage -- **Documentation**: Both tools for comprehensive docs +1. **Understanding Phase**: Use Gemini for analysis +2. **Implementation Phase**: Use Codex for development +3. **Quality Phase**: Use Codex for testing and validation -### Parallel Strategy -For complex projects requiring both broad context and deep analysis: -- **Gemini** for architectural understanding -- **Codex** for focused development tasks -- Run both via Task agents when comprehensive coverage needed +### Common Scenarios +```bash +# Project Analysis +~/.claude/scripts/gemini-wrapper -p " +PURPOSE: Understand codebase architecture +TASK: Analyze project structure and identify patterns +EXPECTED: Architecture overview and integration points +RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on integration points +" -### Frequency Guidelines -- **Daily**: Use tools for routine development tasks -- **Immediate**: Engage tools at first sign of complexity -- **Continuous**: Integrate tools into regular workflow -- **Proactive**: Don't wait for problems - use tools preventively +# Feature Development +codex --full-auto exec " +PURPOSE: Implement user authentication +TASK: Create JWT-based authentication system +EXPECTED: Complete auth module with tests +RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) | Follow security best practices +" -s danger-full-access -## 🔗 Reference +# Code Review Preparation +~/.claude/scripts/gemini-wrapper -p " +PURPOSE: Prepare comprehensive code review +TASK: Analyze code changes and identify potential issues +EXPECTED: Review checklist and improvement suggestions +RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/quality.txt) | Focus on maintainability +" +``` -**Complete syntax and usage patterns**: @~/.claude/workflows/tools-implementation-guide.md \ No newline at end of file +## 📋 Planning Checklist + +For every development task: +- [ ] **Purpose defined** - Clear goal and intent +- [ ] **Gemini analysis** completed for understanding +- [ ] **Template selected** - Appropriate template chosen +- [ ] **Constraints specified** - File patterns, scope, requirements +- [ ] **Implementation approach** - Tool selection and workflow +- [ ] **Quality measures** - Testing and validation plan + +## 🎯 Key Features + +### Gemini +- **Command**: `~/.claude/scripts/gemini-wrapper` +- **Strengths**: Large context window, pattern recognition +- **Best For**: Analysis, architecture review, code exploration + +### Codex +- **Command**: `codex --full-auto exec` +- **Strengths**: Autonomous development, mathematical reasoning +- **Best For**: Implementation, testing, automation +- **Required**: `-s danger-full-access` for development + +### File Patterns +- All files: `@{**/*}` +- Source files: `@{src/**/*}` +- TypeScript: `@{*.ts,*.tsx}` +- With docs: `@{CLAUDE.md,**/*CLAUDE.md}` +- Tests: `@{src/**/*.test.*}` + +## 🔧 Best Practices + +- **Start with templates** - Use predefined templates for consistency +- **Be specific** - Clear PURPOSE, TASK, and EXPECTED fields +- **Include constraints** - File patterns, scope, requirements in RULES +- **Test patterns first** - Validate file patterns with `ls` +- **Document context** - Always reference CLAUDE.md for context \ No newline at end of file diff --git a/.claude/workflows/tools-implementation-guide.md b/.claude/workflows/tools-implementation-guide.md deleted file mode 100644 index 3e102cdc..00000000 --- a/.claude/workflows/tools-implementation-guide.md +++ /dev/null @@ -1,402 +0,0 @@ ---- -name: tools-implementation-guide -description: Comprehensive implementation guide for Gemini and Codex CLI tools -type: technical-guideline ---- - -# Tools Implementation Guide - -## 🚀 Quick Start - -### ⚡ Tool Selection at a Glance - -| Tool | Primary Use | Command Pattern | File Loading | Best For | -|------|-------------|-----------------|---------------|-----------| -| **Gemini** | Analysis & Understanding | `~/.claude/scripts/gemini-wrapper -p "prompt"` | `--all-files` or `@{patterns}` | Large context analysis, pattern detection | -| **Codex** | Development & Implementation | `codex --full-auto exec "task" -s danger-full-access` | `@{patterns}` or autonomous discovery | Feature development, automation | - -### 🎯 Quick Commands - -**Gemini (Analysis)**: -```bash -# Pattern analysis -~/.claude/scripts/gemini-wrapper -p "analyze authentication patterns" - -# Architecture review -cd src && ~/.claude/scripts/gemini-wrapper -p "review overall architecture" -``` - -**Codex (Development)**: -```bash -# Autonomous feature development -codex --full-auto exec "implement JWT authentication system" -s danger-full-access - -# Targeted development -codex --cd src/auth --full-auto exec "refactor authentication module" -s danger-full-access -``` - -### ⚠️ Critical Differences - -| Aspect | Gemini | Codex | -|--------|--------|--------| -| **Wrapper Script** | ✅ Has wrapper: `~/.claude/scripts/gemini-wrapper` | ❌ No wrapper: direct `codex` command only | -| **File Discovery** | Auto `--all-files` for small projects | Autonomous discovery with `--full-auto` | -| **Sandbox Mode** | Not required | 🔒 Required: `-s danger-full-access` | -| **Default Mode** | Interactive analysis | Autonomous execution | - ---- - -## 📚 Shared Resources - -### 📁 Template System - -**Base Structure**: `~/.claude/workflows/cli-templates/` - -#### Prompt Templates (`prompts/`) -``` -analysis/ # Gemini primary, Codex compatible -├── pattern.txt - Code pattern analysis -├── architecture.txt - System architecture review -├── security.txt - Security assessment -├── performance.txt - Performance analysis -└── quality.txt - Code quality review - -development/ # Codex primary -├── feature.txt - Feature implementation -├── component.txt - Component development -├── refactor.txt - Refactoring tasks -├── testing.txt - Test generation -└── debugging.txt - Debug and fix issues - -planning/ # Cross-tool compatible -├── task-breakdown.txt - Task decomposition -└── migration.txt - Migration planning - -automation/ # Codex specialized -├── scaffold.txt - Project scaffolding -├── migration.txt - Data migration -└── deployment.txt - Deployment automation - -review/ # Cross-tool compatible -└── code-review.txt - Code review process - -integration/ # Codex primary -├── api-design.txt - API specification -└── database.txt - Database design -``` - -**Usage**: `$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)` - -#### Planning Role Templates (`planning-roles/`) -- **business-analyst.md** - Business requirements analysis -- **data-architect.md** - Data modeling and architecture -- **feature-planner.md** - Feature specification -- **innovation-lead.md** - Technology exploration -- **product-manager.md** - Product roadmap -- **security-expert.md** - Security architecture -- **system-architect.md** - System design -- **test-strategist.md** - Testing strategy -- **ui-designer.md** - UI/UX design -- **user-researcher.md** - User research - -**Usage**: `$(cat ~/.claude/workflows/cli-templates/planning-roles/[role].md)` - -#### Tech Stack Templates (`tech-stacks/`) -- **go-dev.md** - Go development patterns -- **java-dev.md** - Java enterprise standards -- **javascript-dev.md** - JavaScript fundamentals -- **python-dev.md** - Python conventions -- **react-dev.md** - React architecture -- **typescript-dev.md** - TypeScript guidelines - -**Usage**: `$(cat ~/.claude/workflows/cli-templates/tech-stacks/[stack]-dev.md)` - -### 📂 File Pattern Reference - -#### Universal Patterns -```bash -* # Any character (excluding path separators) -** # Any directory levels (recursive) -? # Any single character -[abc] # Any character within brackets -{a,b,c} # Any of the specified options -``` - -#### Common Pattern Examples -```bash -@{**/*} # All files recursively -@{src/**/*} # All source files -@{*.ts,*.js} # TypeScript and JavaScript files -@{CLAUDE.md,**/*CLAUDE.md} # Documentation hierarchy -@{package.json,*.config.*} # Configuration files -@{src/**/*.test.*} # Test files -``` - -#### Cross-Platform Rules -- Always use forward slashes (`/`) for paths -- Quote paths with spaces: `@{"My Project/src/**/*"}` -- Escape special characters: `@{src/**/*\[bracket\]*}` - -### ⏱️ Execution Environment -- **Default Timeout**: 20 minutes for complex analysis and development workflows -- **Error Logging**: Comprehensive logging and recovery mechanisms -- **Token Management**: Automatic optimization for large codebases - ---- - -## 🔍 Gemini Implementation Guide - -### 🎯 Purpose & Strengths -- **Large context window** for simultaneous multi-file analysis -- **Pattern detection** across multiple modules -- **Architectural understanding** of complex codebases -- **Cross-module relationship** analysis - -### ⭐ Primary Method: gemini-wrapper (RECOMMENDED) - -**Location**: `~/.claude/scripts/gemini-wrapper` (auto-installed) - -**Smart Features**: -- **Token Threshold**: 2,000,000 tokens (configurable via `GEMINI_TOKEN_LIMIT`) -- **Auto File Loading**: Small projects get `--all-files`, large projects use targeted 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", "review", "understand", "inspect" → `--approval-mode default` -- **All Other Tasks**: → `--approval-mode yolo` - -### 📝 Command Patterns - -#### Automatic Management (90% of use cases) -```bash -# Analysis task - auto detects and configures appropriately -~/.claude/scripts/gemini-wrapper -p "Analyze authentication module patterns" - -# Development task - auto configures for execution -~/.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" -``` - -#### Template-Enhanced Analysis -```bash -# Single template -cd frontend/components && ~/.claude/scripts/gemini-wrapper -p "$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)" - -# Multi-template composition -~/.claude/scripts/gemini-wrapper -p "$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) - -Additional Security Focus: -$(cat ~/.claude/workflows/cli-templates/prompts/analysis/security.txt)" -``` - -#### Manual Control (when needed) -```bash -# Direct control with all files -gemini --all-files -p "Analyze authentication module patterns" - -# Pattern-based targeting -gemini -p "@{src/auth/**/*} @{CLAUDE.md} Analyze authentication patterns" -``` - -### 🔄 Token Limit Fallback Strategy -```bash -# If automatic loading fails due to token limits, retry with patterns: -# Original: ~/.claude/scripts/gemini-wrapper -p "Analyze patterns" -# Fallback: -gemini -p "@{src/auth/**/*} @{src/middleware/**/*} @{CLAUDE.md} Analyze patterns" -``` - ---- - -## 🛠️ Codex Implementation Guide - -### 🎯 Purpose & Strengths -- **Autonomous development** workflows -- **Mathematical reasoning** and optimization -- **Security analysis** and implementation -- **Intelligent code generation** -- **Full project automation** - -### 🔒 Sandbox Modes (REQUIRED) -```bash --s read-only # Safe analysis mode, no modifications --s workspace-write # Standard development mode --s danger-full-access # Full system access (RECOMMENDED for development) -``` - -**⚠️ CRITICAL**: No wrapper script exists - always use direct `codex` command - -### ⭐ Default Mode: Full Autonomous (RECOMMENDED) - -**🎯 Golden Rule**: Always start with `codex --full-auto exec "task" -s danger-full-access` - -**Why Full-Auto is Primary Choice**: -- 🧠 **Intelligent File Discovery**: Auto-identifies relevant files -- 🎯 **Context-Aware Execution**: Understands project dependencies -- ⚡ **Streamlined Workflow**: Just describe what you want -- 🚀 **Maximum Automation**: Full autonomous capabilities -- 📚 **Smart Documentation**: Includes relevant CLAUDE.md files - -### 📝 Command Patterns (Priority Order) - -#### 1. Autonomous Development (PRIMARY - 90% of tasks) -```bash -# RECOMMENDED: Full autonomous mode -codex --full-auto exec "Implement user authentication with JWT tokens" -s danger-full-access - -# Directory-specific autonomous development -codex --cd src/auth --full-auto exec "Refactor authentication module using latest patterns" -s danger-full-access - -# Complex feature development -codex --full-auto exec "Create a complete todo application with React and TypeScript" -s danger-full-access -``` - -#### 2. 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" -s danger-full-access -``` - -#### 3. Controlled Development (When Explicit Control Needed) -```bash -# Explicit patterns for specific control -codex --full-auto exec "@{src/auth/**/*,CLAUDE.md} Refactor authentication module" -s danger-full-access - -# Directory-specific with patterns -codex --cd src/auth --full-auto exec "@{**/*,../../CLAUDE.md} Refactor module" -s danger-full-access -``` - -### 🚀 Advanced Workflow Patterns - -#### Multi-Phase Development -```bash -# Phase 1: Autonomous Analysis -codex --full-auto exec "Analyze current architecture for payment integration" -s danger-full-access - -# Phase 2: Autonomous Implementation -codex --full-auto exec "Implement Stripe payment integration" -s danger-full-access - -# Phase 3: Autonomous Testing -codex --full-auto exec "Generate comprehensive tests for payment system" -s danger-full-access -``` - -#### Cross-Project Learning -```bash -# Learn from other projects -codex --full-auto exec "Implement feature X by learning patterns from ../other-project/" -s danger-full-access - -# Explicit cross-project patterns -codex --full-auto exec "@{../other-project/src/**/*,src/**/*,CLAUDE.md} Implement feature X" -s danger-full-access -``` - -### ⚠️ Critical Requirements -- **File References**: Unlike Gemini, Codex has NO `--all-files` flag -- **Sandbox Required**: Must specify `-s` parameter for write operations -- **Pattern Syntax**: Use `@{patterns}` when not using full-auto mode -- **Documentation Loading**: Must explicitly reference `@{CLAUDE.md}` when using patterns - ---- - -## ✅ Best Practices & Guidelines - -### 🎯 Tool Selection Strategy - -**Choose Gemini when**: -- Understanding large codebases (>50 files) -- Analyzing patterns across modules -- Cross-module dependency analysis -- Code convention detection -- Architectural review - -**Choose Codex when**: -- Building new features -- Algorithm optimization -- Security implementation -- Autonomous development workflows -- Mathematical problem solving - -### 🛠️ Development Workflow - -#### Pre-Development Pattern -1. **Context Gathering** (Gemini): `~/.claude/scripts/gemini-wrapper -p "analyze project architecture"` -2. **Implementation** (Codex): `codex --full-auto exec "implement feature based on analysis" -s danger-full-access` -3. **Quality Assurance** (Codex): `codex --full-auto exec "generate tests and validate" -s danger-full-access` - -#### Error Prevention -- **Test patterns first**: Validate `@{patterns}` match existing files -- **Quote complex paths**: Use proper shell quoting for paths with spaces -- **Start simple**: Begin with basic patterns, add complexity as needed -- **Include documentation**: Always reference CLAUDE.md files for context - -#### Token and Context Management -- **Gemini**: Rely on wrapper for automatic token management -- **Codex**: Trust full-auto mode for intelligent file discovery -- **Manual patterns**: Use only when autonomous modes need guidance -- **Fallback strategies**: Have targeted patterns ready for large projects - -### 📊 Template Integration Strategy - -#### Template Composition -```bash -# Combine multiple templates -codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) - -$(cat ~/.claude/workflows/cli-templates/planning-roles/system-architect.md) - -Task: Implement authentication system" -s danger-full-access -``` - -#### Cross-Tool Template Reuse -- Templates work identically with both tools -- Use `cat` command for seamless integration -- Combine analysis and development templates -- Build complex prompts from multiple sources - -### 🚨 Troubleshooting - -#### Common Issues -1. **Token limit exceeded** (Gemini): Wrapper automatically retries with targeted patterns -2. **File not found** (Both): Validate patterns with `ls` before using -3. **Sandbox errors** (Codex): Ensure `-s` parameter is specified -4. **Pattern matching** (Both): Test with simple patterns first - -#### Recovery Strategies -- **Gemini**: Fallback from `--all-files` to specific patterns -- **Codex**: Fallback from full-auto to explicit patterns -- **Both**: Use directory navigation to reduce complexity -- **Documentation**: Always include CLAUDE.md for context - ---- - -## 🎯 Strategic Integration Summary - -### Template Ecosystem -- **Cross-tool compatibility**: Templates work with both Gemini and Codex -- **Layered approach**: Combine prompt templates with planning roles and tech stacks -- **Reusable patterns**: Build library of common development patterns - -### Autonomous Development Pipeline -1. **Analysis Phase** (Gemini): Large context understanding -2. **Development Phase** (Codex): Autonomous implementation -3. **Quality Phase** (Codex): Testing and validation - -### Key Reminders -- **Gemini excels at understanding** - use for analysis and pattern recognition -- **Codex excels at building** - use for development and implementation -- **Start with autonomous modes** - leverage full capabilities before manual control -- **Trust the intelligence** - both tools excel at their specialized functions - ---- - -**Quick Reference**: For strategic guidance on tool selection, see `@~/.claude/workflows/intelligent-tools-strategy.md` \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 0efa2abf..d21d3a7a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,6 @@ This document defines project-specific coding standards and development principl ### CLI Tool Context Protocols For all CLI tool usage, command syntax, and integration guidelines: - **Intelligent Context Strategy**: @~/.claude/workflows/intelligent-tools-strategy.md -- **Implementation Guide**: @~/.claude/workflows/tools-implementation-guide.md **Context Requirements**: - Identify 3+ existing similar patterns before implementation