4 posts tagged with "Agents"

Over the years, I've spoken to a lot of engineering teams about documenting their software architecture. Different industries, different sizes, different tech stacks. But when I ask what their biggest problem is, the answer is nearly always the same: keeping it up to date.

Nobody I speak to thinks documentation doesn't matter. Most teams are already documenting their architecture, their specs and their APIs. What they struggle with is keeping it all up to date as things change. The information is scattered across the organization: diagrams in one tool, docs in a wiki, specifications in repositories, each in a different place for a different audience. It's no wonder it's hard to keep up to date.

The code moves on, and the docs don't. Keeping them current starts to feel like a job in itself. If there's one problem everyone shares with documentation, it's that it goes out of date.

In this post, I want to dig into that drift: why it happens, what it costs, and how you can bring your own models to EventCatalog to keep your architecture knowledge in sync across your organization.

Architecture decision records (ADRs) are growing in popularity, and they're becoming the standard way to capture an organization's decisions and the conversations behind them.

Teams spend time debating options and writing them up. The ADR goes into a GitHub repository or a document, and people may refer back to it, if you're lucky. But the code keeps changing across the organization, with no automated checks against those ADRs.

I'm happy to share a new workflow in EventCatalog that lets you document your ADRs and add automated checks to make sure code changes adhere to them.

More teams are moving AI agents from demos into real systems. Agents are reviewing payments, answering support questions, querying internal data, calling MCP servers, creating tickets, summarizing incidents, and producing work that downstream systems depend on.

That changes the architecture. If an agent consumes information, calls tools, writes data, or produces artifacts, it needs to be visible in the same place as the rest of your system.

EventCatalog 3.41.0 adds first-class agent documentation. You can now document agents alongside your domains, services, events, commands, data stores, tools, and flows.

I've been using Claude Code and Cursor every day to work on EventCatalog, and I kept running into the same frustrating thing — the agent would confidently spit out frontmatter that didn't exist, point at folders we'd renamed months ago, or call an API that changed two releases back. I'd read the diff, sigh, and fix it by hand. Every time.

It's not really the agent's fault. It's working from a snapshot of the web that's months (or years) out of date, and EventCatalog moves fast. So I kept asking myself: why are we making agents guess what our API looks like when the answer is already sitting in node_modules?

That's what shipped in 3.35.1. The full EventCatalog docs are now bundled inside the npm package, version-matched to whatever you have installed. No more guessing. No more stale snippets. The agent reads the same docs you do.