How to Prepare Your Repository for Codex
OpenAI Codex needs structured repository context to produce reliable code changes. Here is how to prepare your repository so Codex understands your codebase, follows conventions, and hands back reviewable output.
How to Prepare Your Repository for Codex
OpenAI Codex is the model family powering GitHub Copilot and the Copilot API. It reads code, understands context, and generates changes — but like all coding agents, it works best when the repository tells it what it needs to know.
This post shows how to prepare a repository so Codex produces reliable, reviewable output instead of plausible but wrong code.
What Codex reads at startup
When Codex enters a repository — via Copilot, the API, or a CLI tool built on top of it — it reads the files in scope for the current task. It does not have a fixed startup sequence the way Claude Code does with AGENTS.md, but it does benefit from the same structural context:
- Explicit project instructions in files like
AGENTS.mdgive Codex durable operating context that survives across sessions. - Architecture notes help Codex understand which files matter and which boundaries should not be crossed.
- Validation commands let Codex know exactly which checks prove a change is correct before handing it back.
Without these, Codex works primarily from what it can infer from the surrounding code and the current task prompt — which means it often guesses wrong on non-trivial changes.
The minimum viable setup
You do not need a full harness to get better results from Codex. Start with this:
1. Add AGENTS.md
AGENTS.md at the root is the single highest-impact change you can make for any coding agent, including Codex. It should answer:
- What this project does — one or two sentences
- Where to start reading — key entry points and important files
- What not to touch — safety boundaries, irreversible changes
- How to validate — exact commands for each change type
Example:
# Project: Order management API
Node.js + Fastify REST API. Handles order creation, fulfillment, and
status tracking. PostgreSQL via Prisma ORM.
# Key files
- `src/index.ts` — server entry point
- `src/routes/` — all HTTP handlers
- `src/services/` — business logic
- `prisma/schema.prisma` — database schema
# Do not touch
- `src/auth/` — shared with another team, get approval first
- `prisma/migrations/` — never modify directly
# Validation
All changes must pass before handing back:
- `npm test`
- `npm run lint`
- `npm run build`2. Document the validation matrix
Codex can run commands, but it needs to know which commands apply to which change type. A simple table in AGENTS.md makes this explicit:
| Change type | Required checks |
|---|---|
| Frontend component | npm test -- --testPathPattern=components && npm run build |
| API route | npm test && npm run typecheck && npm run build |
| Database migration | npx prisma migrate validate then ask a human |
| Config or docs | npm run lint |
3. Add architecture notes for non-trivial projects
If the project has non-obvious structure, a short architecture note helps Codex avoid destructive changes:
# Architecture
- Express API on port 3000
- PostgreSQL via Prisma ORM
- Auth via JWT — tokens expire after 24h
- Background jobs via BullMQ — Redis on port 6379
- Frontend is a separate repo — do not serve static files hereBeyond the minimum: full harness
For teams working on shared or high-stakes codebases, the full harness adds:
Decision records
Decision records document why the codebase is the way it is. They prevent Codex from reopening settled questions or undoing deliberate choices.
# Decision: Chose PostgreSQL over MongoDB for orders
**Date:** 2024-11-03
**Status:** accepted
**Why:** Financial transactions require ACID compliance. MongoDB's eventual
consistency creates edge cases we cannot afford for order state.
**What would reopen this:** A demonstrated inability of the team to work
with PostgreSQL at scale, or a specific technical requirement that
MongoDB solves and PostgreSQL cannot.Story packets
A story packet replaces a vague task description with a structured unit of work:
## Story packet
**What to build:** [one sentence]
**Where to work:** [specific files]
**Acceptance criteria:** [checklist]
**Validation commands:** [exact commands]
**What not to touch:** [safety boundaries]When Codex receives a story packet instead of a free-form prompt, the output is more bounded and more reviewable.
Common mistakes
No explicit validation commands
“Run tests” is not a validation command. “Run npm test for unit tests and npm run integration-tests for API behavior” is. Be specific — Codex will run whatever you tell it to run, so make sure what you tell it actually proves correctness.
Missing safety boundaries
The most common Codex failure: it modifies a shared utility, an auth layer, or a migration file that other things depend on. Be explicit about what not to touch. One line in AGENTS.md prevents emergency rollbacks.
Including too much in AGENTS.md
If AGENTS.md is more than one screen of text, it loses coherence. Keep the top-level instructions concise. Move detailed architecture docs and decision records into linked files so agents can find them but are not forced to read everything upfront.
No feedback loop
If Codex keeps making the same mistake, the repo context should improve. Update AGENTS.md. Add a decision record. The harness grows from real failure cases, not from templates applied in advance.
Quick checklist
Before your next Codex session:
-
AGENTS.mdexists at the root -
AGENTS.mdsays what the project does in one sentence -
AGENTS.mdlists key files and directories -
AGENTS.mdspecifies what not to touch -
AGENTS.mdhas exact validation commands for each change type - Architecture context is documented if the project is non-trivial
- Decision records exist for non-obvious choices
That is the minimum viable setup. Run a session and watch where Codex needs to guess — those gaps are where you add context.
How this differs from preparing for Claude Code
Both Claude Code and Codex benefit from the same repository-level context. The difference is in tool behavior:
| Claude Code | Codex (GitHub Copilot) | |
|---|---|---|
| Reads AGENTS.md | Yes — at every invocation | Yes — as part of project context |
| Runs validation commands | Yes — built-in | Yes — via natural language or explicit prompts |
| Supports story packets | Yes — native format | Yes — via structured task prompts |
| Tool-specific quirks | Reads .claude/commands.md | Best via explicit AGENTS.md validation matrix |
The core principle is the same: make the repository legible so agents do not have to guess. The exact file placement and command format may differ slightly by tool, but AGENTS.md at the root works for both.
Related pages
- What Is an Agent-Ready Repository? — foundational concept
- Context Engineering for Coding Agents — the parent framework
- How to Write an AGENTS.md That Actually Works — practical guide
- AGENTS.md Template — copy and adapt for your project
See also
- How to Prepare Your Repository for Claude Code — the parallel guide for Claude Code users
- AGENTS.md vs Cursor Rules — choosing the right context file approach
repository-harnesson GitHub — the open-source implementation
FAQ
Does OpenAI Codex read AGENTS.md?
Codex-based tools (GitHub Copilot, the Copilot API, the Codex CLI) read the repository context for the current task, and many follow the AGENTS.md convention. Unlike Claude Code, there is no single fixed startup sequence — the contract is whatever the tool that wraps Codex decides to honor. Adding AGENTS.md at the root is the safest bet for broad coverage.
What is the most important file to add for Codex reliability?
A clear README.md plus AGENTS.md at the root. The README explains how to install, build, and run, which Codex needs to know to make correct changes. AGENTS.md adds operating constraints, validation rules, and safety boundaries. Together they form the minimum context that gets Codex out of “plausible but wrong” territory.
How is Codex different from Claude Code for repository setup?
Claude Code has a fixed startup sequence that always reads AGENTS.md and a known set of supporting files. Codex is the model — the repository setup that matters depends on the tool wrapping it (Copilot, the API, a custom CLI). The repository itself should be opinionated and tool-agnostic. Durable rules go in AGENTS.md; tool-specific commands live in the tool’s own config.
Does Codex run validation commands automatically?
Only if the surrounding tool runs them. Codex itself generates code; whether the code is tested depends on the wrapper. To get reliable output, encode the exact validation command(s) in AGENTS.md and reference them in the task prompt or story packet. Without that, validation is up to chance.
How do I keep Codex from making risky changes?
Add a “Do not do without asking first” section to AGENTS.md listing the risky areas: migrations, authentication, billing, secrets, destructive operations. Codex reads this as part of the task context and uses it to scope what it touches. For high-stakes changes, use a story packet so the model proposes a plan before editing code.
Should I use a different AGENTS.md for Codex and Claude Code?
No. One AGENTS.md at the root works for both. Tool-specific commands go in tool-specific config files (.claude/commands.md for Claude Code, Codex’s own config for Codex). The shared rules — what the project does, what proves a change is correct, what not to touch — should live in exactly one place so the two tools never disagree on the operating contract.
Can Codex work on a greenfield project with no AGENTS.md?
Yes, and on small greenfield projects the absence of AGENTS.md hurts less because the model can read the entire codebase quickly. The cost shows up as the project grows: more files, more conventions, more ways to break things. Add AGENTS.md early — it is much easier to write when there are few enough decisions to capture.