agent-md-refactor

To refactor a bloated AGENTS.md file, extract essential universal guidance into a minimal root file and move detailed instructions into a linked, categorized .claude or docs directory. This reduces context load by applying progressive disclosure principles to your agent instructions.

You should restructure your agent instruction files when root documents like CLAUDE.md or COPILOT.md grow beyond 50 lines. At that point, the oversized files create excessive context load and benefit from systematic simplification into linked, categorized documentation.

The best way to organize large agent docs is through a 5-phase process: detecting contradictions, extracting essentials, grouping remaining instructions, creating a categorized file structure, and flagging content for deletion. This creates a minimal root file with linked detailed instructions.

Yes, this documentation refactoring process works with COPILOT.md, CLAUDE.md, AGENTS.md, and similar root documents. It standardizes the structure and navigation across different projects by creating a minimal root file with a linked, categorized documentation directory.

Progressive disclosure applies to agent instructions by keeping the root document minimal with only universal guidance, then linking to categorized files in a .claude or docs directory for detailed instructions. This structured approach enables reusable documentation and reduces context load.

A limitation of refactoring agent docs into linked files is that the process requires flagging content for deletion during the restructuring phase. Additionally, the 5-phase process specifically targets root documents exceeding 50 lines and may not suit minimal instruction files that already follow progressive disclosure.