Claude-Code-Workflow/.claude/workflows/codex-unified.md

name, description, type

name	description	type
codex-unified	Comprehensive Codex CLI guidelines - core rules, syntax, patterns, templates, and best practices with automation focus	technical-guideline

🚀 Command Overview: codex

• Purpose: An AI-powered CLI tool for automated codebase analysis, intelligent code generation, and autonomous development workflows.
• Key Characteristic: No --all-files flag - requires explicit @ pattern references for file inclusion.
• Default Mode: --full-auto automation mode for autonomous task execution.
• 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.

⚙️ Command Syntax & Arguments

• Basic Structure:

  codex exec "prompt with @{patterns}"
  codex --full-auto "automated development task"
  

• Key Commands:

  • codex exec "..." ≡ gemini -p "..." (non-interactive automation mode)
  • codex --full-auto "..." (default autonomous development mode)
  • codex --cd /path "..." (specify working directory)

• Template Usage:

  # Direct execution (most common)
  codex exec "@{src/**/*} @{CLAUDE.md} Refactor authentication system"
  
  # With template injection
  codex exec "@{src/**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)"
  
  # Multi-template composition
  codex exec "@{src/**/*} @{CLAUDE.md} $(cat <<'EOF'
  $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt)
  
  Development Focus:
  $(cat ~/.claude/workflows/cli-templates/prompts/development/component.txt)
  EOF
  )"
  

📂 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:

  @{**/*}                    # 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\]*}.

📁 Shared Template Directory Structure

📋 Complete Template Reference: See Shared Template System for comprehensive template directory structure, cross-tool compatibility, and detailed usage patterns.

💡 Cross-Tool Usage: Analysis templates (analysis/) work with Codex for understanding existing code before development. See shared template system for complete compatibility matrix.

📦 Standard Command Structures

• Module-Specific Development (Folder Analysis Required)

  # MUST use @{folder/**/*} pattern since codex has no --all-files
  codex exec "@{src/auth/**/*,CLAUDE.md} Refactor authentication module using latest patterns"
  
  # Alternative: use --cd flag to navigate + include folder
  codex --cd src/auth exec "@{**/*,../../CLAUDE.md} Implement JWT refresh token functionality"
  
  # Template-enhanced development (see shared-template-system.md for all available templates)
  codex exec "@{backend/services/**/*,package.json,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/refactor.txt)"
  

• Basic Development Task

  codex exec "@{src/**/*,*.json,CLAUDE.md} Implement user authentication with JWT"
  

• Template-Enhanced Development

  codex exec "@{src/**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)
  
  ## Task: User Authentication System
  - JWT token management
  - Role-based access control
  - Password reset functionality"
  

• Full Auto Mode (Default)

  codex --full-auto "@{**/*} Create a complete todo application with React and TypeScript"
  

• Debugging & Analysis

  codex exec "@{src/**/*,package.json,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/debugging.txt)
  
  ## Issue: Performance degradation in user dashboard
  - Identify bottlenecks
  - Propose optimizations
  - Implement solutions"
  

⭐ 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:

• --full-auto is preferred: Maximizes autonomous capabilities
• codex exec for specific tasks: Use when you need precise control
• Let codex decide: Trust the AI's architectural decisions in auto 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 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:

# Understand existing patterns before implementing
codex exec "@{src/**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)"

Feature Development:

# Implement new feature with full context
codex exec "@{**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)

## Feature: Advanced Search Functionality
- Full-text search capabilities
- Filter and sort options
- Performance optimization"

Quality Assurance:

# Comprehensive testing and validation
codex exec "@{src/**/*,test/**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/testing.txt)"

🎨 Advanced Usage Patterns

Multi-Phase Development:

# Phase 1: Analysis
codex exec "@{**/*,CLAUDE.md} Analyze current architecture for payment system integration"

# Phase 2: Implementation
codex --full-auto "@{**/*,CLAUDE.md} Implement Stripe payment integration with the analyzed architecture"

# Phase 3: Testing
codex exec "@{**/*,CLAUDE.md} Generate comprehensive tests for the payment system"

Cross-Project Learning:

# Learn from similar implementations
codex exec "@{../other-project/src/**/*,src/**/*,CLAUDE.md} Implement feature X using patterns from other-project"

Remember: Codex excels at autonomous development - trust its intelligence while providing comprehensive context through proper @ pattern usage.