agents-md-mapper

AGENTS.md Mapper

Overview

Maintain a concise, current AGENTS.md for a repository as the codebase changes. Treat the file as a navigational map for future coding agents: show where to start, where important things live, how to validate changes, and which deeper docs outrank the map.

When to Use

• Create a new AGENTS.md for a repository that does not have one
• Refresh an existing AGENTS.md that may be stale after refactors, path moves, package splits, or architecture changes
• Update the map after tooling, tests, CI, docs, or ownership signals changed
• Point AGENTS.md at new architecture docs, runbooks, or generated references that became the source of truth
• Add lightweight checks that detect drift between AGENTS.md and repository reality

Core Contract

1. Keep the map compact

• Prefer roughly 90 to 100 lines
• Prefer bullets over paragraphs
• Prefer concrete paths and commands over abstract advice
• Link to deeper docs instead of copying them

2. Treat repository evidence as the source of truth

• Read the repository tree before writing claims about structure
• Read actual config files before listing commands
• Read CI workflows before describing validation
• Read docs and architecture references before summarizing boundaries
• Read recent git history before carrying forward old paths or retired modules

3. Optimize for agent legibility

• Surface entry points, domain boundaries, and validation commands first
• Make the navigation order obvious
• Remove stale or duplicated sections aggressively
• Normalize heading order so future updates stay mechanical

4. Omit unsupported detail

• If evidence is weak, omit the claim
• If a detail is volatile, point to its source doc instead of embedding it
• If two docs disagree, prefer the one supported by current code and CI

Inputs to Inspect

Inspect repository evidence, not guesswork:

• Current top-level tree and major subdirectories
• Key top-level files such as README, pyproject.toml, package.json, Cargo.toml, Makefile, justfile, or task runner configs
• Existing AGENTS.md, if present
• ARCHITECTURE.md, docs/, runbooks, plans, references, and generated indexes
• CI workflows and automation config
• Recent git history, especially merges, path renames, retired modules, and tooling changes
• Ownership signals such as CODEOWNERS, package manifests, and boundary-enforcement config