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.
• Directory Analysis Rule: When user intends to analyze specific directory (cd XXX), use: codex --cd XXX exec "@{**/*} prompt" or cd XXX && codex exec "@{**/*} prompt"
• Default Mode: --full-auto 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 codex --full-auto "your task description" for maximum autonomous capabilities. This is the recommended approach for 90% of development tasks.

Why --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 codex exec Instead:

• ✅ 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):

  codex --full-auto "autonomous development task"  # DEFAULT & RECOMMENDED
  codex exec "prompt with @{patterns}"              # For specific control needs
  

• Key Commands (In Order of Preference):

  • codex --full-auto "..." ⭐ PRIMARY MODE - Full autonomous development
  • codex exec "..." - Controlled execution when you need specific patterns
  • codex --cd /path --full-auto "..." - Directory-specific autonomous development

• Template Usage (Preferred Approaches):

  # RECOMMENDED: Full autonomous mode (let Codex handle file discovery)
  codex --full-auto "Refactor authentication system using best practices"
  
  # Alternative: Direct execution with explicit patterns
  codex exec "@{src/**/*} @{CLAUDE.md} Refactor authentication system"
  
  # Advanced: Template injection with autonomous mode
  codex --full-auto "$(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:

  @{**/*}                    # 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 5 minutes to handle complex autonomous development workflows.
• Autonomous Intelligence: Codex automatically manages file discovery and context gathering in --full-auto mode.

📁 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

  # RECOMMENDED: Full autonomous mode with directory context
  codex --cd src/auth --full-auto "Refactor authentication module using latest patterns"
  
  # Alternative: Full autonomous mode with explicit task description
  codex --full-auto "Refactor the authentication module in src/auth/ using latest security patterns"
  
  # Fallback: Explicit patterns when autonomous mode needs guidance
  codex exec "@{src/auth/**/*,CLAUDE.md} Refactor authentication module using latest patterns"
  

• Basic Development Task

  # RECOMMENDED: Let Codex handle everything autonomously
  codex --full-auto "Implement user authentication with JWT tokens"
  
  # Alternative: Explicit file patterns if needed
  codex exec "@{src/**/*,*.json,CLAUDE.md} Implement user authentication with JWT"
  

• Template-Enhanced Development

  # RECOMMENDED: Autonomous mode with template guidance
  codex --full-auto "$(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
  codex exec "@{src/**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)"
  

• Full Auto Mode (PRIMARY RECOMMENDATION)

  # OPTIMAL: Let Codex discover files and handle everything
  codex --full-auto "Create a complete todo application with React and TypeScript"
  
  # Alternative: Explicit patterns if you want to control file scope
  codex --full-auto "@{**/*} Create a complete todo application with React and TypeScript"
  

• Debugging & Analysis

  # RECOMMENDED: Autonomous debugging mode
  codex --full-auto "$(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 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):

• --full-auto is the PRIMARY choice: Use for 90% of all tasks - maximizes autonomous capabilities
• codex exec 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 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 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:

# RECOMMENDED: Autonomous pattern analysis
codex --full-auto "$(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
codex exec "@{src/**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)"

Feature Development:

# RECOMMENDED: Full autonomous feature development
codex --full-auto "$(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
codex exec "@{**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)"

Quality Assurance:

# RECOMMENDED: Autonomous testing and validation
codex --full-auto "$(cat ~/.claude/workflows/cli-templates/prompts/development/testing.txt)

Generate comprehensive tests and perform validation for the entire codebase."

# Alternative: Specific test scope control
codex exec "@{src/**/*,test/**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/testing.txt)"

🎨 Advanced Usage Patterns

Multi-Phase Development (Full Autonomous Workflow):

# Phase 1: Autonomous Analysis
codex --full-auto "Analyze current architecture for payment system integration"

# Phase 2: Autonomous Implementation (RECOMMENDED APPROACH)
codex --full-auto "Implement Stripe payment integration based on the analyzed architecture"

# Phase 3: Autonomous Testing
codex --full-auto "Generate comprehensive tests for the payment system implementation"

# Alternative: Explicit control when needed
codex exec "@{**/*,CLAUDE.md} Analyze current architecture for payment system integration"

Cross-Project Learning:

# RECOMMENDED: Autonomous cross-project pattern learning
codex --full-auto "Implement feature X by learning patterns from ../other-project/ and applying them to the current codebase"

# Alternative: Explicit pattern specification
codex exec "@{../other-project/src/**/*,src/**/*,CLAUDE.md} Implement feature X using patterns from other-project"

Remember: Codex excels at autonomous development - --full-auto mode should be your default choice. Trust its intelligence for file discovery, context gathering, and implementation decisions. Use explicit @ patterns only when you need precise control over file scope.