agent-md-refactor

Restructure bloated agent instruction files by refactoring monolithic configurations into a structured hierarchy using progressive disclosure. This splits essential root instructions from detailed topic-specific guidelines into linked markdown files for better maintainability.

Progressive disclosure for agent documentation is an organizing principle that separates universally applicable instructions from topic-specific guidelines. It structures information so essential rules remain in a root file while detailed guidelines link out to categorized sub-files.

Split a large CLAUDE.md or AGENTS.md file by transforming the monolithic document into a concise root file with links to categorized sub-files. This separates code style, testing, and Git workflow guidelines into distinct linked markdown files.

The best way to organize agent configuration markdown is applying progressive disclosure principles to separate essential instructions from detailed topic-specific guidelines. This approach addresses poor maintainability and information overload by creating linked, categorized markdown files.

Refactor your agent instructions when documentation becomes overly long and complex, causing information overload and poor maintainability. A 500-line monolithic configuration file is a strong indicator that splitting into a structured hierarchy is necessary.