Configuration Reference

Every AI coding tool uses a configuration file to understand your project. Get it wrong and the tool ignores your coding standards, generates the wrong test framework, or uses the wrong import style on every single request. This reference shows you exactly how to configure each tool, with complete examples you can copy into your project today.

What You Will Walk Away With

Complete configuration file syntax for Cursor, Claude Code, and Codex
A starter template for each tool you can paste into any project
Feature mapping between configuration systems
Advanced patterns for monorepos, multi-language projects, and team setups

Configuration Systems at a Glance

Aspect	Cursor	Claude Code	Codex
Primary file	`.cursor/rules/*.mdc`	`CLAUDE.md`	`AGENTS.md`
Secondary config	`.cursorrules` (legacy)	`.claude/settings.json`	`~/.codex/config.toml`
Format	MDC (Markdown + frontmatter)	Markdown	Markdown + TOML
Scope	Per-project, per-directory	Per-project, per-user, per-directory	Per-project, per-user
Auto-discovered	Yes (`.cursor/rules/`)	Yes (`CLAUDE.md` in project root)	Yes (`AGENTS.md` in project root)
Glob targeting	Yes (frontmatter `globs`)	Via directory placement	No
Version controlled	Yes	Yes	Yes (`AGENTS.md`), No (`config.toml`)

Cursor: `.cursor/rules/`

Directory Structure

.cursor/
  rules/
    project.mdc          # Global project rules (always active)
    typescript.mdc       # Active only for .ts/.tsx files
    testing.mdc          # Active only for test files
    api-routes.mdc       # Active only for API route files
    react-components.mdc # Active for React component files

Rule File Format (MDC)

Each .mdc file uses frontmatter to control when the rule activates:

---
description: "TypeScript coding standards for the project"
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

## TypeScript Standards

- Use strict mode. Never use `any` -- use `unknown` with type guards instead.
- Prefer interfaces for object shapes, type aliases for unions and intersections.
- All exported functions must have explicit return types.
- Use single quotes for imports and strings.
- Organize imports: external deps, then internal absolute imports (`~/`), then relative imports, then type imports.

## Error Handling

- Never swallow errors silently. Always log or rethrow.
- Use custom error classes that extend `Error` for domain errors.
- API routes must return structured error responses with status codes.

## Naming Conventions

- Files: kebab-case (`user-auth.ts`)
- Components: PascalCase (`UserAuth.tsx`)
- Functions: camelCase (`getUserById`)
- Constants: UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`)
- Types/Interfaces: PascalCase with descriptive names (`UserAuthResponse`)

Frontmatter Fields

Field	Type	Description
`description`	string	What this rule does (shown in the UI and used for auto-selection)
`globs`	string[]	File patterns that activate this rule (e.g., `["*/.ts"]`)
`alwaysApply`	boolean	If `true`, rule is active for every request regardless of file context

Rule Types

Type	`alwaysApply`	`globs`	Behavior
Always active	`true`	—	Included in every request
Auto-attached	`false`	Set	Activated when working with matching files
Agent-selected	`false`	—	Agent reads the description and decides whether to include it

Complete Starter Template

---
description: "Core project rules -- always active"
alwaysApply: true
---

## Project: [Your Project Name]

Tech stack: Next.js 15 (App Router), TypeScript 5, Tailwind CSS, Drizzle ORM, PostgreSQL.

## Coding Standards

- TypeScript strict mode, no `any` types
- Functional components with hooks, no class components
- Server Components by default, "use client" only when needed
- All API routes return typed JSON responses
- Tests with Vitest, integration tests with Playwright

## File Organization

- `src/app/` -- Next.js App Router pages and layouts
- `src/components/` -- Reusable React components
- `src/lib/` -- Shared utilities, database queries, type definitions
- `src/server/` -- Server-only code (API handlers, background jobs)

## Common Commands

- Build: `npm run build`
- Test: `npm run test`
- Lint: `npm run lint`
- Dev: `npm run dev`
- Database migrate: `npm run db:migrate`

## Rules

- ALWAYS run tests after making changes to core business logic
- NEVER commit code that fails type checking
- ALWAYS use parameterized queries for database operations
- NEVER expose internal error details in API responses

Advanced: File-Scoped Rules

---
description: "API route conventions for Next.js App Router"
globs: ["src/app/api/**/*.ts"]
---

## API Route Pattern

Every API route must:
1. Validate input with zod schemas
2. Return typed responses using the ApiResponse<T> generic
3. Handle errors with the withErrorHandler wrapper
4. Log request metadata for observability

Example structure:
- Parse request body/params with zod
- Call service layer (never query DB directly in routes)
- Return { success: true, data } or { success: false, error }

Legacy: `.cursorrules`

The .cursorrules file in the project root is the older single-file format. It still works but the directory-based system is preferred for new projects. If both exist, .cursor/rules/ takes precedence.

Claude Code: `CLAUDE.md`

File Locations

Location	Scope	Discovery
`./CLAUDE.md`	Project root (main config)	Auto-loaded when Claude starts in this directory
`./src/CLAUDE.md`	Subdirectory-specific	Loaded when Claude reads files in `src/`
`~/.claude/CLAUDE.md`	User-level (all projects)	Always loaded, applies globally

Claude Code reads all CLAUDE.md files from the project root up through subdirectories. Subdirectory files add context for that part of the codebase. User-level files set personal preferences that apply everywhere.

File Format

Plain Markdown. No frontmatter required. Claude reads it as natural language instructions.

## Project Overview

This is a SaaS billing platform built with Express.js and TypeScript.
The API serves a React frontend and handles Stripe subscription management.

## Architecture

- `src/api/` -- Express route handlers (REST API)
- `src/services/` -- Business logic layer
- `src/models/` -- Drizzle ORM schema and queries
- `src/jobs/` -- Background job processors (Bull queue)
- `src/middleware/` -- Auth, rate limiting, error handling
- `tests/` -- Vitest unit tests and Supertest integration tests

## Coding Standards

- TypeScript strict mode, explicit return types on exported functions
- Use `Result<T, E>` pattern for error handling (no throwing in services)
- All database queries go through the repository pattern in `src/models/`
- API responses follow the shape: `{ ok: boolean, data?: T, error?: string }`

## Common Commands

- Build: `npm run build`
- Test: `npm test` (runs Vitest)
- Test single file: `npm test -- src/services/billing.test.ts`
- Lint: `npm run lint`
- Dev server: `npm run dev` (port 3000)
- Database migrate: `npm run db:migrate`
- Database seed: `npm run db:seed`
- Type check: `npx tsc --noEmit`

## Testing Patterns

- Unit tests go next to the source file: `billing.ts` -> `billing.test.ts`
- Integration tests for API routes go in `tests/integration/`
- Use `createTestContext()` from `tests/helpers.ts` for database fixtures
- Mock external services (Stripe, email) using `vi.mock()`

## Important Notes

- NEVER import from `src/api/` inside `src/services/` (dependency flows downward)
- ALWAYS run `npm test` before suggesting a task is complete
- The `STRIPE_SECRET_KEY` env var must be set for billing tests
- Rate limiting middleware is applied globally -- do not add it per-route

Subdirectory CLAUDE.md

Place additional CLAUDE.md files in subdirectories for context-specific instructions:

## Service Layer Rules

All services in this directory:
- Accept typed input parameters (no raw request objects)
- Return `Result<T, ServiceError>` -- never throw exceptions
- Are stateless -- no instance variables or module-level state
- Have corresponding test files in the same directory

## Dependencies

Services can import from:
- `src/models/` (database access)
- `src/lib/` (shared utilities)
- Other services (but watch for circular dependencies)

Services must NOT import from:
- `src/api/` (routes)
- `src/middleware/`
- `src/jobs/` (use event emitters instead)

Claude Settings: `.claude/settings.json`

This file controls permissions and behavior, not project context:

{
  "permissions": {
    "allow": [
      "Bash(npm run test*)",
      "Bash(npm run lint*)",
      "Bash(npm run build)",
      "Bash(npx tsc --noEmit)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push*)",
      "Bash(npm publish*)",
      "Bash(curl*)",
      "Bash(wget*)"
    ]
  }
}

`.claude/commands/` Custom Slash Commands

Create reusable workflows as markdown files:

---
allowed-tools: [Read, Edit, Bash]
description: Fix a GitHub issue end to end
argument-hint: issue-number
---

Fix GitHub issue #$ARGUMENTS:

1. Run: !gh issue view $ARGUMENTS --json title,body,labels
2. Understand the problem described
3. Find the relevant code
4. Implement the fix
5. Write or update tests
6. Run: !npm test
7. Create a descriptive commit message

Each file becomes a slash command named after the file. For example, .claude/commands/fix-issue.md becomes /fix-issue 42.

Codex: `AGENTS.md` and `config.toml`

AGENTS.md

The project-level configuration. Placed in the repository root. Format is plain Markdown, similar to CLAUDE.md.

## Project

SaaS billing platform. Express.js + TypeScript backend, React frontend.
Stripe integration for subscriptions. PostgreSQL via Drizzle ORM.

## Architecture

- `src/api/` -- REST route handlers
- `src/services/` -- Business logic
- `src/models/` -- Database schema and queries
- `src/jobs/` -- Background processors
- `tests/` -- Test suites

## Standards

- TypeScript strict mode
- Functional patterns preferred over classes
- Result type for error handling in services
- All DB access through repository pattern
- API responses: `{ ok: boolean, data?, error? }`

## Commands

- Test: `npm test`
- Build: `npm run build`
- Lint: `npm run lint`
- Dev: `npm run dev`
- Migrate: `npm run db:migrate`

## Rules

- ALWAYS run tests before marking work complete
- NEVER modify migration files that have already been applied
- ALWAYS use parameterized queries
- NEVER expose stack traces in API responses
- ALWAYS validate input with zod schemas at API boundaries

Subdirectory AGENTS.md

Like Claude Code, Codex supports AGENTS.md files in subdirectories for context-specific instructions:

## API Route Conventions

Routes in this directory:
- Use Express Router pattern
- Validate all inputs with zod
- Call service layer for business logic
- Return consistent response shapes
- Include OpenAPI JSDoc annotations

config.toml (CLI Configuration)

Located at ~/.codex/config.toml. Controls CLI behavior, not project context.

# Default AI model
model = "gpt-5.3-codex"

# Default approval policy: untrusted | on-failure | on-request | never
approval_policy = "on-failure"

# Default provider
model_provider = "openai"

# History and session settings
[history]
persistence = "save-all"
max_bytes = 10485760

# Sandbox configuration
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

# Custom providers (for non-default API endpoints)
[model_providers.custom]
name = "My Custom Provider"
base_url = "https://api.example.com/v1"
env_key = "CUSTOM_API_KEY"

Codex Automations Configuration

Codex supports GitHub, Slack, and Linear automations configured through the Codex App (web interface). These are not file-based but worth understanding alongside the configuration files.

Automation	Trigger	Configuration
GitHub Issues	Assign to `@codex`	Codex App > Settings > Automations
Slack	Message in configured channel	Codex App > Settings > Slack
Linear	Assign to Codex agent	Codex App > Settings > Linear

Side-by-Side Comparison

Telling the AI About Your Project

---
description: "Project overview"
alwaysApply: true
---

## Project
SaaS billing platform.
Express + TypeScript + PostgreSQL.

## Stack
- Express.js with TypeScript
- Drizzle ORM + PostgreSQL
- Vitest for testing
- Stripe for billing

File: .cursor/rules/project.mdc

## Project Overview
SaaS billing platform.
Express + TypeScript + PostgreSQL.

## Architecture
- Express.js with TypeScript
- Drizzle ORM + PostgreSQL
- Vitest for testing
- Stripe for billing

File: CLAUDE.md (project root)

## Project
SaaS billing platform.
Express + TypeScript + PostgreSQL.

## Standards
- Express.js with TypeScript
- Drizzle ORM + PostgreSQL
- Vitest for testing
- Stripe for billing

File: AGENTS.md (project root)

Defining Coding Standards

---
description: "TypeScript coding standards"
globs: ["**/*.ts", "**/*.tsx"]
---

- Use strict TypeScript, no `any`
- Prefer interfaces over type aliases for objects
- Explicit return types on exported functions
- Single quotes, no semicolons

File: .cursor/rules/typescript.mdc

## Coding Standards

- Use strict TypeScript, no `any`
- Prefer interfaces over type aliases for objects
- Explicit return types on exported functions
- Single quotes, no semicolons

Section in CLAUDE.md

## Standards

- Use strict TypeScript, no `any`
- Prefer interfaces over type aliases for objects
- Explicit return types on exported functions
- Single quotes, no semicolons

Section in AGENTS.md

Specifying Build and Test Commands

---
description: "Build and test commands"
alwaysApply: true
---

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Dev: `npm run dev`

File: .cursor/rules/commands.mdc

## Common Commands

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Dev: `npm run dev`

Section in CLAUDE.md

## Commands

- Test: `npm test`
- Build: `npm run build`
- Lint: `npm run lint`
- Dev: `npm run dev`

Section in AGENTS.md

Setting Guardrails (Do / Do Not)

---
description: "Project guardrails"
alwaysApply: true
---

## Always
- Run tests after changing business logic
- Use parameterized queries for all DB operations
- Validate inputs at API boundaries

## Never
- Import from `src/api/` inside `src/services/`
- Commit code that fails type checking
- Expose internal errors to API consumers

File: .cursor/rules/guardrails.mdc

## Important Notes

- ALWAYS run tests after changing business logic
- ALWAYS use parameterized queries for all DB operations
- ALWAYS validate inputs at API boundaries
- NEVER import from `src/api/` inside `src/services/`
- NEVER commit code that fails type checking
- NEVER expose internal errors to API consumers

Section in CLAUDE.md

## Rules

- ALWAYS run tests after changing business logic
- ALWAYS use parameterized queries for all DB operations
- ALWAYS validate inputs at API boundaries
- NEVER import from `src/api/` inside `src/services/`
- NEVER commit code that fails type checking
- NEVER expose internal errors to API consumers

Section in AGENTS.md

Monorepo Configuration

When your repository contains multiple packages or services, each tool handles scoping differently.

Create rules at multiple directory levels:

.cursor/
  rules/
    monorepo.mdc          # alwaysApply: true (shared standards)

packages/
  api/
    .cursor/
      rules/
        api-rules.mdc     # globs: ["**/*.ts"] (API-specific)
  web/
    .cursor/
      rules/
        web-rules.mdc     # globs: ["**/*.tsx"] (frontend-specific)

Rules merge when the agent accesses files across packages.

Place CLAUDE.md files at each level:

CLAUDE.md                  # Root: shared standards, monorepo structure
packages/
  api/
    CLAUDE.md              # API service: Express patterns, DB access
  web/
    CLAUDE.md              # Frontend: React patterns, state management
  shared/
    CLAUDE.md              # Shared library: export conventions

Claude reads the root file plus the subdirectory file when working in that package.

Place AGENTS.md files at each level:

AGENTS.md                  # Root: shared standards, monorepo structure
packages/
  api/
    AGENTS.md              # API service: Express patterns, DB access
  web/
    AGENTS.md              # Frontend: React patterns, state management
  shared/
    AGENTS.md              # Shared library: export conventions

Codex discovers and merges configurations as it navigates the repository.

Multi-Tool Configuration

Many teams use more than one tool. Here is how to maintain configurations without duplication.

Strategy: Single Source of Truth

Keep your standards in one canonical file and derive tool-specific configs from it:

docs/
  coding-standards.md      # The source of truth

CLAUDE.md                  # Includes: "See docs/coding-standards.md for full standards"
AGENTS.md                  # Includes: "See docs/coding-standards.md for full standards"
.cursor/rules/
  standards.mdc            # Copy relevant sections from coding-standards.md

Strategy: Shared Guardrails, Tool-Specific Features

# .cursor/rules/project.mdc (Cursor-specific)
---
alwaysApply: true
---
[Shared standards copied here]

## Cursor-Specific
- Use Tab autocomplete for boilerplate
- Use @codebase for cross-file analysis
- Generate commit messages with Cmd+Shift+P > Generate Commit

# CLAUDE.md (Claude Code-specific)
[Shared standards here]

## Claude Code-Specific
- Run /compact when context exceeds 100K tokens
- Use claude -p for CI/CD pipeline integration
- Create custom commands in .claude/commands/ for repeated tasks

# AGENTS.md (Codex-specific)
[Shared standards here]

## Codex-Specific
- Use auto-edit mode for normal development
- Reserve full-auto for sandboxed environments
- Assign GitHub issues to @codex for automated fixes

Configuration Checklist

Use this when setting up a new project or onboarding a new tool:

Define project context: Tech stack, architecture, file organization. Include this in your configuration file so the AI understands what it is working with.
Specify coding standards: Naming conventions, import order, error handling patterns, type conventions. Be specific — “use interfaces for object shapes” is better than “follow TypeScript best practices.”
List common commands: Build, test, lint, dev server, database migration. The AI will run these to verify its work.
Set guardrails: What should the AI always do? What should it never do? These prevent costly mistakes like deleting migration files or pushing directly to main.
Add test patterns: Where do tests live? What test runner? How to run a single test? What mocking patterns to use? The AI writes better tests when it knows your conventions.
Document architecture boundaries: Which modules can import from which? What is the dependency direction? This prevents the AI from creating circular dependencies.
Include environment notes: Required environment variables, database connection strings (not the values — the names), external service dependencies. This helps the AI set up test fixtures correctly.

Quick Reference Card

What You Want	Cursor	Claude Code	Codex
Global project rules	`.cursor/rules/project.mdc` with `alwaysApply: true`	Top-level sections in `CLAUDE.md`	Top-level sections in `AGENTS.md`
File-type rules	`globs: ["*/.ts"]` in frontmatter	Subdirectory `CLAUDE.md`	Subdirectory `AGENTS.md`
User preferences	VS Code `settings.json`	`~/.claude/CLAUDE.md`	`~/.codex/config.toml`
Permission control	Privacy Mode in Settings	`.claude/settings.json`	`--ask-for-approval` flag
Custom commands	Command palette extensions	`.claude/commands/*.md`	Codex slash commands
Reusable workflows	`.cursor/rules/` with `description`	Custom slash commands	Codex Automations
Ignore patterns	Standard `.gitignore`	Standard `.gitignore`	Standard `.gitignore`
Model selection	Settings > Models	`/model` command	`--model` flag or `config.toml`

Configuration Reference

What You Will Walk Away With

Configuration Systems at a Glance

Cursor: .cursor/rules/

Directory Structure

Rule File Format (MDC)

Frontmatter Fields

Rule Types

Complete Starter Template

Advanced: File-Scoped Rules

Legacy: .cursorrules

Claude Code: CLAUDE.md

File Locations

File Format

Subdirectory CLAUDE.md

Claude Settings: .claude/settings.json

.claude/commands/ Custom Slash Commands

Codex: AGENTS.md and config.toml

AGENTS.md

Subdirectory AGENTS.md

config.toml (CLI Configuration)

Codex Automations Configuration

Side-by-Side Comparison

Telling the AI About Your Project

Defining Coding Standards

Specifying Build and Test Commands

Setting Guardrails (Do / Do Not)

Monorepo Configuration

Multi-Tool Configuration

Strategy: Single Source of Truth

Strategy: Shared Guardrails, Tool-Specific Features

Configuration Checklist

Quick Reference Card

Cursor: `.cursor/rules/`

Legacy: `.cursorrules`

Claude Code: `CLAUDE.md`

Claude Settings: `.claude/settings.json`

`.claude/commands/` Custom Slash Commands

Codex: `AGENTS.md` and `config.toml`