Good tech docs help so many teams

This is my second summer working with AI agents on a daily basis. While using my mobile phone for some multi-agent work, my handset started getting sponsored ads for companies like Okta in the screenshot that accompanies this post. I imagine that means many people are looking at teams of agents working together. Here are some of my takeaways.

During workshops with the Irish Research and Development Group I suggest people should not start multi-agent. In my experience, one well-designed single agent easily outplays a gaggle of downloaded agents.

I give every agent one clear job spec. And I watch that agent do its job before letting it play with a team of agents.

I use process diagrams to illustrate four patterns of agent behaviours: linear pipeline, router, parallel fan-out, and human-in-the-loop. These patterns cover the majority of real business workflows.

When I teach, I share several costly mistakes that I have made that have cost me time and money. I attribute some of the mistakes to my desire to use complex architecture that was unjustified by the workflow.

Tech docs help troubleshoot snags so I log everything at every handoff. I can target what I can see. I cannot fix stealth problems.

High quality tech docs help me dial back multi-agent workflows. I keep numbered pages in my handwritten notes that correspond to the dates I cobble agents together.

This is something I noticed in several of the best Github repos and community plugins that I currently use.