AGENT-README.md

README.md is for humans. AGENT-README.md is for the machines that now read your code.

status: draft spec: v0.1 feedback wanted license: CC BY 4.0

Read the draft spec → View this site's agent-readme.md Grab a template

What is it?

An AGENT-README.md is a single Markdown file, placed at the root of a repository (or served at a site's /agent-readme.md), that gives an AI agent the context it needs to act safely and correctly in your project.

Think of it as robots.txt for autonomous coding agents - but human-readable, richer, and written in the format agents already understand best: Markdown.

If a capable agent read only this one file, would it know how to build, test, and change your project without breaking things? That is the bar an AGENT-README.md aims to clear.

Why now?

Coding agents already read your files, run your commands, and open pull requests. Today that guidance is scattered across a dozen bespoke files - AGENTS.md, CLAUDE.md, .cursorrules, llms.txt, Copilot instructions - each tool with its own name and shape.

AGENT-README.md proposes one obvious, tool-neutral name and a light structure that any agent (or human) can follow.

What goes in it

Purpose

What the project is and what "done" looks like.

Commands

Exact build, test, lint, and run commands - copy-paste ready.

Guardrails

Do-not-touch zones, secrets handling, destructive-action rules.

Conventions

Code style, structure, and patterns to follow.

Context

Architecture notes and links to deeper docs.

Current state

Active refactors and known-failing areas, so agents skip work in progress.

Surprises

The non-obvious calls a newcomer would trip over.

Contacts

Who owns what, and where to ask.

Minimal example

# AGENT-README

## Purpose
A CLI that converts CSV to Parquet. "Done" = tests pass and `--help` is accurate.

## Setup & commands
- Install: `npm ci`
- Build:   `npm run build`
- Test:    `npm test`
- Lint:    `npm run lint`  # must pass before any commit

## Guardrails
- Never edit files under `vendor/` or `dist/`.
- Never commit anything in `.env*`.
- Ask before deleting files or rewriting git history.

## Conventions
- TypeScript, strict mode. No `any`.
- Prettier is the source of truth for formatting.

## Contacts
- Owner: @maintainer · Issues: /issues

This very site ships one. Read it at /agent-readme.md - served straight from the domain root, dogfooding the idea.

How it relates to what exists

File	Audience	Scope
`README.md`	Humans	Onboarding, overview
`AGENTS.md` / `CLAUDE.md`	Specific tools	Tool-specific instructions
`llms.txt`	LLMs (web)	Content discovery for sites
`AGENT-README.md`	Any agent	How to work in this project

The goal is not to replace these - it is to offer one obvious, portable default, and to point at the others where they fit. For a fuller treatment, see AGENTS.md vs. AGENT-README.md.

Get involved

This is an early draft. The spec, the name, the structure - all open for discussion. Read the draft specification and the roadmap, try a template, then:

Discuss the spec → Open an issue GitHub repo

Show it off

Does your repository ship an AGENT-README.md? Add the badge to your README.md:

[![agent-readme](https://agent-readme.md/badge.svg)](./AGENT-README.md)