How to Use Codex Efficiently with AGENTS.md and PLAN.md

GEN AI Content
As AI coding assistants like OpenAI Codex, Cursor, and various agentic coding tools become mainstream, developers are realizing a common pitfall: Context Loss.

When building complex applications, AI agents often forget the overarching architecture, stray from coding standards, or get stuck in a loop of microscopic fixes without progressing the actual project. The solution isn't to write longer, more complex one-off prompts. The solution is State Management via Markdown.

In this article, I will show you how to drastically improve your AI coding efficiency by introducing two foundational files to your repository: AGENTS.md and PLAN.md.

---

The Problem: Why AI Agents Fail in Large Repositories

When you ask an AI (powered by Codex or similar LLMs) to "add a user authentication feature," it faces several hurdles:

1. It doesn't know your specific architectural preferences.
2. It doesn't know what has already been built versus what is planned.
3. It relies purely on the immediate context window, which gets diluted over long chat sessions.

To solve this, we treat the AI as a new developer joining a highly organized team. We give it a Role and a Roadmap.

---

1. Defining the Roadmap: PLAN.md

PLAN.md is a living document that acts as the brain's memory for your project. Instead of explaining where you are in the project every time you open a new chat session, you simply tell the AI: "Check PLAN.md for our current status and execute the next unchecked task."

What goes into PLAN.md?

• High-Level Architecture: A brief summary of what the app does.
• Current Phase: Where the project currently stands.
• Actionable Checklists: Broken down into atomic, manageable steps.

Example PLAN.md

# Project Name: TaskFlow API
**Description:** A lightweight task management REST API.

## Architecture
- **Language:** Python 3.11
- **Framework:** FastAPI
- **Database:** PostgreSQL (via SQLAlchemy)

## Roadmap

### Phase 1: Foundation (COMPLETED)
- [x] Setup virtual environment and requirements.txt
- [x] Configure database connection URL
- [x] Create base SQLAlchemy models

### Phase 2: Authentication (IN PROGRESS)
- [x] Create User database model
- [ ] Implement JWT token generation (<- WE ARE HERE)
- [ ] Create `/login` and `/register` endpoints
- [ ] Add auth middleware to protect routes

### Phase 3: Task Management (TODO)
- [ ] Create Task database model
- [ ] CRUD endpoints for Tasks

How this helps Codex:

When Codex reads this file, it instantly understands the tech stack, what it shouldn't reinvent (since Phase 1 is done), and exactly what its current objective is. Once a task is done, you ask the AI to update the PLAN.md file by checking off the box.

---

2. Defining the Rules: AGENTS.md

If PLAN.md is what to do, AGENTS.md is how to do it.

Different tasks require different mindsets. You might want the AI to act as a strict Security Auditor one day, and a creative Frontend Designer the next. AGENTS.md defines the personas, constraints, and strict coding rules the AI must follow.

What goes into AGENTS.md?

• System Prompts / Personas: Clear definitions of the agent's role.
• Strict Coding Constraints: Rules about typing, testing, formatting, or banned libraries.
• Communication Rules: How the AI should respond (e.g., "Do not apologize, just provide the code").

Example AGENTS.md

# AI Agent Directives

When interacting with this repository, you must adopt one of the following roles based on the task. If not specified, default to `@BackendDev`.

## @BackendDev
**Role:** Senior Python Backend Engineer.
**Rules:**
1. **Type Hinting:** ALL functions and methods must have strict Python type hints.
2. **Error Handling:** Never use bare `except:`. Always catch specific exceptions and log them.
3. **No Mocks:** When writing tests, prefer testing against the local SQLite test DB over mocking SQLAlchemy.
4. **Banned Libraries:** Do not use `requests`. Use `httpx` for all HTTP calls.

## @RefactorBot
**Role:** Code Quality Inspector.
**Rules:**
1. Your job is to reduce cognitive complexity.
2. Extract nested `if` statements into early returns.
3. Ensure all functions adhere to the Single Responsibility Principle (SRP).
4. Do NOT change the public API or behavior of the code.

## General AI Rules
- Before writing any code, read `PLAN.md` to understand the context.
- Keep responses concise. Output the updated code blocks directly.
- If a task requires modifying `PLAN.md`, do it in the same commit/response.

---

3. The Workflow: Putting It All Together

Now that you have both files at the root of your project, your workflow with Codex (or tools like Cursor / Cline / GitHub Copilot) becomes incredibly streamlined.

Step 1: The Bootstrapping Prompt

When you start a new session, your first prompt should be simple:

"Please read PLAN.md to understand our current progress, and read AGENTS.md to understand your coding guidelines. Assume the role of @BackendDev. Execute the next unfinished task in Phase 2."

Step 2: The Execution Loop

The AI will read the files, realize it needs to build the JWT token generation, and write the code adhering strictly to the type-hinting and error-handling rules defined in AGENTS.md.

Step 3: State Updating

Once the code is written and tested, you give the final command of the cycle:

"Great. Update PLAN.md to check off the JWT task, and briefly outline the technical approach for the /login endpoint next."

---

Conclusion

By externalizing your project state into PLAN.md and your system prompts into AGENTS.md, you transition from prompting an AI to managing an AI.

This method drastically reduces hallucinations, saves token context (because the AI isn't guessing the project structure), and allows you to pause and resume complex projects weeks later without missing a beat. Try adding these two files to your repository today, and watch your AI coding assistant become a true 10x engineering partner!