Using the AGENTS.md file

What is AGENTS.md?

Think of it this way: a README.md is written for human developers to understand a project. An AGENTS.md is written exclusively for AI assistants to understand how to write code for your project.

Place it at the root of your repository, and Codex automatically reads it at the start of every session.

Creating Your AGENTS.md

You can generate a starter file using the CLI:

codex init

Or create one manually. Here's a comprehensive example:

# AGENTS.md

## Project Overview
This is a full-stack e-commerce platform built with
Next.js 14 (App Router) and Go Fiber backend.

## Tech Stack
- Frontend: Next.js 14 with App Router (NOT Pages Router)
- Styling: TailwindCSS v4 with custom theme tokens
- Backend: Go Fiber v2
- Database: MySQL 8 with raw SQL (no ORM)
- Auth: JWT with httpOnly cookies

## Code Style Rules
- Use TypeScript strict mode for all frontend code
- Use functional components with hooks (no class components)
- Name files with kebab-case (e.g., user-profile.tsx)
- Use named exports, not default exports
- Import order: React → Third-party → Local modules → Styles

## Architecture Rules
- API routes go in app/api/[resource]/route.ts
- Shared components go in components/ui/
- Business logic goes in lib/ directory
- Never put business logic in components
- All database queries must use parameterized statements

## Testing Rules
- Write unit tests with Vitest in __tests__/ directories
- Use React Testing Library for component tests
- Minimum 80% coverage for new code
- Mock external APIs, never call them in tests

## What NOT to Do
- Do NOT use the Pages Router
- Do NOT use CSS Modules — use TailwindCSS only
- Do NOT install new dependencies without asking
- Do NOT use any deprecated React patterns (e.g., componentDidMount)

Key Sections to Include

🏗️ Framework Rules

Specify exactly which version of each framework you use and any specific configuration constraints. This prevents Codex from generating code with legacy syntax or wrong patterns.

🎨 Styling Rules

Define your styling approach clearly. Do you use TailwindCSS, CSS Modules, styled-components, or vanilla CSS? Include any custom theme tokens or design system conventions.

🧪 Testing Rules

Specify your test runner, file naming conventions, directory structure, and coverage requirements. This ensures generated tests actually fit into your CI pipeline.

🚫 Anti-Patterns

Explicitly list things the AI should never do. This is often the most valuable section — it prevents the most common mistakes.

Nested AGENTS.md Files

You can place additional AGENTS.md files in subdirectories for module-specific rules:

my-project/
├── AGENTS.md              # Global project rules
├── src/
│   ├── api/
│   │   └── AGENTS.md      # API-specific conventions
│   ├── components/
│   │   └── AGENTS.md      # Component patterns
│   └── database/
│       └── AGENTS.md      # SQL and migration rules

Codex reads all AGENTS.md files in the path hierarchy, with more specific files taking precedence.

Enforcing Consistency

By maintaining an up-to-date AGENTS.md, you ensure that:

• The AI stops hallucinating legacy syntax
• Generated code matches your team's current standards
• New team members (and AI agents) follow the same patterns
• Code reviews require fewer rounds of feedback

What's Next

In the next episode, we'll explore the Codex IDE Extension — ghost text predictions, inline chat, and sidebar communication right inside your editor.