AI Documentation Dividend

A friend recently asked me what qualities make a great engineering manager, and one of the things I mentioned was risk management – specifically, the value of investing in design artifacts like system diagrams, reference architectures, and clear interface boundaries before diving into execution. In my experience, the hard part was never knowing these things were valuable. The hard part was convincing anyone to pay for them.

That dynamic is shifting in an interesting way. As organizations start investing in agentic AI workflows for software development, there's a new top-down pressure to produce exactly the kind of context-rich documentation that engineering managers have been quietly advocating for years. Agentic systems need well-defined boundaries, clear interface contracts, and accurate architectural references to make good decisions autonomously. Leadership is now asking for these artifacts because AI needs them — and that's creating buy-in that was historically very difficult to generate.

The irony isn't lost on me. Human engineers have always needed this context too. The difference is that "invest in documentation" never made it past a quarterly planning meeting, while "enable our AI agents to work effectively" apparently does. I'm not complaining... I'll take the win! But it's worth naming: if your organization is finally building out these maintainability artifacts for AI, make sure your engineers benefit from them just as much.