AGENTS.md and CLAUDE.md: what they do and what to include
AGENTS.md and CLAUDE.md provide project instructions for AI coding assistants. Learn how they differ, where to place them and what to include, with practical examples.
Overview & context
AGENTS.md and CLAUDE.md are files that give AI coding assistants instructions for working in a repository. They describe how to run and test the project, which conventions to follow and what to watch for when making changes. Keeping these instructions in the repository lets you share them with your team instead of repeating them in every prompt.
1. The difference between AGENTS.md and CLAUDE.md
AGENTS.md is an open format for project instructions supported by multiple development tools. CLAUDE.md provides instructions for Claude Code. Both use Markdown, so you can write plain text, headings, lists and command examples.
If you use several tools, you can keep shared instructions in AGENTS.md and import them from CLAUDE.md with the line `@AGENTS.md`. According to the Claude Code documentation, version 2.1.277 introduced direct AGENTS.md loading as well. By default, it loads AGENTS.md when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or its parents. Loading also depends on client settings; an import lets you use the shared instructions alongside your own CLAUDE.md.
@AGENTS.md
## Claude Code instructions
Add rules that apply only to Claude Code here.2. What to include in an instruction file
Record what an assistant needs to make changes: the working directory for each command, how to check the result and rules that aren't obvious from the code. Replace vague instructions such as "follow the project's style" with a specific convention or a link to its documentation.
The table and sample below describe an example project with a TypeScript frontend. Adjust the commands and paths to match your repository and check that they work.
# Repository instructions
## Setup
- Run frontend commands in the frontend directory.
- Install dependencies with npm ci.
- Start the development server with npm run dev.
## Checking changes
- Run npm run lint and npx tsc --noEmit.
- If a check fails, report the error in your final description of the changes.
## Conventions
- Store shared components in src/components.
- Add interface text to both messages/cs.json and messages/en.json.
- Don't edit files in the generated directory manually.| Area | Example instruction |
|---|---|
| Running the project | Run npm ci and npm run dev in the frontend directory. |
| Checking changes | Run npm run lint and npx tsc --noEmit in the frontend directory. |
| Project structure | Shared components are in src/components; translations are in messages. |
| Conventions | Store interface text in translation files. |
| Generated files | Don't edit the generated directory manually; use npm run generate. |
| Change restrictions | Create database migrations only when explicitly requested. |
3. Where to place the files
Put shared instructions in the repository root. In a larger project, you can add separate AGENTS.md files to directories such as frontend and backend. Each file can describe the commands and conventions for that part of the project.
The AGENTS.md specification gives the file closest to the edited code precedence when instructions conflict. Check your tool's documentation for its exact discovery and loading rules. The `@AGENTS.md` import is Claude Code syntax; don't assume other tools support the same imports.
A Markdown rule doesn't enforce test execution or prevent deployment. Configure required checks in CI, permissions or the relevant tool's settings as well.
4. Keeping instructions and links up to date
Review the instruction file when commands, project structure or workflows change. Keep detailed architecture descriptions in your project documentation and link to them from the instructions. A link to a specific document is more useful than a second copy of the same text.
You can also include links to logs or test environments in AGENTS.md. If several repositories share them or they change often, maintain them in one place and tell the assistant where to look. The same approach applies to project links in general. Record deployed versions in the system that tracks deployments.
5. Linking a repository to AboutTheApp
If you track your app in AboutTheApp, you can point the assistant to its record. Add the app's alias, its unique identifier, to AGENTS.md. The assistant can then use MCP (Model Context Protocol, a protocol for connecting AI tools to external sources) to look up recorded links, versions and customer installations.
In the dashboard, open the app card's Integrate panel and the AGENTS.md and CLAUDE.md section. Copy the provided text into your instruction file. The example below uses my-app as a placeholder alias.
## AboutTheApp
This repository is the app `my-app` in AboutTheApp.
- Links (repository, environments, monitoring, documentation), versions, customer installations and components: AboutTheApp MCP server https://aboutthe.app/mcp, product `my-app`.
- Public profile: https://aboutthe.app/my-app6. Connecting the MCP server
Adding a server address to AGENTS.md doesn't configure the connection. You also need to add the AboutTheApp MCP server to your client and sign in with your account. You'll find the configuration in the dashboard under Account → AI tools (MCP).
Once connected, you can ask questions such as "Where can I find this app's logs?" or "Which version is the customer running in production?". The assistant uses the alias from the file to look up records in AboutTheApp. The server provides read-only access according to the signed-in account's permissions; the answer is only as current as those records.
Don't store passwords, API keys or access tokens in instruction files. Before publishing a file, also check the addresses and identifiers it contains. Configure access to private data through sign-in in your client.
- 1
Add the server to your client
For Claude Code, use the command below. The --scope user option stores the connection for your user account. See the MCP server guide for other clients.
- 2
Complete sign-in
In Claude Code, enter /mcp, select abouttheapp and complete sign-in and access authorization in your browser.
claude mcp add --scope user --transport http abouttheapp https://aboutthe.app/mcpFrequently asked questions
What's the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is an open format for project instructions supported by multiple tools. CLAUDE.md is used by Claude Code. Both use Markdown; you can keep shared instructions in AGENTS.md and import them from CLAUDE.md with the line @AGENTS.md.
Does Claude Code read AGENTS.md?
Yes, direct loading is supported from version 2.1.277. By default, it gives precedence to CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md in the working directory and its parents. Support also depends on client settings. If you use CLAUDE.md, you can add an @AGENTS.md import to it.
How long should an instruction file be?
Keep it focused on concise instructions needed for work in that project. AGENTS.md has no required length. Move detailed procedures and descriptions into separate documentation and link to them from the file.
Can a repository have multiple AGENTS.md files?
Yes. Put shared rules in the repository root and instructions for individual parts of the project in the relevant subdirectories. Check how your tool loads them and resolves conflicts.
Should AGENTS.md include links to documentation, logs and monitoring?
Yes, if they help with work on the project. For frequently changing or shared information, link to a central record rather than maintaining copies in several repositories. Also consider who has access to the repository.
Is an MCP server address in AGENTS.md enough to connect AboutTheApp?
No. The file identifies the app and its data source, but you also need to add the MCP server to your client and sign in. The assistant can then read data available to your account.
In short
Start with commands for running and checking the project. Add specific conventions and links to detailed documentation. Update the instruction file when your workflow changes.
App links and versions in one place
Track them in AboutTheApp and make them available to your AI assistant through the MCP server.