"A few months into working with AI agents on a documentation project, I'd noticed some inconsistency in agent behaviors and decided to do some digging. Turns out the AGENTS.md file in our repo โ the one telling agents how to behave, where things were, and what to escalate โ had grown to over 800 lines, and a few people (or likely their agents) had added rules independently, some subtly contradicting each other.
The agents weren't broken. They were following instructions that didn't serve them well.
In a previous post, I argued that agent configuration files are documentation and that their formats, structures, and purposes map directly to work technical communicators already do. That post covered the what: five doc types (project descriptions, agent definitions, orchestration patterns, skills, and plans/specs) and why writers are well-positioned to create them.
This post goes further. These files are internal documentation, full stop. They encode how your team actually works. And if you don't manage them with the same rigor you'd apply to any internal doc set, they'll degrade in the same ways: outdated content, conflicting guidance, and gaps nobody notices until something breaks."
https://instructionmanuel.com/agentic-docs-are-internal-docs
#TechnicalWriting #AI #AIAgents #AgentConfigs #Documentation #DocsAsCode #LLMs #GenerativeAI #Markdown