agent-md-refactor

Refactoring a bloated CLAUDE.md file involves splitting monolithic instructions into a minimal root file with linked sub-files using progressive disclosure. This structure categorizes rules and minimizes root file size to optimize agent context and instruction clarity.

Progressive disclosure for agent instruction files is an organizational technique that splits monolithic configurations into a minimal root file and categorized, linked sub-files. This hierarchy prevents context token waste and improves overall agent performance.

Agent instruction files accumulate contradictory guidelines over time as rules are added. A refactoring process systematically analyzes instruction content to identify and surface these conflicting guidelines for user resolution before restructuring.

Pruning redundant or vague rules in AGENTS.md requires systematically analyzing instruction content to flag outdated or repetitive guidelines for deletion. This optimization reduces token waste and clarifies the agent's operational boundaries.

Refactoring agent instructions applies to any project-specific configuration file like CLAUDE.md or AGENTS.md. The process analyzes the file's instruction content to categorize rules and build a linked documentation hierarchy regardless of the specific filename.

The best way to organize monolithic agent prompts is applying progressive disclosure principles to split them into a structured, linked documentation hierarchy. This approach categorizes rules, detects contradictions, and prunes vague instructions to minimize root file size.