agent-md-refactor

You can refactor a bloated CLAUDE.md by extracting universally applicable rules into a minimal root file and moving task-specific details into linked topic files. This progressive disclosure approach reduces context waste and maintenance overhead.

Progressive disclosure for agent instruction files is an md-organization strategy that separates universal root instructions from themed markdown documents. It replaces monolithic files with a minimal root linking to focused docs, minimizing context loading costs.

Split your AGENTS.md into linked topic files when it exceeds recommended length, mixes unrelated topics, or contains conflicting guidelines. These issues create noise, cause contradictions, and increase token usage during agent operations.

Yes, you can detect contradictions in your COPILOT.md before reorganizing it by scanning for conflicting instructions. The refactoring process surfaces contradictions as questions for resolution before extracting universal root instructions and grouping remaining content.

Organize remaining content into themed markdown files by grouping related details into 3 to 8 clear topic files with consistent templates. The process also verifies cross-file links and recommends deleting vague, redundant, or outdated instructions.

A limitation of progressive disclosure for agent docs is the potential for broken cross-file links if templates are not properly verified. Additionally, automated pruning recommendations might flag vague or outdated instructions for deletion that still hold niche relevance.