A proposed convention for the .agents/ directory to prevent context bloat and improve agent reasoning in complex codebases.
What it is, and how people use it
A proposed convention for the .agents/ directory to prevent context bloat and improve agent reasoning in complex codebases. It sits on the AGENTS.md & Design.md shelf of the catalog, maintained by @bgreenwell.
Why builders keep it installedAGENTS.md & Design.md benefits
AGENTS.md tells any coding agent how to build, test and ship inside your repo in one screen. Onboarding time for agents drops from a dozen correction turns to none.
Declare which commands are safe, which files are off-limits and how migrations run. The agent respects the guardrails instead of discovering them by breaking things.
One file serves Copilot, Claude Code, Codex and Cursor. It is becoming the industry's shared README-for-robots, checked into the repo where it stays fresh.
The convention is to update the file in the same PR that changes the build. Your agent context never goes stale because the team owns it like any other doc.
Contributorsloading from GitHub…
Languagesestimated from snapshot
- TypeScript 61.3%
- Shell 38.7%