Complete 2026 Guide to Codex Best Practices

1. AGENTS.md Configuration Principles

File size limit : keep each file under 100 lines (hard limit 300 lines).

Only store information that Codex cannot infer from the code (e.g., context that is already obvious).

When the rule set grows, split it into sub‑directories and load them by scope.

Tag or number critical rules so they are not missed.

AGENTS.md Scope Rules

Direct user command > deeper AGENTS.md > shallow AGENTS.md

Each AGENTS.md applies to the entire directory tree that contains it.

Deeper files have higher priority.

System / developer / user commands have the highest priority.

Example AGENTS.md Structure

# Project Name

## Workflow
- Run <code>npm test</code> after each code change
- Use Conventional Commits (feat:, fix:, refactor:, docs:)
- Create PR with <code>gh pr create</code>

## Tech Stack
- Node.js 18+, Express 4.x, PostgreSQL 16
- Tests: Jest + React Testing Library
- Auth: JWT + bcrypt

## Code Standards
- Files < 300 lines; split if larger
- Prohibit <code>any</code> type
- All public APIs must have JSDoc comments

## Required Checks (run in order)
1. <code>npm run lint</code> – fix lint issues
2. <code>npm test</code> – run relevant tests
3. <code>npm run typecheck</code> – type checking

2. Workflow Best Practices

Phased Workflow

Understand the codebase → modify.

Plan → implement.

Generate → verify.

Avoid compressing all steps into a single large prompt.

Small Tasks

Tasks that take 3–5 minutes should be expressed in a single sentence.

Complex workflows are reserved for multi‑file, multi‑step tasks.

Simple renames are handled with one‑line commands.

Let Codex Understand the Codebase First

codex exec "Please explain the overall structure of the src/ directory, including:
1. Core modules
2. Dependency relationships
3. Entry file location"

Parallel Task Strategy

Assign independent tasks to separate Codex instances.

Use background processing to keep the workflow continuous.

Avoid dependency blocking between tasks.

Community suggestion: distribute well‑scoped tasks across multiple agents.

3. Debugging and Error Handling

Paste Bug and Say "fix"

Paste the error message and issue the single word "fix".

Do not guide how to fix it or guess the cause.

Codex’s debugging ability is strong; over‑guiding can bias results.

Success rate exceeds 80%.

Two Failures = Restart

If the same issue fails more than twice, start a new session.

Long sessions cause context compression and performance loss.

Recommendation: restart after two failed attempts.

Force Rewrites of Mediocre Solutions

When Codex produces a working but inelegant solution, ask it to discard the current knowledge and implement an elegant version.

Rewrites are usually far better than patches.

4. Context Management

Long Sessions Degrade Performance

Codex’s web container has a limited context window.

Repeated compression reduces understanding ability.

Community proposal: automatically start a new session after N compressions (e.g., auto_new_session_after_compactions = N).

Practical Recommendations

Split complex tasks into phases, opening a new session for each phase.

Write key decisions and context into AGENTS.md instead of relying on conversation memory.

Carry a concise context summary into new sessions.

5. Prompt Engineering

Golden Prompt Structure

【Task Type】Please fix/implement/refactor ...

【Problem Description】
- Specific, clear description
- Current behavior vs expected behavior

【Constraints】
- Any limits or requirements
- Files/modules not to modify

【Reference Info】
- Relevant file paths
- Error messages or logs
- Example code snippets

Best‑Practice Tips

Provide exact file paths and line numbers (e.g., "Fix src/auth/login.py lines 45‑62").

Specify the desired output format (e.g., generate a PR with code changes, at least three unit tests, and updated README).

State the test command to verify the fix (e.g., npm test -- --testPathPattern=auth).

Include error logs when relevant.

6. Subagents (子智能体)

Adding "use subagents" in the prompt lets Codex automatically split work among multiple sub‑agents.

Specialized sub‑agents (e.g., "frontend component agent") outperform generic mega‑agents.

Each sub‑agent has its own context window, preventing pollution and bias.

Multiple agents can cooperate by sharing AGENTS.md and coordinating via CI/CD pipelines.

7. Skills and MCP Plugins

MCP Server (Model Context Protocol)

The MCP protocol enables external tool integration. Example tools:

xlsx-for-ai : 39 Excel operations (read/write, pivot, charts, etc.). Install with npm install -g xlsx-for-ai.

Community MCP Registry : registry.modelcontextprotocol.io (browse and install).

Skill directory layout:

skills/
  api-design/
    SKILL.md          # Core rules and index
    references/       # Corpus, reference material
    scripts/          # Helper scripts
    examples/        # Example code

The core file contains only core rules and index.

References and checklists go in references/.

Progressively disclose content; Codex reads sub‑directories only when needed.

8. Permissions and Security

Execution Environment

Codex runs in isolated cloud containers.

Internet access is disabled during task execution.

Only code and pre‑configured dependencies from the GitHub repository are accessible.

Prompt Injection Risks

Community discussion highlights that hidden commands in files can cause unintended actions. Mitigations:

Trust‑domain separation: treat user input as high‑trust, retrieved documents as low‑trust, tool results as medium‑trust.

Map permissions: retrieved text can provide information but cannot authorize shell/file/network operations.

Manual review of all generated code changes.

Principle of least privilege: do not grant unnecessary permissions to Codex.

User Responsibility Checklist

Manually review and verify all agent‑generated code.

Never store sensitive data (keys, passwords, tokens) in the codebase.

Regularly update security rules in AGENTS.md.

Check diffs carefully before committing.

9. Common Gotchas (陷阱)

Giving Up Too Early : Split the task into smaller, isolated units and run each as a separate PR.

Context Compression Degrades Ability : Phase complex tasks, start new sessions per phase, write key decisions to AGENTS.md, optionally reset with git reset --hard.

Test Issues : Adopt TDD (write tests first), scrutinize generated tests, enforce strict test changes.

Forgetting to Compile : Include compilation steps in AGENTS.md and enforce compilation before testing.

Working Directory Chaos : Run git status after each task, perform Git operations manually, ensure Codex only modifies files.

Rewrites Without Deleting Old Code : Review diffs to confirm deletions, explicitly instruct Codex to remove old implementations, verify file list.

Prompt Injection : Enforce trust‑domain separation, manually review changes, never store secrets in the repository.

Long‑Session Quality Decay : Break complex tasks into phases, start a new session for each phase, summarize key context in AGENTS.md.

10. Typical Use Cases and Examples

Scenario 1: Daily Bug Fix

codex exec "Fix pagination bug in src/api/user.ts.
Current behavior: page 2 returns empty data.
Expected behavior: correctly return user list for page 2.
Reference: Issue #1234.
After changes run: npm test -- user.test.ts"

Scenario 2: Bulk Refactor

codex exec "Refactor all class components under src/components/ to functional components.
Requirements:
1. Use React Hooks instead of lifecycle methods.
2. Preserve existing functionality.
3. Update related test files.
4. Run npm test to verify."

Scenario 3: Test Coverage

codex exec "Add unit tests for all utility functions in src/utils/.
Requirements:
1. At least two test cases per function.
2. Cover normal and edge cases.
3. Name test files *.test.ts.
4. Verify with npm test."

Scenario 4: Codebase Q&A

codex exec "Explain the authentication flow in src/auth/.
Include:
1. User login process
2. Token generation and verification
3. Permission checking mechanism
4. Relevant configuration files"

11. Installation and Quick Start

Installation

# npm
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# Start interactive TUI
codex

# Non‑interactive one‑liner
codex exec "Fix src/auth.py login verification vulnerability"

System Requirements

macOS 12+, Ubuntu 20.04+, Windows 11 (WSL2)

4 GB RAM (8 GB recommended)

Git 2.23+ (recommended)

Login to ChatGPT Account

# Choose "Sign in with ChatGPT"
# Using a ChatGPT account gives access to Plus/Pro/Enterprise plans

Debugging and Logging

# View detailed logs
tail -F ~/.codex/codex-tui.log

# Custom log level
RUST_LOG=codex_core=debug codex

# Custom log directory
codex -c log_dir=./.codex-log

12. Core Principles Summary

Context is a precious resource – keep prompts concise, compress regularly, and reset when polluted.

Break complex tasks into phases, opening a new session for each.

Record key decisions in AGENTS.md.

System constraints > prompt constraints – use AGENTS.md instead of asking Codex to remember.

Critical rules should be tagged or numbered.

Programmatic checks must be executed and verified.

Divide and conquer: sub‑agents, staged workflows, separate specification from implementation.

Avoid over‑engineering; simple tasks deserve one‑sentence prompts.

Continuously improve by logging Gotchas, reviewing weekly, and converting frequent issues into formal rules.

Prioritize security: trust‑domain separation, manual code review, and least‑privilege execution.

13. References

OpenAI Codex official documentation: https://platform.openai.com/docs/codex

GitHub repository (openai/codex, 82.8k ⭐): https://github.com/openai/codex

Codex App: https://chatgpt.com/codex

Developer docs: https://developers.openai.com/codex

MCP registry: registry.modelcontextprotocol.io

Community discussions: https://github.com/openai/codex/discussions

Prompt injection risk discussion: https://github.com/openai/codex/discussions/6162

Session refresh strategy: https://github.com/openai/codex/discussions/22642

Local automated memory (Sentinel‑AI) proposal: https://github.com/openai/codex/discussions/21728