Agents and Workspace Rules

What is an AGENTS.md file?

Project-level systems instructions and agent skills, project context, etc. can be built into a project’s “README for agents” called AGENTS.md. Think of AGENTS.md as the onboarding handbook for an AI agent entering a specific project. It tells the agent what the project is and how it should behave to blend in seamlessly with human contributors.

The challenge with AGENTS.md is that it is automatically loaded into the context window by AI agents working in the project. Hence, it already fills up part of the context window, limiting space for your conversation prompts and results. One solution is to have a concise AGENTS-mini.md (with perhaps a more detailed AGENTS-LONG.md loaded when needed) This works well as long as the concise version is sufficient —

Comparing README.md, DEVELOPER.md, and AGENTS.md

In a collaborative repository, documentation is stratified by target audience, technical depth, and operational purpose. A human developer uses the README.md to get started, reads DEVELOPER.md to understand why the code is designed the way it is, and defines rules in AGENTS.md so that their AI partner knows exactly how it must behave when editing files. The table below outlines how these three entrypoint documents complement one another:

Metric README.md DEVELOPER.md AGENTS.md
Primary Audience Users, evaluators, and prospective contributors. Human developers, maintainers, and onboardees. AI coding assistants (e.g., Antigravity, Copilot).
Core Goal Welcoming introduction; get the project running and explain what it does. Explain the codebase design, module boundaries, and architecture. Dictate strict operational rules, workflows, and programming constraints.
Typical Scope & Content Quick start, installation, dependencies, and licensing. System/reactivity diagrams, module indices, and extension guides. Code formatting rules, file-versioning workflows, and strict constraints.
Tone & Style Descriptive, promotional, and high-level. Explanatory, conceptual, and diagram-heavy. Concise, strict, imperative, and rule-focused.
Location & Integration Repository Root (/README.md) Root, docs/ folder, or package articles (vignettes/). Workspace config folders (e.g., .agents/AGENTS.md). Can be nested to layer subdirectory-specific rules.

AGENTS.md Examples

Ask an AI agent to “create AGENTS.md for this project”. I just did this for multiple projects, including this one. See for instance these example AGENTS.md files with listed sections:

This site uses Just the Docs, a documentation theme for Jekyll.