liveBook · Manning

AGENTS.md

As explained in Vibe Engineering

AGENTS.md is a tool-agnostic convention for a repository-root Markdown file that supplies project context and instructions to AI agents.

Project conventions stated once in a conversation can disappear during context compaction. AGENTS.md puts durable project instructions in a versioned Markdown file at the repository root, where agents can load them into a new session. Shared instructions can reduce inconsistent behavior across agents, but only if each tool actually reads them. section 3.5.2 section 5.4.1

Tool support is not universal, and accounts of individual tools’ behavior can conflict. Verify loading with the tools and configurations your team uses; a missing instruction file may fail silently. Keep genuinely tool-specific instructions in the relevant tool’s own file, or use it as a pointer to shared rules where supported. section 5.4.1 section 3.5.2

Start small and make the file useful at the point of work:

  • Write roughly 20 lines covering conventions, gotchas, and how to run tests. Add commands and architecture constraints that agents need repeatedly. section 10.8.4 section 5.4.1
  • Point to accessible documentation rather than duplicating it. Move detailed examples to files loaded when relevant, and remove redundant or contradictory instructions. section 9.2.3
  • For a larger repository, use the root file to route agents to domain-specific instructions and shared architectural rules. Confirm that the agent follows those references. section 10.1.1
Listing 10.1 Hierarchical AGENTS.md - root as router, package as domain expert
# Root AGENTS.md (context router)
To modify the checkout flow, read @packages/checkout/AGENTS.md
To add a shared utility, read @libs/AGENTS.md
To understand service boundaries, query the project graph: nx graph --focus=checkout
Deprecated packages are tagged with `status:deprecated` - never modify them.
Convention: all inter-service communication via message queues. Never direct HTTP.
# packages/checkout/AGENTS.md (domain-specific)
This is the production checkout service.
Owner: payments-team (Slack: #payments-eng)
SLA: 99.99% - changes require payments-team approval.
DO NOT: make direct DB calls. All data access via message queue (see ADR-047).
ALWAYS: run affected tests and lint before submitting.
Testing: property-based tests in __tests__/properties/ - add new ones for any
 new business rule.

A root file routes agents to package instructions and a dependency graph; a package file adds ownership, constraints, and verification steps. section 10.1.1

Instructions are advisory, not an enforcement boundary. An agent can ignore a prohibited path or invent a command. Use external controls such as pre-commit hooks, CI gates, and sandboxes when violations must be prevented or caught; continue to review and test generated changes. section 5.5.1 section 5.8

Treat the file as maintained engineering infrastructure, not a one-time prompt. Audit it before switching to a cheaper model: bloated or misleading context can produce worse output and more retries. Shared standards improve consistency, but their governance and maintenance cost may not be worthwhile for every small team. section 9.1.3 section 5.8

How Vibe Engineering covers it

How deep it goes
Provides a starting checklist, hierarchical examples, context-audit guidance, and an explicit distinction between advisory rules and enforcement.
Examples
Uses payment-service conventions, a root-to-package instruction hierarchy, and a rules-file audit to illustrate practical configurations.
What you can do after
Operate/configure it by writing concise project rules, checking tool loading, and pairing advisory instructions with external controls.
How it connects
Connects context compaction, context engineering, monorepos, dependency graphs, and agent policies.

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 Vibe Engineering. The section links point to the parts of the book it draws on.