AGENTS.md Across Coding Agents: The Universal Cross-Tool Specification for Codex, Cursor, and Antigravity

AGENTS.md across coding agents serves as the open repository instruction standard recognized by OpenAI Codex, Cursor IDE, and Google Antigravity. By placing an AGENTS.md file in your repository root, engineering teams define universal architecture constraints, command whitelists, and code conventions that execute consistently across terminal CLIs, graphical IDEs, and autonomous background subagents.

What Is the Universal AGENTS.md Specification and Why Does It Matter?

The universal AGENTS.md specification is an open, portable repository guideline standard designed to inform autonomous coding agents about project structure, build commands, testing protocols, and architectural constraints. Unlike proprietary configuration files that lock instructions into a single vendor's ecosystem, AGENTS.md provides a clean markdown document that any language model, CLI agent, or developer environment can parse without specialized plugins.

As software development teams integrate multi-agent workflows, engineers rarely standardize on a single interface. One developer uses the Cursor IDE for daily frontend feature implementation, a backend tech lead executes automated refactoring using the OpenAI Codex CLI in headless terminal sessions, and DevOps engineers deploy Google Antigravity agents to conduct autonomous repository audits in CI pipelines. When each tool requires a bespoke instructions file—such as .cursor/rules/*.mdc, .codex/instructions.md, or .gemini/antigravity/rules/—instructions quickly diverge, resulting in contradictory code suggestions, broken build scripts, and lost engineering velocity.

The AGENTS.md specification solves this fragmentation by establishing a neutral, human-readable source of truth at the repository root. When configured correctly, it eliminates the need to author duplicate prompt rules across separate platforms while ensuring that every assistant operating on the codebase respects identical architectural boundaries.

Core Architecture: The Universal AGENTS.md Schema and Section Directives

To ensure that multiple coding agents interpret instructions predictably, an AGENTS.md file must follow a structured schema. While standard Markdown is forgiving for human readers, large language models rely on clear section hierarchy, unambiguous affirmative directives, and strict command constraints.

An optimal AGENTS.md file should never exceed 2,000 tokens in length, as oversized repository instructions degrade attention accuracy in downstream reasoning models. Below is the production-grade universal schema recommended for cross-agent repositories:

# AGENTS.md - Multi-Agent Repository Guidelines

## 1. Project Overview & Architecture
- **Repository Purpose:** Distributed payment processing service handling webhooks and transaction settlement.
- **Primary Stack:** TypeScript 5.5, Node.js 22 LTS, PostgreSQL 16, Prisma ORM, Vitest.
- **Architecture Pattern:** Clean architecture with domain entities isolated from infrastructure adapters in `src/core` and `src/infra`.

## 2. Command Execution Whitelist
Agents must only execute the following approved commands for verification and testing:
- **Install Dependencies:** `pnpm install --frozen-lockfile`
- **Run Unit Tests:** `pnpm test:unit`
- **Run Integration Tests:** `pnpm test:integration`
- **Database Schema Validation:** `pnpm prisma validate`
- **Type Checking:** `pnpm tsc --noEmit`
- **Linting & Formatting:** `pnpm biome check --apply`

## 3. Strict Prohibitions & Blacklisted Actions
Agents are explicitly forbidden from performing the following actions:
- **NO Database Migrations:** Never execute `pnpm prisma migrate dev` or `pnpm prisma migrate deploy` automatically.
- **NO Force Push:** Never execute `git push --force` or delete remote branches.
- **NO Direct Main Commits:** All changes must be authored on feature branches matching `feature/*` or `fix/*`.
- **NO Unvetted Dependencies:** Do not add third-party npm packages without explicit developer confirmation.

## 4. Code Generation Standards
- **Error Handling:** Always use explicit Result types (`Result<T, AppError>`) instead of throwing uncaught exceptions.
- **Async Safety:** All asynchronous database transactions must pass an explicit timeout parameter (`timeout: 5000`).
- **Telemetry:** Every public API route in `src/api` must instantiate an OpenTelemetry span via `tracer.startActiveSpan()`.

## 5. Agent Verification Protocol
Before marking any task as complete, the agent must run:
1. `pnpm tsc --noEmit` (must pass with 0 errors)
2. `pnpm biome check` (must report no unformatted files)
3. `pnpm test:unit` (all tests must pass)

How Do Codex, Cursor, and Antigravity Parse AGENTS.md Differently?

OpenAI Codex, Cursor IDE, and Google Antigravity parse AGENTS.md through fundamentally different runtime pipelines: Codex reads it as a root system instruction, Cursor blends it into workspace context with 12,000-token budget rules, and Antigravity executes hierarchical multi-directory resolution. Understanding these runtime mechanics prevents critical instructions from being dropped during inference.

In the official Cursor documentation on Project Rules, the team notes: "Rules are included in the prompt context sent to the model to provide project-specific instructions and guidelines." However, because Cursor was historically architected around .cursorrules and modern modular .cursor/rules/*.mdc files, it ingests AGENTS.md as an ambient workspace document. In contrast, OpenAI Codex was built to recognize AGENTS.md as the primary developer instruction preamble.

Notice the structural trade-off: while OpenAI Codex parses AGENTS.md exclusively at the repository root, Google Antigravity searches hierarchically up to three directory levels above the active workspace. If your team maintains a monorepo, nested instructions that work seamlessly in Antigravity or Cursor will be ignored entirely by the Codex CLI unless they are consolidated or bridged into root instructions.

Resolving Precedence: When AGENTS.md Collides with .cursor/rules and Claude Skills

Instruction collisions occur when general guidelines in AGENTS.md contradict granular rules configured in tool-specific formats like .cursor/rules/*.mdc or Claude Code SKILL.md packages. When both AGENTS.md and .cursor/rules/*.mdc exist in a repository, Cursor evaluates modular .mdc glob matches before falling back to root AGENTS.md directives.

To prevent contradictory agent output, engineering organizations should adopt a three-tier rule hierarchy:

1. Tier 1: Global Safety and Repository Laws (AGENTS.md): Universal non-negotiable constraints, such as command execution permissions, Git branch naming rules, banned dependencies, and core architecture conventions. All agents must obey these baseline rules.
2. Tier 2: Tool-Specific Interface Scaffolding (.cursor/rules/*.mdc or CLAUDE.md): Editor-specific optimizations, such as path-based glob filters, automated UI component scaffolding, or hotkey trigger patterns. For a deep dive into structuring path-scoped rules in Cursor, read our guide on migrating to the modular .cursor/rules directory structure.
3. Tier 3: Procedural Executable Workflows (SKILL.md): Multi-step deterministic scripts and parameter-driven routines that run shell scripts, API calls, or database migrations on demand.

If an engineer updates a dependency or changes testing frameworks in .cursor/rules/test.mdc without updating AGENTS.md, an engineer running Codex in terminal will continue executing the outdated testing commands. Learn more about diagnosing and eliminating these runtime conflicts in our complete guide to resolving multi-agent instruction precedence conflicts.

The Sprawl Moment: The Monorepo Microservice Desynchronization

A platform engineering team oversees a monorepo containing 18 interconnected microservices with 35 software engineers deploying code daily. To establish consistent standards, the staff architect writes a detailed 250-line AGENTS.md file at the repository root requiring all database operations to use strict transaction rollbacks and prohibiting any raw SQL queries. However, a senior frontend engineer using Cursor creates a local .cursor/rules/data-fetching.mdc file that permits raw SQL queries inside server actions to speed up query benchmarking, while a DevOps engineer working in Google Antigravity configures subagent workspace rules that bypass transaction wrappers for local seeding scripts. During an emergency midnight hotfix for an authentication token leak, a backend developer executes OpenAI Codex in terminal to generate a database cleanup script. Because Codex only reads the root AGENTS.md while Cursor executes the localized .mdc rule, the developer reviews the code in Cursor where the linter silently approves the syntax, but the script executes unbuffered raw SQL in production that deadlocks the customer session table for 42 minutes.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

Can You Use Monorepo-Scoped AGENTS.md Files Across Nested Packages?

Monorepo-scoped AGENTS.md files can be placed in nested package directories, but runtime support varies significantly across coding agents: Google Antigravity and Cursor recognize nested directories during local context resolution, whereas the OpenAI Codex CLI defaults strictly to the workspace root. To maintain parity across all tools, monorepos must use either an inheritance script or a root index that references child package specifications.

In a typical monorepo structure:

my-org-monorepo/
├── AGENTS.md                    # Root universal guidelines (Tier 1)
├── apps/
│   ├── web/
│   │   ├── AGENTS.md            # Next.js & Tailwind frontend rules
│   │   └── src/
│   └── backend/
│       ├── AGENTS.md            # Go microservice & gRPC guidelines
│       └── main.go
└── packages/
    └── database/
        ├── AGENTS.md            # PostgreSQL schema & migration rules
        └── schema.prisma

When a developer opens apps/web as their primary workspace in Google Antigravity, the runtime automatically merges apps/web/AGENTS.md with the parent repository's AGENTS.md, ensuring both general security policies and specific React patterns apply. For more information on configuring workspace-level boundaries in Antigravity, review our guide on configuring custom workspace skills in Google Antigravity.

However, when running OpenAI Codex from the repository root, Codex will never traverse into apps/web/AGENTS.md unless the active user prompt specifically directs the agent to inspect that path. To bridge this gap, your root AGENTS.md should include an explicit directory routing table:

## Sub-Package Instruction Index
When working within specific subdirectories, you must inspect and adhere to localized guidelines:
- Frontend Application: See `apps/web/AGENTS.md` for component architecture and state management.
- Backend Core Service: See `apps/backend/AGENTS.md` for concurrency and error handling patterns.
- Database Package: See `packages/database/AGENTS.md` for query constraints and connection pooling.

Validating AGENTS.md: Automated POSIX Linter and Compliance Script

Because language models fail unpredictably when repository instructions contain syntax errors, circular references, or excessive token counts, engineering teams should validate AGENTS.md in pre-commit git hooks and CI pipelines. An automated linter guarantees that your instruction files remain within strict token budgets and adhere to required schema sections.

The following POSIX-compliant bash script audits AGENTS.md files across your repository, checking file size, line counts, mandatory heading sections, and forbidden ambiguous phrases (like "try to" or "if possible"):

#!/usr/bin/env bash
# validate-agents-md.sh - Automated Compliance Linter for AGENTS.md
set -euo pipefail

TARGET_FILE="${1:-AGENTS.md}"
MAX_LINES=300
MAX_CHARACTERS=10000

echo "==> Auditing ${TARGET_FILE} for multi-agent compliance..."

if [[ ! -f "${TARGET_FILE}" ]]; then
    echo "ERROR: Target file '${TARGET_FILE}' does not exist!"
    exit 1
fi

LINE_COUNT=$(wc -l < "${TARGET_FILE}")
CHAR_COUNT=$(wc -c < "${TARGET_FILE}")

echo "  - Line count: ${LINE_COUNT} (Limit: ${MAX_LINES})"
echo "  - Character count: ${CHAR_COUNT} (Limit: ${MAX_CHARACTERS})"

if (( LINE_COUNT > MAX_LINES )); then
    echo "ERROR: ${TARGET_FILE} exceeds ${MAX_LINES} lines! Compress instructions to save context window tokens."
    exit 1
fi

if (( CHAR_COUNT > MAX_CHARACTERS )); then
    echo "ERROR: ${TARGET_FILE} exceeds ${MAX_CHARACTERS} characters (~2,500 tokens). Risk of attention degradation."
    exit 1
fi

# Validate mandatory schema sections
REQUIRED_SECTIONS=("Project Overview" "Command Execution" "Prohibitions" "Verification")
for SECTION in "${REQUIRED_SECTIONS[@]}"; do
    if ! grep -qi "${SECTION}" "${TARGET_FILE}"; then
        echo "WARNING: Missing recommended section '${SECTION}' in ${TARGET_FILE}."
    fi
done

# Detect weak, ambiguous phrasing that models ignore
WEAK_PATTERNS=("try to" "if possible" "please consider" "make sure to maybe")
for PATTERN in "${WEAK_PATTERNS[@]}"; do
    if grep -qi "${PATTERN}" "${TARGET_FILE}"; then
        echo "WARNING: Detected weak phrasing '${PATTERN}'. Replace with imperative commands ('Always', 'Never', 'Must')."
    fi
done

echo "SUCCESS: ${TARGET_FILE} passed all multi-agent validation checks!"
exit 0

How Do You Keep AGENTS.md Synchronized Across Every Team Machine?

Keeping AGENTS.md synchronized across multiple developer machines, remote servers, and git branches requires a centralized synchronization engine rather than ad-hoc git commits. Storing personal preferences or machine-specific paths in repository-level files creates git merge conflicts, while sharing rules via Slack or internal wikis guarantees that individual developers will run out-of-sync agent prompts.

Prompttly's two-way sync on Mac writes changes back to repository AGENTS.md and ~/.claude/skills without requiring manual git cherry-picks or export scripts. Instead of manually editing files across dozens of cloned repositories, developers maintain their master prompt and skill library in Prompttly.

With Prompttly:

• Universal Two-Way Sync: Prompts and instructions edited in Prompttly synchronize directly into AGENTS.md, Cursor rules, and Claude Code skill folders across your Mac and cloud workstations.
• Sub-200ms Mac Hotkey Palette: Access your entire instruction catalog instantly from any application on macOS without interrupting your development flow.
• Cross-Worktree Parity: Automatically propagate updated agent guidelines across multiple git worktrees and submodules without branch pollution. Read our technical deep dive on syncing AGENTS.md across git worktrees.
• Cross-Agent Tooling: Seamlessly bridge your workflows between terminal agents and web chat interfaces using our free Custom Instructions Generator and Claude Skill Creator.

To explore how teams build an enterprise-wide prompt repository that spans OpenAI Codex, Cursor, Antigravity, and Claude Code, see our comprehensive guide on building a cross-agent skill library, or browse our central AI agent resource library for additional architectural patterns.

Frequently Asked Questions About AGENTS.md Across Coding Agents