Claude Code vs. Codex: Comparing the Official Best Practices

Claude Code and Codex are the two flagship products in the coding-agent market. The value of their official best-practice guides isn’t “which one is better” — it’s how to operate a coding agent reliably: a shift from “choosing a tool” to “building operating habits.”

A Shared Operating Model

The two official guides converge on eight points:

Context first — task, files, constraints, and the definition of “done” must be explicit
Plan first when ambiguity is high — use plan/interview mode before implementing
Verify with runnable checks — tests, builds, lint, screenshots
Persist guidance — CLAUDE.md or AGENTS.md, instead of rewriting it into every prompt
Control permissions — loosen them only after trust is established
Use external context judiciously — MCP and CLI tools
Scale out only once reliable — skills, hooks, subagents, automations, parallel sessions
Independent review — long-running tasks need fresh-context review or diff review

Claude Code’s Official Themes

Theme	Key points
Verify the work	Provide tests, builds, screenshots; without checks, the human becomes the only verification loop
Explore before coding	explore → plan → implement → commit/PR; small changes can skip planning
Rich context	`@` file references, screenshots, URLs, logs
Configure the environment	`/init` to build `CLAUDE.md`; permissions, sandbox, MCP, hooks, skills
Manage sessions	`/clear` between tasks; subagents to preserve main context; checkpoints, `/rewind`
Scale with automation	`claude -p` for non-interactive runs; worktrees for parallelism; adversarial review before release

Common failures: mixing unrelated tasks into the same context-heavy session; not clearing and restarting after repeated corrections; letting Claude work without verifiable checks.

Codex’s Official Themes

Theme	Key points
Prompt structure	Goal, Context, Constraints, Done when
Plan mode	Plan first for complex/ambiguous tasks; can interview the user
`AGENTS.md`	An open-format README for agents: layout, commands, conventions, PR expectations, verification standards
`config.toml`	Personal `~/.codex/` plus repo `.codex/`; model, sandbox, approval, MCP
Testing and review	Create/update tests, run checks, confirm behavior, `/review`
Skills	Single responsibility, `SKILL.md`, clear triggers
Automations	Schedule background runs only once the workflow is stable
Session control	threads, worktrees, resume/fork; avoid multiple threads editing the same file

Common failures: piling durable rules into the prompt instead of AGENTS.md; not stating the build/test/verify process; skipping planning for multi-step work; granting broad permissions too early; automating before the workflow is stable.

Side-by-Side Comparison

Dimension	Claude Code	Codex
Persistent repo guidance	`CLAUDE.md`	`AGENTS.md`
Planning	explore → plan → code	Plan mode / PLANS.md
Verification	runnable checks + screenshots	done-when + tests + review loop
Permissions	auto mode, `/permissions`, `/sandbox`	sandbox, approval policy
Long-running tasks	checkpoints, `/rewind`, resume	threads, `/fork`, goals, worktrees
Extensibility	hooks, skills, subagents, plugins	skills, automations, config profiles

Relationship to Harness

The official practices map onto the five Harness dimensions:

Context → CLAUDE.md / AGENTS.md, rich references
Permissions → sandbox, approval, auto mode
Routing → subagents, plan mode, skills
Governance → hooks, rules
Evaluation → tests, review, verification-before-completion

See Agentic Coding Agent Core Concepts for the core concept map.

A Checklist for Learners