Back to glossary

README.md

Plain-Language Definition

README.md is the guide written for humans that sits at the project root and optionally in subdirectories. While AGENTS.md serves agents, README.md serves people browsing in GitHub, an IDE, or a knowledge-base tool. It explains what the project is and how to navigate it.

Technical Definition

A human-facing per-directory guide optimized for browsing. Every aDNA instance MUST have a root README.md. Subdirectory README.md files are OPTIONAL — create them when human navigation would benefit. README.md complements AGENTS.md: agents read AGENTS.md for machine-optimized instructions; humans read README.md for narrative context. (aDNA Standard §4.6)

Usage Examples

  • This vault’s root README.md is the first thing a human sees on GitHub — it explains what aDNA.aDNA is, how to explore the vault, and where to start.
  • The dual README.md / AGENTS.md pattern embodies the dual-audience principle: same content, two registers.

See Also