agent-md-refactor

To refactor a monolithic CLAUDE.md file, apply progressive disclosure to split long instructions into a minimal root file and linked Markdown documents. This extracts universal rules and moves context-specific guidelines into categorized files for better maintainability.

Progressive disclosure for agent instructions is an organization method that keeps essential details in a root file and moves less critical instructions into linked, categorized Markdown documents. This structure improves clarity and makes agent instructions easier to process and manage.

Resolving contradictions in AGENTS.md documentation involves analyzing the file to identify conflicting instructions and extracting essential universal rules. The refactoring process flags vague or redundant instructions for deletion to ensure consistent agent behavior.

Yes, you can split agent instructions by categories like testing and git workflow. The refactoring process organizes content by extracting context-specific details from the root file and moving them into separate categorized Markdown files such as typescript.md or testing.md.

The best way to maintain long Markdown agent instruction files is restructuring them via progressive disclosure. This separates essential universal rules into a concise root file and links to categorized documents, resolving contradictions and eliminating redundant instructions.