agent-md-refactor

You refactor bloated agent docs by applying progressive disclosure, moving detailed instructions into linked, categorized files under a .claude directory while keeping a concise root reference.

Progressive disclosure is a structuring technique that minimizes the root agent document by linking out to self-contained, topic-specific guideline files, preventing context bloat and ensuring consistent execution.

You organize guidelines by creating topic-specific markdown files such as code-style.md, git-workflow.md, and architecture.md inside a dedicated .claude directory, linking them from the root file.

You need linked files when your root agent instructions become bloated, making it difficult to maintain actionable, self-contained guidance for categories like typescript, testing, and architecture.

Yes, keeping a minimal root document with linked, categorized guideline files enables teams to safely maintain structured, actionable instructions across topics like git workflow and code style.

A single root file becomes bloated and hard to maintain, reducing execution consistency and making it difficult to safely update self-contained guidelines for specific topics like testing or architecture.