How to Get the Most Out of OpenAI Codex: Best Practices for Developers

Mar 25, 2026

Problem

Codex kept making unexpected changes to my codebase. One time it renamed two zones in my game project without asking. Another time it consolidated my loot tables beautifully - but forgot to include an entire category of items. I’d ask it to implement a feature, and it would work, but with these random side effects that drove me crazy.

A Reddit user described it perfectly: “It’s great until it’s not. Just like other LLMs. You need to keep it on a tight leash and double check all specs.”

The question nagging at me: How do I get the benefits of Codex without the random mess?

What I Found

I dug into a Reddit thread on r/codex where developers shared their Codex experiences. Two patterns emerged:

The positive experience (7 upvotes): “Been working closely with it for the last 3 weeks. With proper documenting system: markdowns, tickets, etc. it works great.”

The cautionary experience (2 upvotes): “Just now, I submitted a zone map and loot tables for my project. Codex consolidated everything real neat but also renamed 2 out of 5 zones and forgot to include one crucial type of loot.”

The difference wasn’t the tool - it was the approach. Developers who set up proper documentation systems got consistent results. Those who didn’t got the “great until it’s not” experience.

How to Solve It

I learned that getting the most out of Codex requires two things: a documentation system and active oversight. Here’s how to set up both.

Step 1: Create AGENTS.md

AGENTS.md is a configuration file that tells Codex how to behave in your project. It’s like CLAUDE.md but for Codex.

# Project Documentation for Codex

## Project Structure
- `src/` - Source code
- `docs/` - Documentation
- `tests/` - Test files

## Naming Conventions
- Components: PascalCase (e.g., UserProfile.tsx)
- Utilities: camelCase (e.g., formatDate.ts)
- Constants: UPPER_SNAKE_CASE

## Code Style
- Use TypeScript for type safety
- Follow ESLint configuration
- Max line length: 100 characters

## Constraints
- Never rename existing components without explicit instruction
- Always verify all required elements are included
- Double-check imports and dependencies

I tested this with my game project. Before AGENTS.md, Codex would rename things randomly. After adding the naming conventions and constraints, it started asking before making naming changes.

Step 2: Set Up a Documentation Structure

The Reddit user mentioned “markdowns, tickets, etc.” I tried to figure out what that meant in practice. Here’s what worked:

project/
├── AGENTS.md          # Codex behavior configuration
├── README.md          # Project overview
├── docs/
│   ├── architecture.md
│   ├── api.md
│   └── contributing.md
├── tickets/
│   ├── active/        # Current work items
│   └── completed/     # Finished tasks
└── src/
    └── components/

The key insight: Codex needs context to make good decisions. When I only gave it a task, it made assumptions. When I gave it context (architecture docs, naming conventions, existing patterns), it made fewer mistakes.

Step 3: Create a Ticket System

I started using simple markdown files for tracking work:

# Add User Authentication

## Requirements
- JWT token-based auth
- Login endpoint: POST /auth/login
- Logout endpoint: POST /auth/logout
- Token refresh: POST /auth/refresh

## Constraints
- Do NOT modify existing user schema
- Use bcrypt for password hashing
- Token expiry: 7 days

## Files to Modify
- src/routes/auth.ts (new)
- src/middleware/auth.ts (new)
- src/types/user.ts (add auth types)

## DO NOT
- Rename existing files
- Change existing API endpoints
- Remove existing middleware

This solved the “forgot to include” problem. By explicitly listing what to modify and what NOT to touch, Codex had clear boundaries.

Step 4: The Verification Checklist

Even with documentation, I still check Codex’s output. The Reddit warning stuck with me: “double check all specs.”

I use this checklist after every Codex output:

[ ] Did it rename anything without asking?
[ ] Are all required components included?
[ ] Do imports resolve correctly?
[ ] Did it follow naming conventions?
[ ] Are all requirements from ticket met?
[ ] Did it touch any files it shouldn't have?

Why This Works

The documentation approach works because it addresses Codex’s core limitation: it makes assumptions when context is missing.

Without documentation:

I ask: “Add user authentication”
Codex guesses: file names, naming patterns, where to put things
Output: works, but with random changes

With documentation:

I ask: “Add user authentication” + point to ticket
Codex reads: AGENTS.md, architecture docs, ticket constraints
Output: follows established patterns, fewer surprises

The verification step catches what documentation misses. Even with perfect docs, Codex sometimes hallucinates. Checking output prevents these hallucinations from reaching production.

Common Mistakes I Made

Mistake 1: No documentation, just prompts

I used to just describe what I wanted in the chat. Codex would implement it, but each implementation had different patterns. No consistency.

# BAD: Relying on chat prompts alone
Me: "Add a user profile component"
Codex: *creates UserProfile.tsx*

Me: "Add a settings component"
Codex: *creates SettingsComponent.ts*

# Notice the inconsistent naming (Profile vs Component)

Mistake 2: Vague AGENTS.md

My first AGENTS.md was too generic:

Write clean code. Be helpful. Follow best practices.

These are goals, not rules. Codex can’t follow them consistently because they’re subjective.

Mistake 3: Skipping verification

I trusted Codex’s output too much. The loot table incident taught me: always verify. It takes 30 seconds to check the output, but saves hours of debugging unexpected changes.

The Balanced Approach

I now treat Codex as a powerful junior developer. It can implement complex features quickly, but needs:

Clear instructions (tickets)
Established patterns (AGENTS.md)
Code review (verification)

This mindset shift changed everything. Instead of hoping Codex would “just work,” I built a workflow that accounted for its strengths (speed, pattern recognition) and weaknesses (assumptions, occasional hallucinations).

Summary

Getting the most out of Codex requires a structured approach:

Create AGENTS.md with specific rules, not vague goals
Document your project structure so Codex has context
Use tickets to specify requirements and constraints
Verify outputs against your checklist before accepting

The Reddit user was right: Codex is great until it’s not. But with proper documentation and active oversight, the “until it’s not” moments become rare. I’ve gone from frequent surprises to predictable, useful outputs - and saved hours of debugging random changes.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion - r/codex

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!