Until recently, what consumed the most time in the agile development cycles was implementation, along with the stages that follow it: QA, testing and the corresponding feedback before starting the next iteration. Now, with LLMs and the new techniques that have grown out of them (autonomous loops, agent graphs, vibe coding), in my experience implementation time has stopped being a problem, but it hasn’t disappeared: it has spread across two points, planning and verification.
A thin plan can create more problems than it solves
If we leave a poor specification, the AI makes assumptions and resolves them quickly. The result can be code that is correct and functional as an isolated piece, while its integration with the rest of the system is problematic.
We can end up facing duplicated libraries, conflicting dependencies, or design decisions that may cause scaling problems down the road.
In one concrete case, while experimenting with autonomous loops, I built a project in Go and at the end of the cycle I found subsystems disconnected from each other, and implementation choices that weren’t the ones I expected. Sometimes they turned out for the better, but mostly they created future problems that made refactoring expensive.
The solution I propose is not going back to waterfall development, but improving how we document.
Let’s stop treating the AI like a junior (or let’s treat juniors better)
I don’t remember when people started saying “treat the AI like a junior”, but I think it’s a phrase that steers us away from using it correctly.
Historically, juniors are people who may have a decent level of coding but lack the experience to see the tradeoffs of the profession and make sound architecture decisions, which is where the value is.
But the AI acts like one particular kind of junior: the one who doesn’t ask questions, assumes answers to the doubts that come up during development, and charges ahead like the wind.
This type isn’t bad, they simply need guidance. With a person, we need to give them time and attention so they can grow. With the AI, we need to get ahead of it with the project’s context; once again, documentation.
Living documentation
We should give shape to this knowledge base, and make it accessible and easy to update, for both humans and AI agents.
I propose living documentation: one that lives in a folder of files that are added, modified or even deleted as the project’s development cycles move forward.
Although I currently have several projects running in parallel with different documentation structures, they all share some things: a vault directory (Obsidian-style) that holds the project’s documentation, built on progressive disclosure as the base on which the files inside the directory relate to each other.
This approach to documentation is a structural part of my autonomous loop, Gubia. As the loop completes implementation tasks, relevant project information is documented in the vault, and the loop itself later references it to make correct architecture and design decisions.
This in turn makes verification easier. Since the vault is updated right after implementation, whoever reviews doesn’t need to read all the code line by line: they have documents that tell them what was done, why, and where to look. Mind you, this doesn’t replace tests or CI, but it reduces review time and prevents decisions that contradict what is documented.
In my experience, implementing new features is no longer a bottleneck. The time goes into planning at the start of each development cycle and into review at the end of it, and living documentation keeps the LLM as close to our vision as possible.