Step 1: Create AGENTS.md
Add an AGENTS.md file to the root of your repository with setup, test, and convention instructions
Step 2: Codex reads the file
When a task starts, Codex reads AGENTS.md first and uses it to configure the environment
Step 3: Setup commands run
The setup commands you specified are executed to prepare the container with correct dependencies
Step 4: Conventions guide coding
Your coding conventions and guidelines inform how Codex writes and structures its changes
Step 5: Tests verify results
After making changes, Codex runs the test commands you specified to verify everything works
Example AGENTS.md file
A well structured AGENTS.md covers the essentials Codex needs to work with your project:
# My Project
## Setup
npm install
npm run build
## Tests
npm test
## Lint
npm run lint
## Conventions
- Use TypeScript strict mode
- All components go in src/components/
- Use functional components with hooks
- API calls go through src/lib/api/
- Use Tailwind for styling, no CSS modules
## Do Not Modify
- src/generated/ (auto-generated files)
- migrations/ (use the migration tool instead)
## Notes
- The app uses Supabase for the database
- Auth is handled by NextAuth.js
- All environment variables are listed in .env.exampleStart simple, then expand
You do not need a comprehensive AGENTS.md on day one. Start with just your setup and test commands. Codex will work reasonably well with just those. As you notice patterns where Codex makes choices you disagree with, add conventions to address them. Over time, your AGENTS.md will naturally grow into a complete project guide.