Some lessons from our experience with vmblu

During the development of vmblu we have used it intensively to develop apps. Doing that was at times exhilirating because of the results we obtained, but equally sobering when we experienced how things could veir into weird territory.

Vmblu was developed in parallel with the lightning fast development of coding agents: from code-completers to agentic software writers that can write, test and deply whole systems in under a year. Part of what we experienced was because of this parallel development: sometimes we tried to do things that a coding agent turned out to be much better at a few weeks later, sometimes we overestimated the capabilities of an agent. But a constant during the whole development of vmblu was always that the basic thesis of the project - architecture matters - continued to grow in importance.

At first we thought it would be important for the coding agent as a better substitute for holding an entire code base in his context, but we also saw it as indispenasble for the human to understand what the coding agent had been developing, without having to go through the code that had been produced.

The lessons that we describe below are not user guide style 'how to' lessons, therefore we have the user guide and the examples you can find on our website. What we want to share here are more subtle lessons about what it's like - in our experience - to work with coding agents when they have to do architecture work iso just generating code.

The difference between vmblu and other architecture guidelines or frameworks is that the vmblu model is the system, not just a description of the system and every project artefact is ultimately derived from the model. The schemas for the model files and other artefacts and the description of the vmblu wow, explain this in detail to an agents that has to apply vmblu to a project, and very early on it was our experience that agents understand this very well. For example the formal schema files, that can also be checked, turned out to formats that agents can handle very well, even if they are not plain english text files. So we never had any serious problems with agents not understanding the 'basic language' from vmblu. Sometimes we had to introduce improvements, like when we separated the purely graphical information of a model file (eg the wire between two pins) from the logical information (which pins are connected), because the the 'graphical noise' of redrawing cleaner routes or repositioning nodes, could over-stimulate the agent, but apart from that the concept of an architectural model and its relation to the actual code was immediately well understood.

Take your time to design

For the first examples we developed, the agent was amazingly quick to come up with some architecture that looked very reasonable and sound.

It was completely ready - nodes, interfaces, pins and even the detailed layouts of the messages to be exchanged between the nodes. Remarkable !

All we had to do then was to let the coding agent start coding and a complete working system was ready after a short time, tests and everything. And in most cases the system worked or had only a very limited easy to correct bugs.

But of course there is something unnatural to this way of developing a system. First of all, it is rare that you know exactly from the start how the work of an app will have to be split up in nodes and what type of interfaces you will need between the node, and second, as with any design method, there is more then one way to design the system.

Designing is an iterative process, so take your time to iterate. Your agent is not so smart that he can see the complete system in his mind instantly. But he will be very helpfull in thinking along with the human why and how certain functionality has to be organised while building the system.

vmblu is modular and high level, so you can easily reason about what a part of the system has to do and how it fits in the overall design of the system.

Be critical

We all have had the experience where a coding agent makes a very confident statement about how something should work, only to discover that it is actually nonsense. Be socratic with your agent: ask 'why' again and again. In our experience this works very well and helps the agent to think about the design. Often just asking the question makes the agent realize that he has jumped the gun and should review his work.

Implement stepwise

The vmblu blueprint is not documentation: it is the system, so if you add, remove or change a node it changes the system, not just the specification. This also means that the agent always has an up to refererence of the system, not just a trail of prompts. That makes it also easier to build the system incrementally without ending up with a tangled blob of code and prompts.

Check and inquire about the code

vmblu uses a compiler framework in parallel with the agent to extract key information from the source code. This servers two purposes: first it allows to automatically check that for example the message data contracts are respected in the software. If agent or human make changes in a message interface that conflict with the design data it will be flagged. Second it gives a developer an additional tool to find his way in the code, eg to find a message handler or where a message has been sent.

As a general rule I do not think it is necessary to read and vet the entire codebase, but in case you want to understand or change something in a implementation the handlers are a good point to start. The code generatde by an agent will be functional, and if it contains a bug it will quickly be found, but do not assume that agents will have chosen the most optimal implementation for a given requirement. So for critical sections I would recommend to have a look. Agents are usually very good at explaining how the code works and to change code when required.

Stay within the framework

The vmblu skill clearly explains the coding agent how vmblu projects are structured and must be handled and the agent applies this context most of the time, but occasionally it can happen that for some change to the system, the agent decides to take a shortcut and adds code that is orthogonal to the vmblu approach, for example by adding some code that creates a direct link between nodes, eg by having shared or weird global variables. In general it is wise to remind the agent if this happens to make changes the vmblu-way. It does not happen often, but better to keep an eye on it.

Something about the runtime

vmblu uses a runtime to switch messages between nodes. Second it gives a uniform and controlled access surface for outside agents that use the system you have built and third it allows to impose restrictions on what nodes can do and to intercept deviations from that policy.

If despite these advantages, just hearing the word runtime puts you off, then consider the following: first the runtime itself is fully open source and already consists in several flavors that are the most appropriate for the project at hand. The runtime is smart but not big and if you would want to change it, your coding agent will happily do that for you. Second, any more or less sophisticated application has some mechanism to keep the ball rolling, a top level event loop or whatever, so having a well designed run-of-the-mill solution is actually not a bad thing.