Skip to content
explainroo
Working with AI agents

AGENTS.md: Writing Instructions for Coding Agents

Updated 4 min read

With explainroo How to Prompt a Coding Agent to Make an Explainer Video
On this page
  1. Include project context and verification commands
  2. Keep instructions short and actionable
  3. Put specialized guidance where it applies
  4. Check compatibility across coding agents
  5. Review the file as project configuration

An AI coding agent working in a Git repository uses an AGENTS.md file for project-specific instructions in Markdown. The file can describe the project, explain how to run its checks, and name important tools or conventions. Coding agents that support the format read the instructions while working in the repository.

A useful AGENTS.md is short, accurate, and focused on guidance the agent needs across many tasks. Use it for essential project context and verification commands. Link to other documentation for details that apply only to certain tasks. Support varies by tool, so check how each agent reads repository instructions before relying on the file.

Include project context and verification commands

Describe the project and its purpose in one sentence. Then explain setup details an agent might otherwise get wrong, such as using a package manager other than npm. When the commands are not obvious, name the ones used to build and type-check the code, as well as those used to test and lint it.

For example, a JavaScript repository that uses pnpm should say so explicitly. A coding agent that assumes npm might run the wrong command or modify the wrong lockfile. Likewise, name the command that verifies a change instead of telling the agent to “test thoroughly.”

Add guidance about architecture or tools only when it changes how the agent should work. A Dynatrace template’s AGENTS.md, for example, tells the agent to consult knowledge-base tools before writing DQL queries or using Strato UI components, and requires build and lint checks. Those instructions give the agent concrete actions tied to that project.

Keep the file focused on repository-wide requirements. A personal preference that applies only to one developer, or a rule that matters for one specialized task, belongs elsewhere unless the repository has adopted it as a shared requirement.

Keep instructions short and actionable

Every instruction adds context for the agent to consider. How much context the agent loads depends on the tool, but instructions that apply to every task deserve special scrutiny. A rule such as “run npm run lint before finishing” is actionable; a long overview of every directory often adds detail the agent can discover by inspecting the repository.

An ETH Zurich study summarized by Philipp Schmid found that, in its evaluated tasks, generated instruction files reduced success by about 3% on average and raised inference cost by more than 20%. Human-written files produced a modest performance improvement, while unnecessary requirements increased reasoning-token use. These results do not show that every instruction file harms performance. They do show why each extra rule needs a clear purpose.

Use the repository’s formatter and linter for style rules they can enforce. They apply the rules consistently and report violations directly. Readers can overlook or interpret prose in AGENTS.md differently. When an instruction needs a longer explanation, point to the relevant documentation rather than copying it into the file. A link to a current guide is easier to maintain than an embedded code sample or a detailed directory map that can go stale.

Put specialized guidance where it applies

A root AGENTS.md should cover work across the repository. For a monorepo or a large codebase, separate instructions by area when the coding agent supports scoped files. A Strapi documentation repository describes root-level instructions and allows area-specific files to add or override guidance within their scope.

Do not assume every tool interprets nested files the same way. Support for AGENTS.md, directory-based instruction inheritance, and targeted instructions varies. VS Code, for example, documents its own custom instruction options, including instructions targeted to particular files. Check the documentation for the specific agent or editor before organizing rules around file scope.

Progressive disclosure keeps the root file lean: put a short instruction in the root and direct the agent to more detailed material when the task calls for it. A specialized task may have its own instructions, scripts, or references, sometimes packaged as an agent skill. The agent then consults that material when relevant instead of carrying it into every task.

Check compatibility across coding agents

Several coding tools support the shared AGENTS.md format, but not all do. Claude Code uses CLAUDE.md for its repository instructions, according to AI Hero’s overview. Other tools may use different file names or instruction mechanisms. A repository that uses multiple agents should check which files each agent reads and keep shared requirements consistent.

If two tools require different filenames, maintain one authoritative set of instructions and provide compatibility files or links where supported. A symbolic link is one option on platforms and tools that handle it consistently. Avoid editing multiple copies by hand. Conflicting versions give agents different instructions.

Review the file as project configuration

Treat AGENTS.md as maintained project configuration. After adding a rule, ask whether it solves a recurring problem, whether the agent can follow it, and whether a script or existing document would handle it better. Remove rules when the project changes or when they duplicate automated checks.

Avoid filling the file with generated summaries. In the study summarized by Schmid, generated files sometimes duplicated existing documentation, and codebase overviews did not help agents find relevant files faster in the evaluated tasks. An overview is still useful when it supplies context the repository does not make discoverable; otherwise, describe the project’s purpose and point to authoritative documentation.

Free and open source

Let your AI agent make the video

explainroo lets a coding agent like Claude Code or Codex make narrated explainer videos and product demos. The voice, the word timing and the rendering run on your own computer, with no API key and no cost per video. Optional outside services use your own key.

Copy this into your AI agent

Make me a short explainer video about [your topic]. Use explainroo for it: run npx --yes explainroo docs and follow what it prints.

Getting started Example videos GitHub

Made with explainroo: How explainroo makes a video

More on working with ai agents

All guides on working with ai agents