🧠Building with AI7 min readUpdated: Nov 16, 2026

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.

👨‍💻
Roman
AboutTheApp

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.

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.

AGENTS.md
# 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.
AreaExample instruction
Running the projectRun npm ci and npm run dev in the frontend directory.
Checking changesRun npm run lint and npx tsc --noEmit in the frontend directory.
Project structureShared components are in src/components; translations are in messages.
ConventionsStore interface text in translation files.
Generated filesDon't edit the generated directory manually; use npm run generate.
Change restrictionsCreate 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.

Instructions don't replace automated checks

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.

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.

AGENTS.md
## 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-app

6. 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.

Keep credentials separate

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. 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. 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/mcp

Frequently 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.

AboutTheApp

App links and versions in one place

Track them in AboutTheApp and make them available to your AI assistant through the MCP server.