Codex Workflow Patterns
Codex can be integrated into various development workflows, from daily coding to complex refactoring, significantly improving efficiency.
Daily development workflow
Daily development is the most common workflow pattern, suitable for building new features or small-scale modifications.
Workflow Steps
| Steps | Operation | Codex Interaction |
|---|---|---|
| 1 | Clarify Requirements | Describe the functionality you want to implement |
| 2 | Codex Analysis | Codex understands project structure and conventions |
| 3 | Solution Discussion | Confirm the implementation approach with Codex |
| 4 | Code Generation | Codex writes code and modifies files |
| 5 | Validation Testing | Run tests to confirm functionality is correct |
| 6 | Iterative optimization | Adjust code based on feedback |
Example: Adding a New API Endpoint
Daily development process
# Step 1: Describe Requirements
"Add a GET endpoint at the /api/users path that returns the user list,
Supports pagination parameters page and limit
# Steps 2-3: Codex analyzes and confirms the plan
Codex will analyze the existing API structure and confirm:
- Route definition locations
- Database query methods
- Response format specifications
# Step 4: Code Generation
Codex automatically creates:
- Route definitions
- Data query logic
- Error handling
- Response formatting
# Step 5: Verification Testing
"Run tests and check the new endpoint"
# Step 6: Iterative Optimization
"Add cache support; response time should be less than 100ms"
"Add a GET endpoint at the /api/users path that returns the user list,
Supports pagination parameters page and limit
# Steps 2-3: Codex analyzes and confirms the plan
Codex will analyze the existing API structure and confirm:
- Route definition locations
- Database query methods
- Response format specifications
# Step 4: Code Generation
Codex automatically creates:
- Route definitions
- Data query logic
- Error handling
- Response formatting
# Step 5: Verification Testing
"Run tests and check the new endpoint"
# Step 6: Iterative Optimization
"Add cache support; response time should be less than 100ms"
Code comprehension workflow
When you need to understand legacy code or unfamiliar projects, use this workflow.
Exploratory workflow
- Start from the entry point and let Codex explain the overall architecture
- Gradually dive into key modules to understand the core logic
- Trace data flow and call chains
- Summarize key points and considerations
Understanding legacy projects
# Overall Architecture
"Analyze the overall architecture of this project, explain the main modules and their relationships"
# Core Modules
"Explain how the src/auth module works, including the authentication flow and permission checks"
# Data Flow Tracing
"Trace the complete flow from request to response after user login"
# Key Summary
"Summarize the core design patterns of this project and areas that need attention"
"Analyze the overall architecture of this project, explain the main modules and their relationships"
# Core Modules
"Explain how the src/auth module works, including the authentication flow and permission checks"
# Data Flow Tracing
"Trace the complete flow from request to response after user login"
# Key Summary
"Summarize the core design patterns of this project and areas that need attention"
Quickly ramp up on new projects
Getting started guide for new projects
# Project Overview
"What is this project? What are its main features and technology stack?"
# Development Guide
"How do I start the local development environment? How do I run tests?"
# Code Standards
"What are the code standards for this project? What conventions are there?"
# Module Navigation
Which files should be modified to add feature X?
"What is this project? What are its main features and technology stack?"
# Development Guide
"How do I start the local development environment? How do I run tests?"
# Code Standards
"What are the code standards for this project? What conventions are there?"
# Module Navigation
Which files should be modified to add feature X?
Refactoring Workflow
Refactoring requires careful handling; Codex can help you systematically improve code structure.
Refactoring Principles
- First understand the existing code structure
- Refactor in small steps, improve gradually
- Validate at each step to ensure functionality remains unchanged
- Maintaining test coverage
Refactoring workflow steps
| Steps | Description |
|---|---|
| Identify Problems | Codex analyzes code and identifies areas that need improvement |
| Devise a Plan | Discuss the refactoring plan, confirm the improvement direction |
| Execute Step by Step | Make small-scale changes, validate after each modification |
| Test and Verify | Run all tests to ensure functionality is correct |
| Clean Up and Optimize | Remove redundant code, optimize naming |
Refactoring Example
# Identify Problems
Analyze the src/utils module, identify code duplication and unreasonable designs
# Devise a Plan
Discuss how to refactor this module while maintaining backward compatibility
# Execute Step by Step
Step 1: Extract common functions into utils/common.py
# Test and Verify
Run all tests to confirm the refactoring has not broken functionality
# Continue to Next Step
Step 2: Simplify complex functions by splitting them into smaller units
Analyze the src/utils module, identify code duplication and unreasonable designs
# Devise a Plan
Discuss how to refactor this module while maintaining backward compatibility
# Execute Step by Step
Step 1: Extract common functions into utils/common.py
# Test and Verify
Run all tests to confirm the refactoring has not broken functionality
# Continue to Next Step
Step 2: Simplify complex functions by splitting them into smaller units
When refactoring, use /plan mode to create a plan first, then execute step by step to avoid large one-time changes.
Bug Fix Workflow
Codex can help you quickly locate and fix bugs.
Fix Workflow
| Steps | Operation |
|---|---|
| Describe the Problem | Describe the bug's symptoms and trigger conditions |
| Provide Information | Share error messages, logs, and screenshots |
| Find the Root Cause | Codex analyzes and finds the root cause |
| Generate Fix | Codex proposes a fix |
| Verify Fix | Run tests to confirm issues are resolved |
| Prevent Recurrence | Add tests to cover this scenario |
Bug Fix Example
# Describe the Problem
Users occasionally encounter 500 errors during login, and the error log shows:
TypeError: Cannot read property 'id' of undefined"
# Provide Information
Here is the complete error stack: [paste stack information]
# Find the Root Cause
After analysis, Codex found the issue: the user object is null in some cases
# Generate Fix
Fix this issue and ensure it does not affect the normal login flow
# Verify Fix
Run all login-related tests
# Prevent Recurrence
"Add a test covering the scenario where the user object is null"
Users occasionally encounter 500 errors during login, and the error log shows:
TypeError: Cannot read property 'id' of undefined"
# Provide Information
Here is the complete error stack: [paste stack information]
# Find the Root Cause
After analysis, Codex found the issue: the user object is null in some cases
# Generate Fix
Fix this issue and ensure it does not affect the normal login flow
# Verify Fix
Run all login-related tests
# Prevent Recurrence
"Add a test covering the scenario where the user object is null"
Screenshot-assisted debugging
Use screenshots to help Codex understand the issue:
Image input
# Attach screenshot in CLI
codex -i error-screenshot.png "Explain this error and fix it"
# Paste screenshot in IDE
Paste the screenshot directly in the conversation and describe the problem
codex -i error-screenshot.png "Explain this error and fix it"
# Paste screenshot in IDE
Paste the screenshot directly in the conversation and describe the problem
Code review workflow
Codex can review code changes, identify issues, and provide improvement suggestions.
Review Mode
| Mode | Trigger Method | Applicable scenarios |
|---|---|---|
| Review Mode | Enable in the App | Review uncommitted local changes |
| /review command | Use in CLI/IDE | Review changes in a specified scope |
| GitHub Integration | @codex review in PR | Review Pull Request |
Local Review
Review Mode
# Enable Review Mode in App
Click the eye icon in the toolbar
# Or use it in CLI
/review
# Specify review scope
/review src/auth/
# Review specific commits
/review HEAD~3..HEAD
Click the eye icon in the toolbar
# Or use it in CLI
/review
# Specify review scope
/review src/auth/
# Review specific commits
/review HEAD~3..HEAD
Customize review focus
Specify review focus
# Security Review
/review for security issues
# Performance Review
/review for performance regressions
# Code Style
/review for code style consistency
# Comprehensive Review
/review --detailed
/review for security issues
# Performance Review
/review for performance regressions
# Code Style
/review for code style consistency
# Comprehensive Review
/review --detailed
Test writing workflow
Codex can help you write and maintain test code.
New Feature Testing
Write Tests
# Write tests for the new feature
"Write unit tests for the GET endpoint of src/api/users.py,
covering normal responses, empty list, pagination boundaries, and other scenarios"
# Verify Tests
"Run the newly written tests"
# Supplement Coverage
"Check test coverage and supplement uncovered edge cases"
"Write unit tests for the GET endpoint of src/api/users.py,
covering normal responses, empty list, pagination boundaries, and other scenarios"
# Verify Tests
"Run the newly written tests"
# Supplement Coverage
"Check test coverage and supplement uncovered edge cases"
Fix Tests
Fix failing tests
# Analyze failing tests
"Test test_user_login failed; analyze the cause and fix it"
# Batch Fix
"Run all tests and fix failing tests"
"Test test_user_login failed; analyze the cause and fix it"
# Batch Fix
"Run all tests and fix failing tests"
Documentation generation workflow
Codex can help generate and update documentation.
Generate documentation
Documentation generation
# API Documentation
"Generate API documentation for the src/api module, including request and response formats for each endpoint."
# README Update
"Update README.md, adding descriptions and usage examples for new features."
# Inline Comments
"Add comments to complex functions, explaining key logic."
"Generate API documentation for the src/api module, including request and response formats for each endpoint."
# README Update
"Update README.md, adding descriptions and usage examples for new features."
# Inline Comments
"Add comments to complex functions, explaining key logic."
Best Practices
Workflow Selection
- Daily development: continuous interaction, iterative improvement
- Refactoring: plan first, then execute, validate in small steps
- Bug Fix: Provide sufficient information and verify the root cause
- Review: Conduct regularly, focus on security issues
Efficiency Tips
- Use AGENTS.md to define project conventions, reducing repeated instructions
- Use Skills to encapsulate common workflows
- Use Worktree to isolate different tasks
- Configure a reasonable Approval policy
FAQ
Q: How to handle large-scale refactoring?
Use /plan mode to create a step-by-step plan, verifying after each step.
Q: How to prevent bugs from recurring after fixing?
Add dedicated tests to cover this scenario, and add relevant check rules in AGENTS.md.
Q: How to help Codex understand project conventions?
Create an AGENTS.md file to define the project's tech stack, code conventions, testing requirements, etc.
Q: How are review results shared with the team?
Use GitHub integration to review in the PR, results will be automatically added as comments.
other extensions