agent-md-refactor

To refactor a long agent instruction file, restructure the monolithic Markdown into a concise root file and linked sub-files. This progressive disclosure organizes detailed instructions into separate categorized documents for improved readability.

Progressive disclosure for agent instructions is the process of splitting a monolithic configuration file into a concise root overview with links to detailed, categorized sub-files, making the hierarchy easier to navigate.

Resolving contradictory instructions in a CLAUDE.md or AGENTS.md file involves refactoring the monolithic document to identify conflicts, address contradictions, and flag redundant content for deletion during the restructuring process.

You should split monolithic agent instructions into separate files when the configuration becomes overly long and complex, such as a 500-line file, to distill it into a single-page overview with links to detailed sections.

Refactoring agent instructions preserves existing content categories by organizing them into linked sub-files. It categorizes detailed instructions for specific areas like code style, testing, and Git workflow into separate, maintainable documents.