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](apps/web/AGENTS.md)
- API: `apps/api/` -> [see apps/api/AGENTS.md](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

hierarchical-agents