agent-md-refactor

Refactoring bloated AGENTS.md or CLAUDE.md files involves extracting universal instructions into a minimal root file and organizing specialized topics into linked documentation. This progressive disclosure approach reduces context waste and maintenance burden while preserving essential agent instructions.

Progressive disclosure for agent instruction files keeps only universal rules in the root document and moves specialized topics into categorized, linked docs. This structure minimizes the root file size, reduces context token consumption, and logically separates instructions for easier maintenance.

Yes, contradiction detection scans your COPILOT.md and other agent instruction files to surface conflicting rules before restructuring. Identifying these conflicts early ensures the resulting minimal root and linked documentation hierarchy remains consistent and accurate.

Organizing agent instructions into a minimal root and linked documentation requires intelligent categorization. The process extracts essentials for the root file, groups remaining instructions into logical categories, creates a hierarchy of topic-specific linked files, and flags outdated or vague instructions for deletion.

You should clean up large agent instruction files when context load becomes excessive or maintenance grows difficult. If your AGENTS.md or CLAUDE.md contains contradictory, outdated, or overly vague instructions, restructuring into a minimal root with linked docs resolves these issues.