agents-md-best-practices

Refactor AGENTS.md by reorganizing content into a minimal root file plus linked category docs under docs/agents/. This process applies progressive disclosure by extracting root essentials, grouping remaining instructions, and flagging deletions.

Detect contradictions in AGENTS.md by auditing the file for conflicting directives before restructuring. The refactoring process surfaces these contradictions for resolution to ensure a reproducible and clean documentation output.

Split a large AGENTS.md by clustering instructions into categories and creating one linked file per group under docs/agents/. This approach distills a concise root file with essential project descriptions and build commands while distributing detailed instructions.

Identify essential instructions for the root AGENTS.md by extracting a concise one-sentence project description, non-standard build or typecheck commands, and items relevant to every task. All other content is grouped into category docs.

You can draft AGENTS.md refactoring changes without applying them by specifying a draft-only mode. This generates proposed templates and deletion flags for user confirmation without modifying the original files.

Redundant or vague instructions are flagged for deletion during AGENTS.md audits. The process requires user confirmation before removing these flagged items to prevent accidental loss of potentially relevant directives.