Architecture diagrams often lag behind code because their upkeep competes with implementation work. A coding agent can help assemble a draft from context it can inspect, but a draft is not an architectural decision. The safer workflow is to let automation handle repetitive edits and make the human review surface explicit.
Keep the model reviewable
In tlDiagram, diagrams are built from elements, connectors, and views. An element can represent a system, service, database, or other architectural participant; connectors express relationships; views organize what is visible at a particular level. A nested view lets a reader move from a broad context to more detailed contents without putting every class and queue on one canvas.
That structure gives an agent concrete operations to perform, but it does not settle questions such as whether two services belong to one boundary, whether a dependency is important, or whether a relationship is a runtime call or an ownership link. Those questions need team context. Treat generated names, inferred edges, and descriptions as proposals to inspect.
Connect through the MCP server
The open-source tld project includes an MCP server launched with tld mcp. It communicates over stdio, the standard input and output transport used by many MCP clients. The documented tools cover creating or updating elements, connecting and removing items, managing nested views, querying and inspecting the workspace, rendering a view as Mermaid, validating, and pulling current YAML.
A typical client configuration points to the installed executable and chooses the project directory as its working directory:
{
"mcpServers": {
"tld": {
"command": "tld",
"args": ["mcp"],
"cwd": "/path/to/your/project"
}
}
}When started, the MCP process checks for a running tld serve instance and starts one in the background if needed. It uses the detected YAML workspace, or the workspace selected with -w; without one, it uses the configured database target. This detail matters: tool calls can modify real diagram data. Agree on the working directory and target before asking an agent to make changes.
Ask for bounded work
Give an agent a narrow task with constraints. “Map the request path for checkout from the API entry point through its persistence dependencies” is more reviewable than “diagram the whole application.” Name the intended view level, the source material it should inspect, and any conventions the team already uses. Ask it to preserve existing identities and avoid deleting ambiguous elements.
For an initial pass, have the agent list candidate elements and relationships before it writes them. Then let it apply a small batch, validate, and show the resulting plan or rendered view. The MCP integration exposes a validation tool; the CLI also offers tld plan and tld validate for inspecting and checking changes. A short diff is easier to evaluate than a large rewrite, especially when the architecture is already maintained by a team.
Review meaning, not just syntax
Validation can catch structural problems and report architectural warnings, but it cannot establish that the picture matches production reality. Review whether the named components exist, whether arrows represent actual dependencies, whether the level of detail fits the audience, and whether ownership or trust boundaries have been interpreted correctly. Where available, keep links from elements to source files or symbols so reviewers can follow the evidence.
For changes that matter, put the diagram update alongside the code change or another established review artifact. The repository describes YAML workflows and Git-oriented use, and the docs explain how an optional .tld/ workspace stores version-controlled elements and connectors. A reviewer can then see both the changed model and its rationale. Avoid treating agent output as automatically approved simply because it passes validation.
Make automation earn trust
Start with one bounded slice, measure how much review time it saves, and record recurring corrections in the prompt or team conventions. If the agent repeatedly mistakes implementation details for architectural boundaries, reduce its scope or require evidence for each proposed relationship. Keep the final decision with the people who understand the system and its operational constraints.
Used this way, an agent is a drafting assistant with access to structured diagram operations. It can lower the cost of keeping a map current, while explicit scope, validation, and review preserve the judgment that makes the map useful.