Codex Cheat Sheet for Agentic Coding

Codex-style agentic coding means delegating software tasks to an AI agent that can read files, edit code, run commands, inspect failures, and iterate. Treat it like a fast junior engineer with shell access: give it clear intent, tight boundaries, and a definition of done. This cheat sheet focuses on practical workflows for developers using an agentic coding CLI or IDE integration.

1. Mental Model

Agentic coding works best as a loop: inspect, plan, edit, test, explain. The agent is strongest when the repository already has good tests, scripts, type checks, and conventions. It is weakest when the task is vague, the codebase has hidden behavior, or success cannot be verified automatically.

Use Codex for

Small features, bug fixes, test generation, refactors, migrations, dependency upgrades, documentation updates, CLI scripts, and code review preparation.

Avoid blind delegation for

Security-sensitive changes, production data migrations, authentication logic, payments, cryptography, and large architectural rewrites. Use the agent, but review every line.

2. Basic CLI Workflow

Commands vary by tool and version, but a typical Codex-style workflow looks like this:

# Start from a clean branch
git checkout -b fix/login-timeout

# Open an agentic coding session in the current repository
codex

# Or run a focused one-shot task
codex "Find why login sessions expire too early, fix it, and add tests."

# Review all changes after the agent finishes
git diff

# Run your normal checks
npm test
npm run lint
npm run typecheck

# Commit only after human review
git add .
git commit -m 'Fix premature login session expiration'

Keep the working tree clean before starting. This makes it easy to see exactly what the agent changed and to revert bad edits.

3. High-Quality Prompt Template

A good prompt includes goal, context, constraints, verification, and output expectations. Do not ask the agent to “improve the app.” Ask for a specific, testable outcome.

Task: Fix the bug where inactive users are not logged out after 30 minutes.

Context:
- Backend: Node.js + Express in src/server
- Session logic: src/auth/session.ts
- Tests: npm test -- auth

Constraints:
- Do not change public API responses.
- Keep existing cookie names.
- Prefer a small patch.

Definition of done:
- Add or update tests for timeout behavior.
- Run the relevant test command.
- Summarize the root cause and files changed.

Prompt Formula

Implement [specific outcome] in [location]. Preserve [constraints]. Verify with [commands]. Explain [what changed].

4. Common Agentic Commands

Use short commands when interacting with the agent. The best commands are scoped and observable.

Inspect the code path for password reset and summarize it before editing.

Add unit tests for the edge cases in src/billing/proration.ts. Do not change implementation yet.

Refactor this function for readability without changing behavior. Keep the public signature.

Run the failing tests, identify the smallest fix, apply it, then rerun only those tests.

Update the README for the new environment variable. Include an example value.

Review your own diff for accidental behavior changes and remove unrelated edits.

5. Repository Instructions

Many agentic tools support a repository instruction file such as AGENTS.md, CONTRIBUTING.md, or tool-specific config. Put stable rules there so you do not repeat them in every prompt.

# Agent Instructions

## Build and test
- Install dependencies with: npm ci
- Run tests with: npm test
- Run lint with: npm run lint
- Run type checks with: npm run typecheck

## Coding style
- Use TypeScript strict mode.
- Prefer small functions and explicit return types for exported functions.
- Do not introduce new dependencies without explaining why.

## Safety
- Do not edit files under migrations/ unless explicitly asked.
- Do not change public API schemas without updating docs and tests.

This file acts like a standing brief. Keep it short, current, and enforceable.

6. Feature Implementation Recipe

For features, ask the agent to plan first. Then approve or refine the plan before it edits.

We need to add a CSV export button for invoices.

First, inspect the frontend and backend invoice code. Return a short implementation plan with files to change. Do not edit files yet.

After reviewing the plan:

Proceed with the plan. Keep the export endpoint read-only. Add tests for authorization and CSV formatting. Run the relevant backend tests.

7. Bug Fix Recipe

For bugs, push the agent to reproduce before fixing. A bug without a reproduction often leads to speculative edits.

Bug: The checkout total is sometimes one cent higher than expected.

Find the calculation path and add a failing test that reproduces the rounding issue. Show me the test failure before changing production code.

Then continue:

Now make the smallest production-code change to pass the new test. Do not alter unrelated pricing behavior.

8. Refactoring Recipe

Agentic refactors are safest when behavior is pinned by tests. If tests are thin, ask for characterization tests first.

Refactor src/search/queryBuilder.ts for readability.

Rules:
- Preserve behavior exactly.
- Add characterization tests before refactoring if coverage is missing.
- Avoid changing exported types.
- Run tests that cover search.

9. Example Code Task

Here is a compact task for generating a utility with tests.

Create a TypeScript utility called retryAsync in src/utils/retryAsync.ts.

Requirements:
- Accept an async function and retry options.
- Support retries, delayMs, and shouldRetry(error).
- Preserve the original error after the last attempt.
- Add Jest tests for success, eventual success, permanent failure, and shouldRetry=false.

The target implementation might look like this:

export type RetryOptions = {
  retries: number;
  delayMs: number;
  shouldRetry?: (error: unknown) => boolean;
};

const sleep = (ms: number): Promise<void> =>
  new Promise((resolve) => setTimeout(resolve, ms));

export async function retryAsync<T>(
  operation: () => Promise<T>,
  options: RetryOptions,
): Promise<T> {
  let lastError: unknown;

  for (let attempt = 0; attempt <= options.retries; attempt += 1) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;

      const canRetry = options.shouldRetry?.(error) ?? true;
      if (!canRetry || attempt === options.retries) {
        throw lastError;
      }

      await sleep(options.delayMs);
    }
  }

  throw lastError;
}

10. Review Checklist

Never merge agent-written code without review. Check for unrelated edits, over-engineering, missing tests, changed public contracts, weak error handling, new dependencies, secrets in logs, and flaky timing. Run the full test suite when the change touches shared infrastructure.

# Useful review commands
git status
git diff --stat
git diff
npm test
npm run lint
npm run typecheck

11. Best Practices

Keep tasks small. Ask for a plan before large edits. Require tests for behavior changes. Prefer one agent session per branch. Reset bad attempts quickly instead of negotiating with a messy diff. Use the agent to explain unfamiliar code, but verify claims in the source.

The core rule is simple: make success machine-checkable. Codex is most effective when it can run the same commands your team trusts in CI.