Hierarchical Agents Documentation Generator

Purpose

Create a hierarchical AGENTS.md system for codebases that enables AI coding agents to work efficiently with minimal token usage. Generates lightweight root documentation with detailed sub-folder guidance following the "nearest-wins" principle.

When to Use

• Creating AGENTS.md documentation for a new project

• Setting up AI agent guidance for a monorepo

• Optimizing existing documentation for token efficiency

• Implementing JIT (Just-In-Time) indexing patterns

Process

Follow these phases in order. See references/generation-process.md for complete details.

Phase 1: Repository Analysis

Analyze the codebase:

• Repository type (monorepo, multi-package, simple)

• Technology stack (languages, frameworks, tools)

• Major directories (apps, services, packages)

• Build system and testing setup

• Key patterns, conventions, anti-patterns

Output: Structured map of the repository before generating any files.

Phase 2: Generate Root AGENTS.md

Root must be lightweight: ~100-200 lines maximum, universal guidance only. Acts as index and navigation hub. Agents read the closest AGENTS.md to the file being edited — sub-folder files override root (nearest-wins).

Create root file with these sections:

• Project Snapshot (3-5 lines)

• Repo type

• Primary tech stack

• Note about sub-package AGENTS.md files

• Root Setup Commands (5-10 lines)

• Install dependencies, build all, typecheck all, test all

• Universal Conventions (5-10 lines)

• Code style (TypeScript strict? Prettier? ESLint?)

• Commit format (Conventional Commits?)

• Branch strategy

• PR requirements

• Implementation Rules (2-3 lines) — see example below

• Development Workflow (5-7 lines) — see example below

• Security & Secrets (3-5 lines)

• Never commit tokens

• Where secrets go (.env patterns)

• PII handling

• JIT Index - Directory Map (10-20 lines) — see example below

• Reference files by path, not content

• Provide search commands that agents can execute

• Acceptance Criteria (3-5 lines)

• Pre-PR checklist

• What must pass

Example Implementation Rules:

Implementation Rules

Before adding ANY external dependency (gems, npm packages, GitHub Actions, Docker images, APIs, CDN links):

• Use WebSearch to verify the latest stable version BEFORE implementation
• Never trust training data for version numbers

Example JIT Index:

JIT Index (what to open, not what to paste)

Package Structure

• Web UI: apps/web/ -> see apps/web/AGENTS.md
• API: apps/api/ -> see apps/api/AGENTS.md
• Shared packages: packages/**/ -> [see packages/README.md]

Quick Find Commands

• Search function: rg -n "functionName" apps/** packages/**
• Find component: rg -n "export.*ComponentName" apps/web/src
• Find API routes: rg -n "export const (GET|POST)" apps/api

Example Development Workflow:

Development Workflow

• Before coding -> describe approach -> wait for approval
• Ambiguous requirements -> ask first
• If task touches >3 files -> decompose first
• After coding -> list breakage risks + suggest tests
• Bug fix -> write failing test -> fix until green
• When corrected -> add lesson to .agents/lessons/

Phase 3: Generate Sub-Folder AGENTS.md Files

Sub-folders have MORE detail than root — specific patterns, technology-specific conventions, real file examples from the codebase.

For EACH major package/directory, create detailed AGENTS.md:

• Package Identity (2-3 lines)

• Setup & Run (5-10 lines)

• Patterns & Conventions (10-20 lines) - MOST IMPORTANT

• Touch Points / Key Files (5-10 lines)

• JIT Index Hints (5-10 lines)

• Common Gotchas (3-5 lines)

• Pre-PR Checks (2-3 lines)

Key: Patterns & Conventions must include real file paths with DO/DON'T examples.

Phase 4: Special Considerations

Adapt templates for specific package types (Design System, Database, API, Testing). See references/generation-process.md for specialized templates.

Directory Structures

Monorepo

AGENTS.md # Root (lightweight) apps/ web/AGENTS.md # Frontend details api/AGENTS.md # Backend details packages/ ui/AGENTS.md # Design system details shared/AGENTS.md # Shared code details

Simple Project

AGENTS.md # Root (can be more detailed) src/ components/AGENTS.md # Component patterns services/AGENTS.md # Service patterns

Quality Checklist

• Root AGENTS.md is under 200 lines

• Root links to all sub-AGENTS.md files

• Each sub-file has concrete examples (actual file paths)

• Commands are copy-paste ready

• No duplication between root and sub-files

• Every DO has a real file example

• Every DON'T references real anti-pattern

• All paths are relative and verified to exist

• Only major packages/domains have AGENTS.md — not every directory

Maintenance

Update AGENTS.md when:

• Adding new packages or major directories

• Changing build/test commands

• Establishing new conventions

• Refactoring project structure

Related Resources

• references/generation-process.md - Complete step-by-step generation process with templates