Skip to main content
All guides

Conventions

AGENTS.md vs CLAUDE.md vs llms.txt

Three Markdown files keep coming up in AI-assisted development, and they're easy to confuse. Two instruct coding agents inside your repo; one helps AI tools navigate your website. Here's the difference.

Definition: AGENTS.md gives supported coding agents repository instructions. CLAUDE.md supplies Claude Code's project instructions; Claude Code reads AGENTS.md instead when a repo has no CLAUDE.md, and a CLAUDE.md can import it. llms.txt is a proposed index of public website content for AI tools; it does not configure a coding agent or guarantee search inclusion.

Last reviewed: October 2026

Need living codebase context for Claude Code or Cursor?

Moxie Docs indexes your codebase and serves verified conventions and docs over MCP. Free on 1 repo.

Connect 1 repo free

AGENTS.md - instructions for coding agents

AGENTS.md is an open convention: a plain-Markdown file at your repo root that tells coding agents what they need to know to work in your project - build and test commands, code style, conventions, and gotchas that would clutter a human README. There's no required schema; it's just standard Markdown.

It started across tools like OpenAI Codex, Cursor, and Jules, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. A wide range of agents read it, which is the point: write it once, and many tools use it.

CLAUDE.md - Claude Code's project memory

CLAUDE.md is Claude Code's native memory file. It's loaded at the start of every session and holds the same kind of context - commands, conventions, architecture, standing instructions - but it's specific to Claude Code, with support for scoped files (org, user, project, local) and @-imports.

Since v2.1.277, Claude Code reads AGENTS.md as project instructions when the repo has no CLAUDE.md or CLAUDE.local.md; if a CLAUDE.md exists, Claude Code reads that instead by default. The recommended pattern when you keep both is a CLAUDE.md that imports AGENTS.md (via an @AGENTS.md import or a symlink), so both tools share one source of truth and you add Claude-specific notes below.

llms.txt - a map for AI tools

llms.txt is a proposed Markdown index for a website. An H1 names the project; an optional summary and links help an agent find relevant documentation. The August 2026 v2 proposal allows /llms.txt at the root or a scoped path such as /docs/llms.txt, and recommends linking to Markdown versions of pages.

Some sites also publish llms-full.txt with concatenated content. A concise index lets an agent follow the links it needs. Publishing either file does not guarantee that a particular tool will read it or that your pages will appear in AI search results.

To see how documentation sites actually publish these files, read the State of AI-Ready Docs report or check any site with the free llms.txt report.

Which file does each tool actually load?

Checked October 2026. Native discovery and an explicit import are different behaviors; a file name alone does not make every tool read it.

ToolNative project instructionsUsing AGENTS.md
CodexAGENTS.md, with AGENTS.override.md taking precedence in the same directoryLoaded along the path from the project root to the working directory
CursorAGENTS.md and configured .cursor/rules/*.mdc filesRoot and nested files are supported
Claude CodeCLAUDE.md, or AGENTS.md when the repo has no CLAUDE.mdRead directly when there is no CLAUDE.md; otherwise add @AGENTS.md to CLAUDE.md
AI tools reading a websiteDepends on the toolllms.txt is a separate proposal, not a repository instruction file

Sources: Codex instruction discovery, Cursor rules, Claude Code memory and imports, and the llms.txt proposal.

Using llms.txt with Claude Code

Claude Code never loads an llms.txt from your repository as instructions. Where llms.txt helps is outward: when Claude Code needs a library's or vendor's documentation, it can fetch that site's llms.txt with its web fetch tool and follow the links to the pages it needs, instead of crawling HTML.

To make that routine, point to the index from your instructions file rather than pasting the docs in:

MARKDOWN
## External docs
- For Claude Code itself, fetch https://code.claude.com/docs/llms.txt and follow the relevant links.
- For our public API, fetch https://docs.example.com/llms.txt.

Keep the list short and limited to docs your team actually uses. For your own repository's context, an instructions file or an MCP server is the better channel, because llms.txt only covers what is published on a website.

Where the files belong

For a web project, the source directory serving public files may differ by framework. The important distinction is that the first two files live in the repository, while llms.txt is served by the website at its root or a scoped path.

Code
my-project/
  AGENTS.md
  CLAUDE.md
  services/
    billing/
      AGENTS.md
  public/
    llms.txt       -> https://example.com/llms.txt

Copyable AGENTS.md and CLAUDE.md examples

Start with a small shared file. Replace the example commands with commands that actually exist in your repository.

MARKDOWN
# Project instructions

## Verification
- Run npm run lint and npm test after source changes.
- Run npm run build before handing back an app change.

## Conventions
- Reuse the shared UI components.
- Update the setup guide when required environment variables change.

Save that as AGENTS.md. For Claude Code, add a CLAUDE.md containing an explicit import and any Claude-specific notes:

MARKDOWN
@AGENTS.md

## Project context
Read docs/architecture.md before changing service boundaries.

Build your AGENTS.md or create a CLAUDE.md. For what to put in the file, use the AGENTS.md guide and CLAUDE.md guide. For nested files in a monorepo, see AGENTS.md and CLAUDE.md in a monorepo.

A minimal llms.txt example

Use links to public documentation you want readers to find. Publishing this file is optional and does not replace your sitemap, HTML content, or access controls.

MARKDOWN
# Example API

> Documentation for the Example API.

## Guides
- [Quickstart](https://example.com/docs/quickstart): Send your first request.
- [Authentication](https://example.com/docs/auth): Configure an API token.

Generate an llms.txt, then check its structure. Google says its AI search features do not require special optimization.

At a glance

Side by side

Purpose

AGENTS.md

Instruct coding agents in your repo

CLAUDE.md

Instruct Claude Code in your repo

llms.txt

Help AI tools navigate your website

Audience

AGENTS.md

Agents with AGENTS.md support

CLAUDE.md

Claude Code only

llms.txt

External AI assistants

Location

AGENTS.md

Repo root; scoped directories where supported

CLAUDE.md

Repo + user/org/local scopes

llms.txt

Website root or scoped path (/docs/llms.txt)

Format

AGENTS.md

Plain Markdown, no schema

CLAUDE.md

Markdown + @imports

llms.txt

H1 + summary + link lists

Governance

AGENTS.md

Agentic AI Foundation (Linux Foundation)

CLAUDE.md

Anthropic

llms.txt

Independent proposal; no standards body

Status

AGENTS.md

Widely adopted across tools

CLAUDE.md

Native to Claude Code

llms.txt

Website content discovery proposal

Which should you use?

If you want coding agents to follow your project's conventions, start with AGENTS.md, and add a CLAUDE.md that imports it if your team uses Claude Code. Use llms.txt only if you publish a public docs site and want to offer AI tools a curated content index - it's a separate, outward-facing concern. Moxie Docs complements all three: it serves your living codebase context to agents over MCP, and can generate an llms.txt for your docs site.

FAQ

Frequently asked questions

Quick answers to the questions developers ask about AGENTS.md vs CLAUDE.md vs llms.txt.

Get started

Give your agents real codebase context.

Connect a repository and Moxie Docs generates living documentation and serves it to your agents over MCP. Free on 1 repository, no card required.