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

Workflow

Step 1: Discover repository shape

• Collect the top-level tree and major subdirectories
• Identify package roots, module roots, and major domain folders
• Locate docs indexes, architecture docs, and runbooks
• Capture build, test, lint, and run entrypoints from real config files

Step 2: Read the current map and deeper docs

• Open AGENTS.md if it exists
• Open the main onboarding docs first: README, architecture docs, and docs indexes
• Open the exact files that define task runner commands and CI gates
• Note which docs already serve as the system of record

Step 3: Inspect recent change signals

• Review recent git history for renamed paths, new packages, retired directories, and workflow changes
• Check whether new docs or generated references replaced older explanations
• Check whether CI or task runners added or removed validation steps

Step 4: Compare map versus reality

• Verify that listed paths still exist
• Verify that listed commands still exist and still match task runner or CI usage
• Verify that architecture or package boundaries still match current layout
• Verify that linked docs still exist and remain the best source of truth

Step 5: Rewrite for compression and clarity

• Keep only high-value navigational content
• Collapse repeated guidance into one canonical section
• Replace prose-heavy explanations with stable file paths and exact commands
• Remove outdated paths, retired tools, and stale historical detail