SUMMARY
Claude Code (CLI) uses markdown configuration while OpenAI Codex CLI (CLI) uses markdown. They differ on 2 of 11 compared features. Both tools provide AI-assisted development but take different approaches to project configuration.
FEATURE COMPARISON
| Feature | Claude Code | OpenAI Codex CLI |
|---|---|---|
| Config format | markdown | markdown |
| Hierarchy support | ✓ | ✓ |
| Global config | ✓ | ✓ |
| Project config | ✓ | ✓ |
| Subdirectory scoping | ✓ | ✓ |
| File inclusion / imports | ✓ | ✗ |
| Ignore file | .claudeignore | .codexignore |
| IDE integration | CLI | CLI |
| Schema / structure | Free-form (Markdown) | Free-form (Markdown) |
| Git committed | ✓ | ✓ |
| Encoding | UTF-8 | UTF-8 |
FILE MAPPING
SIDE-BY-SIDE CODE SAMPLES
# Project Name
> TypeScript + React monorepo. Deployed on Vercel.
## Code Style
- TypeScript strict mode — no `any`, no `ts-ignore`
- Named exports only (no default exports)
- Prefer functional patterns: map/filter/reduce over for-loops
- Error handling: use Result<T, E> from `src/lib/result.ts`
## Architecture
- `src/routes/` — Route handlers (thin layer, delegates to services)
- `src/services/` — Business logic, one file per domain entity
- `src/db/` — Drizzle ORM schema and query helpers
- `src/lib/` — Shared utilities (logger, result type, validation)
## Commands
```bash
pnpm install # Install dependencies
pnpm dev # Start dev server (port 3000)
pnpm test # Run Vitest suite
pnpm test:e2e # Run Playwright tests
pnpm lint # ESLint + Prettier check
pnpm db:migrate # Run pending Drizzle migrations
```
## Git Conventions
- Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`
- Branch naming: `feat/short-description`, `fix/issue-number`
- Squash merge to main; delete branches after merge
## Notes
- The `src/legacy/` directory is being migrated. Do not add new code there.
- All dates are stored as UTC. Never use local time.
@docs/api-patterns.md
@docs/database-conventions.md
# AGENTS.md
## Project Overview
This is a Next.js 14 e-commerce application using the App Router,
Server Components, and Drizzle ORM with PostgreSQL.
## Code Conventions
- Use TypeScript strict mode throughout
- Prefer Server Components; use "use client" only when necessary
- Name files with kebab-case: `product-card.tsx`, not `ProductCard.tsx`
- Co-locate tests: `product-card.test.tsx` next to `product-card.tsx`
## Architecture
- `app/` — Next.js App Router pages and layouts
- `components/` — Shared UI components
- `lib/` — Utilities, database client, auth helpers
- `actions/` — Server Actions for mutations
## Testing
- Use Vitest for unit tests, Playwright for E2E
- Mock database calls using `lib/test-utils.ts` helpers
- Every new component needs at least one test
## Build Commands
```bash
pnpm dev # Start dev server
pnpm build # Production build
pnpm test # Run Vitest
pnpm test:e2e # Run Playwright
pnpm lint # ESLint check
```
KEY DIFFERENCES
Claude Code: Supported. OpenAI Codex CLI: Not supported.
Claude Code: .claudeignore. OpenAI Codex CLI: .codexignore.
Claude Code concatenates all CLAUDE.md files from global scope down through every directory level. Codex uses nearest-ancestor resolution for AGENTS.md — only the closest file to the working directory applies, though it merges parent files when traversing upward to the project root.
Claude Code supports a global ~/.claude/CLAUDE.md that applies to all projects. Codex has no global equivalent — AGENTS.md is always project-scoped, starting from the repository root.
Claude Code uses .claude/settings.local.json (JSON) for personal overrides of tool permissions. Codex uses AGENTS.override.md (Markdown) for personal instruction overrides, keeping the same format as the main config.
CLAUDE.md supports @filename.md directives to compose instructions from multiple files. AGENTS.md does not support file inclusion — each file is self-contained.
WHICH SHOULD I USE?
PORTABILITY TIP
# Maintain a single source of truth:
cp AI-INSTRUCTIONS.md CLAUDE.md
cp AI-INSTRUCTIONS.md .cursorrules
cp AI-INSTRUCTIONS.md AGENTS.md