Configuring Codex Coding Rules with AGENTS.md: A Practical Guide

Why Explicit Codex Rules Matter

Codex can generate code, but without knowledge of a team’s conventions it may produce code that conflicts with project standards—using the wrong package manager, skipping lint checks, or making unrelated refactors. The first step to turning Codex into a "project‑aware coding partner" is to document the project's rules clearly.

Two Main Types of Rules

Codex recognises two categories of rules:

Collaboration rules stored in AGENTS.md Command‑permission rules stored in .codex/rules/*.rules This article focuses on the former and briefly explains when the latter is appropriate.

Good vs. Bad Rules

Vague aspirations such as "code should be elegant" or "no bugs" are unhelpful. Effective rules describe concrete actions Codex should take. Examples of specific rules include:

Read the relevant module before making changes; avoid guessing.

After modifying JavaScript/TypeScript files, run pnpm lint.

Do not add new production dependencies unless the user explicitly approves.

Preserve existing code style and avoid unrelated refactoring.

These concrete directives enable Codex to know when to read files, run tests, or pause for confirmation.

Using AGENTS.md

According to OpenAI’s documentation, Codex reads AGENTS.md at the start of a task to obtain project‑specific instructions. The simplest approach is to create an AGENTS.md file at the repository root and list the project’s rules.

## Project Agreements

- Use `pnpm` to manage dependencies; avoid `npm install`.
- After modifying front‑end code, run `pnpm lint`.
- After changing core business logic, add or update tests.
- Do not modify `.env`, keys, certificates, or other sensitive files.
- Keep change scope minimal; avoid unrelated formatting or refactoring.

With this file in place, Codex sees the conventions before it begins work.

Global vs. Project Rules

Rules can be layered. Personal habits that apply to all projects belong in a global file, e.g. ~/.codex/AGENTS.md (or C:\Users\YourName\.codex\AGENTS.md on Windows):

## My General Work Habits

- Respond in Chinese.
- Explain the plan before modifying code.
- Prefer using `rg` to search files and text.
- Do not execute dangerous commands proactively.

Project‑specific rules stay in the repository’s AGENTS.md:

## Current Project Rules

- This project uses Vue 3 + TypeScript.
- Package manager is `pnpm`.
- API type definitions are in `src/types/api.ts`.
- Component styles follow the existing Tailwind conventions.
- Run `pnpm lint` at least before committing.

Separating global and project rules prevents personal preferences from polluting team standards while keeping project conventions version‑controlled.

Subdirectory Rules

Large projects can place additional AGENTS.md files in subdirectories, allowing more specific constraints. For example, a payment service might have:

# services/payment/AGENTS.md

## Payment Module Rules

- When modifying payment logic, maintain backward compatibility.
- Do not change amount‑precision handling unless explicitly requested.
- Add tests for refunds, reconciliation, and signature verification.
- Never log full card numbers, tokens, or signature keys.

Codex reads rules from the repository root down to the current working directory, giving precedence to the closest file. This hierarchy is useful for large codebases.

Practical AGENTS.md Template

You can start from the following template and adapt it to your project:

# AGENTS.md

## Project Overview

This is a front‑end admin dashboard project, primarily using React, TypeScript, Vite, and pnpm.

## Development Rules

- Prefer to keep existing directory structure and code style.
- Avoid unrelated refactoring or formatting unchanged files.
- When adding features, reuse existing components and utility functions first.
- Do not add production dependencies unless the user explicitly confirms.

## Command Conventions

- Install dependencies with `pnpm install`.
- Run local development with `pnpm dev`.
- After code changes, run `pnpm lint`.
- When test files are involved, run `pnpm test`.

## Security Boundaries

- Do not modify `.env`, certificates, keys, or production configuration files.
- Do not commit real tokens, passwords, phone numbers, or ID numbers.
- For permission, payment, or login logic, explicitly state risk points.

## Output Practices

- Briefly explain the modification plan before editing code.
- After completion, state which files were changed and whether verification commands were run.

This template focuses on the most error‑prone areas: package manager usage, testing commands, dependency handling, and security boundaries.

The .rules Files (Command Permissions)

Besides AGENTS.md, Codex supports a .rules configuration that controls which commands may run outside the sandbox. It is experimental and primarily used to prompt or forbid certain actions. An example that prompts before viewing a GitHub PR:

prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "Require confirmation before viewing PR information",
    match = [
        "gh pr view 123",
    ],
)

The three possible decisions are allow, prompt, and forbidden. For most new projects, focusing on a well‑crafted AGENTS.md yields the greatest benefit before adding .rules files.

Evaluating Rule Quality

Use four questions to assess a rule:

Does the rule guide a concrete behavior?

Does Codex know when to apply it?

Does it reduce real‑project risk?

Does it avoid over‑restriction?

For instance, the vague rule "write high‑quality code" can be refined to "when modifying an existing module, keep the current architecture and do not add a new abstraction layer unless duplicate logic appears in more than three places".

Conclusion

Codex relies on more than a single prompt; embedding project conventions in rule files makes it behave like a teammate. The three key takeaways are:

Write coding rules primarily in AGENTS.md as Codex’s main entry point.

Separate global habits (in ~/.codex/AGENTS.md) from project‑specific rules (in the repository).

Use .rules to control command permissions when needed.