agents-progressive-disclosure

To refactor bloated CLAUDE.md or AGENTS.md files, rewrite them into a compact routing entrypoint that splits always-on guidance from on-demand documentation. This progressive disclosure approach preserves original rule intent while making project-level instructions easier to load and maintain.

Progressive disclosure for agent instructions is a documentation pattern that moves detailed project rules and workflows into targeted on-demand docs. It keeps a compact root file as a router, ensuring AI agents only load specific guidance when needed, reducing context bloat.

Split always-on rules from on-demand documentation by clustering related instructions and classifying contradictions within the original file. Keep critical guidance in the root entrypoint and route detailed workflows to separate docs that agents read only when required.

Yes, this refactoring approach works with GEMINI.md and similar project-level rule files. It applies docs-based routing to any oversized agent instruction file, validating that the rewritten structure still tells future agents what to read while preserving the original rules.

You need to restructure agent instruction files when they have grown too large to load and maintain effectively. If your AGENTS.md or CLAUDE.md contains bloated, contradictory, or clustered rules that hinder agent readability, progressive disclosure is required.

The best way to organize large agent documentation is creating a router-style root file that directs agents to focused reference docs. This prevents context overflow, validates rule preservation, and ensures agents read only necessary instructions for a specific task.