Rules

Reference intermediate

Codex CLI Configuration Rules

What Is AGENTS.md?

AGENTS.md is the configuration file for Codex CLI. Placed at the project root, it provides persistent instructions that shape how Codex interprets your requests and generates code.

AGENTS.md Structure Template

# Project Overview
[Brief description of what this project does]

# Tech Stack
[Exact versions and key dependencies]

# Code Conventions
[Naming, formatting, patterns]

# File Structure
[Where things live]

# Testing
[How to run tests, what framework, coverage expectations]

# Build & Run
[Commands to build, run, and deploy]

# Constraints
[What NOT to do]

The 8 Rules for Codex Configuration

Rule 1: Define the Sandbox Environment

Codex runs in an isolated sandbox. Specify what it needs:

# Environment
- Node.js 20 with npm
- Python 3.11 with pip
- PostgreSQL client (no server - use mock)
- Environment variables: see .env.example

Rule 2: Specify Verification Commands

Tell Codex how to verify its own work:

# Verification
- Lint: npm run lint
- Type check: npx tsc --noEmit
- Unit tests: npm test
- Integration tests: npm run test:integration
- Build: npm run build

Rule 3: Set Autonomy Boundaries

Be explicit about what Codex can and cannot do:

Allow	Disallow
Create new files in `src/`	Modify configuration files
Install dev dependencies	Install production dependencies
Run tests	Run database migrations
Modify test files	Delete existing source files
Create branches	Push to remote

Rule 4: Include Build Context

# Build System
- Package manager: pnpm (NOT npm or yarn)
- Build command: pnpm build
- Output directory: dist/
- Module system: ESM (type: "module" in package.json)
- Target: ES2022

Rule 5: Define Code Quality Standards

# Quality Standards
- All functions must have TypeScript types (no `any`)
- All public functions must have JSDoc comments
- Maximum function length: 30 lines
- Maximum file length: 200 lines
- Test coverage minimum: 80%
- No console.log in production code (use logger)

Rule 6: Provide Error Handling Patterns

# Error Handling
- Use custom error classes extending BaseError
- Always include error codes for API responses
- Log errors with structured format: { code, message, context }
- Never expose stack traces to clients
- Wrap external API calls in try/catch with specific error types

Rule 7: Document API Patterns

# API Conventions
- RESTful routes: /api/v1/[resource]
- Response format: { data, meta, errors }
- Pagination: cursor-based with ?cursor=&limit=
- Auth: Bearer token in Authorization header
- Rate limiting: 100 req/min per user

Rule 8: Keep Instructions Actionable

Bad (Vague)	Good (Actionable)
"Write good tests"	"Each test file must have: happy path, error case, edge case"
"Follow patterns"	"Use repository pattern: interface in types/, implementation in lib/"
"Be secure"	"Validate all inputs with Zod schemas before processing"

Approval Policies

Policy	Flag	Behavior	Use Case
Untrusted	(default)	Shows plan, asks approval for all changes	Learning, cautious changes
On-request	`--approval-policy on-request`	Auto-applies file edits, asks for shell commands	Standard development
Never	`--approval-policy never`	Everything automatic, no prompts	Automation, CI/CD

Safety Configuration

# Safety Rules
- Never modify: .env, .env.*, secrets/, credentials/
- Never delete: database migrations, user data files
- Always backup: config files before modification
- Always run: linter after every code change
- Require approval: dependency additions, config changes

Multi-Agent Patterns

For monorepos, place AGENTS.md at multiple levels:

repo-root/
  AGENTS.md              # Shared rules (conventions, tools)
  packages/
    frontend/
      AGENTS.md          # Frontend-specific rules
    backend/
      AGENTS.md          # Backend-specific rules
    shared/
      AGENTS.md          # Shared library rules

Lower-level files inherit from and can override parent rules.