Repository Inspection

15.1. Repository Inspection — Understanding the Codebase Before Touching It

The three core tools for exploration

search_files (ripgrep-based, described in 8.2) is the main tool for locating relevant code before making changes — far faster than skimming file by file. Combine it with read_file to see the details, and terminal to run quick investigation commands (git log, git blame, tree).

AGENTS.md — the project map that already exists

As stated in 7.2, if the repo has an AGENTS.md, Hermes automatically loads the merged chain from the repo root down to the working directory — this is usually the best starting point before doing a manual investigation yourself, because it contains conventions that the maintainers have already written down.

Notes

• Always start a development task by having the agent investigate first (“find the files related to X before fixing”) instead of letting it jump straight into fixing — this reduces the risk of fixing the wrong place due to a misunderstanding of the structure.
• For a large repo without an AGENTS.md, consider using /learn (10.4) to have the agent build a knowledge-base skill about the project architecture — useful if you plan to return to work on this repo many times.
• Avoid running Hermes directly from a bare repo root when using worktrees — always work inside a specific worktree directory so the agent has a clear scope.