agent-md-refactor

To refactor a monolithic AGENTS.md file, split long instructions into categorized, linked documents. This progressive disclosure structure keeps a minimal root file for concise overview and navigation, placing detailed guidelines in separate topic-specific files for readability.

Progressive disclosure for agent instructions is a structural technique that keeps essential project descriptions in a minimal root document while placing detailed, categorized guidance in explicitly linked files, preventing large monolithic files from overwhelming readers and hindering execution.

Organize CLAUDE.md files by creating a minimal root document describing the project and navigation, then splitting detailed instructions into categorized linked files. This explicit navigation structure improves readability and allows updating guidelines without breaking workflows.

You need to split root and linked agent instruction files when large, monolithic documents overwhelm readers and hinder quick execution. This technique suits onboarding new teammates, auditing existing instructions, and updating guidelines without disrupting established workflows.

The best way to structure agent docs for onboarding is using progressive disclosure: maintain a minimal root document for concise overview and navigation, splitting detailed guidance into categorized linked files to improve readability and maintainability for new teammates.

Yes, progressive disclosure works for auditing existing agent instructions. By refactoring bloated monolithic files into a minimal root and categorized linked documents, you can easily review, update, and maintain specific guidelines without breaking existing workflows.