Custom Instructions

Provide project-specific guidance and preferences to Codex

Overview

Custom instructions let you provide Codex with context, preferences, and guidelines that persist across sessions. This is especially useful for:

• Defining coding standards and style preferences
• Documenting project-specific conventions
• Providing context about architecture decisions
• Setting workflow preferences

Think of custom instructions as a persistent system prompt that Codex reads at the start of every session.

AGENTS.md Files

Custom instructions are defined in AGENTS.md files. Codex looks for these files in three locations and merges them in order:

1. Global Instructions

   ~/.codex/AGENTS.md - Personal preferences that apply to all projects

   Example use cases:

   • Your preferred coding style
   • Tools you always want to use
   • Communication preferences
2. Repository Instructions

   AGENTS.md at repo root - Team-wide project guidance

   Example use cases:

   • Project architecture overview
   • Team coding standards
   • Important constraints or requirements

   Commit this file to version control so all team members share the same context.

3. Directory Instructions

   AGENTS.md in current working directory - Subsystem-specific notes

   Example use cases:

   • Feature-specific guidelines
   • Module architecture notes
   • Local development setup

File Format

AGENTS.md files use standard Markdown format. Codex treats all content as guidance:

AGENTS.md

# Project Guidelines

## Code Style

- Use TypeScript for all new files
- Prefer functional components with hooks
- Always include JSDoc comments for exported functions

## Architecture

This project uses a feature-based folder structure:

src/ features/ auth/ dashboard/ settings/

## Testing

- Write tests for all business logic
- Use Vitest for unit tests
- Place test files adjacent to source: `component.tsx` → `component.test.tsx`

## Important

Do NOT modify files in the `generated/` directory - they are auto-generated.

Example Configurations

Personal Preferences

~/.codex/AGENTS.md

# My Coding Preferences

- I prefer verbose variable names over abbreviations
- Always use `const` over `let` when possible
- Add comments explaining the "why", not the "what"
- Run prettier after making changes
- Use conventional commits format: `type(scope): description`

# Tools

- Prefer `pnpm` over npm or yarn
- Use `just` for task running instead of npm scripts

Team Standards

AGENTS.md (repo root)

# Acme Corp - Frontend Guidelines

## Tech Stack

- React 18 + TypeScript
- Vite for builds
- TanStack Query for data fetching
- Radix UI for components
- Tailwind CSS for styling

## Code Standards

- Follow the Airbnb TypeScript style guide
- Maximum line length: 100 characters
- Use named exports (no default exports)

## State Management

- Use React hooks for local state
- Use TanStack Query for server state
- Use Zustand for global client state (sparingly)

## API Integration

- All API calls go through `src/api/` modules
- Use OpenAPI types from `src/api/generated/`
- Handle errors with the `useErrorHandler` hook

## Security

- Never commit API keys or secrets
- All user input must be sanitized
- Use environment variables for configuration

## Before Committing

1. Run `pnpm typecheck`
2. Run `pnpm test`
3. Run `pnpm lint:fix`

Feature-Specific

src/features/auth/AGENTS.md

# Authentication Module

## Overview

This module handles user authentication using OAuth 2.0 + PKCE.

## Architecture

- `AuthProvider.tsx` - Context provider for auth state
- `useAuth.ts` - Hook for accessing auth context
- `oauth.ts` - OAuth flow implementation
- `tokens.ts` - Token storage and refresh logic

## Important Notes

- Tokens are stored in httpOnly cookies (not localStorage)
- Token refresh happens automatically 5 minutes before expiry
- All auth routes require HTTPS in production

## Testing Auth

Use the mock auth provider in tests:

```tsx
import { MockAuthProvider } from './test-utils';

<MockAuthProvider user={testUser}>
  <YourComponent />
</MockAuthProvider>

Related

• API integration: src/api/auth.ts
• Backend docs: docs/auth-api.md

## Common Use Cases

<AccordionGroup>
  <Accordion title="Enforce coding style">
    Example AGENTS.md showing code style preferences:
    
    - Use single quotes for strings
    - Include trailing commas in multiline arrays/objects
    - Prefer arrow functions over function declarations
    - Use template literals instead of string concatenation
    
    Keep your style preferences documented so Codex follows them consistently.
  </Accordion>
  
  <Accordion title="Document architecture decisions">
    Use AGENTS.md to document key architectural decisions for your project, such as:
    
    - Monorepo structure and workspace organization
    - Data flow patterns (e.g., unidirectional data flow)
    - Module boundaries and dependencies
    - Coding patterns that should be followed
    
    This helps Codex understand and maintain your architecture.
  </Accordion>
  
  <Accordion title="Define project constraints">
    Document technical constraints in AGENTS.md:
    
    - Browser support requirements
    - Bundle size limits
    - Performance targets (FCP, TTI, Lighthouse scores)
    - Dependency management policies
    - Security and compliance requirements
    
    Clear constraints help Codex make appropriate trade-offs.
  </Accordion>
  
  <Accordion title="Workflow preferences">
    Document team workflows in AGENTS.md:
    
    - Git workflow (branching strategy, commit conventions)
    - Code review requirements
    - Development commands and scripts
    - Testing practices
    - Deployment procedures
    
    Consistent workflows improve code quality and team productivity.
  </Accordion>
  
  <Accordion title="Communication style">
    Set communication preferences in AGENTS.md:
    
    - Explanation depth (concise vs thorough)
    - When to ask clarifying questions
    - How to handle ambiguous requirements
    - Code example preferences
    - Technical writing style
    
    This helps Codex communicate in the style you prefer.
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Be Specific" icon="crosshairs">
    Provide concrete examples and explicit rules rather than vague guidelines
  </Card>
  
  <Card title="Keep It Updated" icon="rotate">
    Review and update instructions as your project evolves
  </Card>
  
  <Card title="Focus on Context" icon="brain">
    Include information Codex can't infer from code alone
  </Card>
  
  <Card title="Use Structure" icon="list">
    Organize with headers and lists for easy scanning
  </Card>
</CardGroup>

### What to Include

<Check>**DO** include:</Check>

- Coding standards and conventions
- Architecture principles
- Project-specific constraints
- Workflow preferences
- Important context about design decisions
- Links to relevant documentation

<Warning>**AVOID** including:</Warning>

- Information that's obvious from the code
- Detailed API documentation (use inline comments instead)
- Temporary notes (use regular comments or TODOs)
- Secrets or sensitive information

## Disabling Project Docs

You can disable loading of AGENTS.md files:

### Command-Line Flag

```bash
codex --no-project-doc

Environment Variable

export CODEX_DISABLE_PROJECT_DOC=1
codex

This only disables project-specific AGENTS.md files. Your personal ~/.codex/AGENTS.md is still loaded.

Advanced Examples

Multi-Language Project

# Polyglot Project Guidelines

## Backend (Rust)

- Follow the Rust API guidelines
- Use `cargo fmt` and `cargo clippy`
- Write doc comments with examples
- Place unit tests in the same file using `#[cfg(test)]`

## Frontend (TypeScript)

- Use strict TypeScript mode
- No `any` types without explicit justification
- Prefer type inference over explicit types when obvious

## Database (PostgreSQL)

- All schema changes go through migrations
- Use snake_case for column names
- Always add indexes for foreign keys
- Include `created_at` and `updated_at` timestamps

## API Contracts

- Use OpenAPI 3.0 specification
- Version APIs with `/v1/`, `/v2/` prefixes
- Never remove fields from existing endpoints (deprecate instead)

Microservices Architecture

# Microservices Guidelines

## Service Boundaries

- auth-service: Authentication and authorization
- user-service: User profiles and preferences
- payment-service: Payment processing and billing
- notification-service: Email, SMS, push notifications

## Inter-Service Communication

- Use gRPC for synchronous calls
- Use message queue (RabbitMQ) for async events
- Never make database calls across services
- Each service owns its data exclusively

## Observability

- Instrument all endpoints with OpenTelemetry
- Log structured JSON with trace IDs
- Set up alerts for error rate > 1%
- Dashboard: https://grafana.internal/services

## Deployment

- Services run in Kubernetes
- Use Helm charts in `k8s/charts/`
- Staging: `kubectl config use-context staging`
- Production: Requires approval + deploy script

Troubleshooting

Instructions not being applied

1. Verify file location: ls -la AGENTS.md
2. Check file is valid Markdown
3. Ensure CODEX_DISABLE_PROJECT_DOC is not set
4. Try codex --no-project-doc to confirm it’s the AGENTS.md causing issues

Too much conflicting guidance

• Simplify global ~/.codex/AGENTS.md to only personal preferences
• Keep repo-level AGENTS.md focused on critical standards
• Use directory-level files sparingly for truly module-specific notes

Codex ignoring specific instructions

• Be more explicit and specific in your wording
• Provide examples that illustrate the rule
• Move critical rules to the top of the file
• Consider if the instruction conflicts with model knowledge

Real-World Examples

Open Source Project

# Contributing to XYZ

## Development Setup
1. Fork and clone the repository
2. Install dependencies: npm install
3. Run tests: npm test
4. Start dev server: npm run dev

## Commit Guidelines
Follow conventional commits:
- feat: New features
- fix: Bug fixes
- docs: Documentation changes
- refactor: Code restructuring
- test: Test changes

## Pull Request Process
1. Update README.md with any new functionality
2. Add tests for new features
3. Ensure CI passes
4. Request review from maintainers

## Code of Conduct
Be respectful and inclusive. See CODE_OF_CONDUCT.md.

Enterprise Application

# Enterprise CRM - Development Guide

## Security Requirements
- All data must be encrypted at rest
- Use parameterized queries (never string concatenation)
- Validate all user input server-side
- Audit logs for all data modifications

## Compliance
- GDPR: Users can export/delete their data
- SOC 2: All changes must be tracked
- HIPAA: PHI must be specially marked

## Performance SLAs
- API response time less than 200ms (p95)
- Page load time less than 2s
- 99.9% uptime requirement

## Deployment
- Staging deploys: Automatic on merge to develop
- Production deploys: Manual approval required
- Rollback plan must be documented

Startup MVP

# Startup MVP Guidelines

## Move Fast
- Prioritize shipping over perfection
- Technical debt is okay if documented
- Use managed services (less infra to maintain)

## Core Principles
- Simple is better than Complex
- Boring technology unless necessary
- Monolith first, split later if needed

## Stack
- Next.js (full-stack)
- Postgres (via Supabase)
- Vercel (hosting)
- Stripe (payments)

## Iteration Speed
- Deploy to staging: On every commit
- Deploy to production: Multiple times per day
- Feature flags: For incomplete features

See Also

Configuration

Global Codex configuration options

Exec Policies

Control command execution

Memory System

How Codex remembers context

Best Practices

Tips for using Codex effectively