hierarchical-agents

Create a hierarchical AGENTS.md system with a lightweight root file (100–200 lines) and detailed sub-folder guidance. This structure minimizes token bloat by using nearest-wins hierarchy and Just-In-Time indexing, so agents load only the context they need for their current directory.

A hierarchical AGENTS.md is a multi-level documentation structure where a compact root file provides index-level guidance with links to sub-folders, and sub-folder AGENTS.md files override root guidance with technology-specific conventions. Agents resolve context by reading the nearest file first, reducing unnecessary token consumption.

Yes. Hierarchical AGENTS.md is designed for monorepos and multi-package projects. The root file indexes all packages with links, while each package sub-folder contains its own AGENTS.md with concrete file examples, executable commands, and JIT directory maps tailored to that package's structure.

JIT indexing uses path hints, glob patterns, and quick-find commands embedded in sub-folder AGENTS.md files. These guide agents to relevant files and executable commands without listing entire directory trees, enabling efficient on-demand lookups that reduce token overhead.

The root AGENTS.md is lightweight, containing only index-level guidance and links to sub-folders. Sub-folder AGENTS.md files are deeper and technology-specific, with conventions, concrete examples, and executable commands. Sub-folder files override root guidance for precise, local context.

Create sub-folder AGENTS.md files for critical packages or directories with distinct technology stacks, build patterns, or dependencies. The nearest-wins hierarchy ensures agents find package-specific guidance first, reducing irrelevant token consumption and improving accuracy.