audit-agents-md

To audit CLAUDE.md and AGENTS.md files, evaluate their density, staleness, redundancy, and actionability. This process verifies source-of-truth relationships and checks repository-specific evidence to produce concrete PASS, WARN, or FAIL findings with recommendations.

Agent behavior drift often occurs because CLAUDE.md or AGENTS.md instruction files contain stale guidance or weak instructions. Auditing these files identifies missed opportunities for clearer behavior and redundant rules caused by recent project modifications.

Checking instruction file density and actionability involves evaluating whether rules are inferable, structurally sound, and cost-effective. The audit verifies source-of-truth relationships and reports PASS, WARN, or FAIL findings with evidence and recommendations.

Before editing an AGENTS.md file, source resolution determines whether the target file is the editable source, a symlink, or a managed copy. This step ensures you only recommend edits to the actual source-of-truth file.

You should review agent instruction files for redundancy and staleness after a project changes significantly, when agent behavior seems off, or when someone explicitly asks for an instruction-file review to catch duplicated rules.

PASS, WARN, or FAIL findings represent the results of evaluating instruction file quality against metrics like density, actionability, and staleness. Each finding includes concrete evidence and recommendations for improving the agent instructions.