I Let CodeSpeak Take Over My Repository

have developed considerably over time, changing into more and more summary and simpler for people to grasp. Within the early days of computing, programmers labored straight with machine code, manually getting into uncooked binary directions utilizing punch playing cards, the place holes encoded knowledge and instructions for early mainframes. This course of was tedious and extremely error-prone: a single misplaced gap may break all the program and pressure builders to begin over from scratch.

To cut back this friction, meeting language emerged, changing uncooked binary code with human-readable mnemonics similar to ADD or MOV, which had been then translated again into machine directions. 

The following main leap got here within the Fifties when the primary compiled high-level languages similar to FORTRAN and COBOL appeared. They launched syntax nearer to mathematical notation and pure language. Later, languages similar to ALGOL, C, and C++ introduced structured programming, reminiscence abstraction, and object-oriented ideas, dramatically decreasing software program complexity and bettering maintainability.

Fashionable languages like Python and Java continued this development by prioritising readability and providing huge ecosystems of built-in libraries, permitting engineers to focus extra on fixing enterprise issues fairly than coping with hardware-level particulars.

Extra not too long ago, nonetheless, the best way we write code has began to shift once more with the rise and widespread adoption of AI. This naturally raises the query: will programming languages evolve as nicely?

It feels more and more believable that at some point we might find yourself coding in plain English. That’s why I used to be excited to attempt one in every of these potential languages of the long run: CodeSpeak, at the moment accessible in alpha preview. Let’s see the way it works.

Setting all the pieces up

As regular, earlier than leaping into constructing, we first have to set all the pieces up. Fortunately, the method is fairly easy. We are able to set up CodeSpeak utilizing the uv bundle supervisor:

uv device set up codespeak-cli
codespeak --version
# CodeSpeak CLI 0.4.1

Subsequent, we have to log in. Operating the next command opens a browser window the place you possibly can both authenticate along with your Google account or create a devoted CodeSpeak login and password. After accepting the Phrases & Situations, you’ll be efficiently authorised.

codespeak login

The ultimate step is establishing your API key, since CodeSpeak follows a Deliver Your Personal Key coverage. For the time being, it solely helps an Anthropic API key, which is sensible given how in style Anthropic fashions are for coding duties proper now. You’ll be able to generate your key in https://platform.claude.com/settings/keys and export it as an setting variable.

export ANTHROPIC_API_KEY=

And that’s it. We’re prepared to begin constructing.

Constructing with CodeSpeak

CodeSpeak helps greenfield growth whenever you put collectively a spec and construct from it. Nonetheless, I assumed it will be extra fascinating to check it on a considerably extra mature mission (or at the very least one that’s already practical) and see how nicely it handles an present codebase.

In my earlier article, I constructed an online software for monitoring and analysing exercise knowledge utilizing spec-driven growth. I’ve been actively utilizing it since then and have already discovered a number of areas for enchancment, so it felt like a great candidate for testing CodeSpeak.

Takeover

Earlier than utilizing CodeSpeak to implement new options, we first have to generate an preliminary model of the specs. Fortuitously, CodeSpeak may also help with that as nicely.

I began by copying all of the code from my health app into a brand new repository. Then, I eliminated all present specs and the structure file to emulate a extra reasonable situation whenever you vibe-coded one thing rapidly and now wish to migrate the mission right into a extra structured workflow with CodeSpeak.

CodeSpeak means that you can migrate solely chosen elements or modules of a mission, however I made a decision to go all in and transfer all the software. The repository comprises round 13K strains of code, so whereas it’s not huge, it’s nonetheless a fairly sized mission for an experiment like this.

We are able to begin producing specs with the next command.

codespeak takeover

CodeSpeak then spends a while analysing your native information. In my case, the entire course of took round a minute. After that, it opened a webpage with a proposed construction for the codebase. It urged splitting my software into 4 modules: Frontend, Backend API, Information Layer, and Backend Exams.

Modules are a well-established programming idea, and it’s straightforward to see why they’re helpful: they create smaller self-contained domains, enhance readability, and make it simpler to reuse elements throughout tasks. So, it’s fantastic that CodeSpeak suggests us to create 4 completely different specs fairly than attempting to place all the pieces in a single lengthy doc. 

Within the browser, you possibly can evaluation every module and ask CodeSpeak to separate, merge, or rethink it. In my case, the urged construction appeared affordable, so I made a decision to maintain all the pieces as is and migrate all modules, permitting all the repository to be managed by CodeSpeak.

After deciding on all modules and beginning the takeover, CodeSpeak processed them one after the other: studying information, producing specs, refining them, and working assessments.

On the finish, it created a specs listing containing 4 specification information (one for every module). Let’s take a look at one in every of them, frontend.cs.md.

The doc begins with an import assertion: import specs/backend_api.cs.md. Imports are used to trace dependencies between modules and keep context for the agent. For instance, when the agent works with the frontend specification, it is aware of to load the backend API spec first. For the reason that backend API spec itself imports the info layer spec, the agent mechanically pulls that in as nicely. Consequently, it will get all of the required context earlier than making modifications to the frontend. That is fairly handy and allows a clear decomposition of the codebase, much like how dependencies and abstractions are dealt with in conventional software program engineering.

The remainder of the doc follows a structured format, describing all main elements of the frontend: from the tech stack to authentication, page-level performance, and the present take a look at protection.

Frontend SPA
├── Stack & Setup
├── Authentication
├── Format & Navigation
├── API Shopper
├── Pages
│   ├── Historical past (/historical past)
│   │   ├── Weekly abstract card
│   │   ├── 12-week coaching tendencies chart
│   │   └── Session listing
│   ├── Log Exercise (/log)
│   │   ├── Cardio type
│   │   └── Power type
│   ├── Session Element (/classes/:id)
│   │   ├── Power session element
│   │   └── Cardio session element
│   ├── Templates (/templates)
│   ├── Settings (/settings)
│   │   ├── Exercise Sorts
│   │   ├── Train Sorts
│   │   └── Workout routines
│   └── Login (/login)
├── Shared Elements
│   ├── ExerciseEntryBlock
│   ├── TimeInput
│   └── ProtectedRoute
├── Utility Modules
│   ├── dateUtils
│   └── unitUtils
└── Exams
    ├── LoginPage.take a look at.tsx
    └── TimeInput.take a look at.tsx

At first look, the generated specs appeared fairly complete and appeared to seize most implementation particulars nicely (even small issues like my choice for the Montserrat font).

In fact, first impressions may be deceptive, so I made a decision to check them correctly. Conveniently, I nonetheless had all the unique specs used to construct the applying. This made it doable to check the specs generated by CodeSpeak towards the originals utilizing an LLM.

The decision was largely constructive: the generated specs captured the overwhelming majority of implementation particulars nicely. Nonetheless, some issues had been lacking. 

The primary gaps had been the mission mission (why we’re constructing this) and roadmap (future plans), which is pretty anticipated since neither may be simply inferred from code alone.

There have been additionally some smaller implementation nuances lacking, similar to what precisely a “template change” means or the exact formulation used to auto-generate titles for energy and cardio exercises. I wouldn’t take into account these omissions crucial, since in lots of circumstances an LLM may in all probability infer them when wanted.

General, CodeSpeak did a superb job producing specs that specify an present codebase. However producing specs was by no means the top aim right here, so let’s put them into apply and really construct one thing.

Implementing a characteristic

I’m already utilizing the applying to trace my exercises, however I might additionally wish to get suggestions from an AI coach to grasp whether or not my coaching is heading in the right direction. Ultimately, I might like to have a totally built-in AI assistant contained in the app, however let’s begin small and add the flexibility to generate a exercise abstract as textual content that may be copied and shared with an AI.

Since we’re working in a spec-driven growth workflow, implementing this characteristic begins with updating the specification. The change is especially UI-related, so I edited frontend.cs.md and added an outline of the brand new performance.

After that, I may construct the characteristic with the next command, which each implements the modifications and ensures all assessments go. So far as I perceive, to implement the change CodeSpeak below the hood appears to be like on the spec diff and tries to generate code that matches it. 

codespeak construct frontend.cs.md

Tip: In the event you solely need a fast implementation with out the total validation move, you need to use codespeak impl as a substitute.

After working the command, CodeSpeak started by studying the specs and analysing what wanted to alter. Initially, it began including CodeSpeak headers to many information, which was barely complicated because it wasn’t clearly associated to my request. Hopefully, it occurs solely on the primary run.

# Generated by CodeSpeak from spec file: specs/backend_api.cs.md
# Modifying this file manually is DISCOURAGED.
# CodeSpeak will attempt to protect guide modifications, but it surely's not assured.

As soon as it completed with the headers, it appropriately recognized the principle activity: including a duplicate exercise abstract button to every session row within the HistoryPage. It applied the change, all assessments handed, and the construct was marked as profitable.

It’s time to check it. The simplest solution to validate a UI change is just to run the app and examine it. So, I launched the mission regionally with Docker Compose. The brand new copy button appeared subsequent to every session within the historical past view and labored appropriately for energy exercises. Nonetheless, once I tried copying a cardio session, it failed. Even worse, it failed silently with no errors in both the browser console or Docker logs.

So now we had a bug. Importantly, the difficulty wasn’t within the specification, however within the implementation itself. To repair this, we are able to use a code change request. For smaller modifications, CodeSpeak helps a handy one-liner.

codespeak change frontend.cs.md -m "Help format of cardio coaching for copy button"

In my case, the request was barely extra complicated, so I selected to create a devoted change request file as a substitute.

codespeak change --new
# Created template change request in 
# /Customers/marie/Paperwork/github/trainlytics_codespeak/change-request.cs.md

Contained in the file, I added the next request masking each the bug repair and higher debugging help.

- Help copying summaries for cardio trainings, because it at the moment fails 
(possible resulting from a distinct knowledge format)
- Add logging for copy failures, as points at the moment don't seem in both 
browser console logs or Docker logs

After that, I requested CodeSpeak to implement the change.

codespeak change frontend.cs.md

Earlier than making any modifications, CodeSpeak first validated whether or not the requested code modifications had been in step with the present specs. If a request contradicts the spec, it pushes you both to revise the request or replace the specification first and rebuild from there. I discovered this notably helpful, because it helps scale back divergence between specs and implementation.

In the long run, CodeSpeak mounted the difficulty and in addition added assessments to stop comparable regressions sooner or later.

So, we efficiently constructed and examined a brand new characteristic whereas additionally studying work with an rising programming language designed for the AI period. With that, let’s wrap issues up and mirror on the expertise.

Abstract

General, I feel this experiment was fairly profitable. CodeSpeak managed to take over a repository with 10K+ strains of code with out dropping any essential implementation particulars, which is genuinely spectacular. After that, we up to date the specification and constructed new performance straight from it.

The primary implementation try wasn’t good, however after submitting a code change request, CodeSpeak not solely mounted the bug but additionally added assessments to stop comparable points from being reintroduced in future builds. I notably favored these automated guardrails, since they assist make the product extra future-proof.

The expertise of constructing with CodeSpeak felt fairly completely different from the spec-driven growth workflow I explored beforehand. Let me spotlight a couple of key variations.

In conventional spec-driven growth, specs are sometimes generated by LLMs and might turn into fairly prolonged. Whereas complete, this will make them tougher for people to learn, keep, and evolve over time. CodeSpeak appears to comply with a really completely different philosophy: specs are deliberately concise and include solely the minimal data wanted to generate code. They’re meant to be learn and edited by people, doubtlessly with some AI help.

This additionally makes it clear that CodeSpeak is primarily designed for engineers. To make use of it successfully, you continue to want to grasp the modular construction of a system and make intentional modifications to specs accordingly. Against this, spec-driven growth can arguably be adopted with a lot much less engineering expertise, because the workflow is usually nearer to chatting with an agent and storing intermediate selections in a repository to protect intent and context.

Nonetheless, I’ve to confess that CodeSpeak was fairly completely different from what I initially anticipated. I’ve used greater than a dozen programming languages earlier than, and CodeSpeak doesn’t actually resemble any of them. In actual fact, the principle innovation appears to be much less in regards to the language itself and extra in regards to the tooling and workflow constructed round it, which is an fascinating shift.

Not like conventional programming languages with strict syntax and semantic guidelines, CodeSpeak means that you can write specs in plain English with only a few constraints. This flexibility is highly effective, but it surely additionally comes with apparent trade-offs: as everyone knows, a poorly written immediate will possible result in poor implementation.

So my hope is that as CodeSpeak matures (and it’s value remembering that it’s nonetheless in alpha preview now), it can develop a extra opinionated strategy to writing high-quality specs, together with higher tooling to validate and enhance them.