AGENTS.md vs Cursor Rules vs OKF
— Which AI Agent Documentation Format Should You Use?

The Problem: Every Agent Needs Context

AI coding agents — whether it's Cursor, GitHub Copilot, Claude Code, or OpenAI Codex — all face the same challenge: they show up to your repo knowing nothing about your project's conventions, architecture, tech stack, or team preferences. Without explicit instructions, agents guess. They suggest patterns that don't match your codebase, generate code in the wrong style, or miss critical project-specific rules.

This guide compares all three across portability, multi-agent support, versioning, discoverability, and practical workflow — so you can choose the right approach (or combination) for your project.

What Is AGENTS.md?

AGENTS.md is a project-level markdown file that provides instructions to AI coding agents, originally designed for OpenAI's Codex CLI and now also supported by GitHub Copilot. It sits at the root of your repository and contains everything an agent should know: your tech stack, coding conventions, architecture decisions, testing strategy, and any project-specific rules.

How AGENTS.md Works

When an agent like Codex or Copilot opens your project, it scans for an AGENTS.md file at the root. The contents are loaded into the agent's system prompt (or made available as context), giving it a base of project knowledge before it starts working. It's a single-file approach: one markdown document, one source of truth.

# AGENTS.md

## Project Overview
- **Name:** My API Service
- **Stack:** TypeScript, Express, PostgreSQL
- **Package manager:** pnpm

## Code Conventions
- Use async/await, never raw promises
- Prefer functional components in React
- File names: kebab-case.ts

## Architecture
- Controllers handle HTTP → delegate to services
- Services contain all business logic
- Repository pattern for database access

## Testing
- Unit tests: vitest
- Integration: supertest + testcontainers
- Coverage minimum: 80%

Key Characteristics

• Single file — One AGENTS.md at the project root for all instructions
• Codex-native — Designed for OpenAI Codex CLI and GitHub Copilot
• Project-scoped — Instructions apply to the whole repository
• Markdown format — Simple, human-readable, version-controlled
• No metadata standard — Free-form markdown with no enforced structure (unlike OKF's YAML frontmatter)

AGENTS.md is the simplest entry point for AI agent documentation. If you're using Codex or Copilot and want a quick way to give context with zero tooling overhead, AGENTS.md is the fastest path. But its tool-specific nature means it won't help agents that don't read it — including Cursor and Claude Code.

What Are Cursor Rules?

Cursor Rules are project-specific configuration files that tell the Cursor IDE how to behave when generating code in your project. They live in the .cursor/rules/ directory (the modern pattern) or in a legacy .cursorrules file at the project root. Unlike AGENTS.md's single-file approach, Cursor Rules use a directory of individual .mdc files, each covering a specific concern.

How Cursor Rules Work

Each rule file in .cursor/rules/ is an MDC (Markdown with Config) file that combines a YAML-style frontmatter block for rule metadata with markdown content for the instructions themselves. Rules can be scoped with gloms (file patterns) so they only apply when working with specific file types. This makes Cursor Rules more granular than AGENTS.md — you can have separate rules for React components, API routes, database schemas, and tests.

.cursor/rules/
├── typescript.mdc      # TypeScript conventions
├── react.mdc           # React component patterns
├── api-routes.mdc      # API route conventions
├── database.mdc        # Database schema rules
├── testing.mdc         # Testing conventions
└── style-guide.mdc     # Code style preferences

---
description: React component conventions
globs: **/*.tsx
alwaysApply: false
---
# React Component Rules

- Use functional components with hooks
- Props interfaces must be prefixed with I (e.g., IButtonProps)
- Export default for page components, named exports for shared
- No inline styles — use Tailwind or CSS modules
- Every component must have a Storybook story

Key Characteristics

• Multi-file structure — Directory of .mdc files, each with a specific purpose
• Glob-scoped rules — Apply rules only to matching file patterns (e.g., *.tsx, *.sql)
• Cursor-only — Only works in Cursor IDE; ignored by Codex, Copilot, Claude Code
• Auto-attachment — Rules with alwaysApply: true are automatically attached to every request
• Granular control — Separate rules for conventions, architecture, style, testing, and deployment
• YAML frontmatter — Structured metadata for description, globs, and attachment behavior

Cursor Rules are the most fine-grained option — perfect for teams that use Cursor as their primary IDE and want precise control over how the agent behaves across different file types and project areas. But they're completely invisible to agents running outside Cursor.

What Is OKF (Open Knowledge Format)?

OKF (Open Knowledge Format) is a directory-based standard for packaging structured domain knowledge as portable markdown bundles. Launched by Google Cloud Platform in mid-2026 and now widely adopted across the AI ecosystem, OKF bundles are language-agnostic, tool-agnostic, and multi-agent by design. Unlike AGENTS.md and Cursor Rules — which are each tied to specific tools — an OKF bundle works with any AI agent that can read structured markdown.

How OKF Bundles Work

An OKF bundle is a directory of markdown files organized by knowledge category (concepts, guides, reference, tutorials), each file prefixed with YAML frontmatter containing title, description, tags, version, and status. Agents consume the bundle by loading it into context directly — no APIs, databases, or infrastructure required.

my-project-knowledge/
├── index.md              # Bundle manifest with metadata
├── log.md                # Changelog
├── concepts/
│   ├── architecture.md   # Architectural decisions
│   ├── data-model.md     # Database design
│   └── auth-flow.md      # Authentication patterns
├── guides/
│   ├── conventions.md    # Coding conventions
│   ├── testing.md        # Testing strategy
│   └── ci-cd.md          # CI/CD pipeline
└── reference/
    ├── tech-stack.md     # Technology stack reference
    └── env-config.md     # Environment configuration

Key Characteristics

• Tool-agnostic — Works with Cursor, Codex, Copilot, Claude Code, and custom agents
• Structured metadata — YAML frontmatter in every file provides title, description, tags, versioning
• Multi-file directory — Knowledge organized by category with cross-file linking
• Git-native versioning — Full change history, PR reviews, and release tagging
• Zero infrastructure — Pure markdown files; no databases, servers, or APIs needed
• Discoverable — Bundles can be listed on BundleDex, making them searchable across the ecosystem
• Offline-capable — Agents can load bundles without network access

OKF is the portable layer between tool-specific formats. You can author your project knowledge as an OKF bundle once and have it consumed by any agent — or use it to generate AGENTS.md and Cursor Rules as tool-specific views of the same knowledge. For a deep dive, see our What Is OKF? guide.

Comparison Table

When to Use Each

Use AGENTS.md When...

• Your team primarily uses GitHub Copilot or OpenAI Codex CLI
• You want the simplest possible setup — one file, zero tooling
• Your project conventions are broad and apply uniformly across the codebase
• You don't need fine-grained, per-file-type rules
• You're just getting started with AI agent documentation and want to experiment

Use Cursor Rules When...

• Your team uses Cursor IDE as the primary development environment
• You need file-type-specific rules (different conventions for React, API routes, database schemas)
• You want auto-attachment of rules based on the files being edited
• You have a large team with well-defined, granular conventions across many file types
• You don't need portability to other AI agents outside Cursor

Use OKF Bundles When...

• You want portability — your project knowledge should work with Cursor, Copilot, Codex, and Claude Code
• You need structured metadata — tagging, versioning, status tracking per knowledge file
• You're building for multiple agents/workflows and don't want to maintain separate formats
• You want your project knowledge discoverable on BundleDex
• You plan to reuse knowledge across multiple projects or packages
• You want versioned, reviewable, auditable knowledge artifacts

How They Work Together

The most powerful pattern isn't choosing one format over the others — it's using them together. OKF bundles serve as the portable, structured source of truth for your project knowledge, while AGENTS.md and Cursor Rules act as tool-specific views generated from that source.

The Layered Approach

Your AI Agent Documentation Stack
=====================================

Layer 1: OKF Bundle (Source of Truth)
├── concepts/architecture.md
├── concepts/coding-standards.md
├── guides/testing-guide.md
├── reference/tech-stack.md
└── reference/deployment.md

Layer 2: Tool-Specific Views (Generated)
├── AGENTS.md          ← Generated from OKF for Codex/Copilot
└── .cursor/rules/     ← Generated from OKF for Cursor
    ├── typescript.mdc
    ├── react.mdc
    └── api-routes.mdc

Layer 3: Agent Consumption
├── Cursor reads .cursor/rules/
├── Codex reads AGENTS.md
├── Copilot reads AGENTS.md
└── Claude Code reads OKF bundle directly

Why This Works

1. Single source of truth — Update your OKF bundle and regenerate tool-specific files. No duplication, no drift.
2. Universal coverage — Every agent gets the context it needs in the format it expects. Cursor gets its .mdc files, Codex gets AGENTS.md, and Claude Code reads the OKF bundle directly.
3. Versioning for free — Your OKF bundle is versioned in git with a changelog. When you update conventions, the change is tracked, reviewable, and deployable as a release.
4. Gradual adoption — Start with AGENTS.md today. When you need Cursor support, add Cursor Rules. When you need multi-agent portability, convert everything to an OKF bundle and generate both tool-specific files from it.

This layered approach mirrors how teams already manage other project assets: a single design system (like Figma) generates platform-specific component libraries. Similarly, a single OKF bundle generates tool-specific agent documentation. See our OKF tutorial for a walkthrough of this workflow.

For a broader view of how agent documentation fits into knowledge management, check out our guide on Knowledge Management for AI Agents.

FAQ