Markdown Mayhem : Taming the Agentic Documentation Explosion

As software engineering enters an era of agentic development—where large language model (LLM)-based agents increasingly participate as autonomous collaborators—the role and form of documenta- tion is undergoing a profound transformation. Traditional human- centered artifacts such as READMEs and developer guides are be- ing augmented, and in many cases supplanted, by agent-facing instruction files including AGENTS.md, .cursorrules, CLAUDE.md, SKILLS.md, and other tool-specific manifests. While these artifacts promise more precise agent behavior and faster onboarding for automated contributors, their unchecked proliferation has intro- duced a systemic documentation failure mode: Markdown Mayhem. This position paper highlights an emerging documentation crisis in agentic software engineering, where too many agents continually update too many markdown files, creating ambiguity, redundancy, and erosion of authoritative truth. We argue that without princi- pled governance, agent-oriented documentation risks undermining both human comprehension and agent reliability, and we propose foundational directions for restoring coherence.