The world is transitioning from Vibe Coding to Agentic Engineering, i.e. professional devs building production systems using agents, and not just going by “vibes”. What’s the core difference? Agents still write most of the code, but humans bear real responsibility for the outcomes. If the system breaks, you fix it, and if your agent doesn’t know how – you figure it out! Software Engineering has always been about this: building systems in such a way that humans can understand them (and therefore can fix them or teach them new tricks). This is why we care about design and architecture, have principles like SOLID, DRY and KISS, use git and CI/CD, and argue about naming a lot. The latest news is: our job is still Software Engineering, but now we can use agents. This is why we call it Agentic Engineering.

CodeSpeak aims to be your Agentic Engineering Toolkit: the set of tools you use to make agentic coding understandable, collaborative, reliable, and productive. We are tackling the core issues of agentic coding:

• Comprehension debt¹: I don’t really know how “my” code works, or even what exactly it does;
• Review overload²: there’s too much generated code to review, and too little information about the intent behind this code;
• Intent loss³: in general, I have to dig through generated code to decipher what was originally intended;
• Forgetful agents create regressions⁴: agents can break already working code while fixing bugs or adding new functionality.

Spec-Driven Development

Among the things that can help with these is the idea of moving the source of truth from the code to spec documents (.md files) written in human language. Its core strength is in raising the level of abstraction: specs can be 5-10x shorter than code, and therefore are that much easier to review and maintain. People are also likely to spend a bit more time working on a spec than on a one-off prompt and therefore understand the nuances of the system better. This family of approaches is called Spec-Driven Development and includes at least two classes of tools divided by the lifetime of the specs they produce:

• “Change Spec” tools: you specify the change you want to make to the system, and the spec lives as long as you are working on the change. When the change is done, its change spec stops updating, and new changes are specified in new specs.
• “Living Spec” tools: the spec lives as long as the functionality it describes. You make changes to the system through making changes to the spec. Essentially, specs act like higher-level code.

Upcoming Version of CodeSpeak

CodeSpeak is in the “Living Specs” camp, and we built the first generation of our product around the idea of spec files (.cs.md) that evolve alongside the code. Many thanks to the hundreds of users of this version who taught us a simple truth: people don’t want to write specs. The vast majority generate specs with agents, which is understandable but also kinda defeats the purpose. The idea of SDD is to place the source of truth in the intent coming from the human. Anything that a model can generate is a derivative artifact, and should be clearly separated from human intent. If we start from a generated spec, this assumption breaks immediately.

We’ve listened to the users, and re-thought our UX. The next version of CodeSpeak is pioneering a new philosophy: instead of relying on lengthy documents, we are adopting a structured approach to specs.

In this new approach, you don’t have to change your workflow to start using CodeSpeak. The prompts you give to your agents already contain your intent. The CodeSpeak plugin will read your prompts as they come and keep track of how your intent evolves. The point is to accurately extract individual atomic requirements and keep them structured, without flattening into a long text. This way, we can see what requirements are added with each prompt, what requirements are dropped when you change your mind, and what requirements are refined when you clarify your ideas. As a result, you get an always-up-to-date structured representation of your intent at every point in your project’s history.

Specs and Structured Requirements

For the new CodeSpeak a spec is not a flat .md file anymore. It’s a set of interconnected requirements that evolve as your agents modify the project. And every word is grounded in your own words and the code you accepted.

What this approach gives you is:

• Agents don’t break existing features when building new ones (and generally don’t forget requirements you told them about);
• Specs don’t grow into giant .md files and don’t “rot” (go out of date or accumulate slop);
• You can review the changes in intent before you look at code diffs; no more deciphering meaning from large PRs made by agents;
• In future versions, each requirement will generate its own tests and you can track intent coverage, not only code coverage;
• Keeping terse requirements in the context instead of large specs can result in token savings too.

Editing Structured Specs

So far, we’ve talked about creating and reading structured specs. But what about editing? Something is only a source of truth if edits in it are translated to changes in the system (i.e. diffs in the code).

With structured requirements, we don’t have a text file to edit, but we can still edit the spec: pull up the requirements relevant to the subsystem/component you are interested in, change/add/remove what you want, and CodeSpeak will instruct your agents to implement the changes.

One benefit in this approach is that you don’t need to type out a prompt with a long preamble explaining the exact situation you want the behaviour to change in. This new editing mode closes the loop: now, structured specs can cover all use cases that current SDD tools can cover.

Roadmap

To summarise, we saw that writing specs is not what people are happy to do, so we are adapting:

• Take what people are happy to write (prompts in their conversations with agents);
• Extract the intent and save it as structured specs (requirements);
• Ditch the command line tool in favour of a seamless integration with agents (plugins for Claude, Codex, etc).

The codespeak CLI is being retired (at least for now), and the new version will ship in a different form, including the plugins for your favourite agents.

In the upcoming CodeSpeak release, we are planning to ship:

• Plugins for Claude / Codex;
• Seamless intent extraction into structured specs;
• Intent aggregation from multiple teammates;
• Intent diffs for review and merge conflicts.

Future releases will bring even more:

• Editing requirements and generating code from those edits (closing the SDD loop);
• Bidirectional connection between requirements and code;
• Intent informs test generation; Tracking intent coverage for test suites;
• Modularity and architectural guardrails.

Of course, plans always change, but this is what we are currently working towards.

Exciting times!

Be the first to hear about the new version:

---

References

• [1] Comprehension Debt - the hidden cost of AI generated code
• [2] The Final Bottleneck
• [3] Prompt Engineering is Dead. Everything is a Spec
• [4] Your AI Coding Tool Has No Memory of the Bug That Broke Prod Last Quarter