agent-md-refactor

To refactor a bloated AGENTS.md or CLAUDE.md file, extract essential instructions into a minimal root file and move detailed guidelines into linked, categorized topic files under a dedicated directory. This progressive disclosure structure keeps agent instructions streamlined and organized.

Progressive disclosure for agent instruction files is an architecture pattern that keeps only essential guidelines in the root file while moving detailed documentation to linked files. It minimizes root file size and organizes instructions into a small set of categorized topics.

You organize linked documentation files by categorizing the remainder of extracted instructions into a small set of topic files under a dedicated directory. The process involves identifying contradictions, extracting root essentials, categorizing the remainder, creating the file structure, and flagging deletions.

You should restructure your COPILOT.md or AGENTS.md into linked files when the monolithic file has grown unwieldy, contains contradictions, or requires progressive disclosure to maintain instruction clarity. The refactoring process flags redundant or vague instructions for removal.

Yes, you can identify redundant or vague instructions before splitting agent documentation. The refactoring process explicitly flags potential deletions and identifies contradictions during the initial phase before extracting essentials and categorizing the remainder into linked files.

Yes, this refactoring approach works for any monolithic agent instruction format like AGENTS.md, CLAUDE.md, or COPILOT.md. It applies progressive disclosure to extract essentials into a minimal root and categorize the remainder into linked topic files.