Workflows Intermediate

This lesson covers practical workflows for using Codex across different types of development tasks: bug fixing, feature implementation, test writing, refactoring, documentation, multi-file changes, parallel tasks, and CI/CD integration.

Bug Fixing Workflow

Bug fixes are one of the most effective use cases for Codex. The key is providing clear reproduction information:

Bug: Users with special characters in their display
name (e.g., "O'Brien") get a 500 error when updating
their profile.

Expected: Profile updates should work for all valid names.
Actual: 500 Internal Server Error, SQL injection risk.

Affected file: src/api/profile.ts, line ~45
Root cause: Display name is not being properly escaped
before the SQL query.

Fix requirements:
- Use parameterized queries instead of string interpolation
- Add input sanitization for the display_name field
- Add a regression test with special characters: O'Brien,
  "Smith", name with <script> tag
- Verify existing profile update tests still pass

Feature Implementation Workflow

For new features, break them down into well-scoped increments:

Feature: Add pagination to the GET /api/products endpoint.

Requirements:
- Accept query parameters: page (default 1), limit (default 20, max 100)
- Return paginated response with metadata:
  { data: [...], meta: { page, limit, total, totalPages } }
- Add Link headers for next/prev pages (RFC 5988)
- Validate page and limit are positive integers
- Return 400 for invalid pagination parameters
- Update existing tests and add new pagination tests
- Follow the existing response format in src/api/types.ts

Files to modify:
- src/api/products.ts (add pagination logic)
- src/api/types.ts (add PaginatedResponse type)
- src/__tests__/api/products.test.ts (add pagination tests)

Test Writing Workflow

Codex excels at generating comprehensive test suites for existing code:

Task: Add unit tests for src/utils/currency.ts

The file exports these functions:
- formatCurrency(amount, currency, locale)
- parseCurrency(formattedString)
- convertCurrency(amount, from, to, rates)
- roundToDecimals(amount, decimals)

Test requirements:
- Use Jest as the testing framework
- Test happy paths with common currencies (USD, EUR, GBP, JPY)
- Test edge cases: zero, negative, very large numbers
- Test error handling: invalid currency codes, null inputs
- Test locale-specific formatting (en-US, de-DE, ja-JP)
- Aim for 100% branch coverage
- Place tests in src/__tests__/utils/currency.test.ts

Refactoring Workflow

Refactoring tasks should clearly define the target structure and preserve existing behavior:

Task: Refactor the monolithic OrderService class.

src/services/OrderService.ts is 800+ lines with too many
responsibilities. Split it into focused service classes:

1. OrderService - core order CRUD operations
2. OrderValidationService - input validation and business rules
3. OrderNotificationService - email and webhook notifications
4. OrderPricingService - price calculation and discounts

Constraints:
- All existing tests must continue to pass
- Update imports in all files that use OrderService
- Keep the same public API (method signatures)
- Use dependency injection pattern consistent with
  existing services in src/services/

Documentation Workflow

Use Codex to generate or update documentation:

• API documentation: Generate OpenAPI/Swagger specs from existing route handlers
• Code comments: Add JSDoc or docstring comments to functions lacking documentation
• README updates: Update setup instructions, API reference, or usage examples
• Migration guides: Document breaking changes and migration steps for API version upgrades

Multi-File Changes

Codex handles coordinated changes across multiple files effectively. When your task requires changes to multiple files, mention all of them explicitly:

Working with AGENTS.md

The AGENTS.md file shapes how Codex approaches all tasks. Optimize it for your project:

Parallel Tasks

Codex can work on multiple tasks simultaneously, each in its own sandbox. This is powerful for batch operations:

• Submit multiple independent bug fixes at the same time
• Generate tests for different modules in parallel
• Run documentation updates alongside feature work
• Process a backlog of small, well-defined issues

Integration with CI/CD

Codex integrates with your CI/CD pipeline through pull requests. When Codex creates a PR:

1. CI triggers automatically

   Your existing GitHub Actions, CircleCI, or other CI pipeline runs on the PR branch.

2. Tests validate the changes

   The CI pipeline runs your full test suite, linting, type checking, and any other checks.

3. Results feed back to review

   CI results appear on the PR, helping you decide whether to approve, request changes, or reject.

4. Merge triggers deployment

   When you merge the PR, your standard deployment pipeline handles the rest.

Team Workflows

For teams using Codex together: