have developed considerably over time, turning into more and more summary and simpler for people to grasp. Within the early days of computing, programmers labored instantly 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 might break all the program and pressure builders to begin over from scratch.
To scale back this friction, meeting language emerged, changing uncooked binary code with human-readable mnemonics resembling ADD or MOV, which have been then translated again into machine directions.
The following main leap got here within the Fifties when the primary compiled high-level languages resembling FORTRAN and COBOL appeared. They launched syntax nearer to mathematical notation and pure language. Later, languages resembling ALGOL, C, and C++ introduced structured programming, reminiscence abstraction, and object-oriented ideas, dramatically decreasing software program complexity and enhancing maintainability.
Trendy languages like Python and Java continued this pattern by prioritising readability and providing huge ecosystems of built-in libraries, permitting engineers to focus extra on fixing enterprise issues slightly than coping with hardware-level particulars.
Extra not too long ago, nonetheless, the way in which 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 effectively?
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 strive considered one of these potential languages of the long run: CodeSpeak, at present obtainable 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 simple. We will set up CodeSpeak utilizing the uv bundle supervisor:
uv software set up codespeak-cli
codespeak --version
# CodeSpeak CLI 0.4.1Subsequent, we have to log in. Operating the next command opens a browser window the place you possibly can both authenticate together with your Google account or create a devoted CodeSpeak login and password. After accepting the Phrases & Situations, you’ll be efficiently authorised.
codespeak loginThe ultimate step is establishing your API key, since CodeSpeak follows a Convey Your Personal Key coverage. In the meanwhile, it solely helps an Anthropic API key, which is sensible given how fashionable Anthropic fashions are for coding duties proper now. You may generate your key in https://platform.claude.com/settings/keys and export it as an atmosphere variable.
export ANTHROPIC_API_KEY=And that’s it. We’re prepared to begin constructing.
Constructing with CodeSpeak
CodeSpeak helps greenfield improvement whenever you put collectively a spec and construct from it. Nonetheless, I assumed it might be extra attention-grabbing to check it on a considerably extra mature challenge (or at the very least one that’s already practical) and see how effectively it handles an current codebase.
In my previous article, I constructed an online utility for monitoring and analysing exercise knowledge utilizing spec-driven improvement. I’ve been actively utilizing it since then and have already discovered a number of areas for enchancment, so it felt like a very good candidate for testing CodeSpeak.
Takeover
Earlier than utilizing CodeSpeak to implement new options, we first have to generate an preliminary model of the specs. Happily, CodeSpeak may help with that as effectively.
I began by copying all of the code from my health app into a brand new repository. Then, I eliminated all current specs and the structure file to emulate a extra reasonable situation whenever you vibe-coded one thing rapidly and now wish to migrate the challenge right into a extra structured workflow with CodeSpeak.
CodeSpeak means that you can migrate solely chosen components or modules of a challenge, however I made a decision to go all in and transfer all the utility. The repository accommodates round 13K strains of code, so whereas it’s not monumental, it’s nonetheless a fairly sized challenge for an experiment like this.
We will begin producing specs with the next command.
codespeak takeoverCodeSpeak then spends a while analysing your native recordsdata. 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 prompt splitting my utility into 4 modules: Frontend, Backend API, Information Layer, and Backend Checks.
Modules are a well-established programming idea, and it’s simple to see why they’re helpful: they create smaller self-contained domains, enhance readability, and make it simpler to reuse elements throughout initiatives. So, it’s fantastic that CodeSpeak suggests us to create 4 totally different specs slightly than attempting to place all the pieces in a single lengthy doc.
Within the browser, you possibly can evaluate every module and ask CodeSpeak to separate, merge, or rethink it. In my case, the prompt construction regarded cheap, 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 choosing all modules and beginning the takeover, CodeSpeak processed them one after the other: studying recordsdata, producing specs, refining them, and working checks.
On the finish, it created a specs listing containing 4 specification recordsdata (one for every module). Let’s take a look at considered one 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 preserve 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. Because the backend API spec itself imports the information layer spec, the agent mechanically pulls that in as effectively. Consequently, it will get all of the required context earlier than making adjustments to the frontend. That is fairly handy and allows a clear decomposition of the codebase, just 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 components of the frontend: from the tech stack to authentication, page-level performance, and the prevailing take a look at protection.
Frontend SPA
├── Stack & Setup
├── Authentication
├── Structure & Navigation
├── API Shopper
├── Pages
│ ├── Historical past (/historical past)
│ │ ├── Weekly abstract card
│ │ ├── 12-week coaching tendencies chart
│ │ └── Session checklist
│ ├── Log Exercise (/log)
│ │ ├── Cardio type
│ │ └── Energy type
│ ├── Session Element (/periods/:id)
│ │ ├── Energy 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
└── Checks
├── LoginPage.take a look at.tsx
└── TimeInput.take a look at.tsxAt first look, the generated specs regarded fairly complete and appeared to seize most implementation particulars effectively (even small issues like my choice for the Montserrat font).
After all, 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 appliance. This made it potential 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 effectively. Nonetheless, some issues have been lacking.
The principle gaps have been the challenge 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, resembling 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 essential, since in lots of instances an LLM might most likely infer them when wanted.
Total, CodeSpeak did a superb job producing specs that designate an current codebase. However producing specs was by no means the top objective right here, so let’s put them into observe and truly construct one thing.
Implementing a characteristic
I’m already utilizing the appliance to trace my exercises, however I might additionally prefer 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 power 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 improvement 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 might construct the characteristic with the next command, which each implements the adjustments and ensures all checks go. So far as I perceive, to implement the change CodeSpeak below the hood seems to be on the spec diff and tries to generate code that matches it.
codespeak construct frontend.cs.mdTip: If you happen to solely desire a fast implementation with out the total validation circulate, you should utilize
codespeak implas an alternative.
After working the command, CodeSpeak started by studying the specs and analysing what wanted to alter. Initially, it began including CodeSpeak headers to many recordsdata, 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 handbook adjustments, but it surely's not assured.As soon as it completed with the headers, it appropriately recognized the primary process: including a duplicate exercise abstract button to every session row within the HistoryPage. It applied the change, all checks handed, and the construct was marked as profitable.
It’s time to check it. The simplest method to validate a UI change is just to run the app and examine it. So, I launched the challenge 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 will use a code change request. For smaller adjustments, CodeSpeak helps a handy one-liner.
codespeak change frontend.cs.md -m "Assist 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 an alternative.
codespeak change --new
# Created template change request in
# /Customers/marie/Paperwork/github/trainlytics_codespeak/change-request.cs.mdContained in the file, I added the next request masking each the bug repair and higher debugging help.
- Assist copying summaries for cardio trainings, because it at present fails
(possible as a consequence of a distinct knowledge format)
- Add logging for copy failures, as points at present don't seem in both
browser console logs or Docker logsAfter 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 adjustments have been according to the prevailing 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 cut back divergence between specs and implementation.
Ultimately, CodeSpeak fixed the difficulty and likewise added checks to stop related regressions sooner or later.
So, we efficiently constructed and examined a brand new characteristic whereas additionally studying how you can work with an rising programming language designed for the AI period. With that, let’s wrap issues up and replicate on the expertise.
Abstract
Total, I feel this experiment was fairly profitable. CodeSpeak managed to take over a repository with 10K+ strains of code with out shedding any essential implementation particulars, which is genuinely spectacular. After that, we up to date the specification and constructed new performance instantly from it.
The primary implementation try wasn’t excellent, however after submitting a code change request, CodeSpeak not solely mounted the bug but additionally added checks to stop related points from being reintroduced in future builds. I notably preferred these computerized guardrails, since they assist make the product extra future-proof.
The expertise of constructing with CodeSpeak felt fairly totally different from the spec-driven improvement workflow I explored beforehand. Let me spotlight just a few key variations.
In conventional spec-driven improvement, specs are sometimes generated by LLMs and may grow to be fairly prolonged. Whereas complete, this could make them tougher for people to learn, preserve, and evolve over time. CodeSpeak appears to comply with a really totally different philosophy: specs are deliberately concise and comprise solely the minimal info 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 adjustments to specs accordingly. Against this, spec-driven improvement can arguably be adopted with a lot much less engineering expertise, for the reason that 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 totally 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 primary innovation appears to be much less concerning the language itself and extra concerning the tooling and workflow constructed round it, which is an attention-grabbing shift.
In contrast to 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 price remembering that it’s nonetheless in alpha preview now), it should develop a extra opinionated method to writing high-quality specs, together with higher tooling to validate and enhance them.
