Guide · Updated June 13, 2026
How to Review AGENTS.md and CLAUDE.md Repositories
Instruction files are now workflow assets. They shape how agents inspect, modify, test, and report on a repository. Treat them as operational policy, not just documentation.
Review scope and precedence
A good AGENTS.md or CLAUDE.md file defines project conventions, allowed commands, test expectations, coding style, review boundaries, and handoff format. It should not bury risky instructions in vague prose.
- Check whether instructions are global, repository-specific, or directory-specific.
- Confirm that test commands and approval rules are concrete.
- Look for explicit prohibited actions: secrets, production writes, destructive commands, and external posts.
Quality signals
The highest-value instruction repositories include examples, fixtures, expected output, and failure behavior. Generic prompt collections are lower value unless they are connected to a repeatable task.
- Strong: task-specific policy for PR review, CI triage, release notes, or incident briefing.
- Weak: generic be helpful instructions with no files, tests, or permissions.
- Risky: instructions that ask the agent to bypass review or run broad shell commands.