---
title: "AGENTS.md Specification"
description: "The root project context standard for orienting AI coding agents without system prompt bloat."
section: "concepts"
type: "concept"
created: "2026-08-22"
updated: "2026-08-27"
confidence: "high"
tags: ["agents", "context-engineering", "skills", "workflow"]
canonical: "https://pyweb.dev/wiki/agents-md-spec"
---
# AGENTS.md Specification

**AGENTS.md** is an emerging industry standard markdown file placed at the root of a project workspace to orient AI coding agents (such as Hermes, Claude Code, Cursor, and Codex) as soon as they inspect a repo.

## The Core Philosophy: "Never Run /init"
Auto-generated agent initialization files typically produce hundreds of lines of generic prose describing basic language syntax and obvious git commands. High-signal `AGENTS.md` files are strictly hand-crafted, concise, and focused exclusively on non-obvious project reality.

## Essential Sections of AGENTS.md
1. **Layout & Entry Points:** The high-level file tree and where persistent vs ephemeral files live.
2. **Toolchain & Non-Obvious Commands:** The exact build, test, and typecheck commands (e.g. `uv run ...` or `pnpm test`), highlighting environment quirks like PEP 668 or package manager constraints.
3. **Architecture Seams & Decisions:** References to `CONTEXT.md` and ADR records.
4. **Pitfalls & Hard Guardrails:** Things the agent must NEVER do (e.g. "Do not push directly to main", "Do not mock database calls in unit tests").

## AGENTS.md vs System Prompts
`AGENTS.md` belongs in the project filesystem, not baked into a static system prompt. This allows agent behaviour to evolve dynamically with repository commits and branch checkouts.

## Related
[context engineering](/wiki/context-engineering), [prompt bloat](/wiki/prompt-bloat), [progressive disclosure](/wiki/progressive-disclosure), [ai coding taxonomy](/wiki/ai-coding-taxonomy).

---

## Agent Navigation

cluster: person (170 pages) | betweenness: 0

### References (outbound)
- [Context Engineering](https://pyweb.dev/wiki/context-engineering.md)

### Referenced by (inbound)
- [AI Coding Taxonomy & Agent Experience](https://pyweb.dev/wiki/ai-coding-taxonomy.md)
- [Context Engineering](https://pyweb.dev/wiki/context-engineering.md)

### Evidence (verified primary sources)
- [aihero-dev-homepage-2026](https://pyweb.dev/wiki/raw/articles/aihero-dev-homepage-2026.md) | origin: https://www.aihero.dev/ | ingested: 2026-08-22 | sha256: 231157fed45f82922924a050e09b5b81a443891814fc1d72c874d864a6075419
- [agentic-engineering-trends-2026-synthesis](https://pyweb.dev/wiki/raw/articles/agentic-engineering-trends-2026-synthesis.md) | origin: https://pyweb.dev/wiki/raw/articles/agentic-engineering-trends-2026-synthesis | ingested: 2026-08-24 | sha256: 6c78ca873a4df069f1606e9f68538de7b428633720e48e184fad0ea31b5d2a25
- [aihero-ai-coding-dictionary-2026](https://pyweb.dev/wiki/raw/articles/aihero-ai-coding-dictionary-2026.md) | origin: https://www.aihero.dev/ai-coding-dictionary | ingested: 2026-08-27 | sha256: 52b0a5da7c9f6dd60dfdbf29031bcf6107c2765b6ef5b3a7f96cc607f42b06c7

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt