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.

The people best positioned to configure AI agents like Claude Code aren't engineers. They're technical writers.

It's a bold claim, so let me back it up.

Welcome to Instruction Manuel! I'm Manny Silva, a technical writer and engineer who spends too much time thinking about documentation, developer experience, and whatever else catches my attention in the tech world.