agent-md-refactor

To refactor bloated agent instructions, split the monolithic file into a minimal root file containing universal essentials and 3 to 8 linked topic-specific documents. This process applies progressive disclosure, making categorized guidelines easier to navigate and maintain.

Progressive disclosure organizes agent instructions by keeping a minimal root file with universal rules and linking to detailed, categorized topic documents. This structure prevents monolithic files like CLAUDE.md from becoming overly long, contradictory, or hard to navigate during onboarding tasks.

Organizing contradictory instructions involves detecting conflicting or mutually exclusive entries within your COPILOT.md and surfacing them for user resolution. The remaining valid guidelines are then grouped into self-contained topic documents with clear names.

Yes, you can split agent guidelines by extracting universal project-wide rules into a minimal root file and moving the rest into 3 to 8 linked documents. This restructuring groups remaining guidance into self-contained topic files with clear names and templates.

The best way to prune agent documentation is to flag vague, redundant, or obsolete instructions for deletion, reducing the maintenance burden. This process isolates universal essentials and outputs a verification checklist to ensure the cleaned file structure remains accurate.

You need to restructure monolithic agent guidance when files like AGENTS.md become overly long, contradictory, or hard to maintain during documentation tasks. Restructuring produces a concise, discoverable file layout that separates universal rules from topic-specific details.