liveBook · Manning

AGENTS.md

As explained in Context Engineering

A portable Markdown file that provides project-specific instructions for AI coding agents.

AGENTS.md is a portable Markdown instruction artifact for AI coding agents. It keeps durable, project-specific guidance in a version-controlled file beside the code, so developers do not need to repeat repository rules in every prompt. The open format is stewarded by the Agentic AI Foundation under the Linux Foundation. section 2.4.1 section 11.3.2

A useful shared file can give agents:

  • A repository overview, architecture constraints, and coding conventions. section 2.4.1
  • Build, test, lint, review, and release instructions, including commands to run before reporting completion. section 11.3.2 section 2.5.4
  • Safety boundaries, such as files not to edit, commands requiring approval, and restrictions on secrets or dependencies. section 11.3.2 section 2.4.1
Listing 2.4 Sample AGENTS.md instruction artifact for a backend Python service
# Project guidance for AI agents

## Purpose
This repository implements the customer billing service for an
e-commerce platform.

## Architecture rules
- Keep business logic inside the `services/` layer.
- Do not place domain logic inside API controllers.

## Coding conventions
- Use Python 3.12 syntax.
- Prefer explicit type hints on public functions.

## Validation steps
Before submitting changes:
1. Run `pytest tests/unit`.
2. Run `pytest tests/integration` if the database code was modified.
3. Run `ruff check .` and `black --check .`.

## Safety constraints
- Do not modify files under `migrations/archive/`.
- Do not hardcode secrets, tokens, or credentials.

## Pull request expectations
- Summarize the functional change.
- List risks and backward-compatibility concerns.

This backend service example combines architecture rules, Python conventions, validation commands, safety constraints, and pull request expectations in one file. section 2.4.1

Place the shared AGENTS.md in the repository root. Codex, Cursor, and Aider can discover it directly; Claude Code can use a CLAUDE.md adapter that imports it with @AGENTS.md and adds tool-specific workflow guidance. Other conventions, such as GitHub Copilot’s repository-wide instructions and Cursor’s path-targeted rules, coexist with the shared baseline. section 2.5.4 section 11.3.2

Check the shared instructions across agents

In a Python task-tracker project, ask each agent to summarize the instructions loaded for its session, then add validation that rejects empty task titles and include a unit test. Check that it makes the required changes, follows the dependency rules, runs the validation commands, and reports any commands it could not run. section 2.5.4

File discovery and the amount of guidance injected into active context differ across agents. Artifact names and locations are evolving integration details, so verify each tool’s behavior rather than assuming every agent reads the same instructions. section 2.4.1 section 11.3.2

How Context Engineering covers it

How deep it goes
Works through file contents, cross-agent setup, an adapter, and a validation exercise while noting discovery differences.
Examples
Uses a backend billing service and a Python task tracker with an empty-title validation task.
What it assumes
Assumes a small Python command-line project with pytest and ruff for the integration exercise.
What you can do after
Apply it via Codex, Cursor, Aider, or a Claude Code adapter and check whether agents follow the shared instructions.
How it connects
Connects project instructions with system prompts, skills, version control, and agent context.

Also explained in

Compare how 2 books explain AGENTS.md →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Context Engineering. The section links point to the parts of the book it draws on.