> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/openai/codex/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

## AGENTS.md Files

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

<Steps>
  <Step title="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
  </Step>

  <Step title="Repository Instructions">
    `AGENTS.md` at repo root - Team-wide project guidance

    Example use cases:

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

    <Info>
      Commit this file to version control so all team members share the same context.
    </Info>
  </Step>

  <Step title="Directory Instructions">
    `AGENTS.md` in current working directory - Subsystem-specific notes

    Example use cases:

    * Feature-specific guidelines
    * Module architecture notes
    * Local development setup
  </Step>
</Steps>

## File Format

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

```markdown AGENTS.md theme={null}
# 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

```markdown ~/.codex/AGENTS.md theme={null}
# 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

```markdown AGENTS.md (repo root) theme={null}
# 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

````markdown src/features/auth/AGENTS.md theme={null}
# 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

```bash theme={null}
export CODEX_DISABLE_PROJECT_DOC=1
codex
```

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

## Advanced Examples

### Multi-Language Project

```markdown theme={null}
# 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

```markdown theme={null}
# 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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Real-World Examples

<Tabs>
  <Tab title="Open Source Project">
    ```text theme={null}
    # 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.
    ```
  </Tab>

  <Tab title="Enterprise Application">
    ```text theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Startup MVP">
    ```text theme={null}
    # 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
    ```
  </Tab>
</Tabs>

## See Also

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Global Codex configuration options
  </Card>

  <Card title="Exec Policies" icon="shield-check" href="/advanced/exec-policies">
    Control command execution
  </Card>

  <Card title="Memory System" icon="database" href="/features/memory">
    How Codex remembers context
  </Card>

  <Card title="Best Practices" icon="star" href="/guides/best-practices">
    Tips for using Codex effectively
  </Card>
</CardGroup>