agent-md-refactor

Refactoring a bloated AGENTS.md involves applying progressive disclosure principles to minimize root content and relocate detailed instructions into organized, linked topic-specific files. This workflow detects contradictions, extracts essentials, and flags obsolete content for deletion.

Progressive disclosure is an organizational approach that keeps universal rules and project context in a minimal root file while moving task-specific guidelines into categorized, linked documents. This improves clarity and maintainability for large instruction sets.

Yes, the refactoring workflow is applicable to projects with CLAUDE.md, COPILOT.md, AGENTS.md, or similar root documentation files. It restructures large instruction sets into topic-specific linked files using a five-phase workflow.

Organize linked documentation by categorizing related instructions into topic-specific files, such as TypeScript conventions, testing guidelines, or architecture patterns. The five-phase workflow enforces grouping related instructions and linking them from a minimal root file.

The best way to handle vague or obsolete instructions is to use a safe refactoring workflow that detects contradictions, extracts essential guidelines, and explicitly flags obsolete or vague content for deletion during the restructuring process.

You should restructure root agent docs into separate linked files when the instruction set grows unwieldy, making it difficult to maintain. Progressive disclosure minimizes root content while preserving universal rules and relocating detailed instructions for better clarity.