DEV Community: Aleks Verein

How we broke the code-review bottleneck with CodeSpeak - and the opportunity it opened

Aleks Verein — Mon, 13 Jul 2026 10:27:18 +0000

For decades, understanding the code better than anyone was an engineer's most valuable skill. The models have that now - and that turns out to be good news. Here's how we moved human review from the diff to the spec, kept the deep dives for code that warrants them, and used what it freed up to take intellectual control of the whole system, not just the code.

There is far more code in the world than there was two years ago, and a fast-growing share of it was never typed by a human. The models got good enough that most teams now let them write - and, increasingly, trust what comes back. Which surfaces a question the industry keeps circling and never quite says out loud: does all of that code still need a person to review it?

The question we keep not quite asking

For now, the answer is yes - because the models still slip more often than a careful human does, especially at the volume they produce. There's simply so much code that checking it has become its own job.

But that gap is closing from both sides. The models keep getting better, and an AI reviewer on every pull request catches more than a tired human ever did. We run one; it's real leverage, and if you ship with agents and you don't, you should. Code quality, the thing everyone is anxious about today, is the kind of problem that gets solved over time.

So play it forward. Suppose it is solved - the models stop making more mistakes than we do, the reviewers close the rest of the gap, and bugs stop being the thing that keeps you up at night. Is human review finished then? Is there anything left for an engineer to hold?

What's left isn't bugs. It's understanding.

There is, and it was never really about bugs. It's understanding - knowing what the code does, why it's shaped the way it is, what breaks if you touch it. The name for that is intellectual control, the thing Dijkstra worried about back in 1972, when he reminded us a program still has to fit inside one head - "the strictly limited size of his own skull."

For most of software's history, that was the most valuable thing an engineer had. Peter Naur put it sharply in 1985: the real product of programming isn't the text, it's a theory of the system that lives in the programmers' minds - so much so that "the death of a program happens when the programmer team possessing its theory is dissolved," even while the binary keeps running. The person who held that theory - who could trace any behavior to its cause without looking it up - was the one a company paid the most and feared losing. Intellectual control of the code was the skill.

And it's the skill the models just learned. Point Claude at a file and it reads, explains, and traces it about as well as the engineer who's prized for doing so - and far faster. Code-level intellectual control, the scarce and expensive thing, is quietly becoming a commodity. If your value was that you understood the code better than the people around you, the floor is moving.

There's one catch, and it's the important one: the model understands the code in front of it brilliantly, but it doesn't keep that understanding. As Sean Goedecke puts it, "AI agents can't retain theories of the codebase. They have to build their theory from scratch every time." The model is a superb momentary reader and a hopeless long-term owner. The persistent theory of the system still has to live in a human.

So the question for engineers isn't whether they've been replaced. It's narrower and more useful: if the model now owns code-level understanding, where should a human's understanding go?

The level nobody held

Up. To the one level intellectual control almost never reached: the whole system.

Be honest about the old world. Individuals held their files, their service, their corner of the map. But the understanding of how the entire thing fit together - across services, across teams, across the years - usually sagged. It lived in nobody's head, or in one over-subscribed person's, or it rotted as people churned and walked out the door with their theory. We tolerated that gap because holding the whole system was a luxury almost nobody could afford: the human budget was already spent, line by line, on the code.

That's what changes. The models can hold the code now. Which frees the scarce human attention that used to go there for the thing we never had the budget for - taking intellectual control of the system. Not "understand less." Understand higher. The frontier moves from "I know this function cold" to "I know how this whole machine behaves" - the more valuable understanding it was always too expensive to have.

That's the opportunity. The rest of this is how we chase it in practice - concrete enough to try on a single module this week.

Review the spec, not the diff

It starts by dropping an assumption: that "understanding the code" means "reading the code." Simon Willison - who co-created the Django web framework - keeps a golden rule: he won't commit code he "couldn't explain exactly what it does to somebody else". We kept his rule and moved its unit. It's no longer "can you explain this line" (Claude can). It's "can a human still explain what this system does." That's the understanding we refuse to give up, and the diff is a terrible place to keep it: at a thousand lines a pull request, the reviewer drowns in detail and surfaces with no theory at all. As Willison notes, once the typing is free, "the natural bottleneck on all of this is how fast I can review the results".

So we review a different artifact: a .cs.md file spec - borrowed from a tool called CodeSpeak, and used deliberately backwards from how it was designed.

CodeSpeak, built by Andrey Breslav (the creator of Kotlin), is a spec-as-source-of-truth system: you write a plain-English .cs.md describing what the software should do, and codespeak build generates the code from it. The spec is what you maintain; the code is the output, about 5–10× longer than the spec that produced it. There's even a one-time codespeak takeover command for pointing it at an existing codebase and extracting a spec from the code - a door you walk through once on your way to living in spec-land.

We inverted it. We keep the code as the source of truth, and treat the .cs.md as a generated description of what the shipped code already does - regenerated from the code, checked against the code, never compiled back into it. We live permanently in the place takeover only visits. We borrow CodeSpeak's format; we never run its compiler. Reverse CodeSpeak, if you want a name for it: the same tool, turned 180°.

Here's the shape of it - a file that's a few hundred lines of types, reducers, and guards collapses into something a reviewer holds in one screen (an illustrative shape, not a specific file):

# CheckoutReducer
## Short description
Folds checkout actions into cart and order state. Pure; no I/O.
## Data
Reads `Cart`; writes `Order`. Money is integer minor units, never floats.
## Functional requirements
- `AddItem` is a no-op when the SKU is already in the cart.
- `Checkout` fails closed when `total` is missing - emits no `Order`.
- `ApplyCoupon` runs before tax; an expired coupon is ignored, not rejected.

That's a few hundred lines of behavior in a dozen you can actually read. Our review step regenerates the spec for every changed file, then builds the reviewer's reading path from the specs, not the source - the rule is blunt: don't open a source file when a sibling spec exists. Instead of a thousand-line diff, you walk a few hundred lines of compressed meaning in dependency order: what each piece does, what contract it holds, what changed.

So two reviewers do two different jobs, and neither pretends to do the other's:

The model reads the code for defects. The human reads the spec for understanding - and still flags bugs, architecture, and design as they go, understanding is just the part this piece is about. We hand the line-by-line control to the thing that's now better at it, and spend the human on the level the model can't keep.

And there's a third reader, a side effect we were counting on: the agents themselves. Working in this codebase, they reach for the .cs.md before the source - the same compressed map the human reviewer walks, at a fraction of the tokens. It doesn't solve Goedecke's problem - the agent still rebuilds its theory every session - but it makes the rebuild cheap: a dozen lines of spec instead of a few hundred lines of code, for every file the task touches.

Keeping the map up

There's an obvious objection, and it's the right one: a map that nothing compiles, imports, or tests will quietly start to lie. A refactor moves the territory and the map says nothing. A description of code that's drifted from the code is worse than no description at all.

So most of the work isn't generating specs - it's keeping them up to date, without a compiler to lean on.

Two things do that. First, a deterministic gate on every change - a small, dependency-free script that runs on the developer's machine, inside the agent pipeline, and in CI on every pull request, and hard-fails the change on any of three findings:

The fingerprint check. Every generated spec ends with a stamped footer recording a hash of the exact source bytes it was generated from. The gate re-hashes the current source: if the code changed and the map didn't - one character is enough - the hashes disagree and the change fails on the spot. No string matching, no judgment call; the file either is the one the spec describes or it isn't. It's the closest thing the map gets to a compiler: not an opinion about drift, a proof of it.
The coverage check. Drift isn't only a map that lies - it's also territory with no map. A changed file that warrants a spec but doesn't have one fails the same gate. So does the mirror image: a spec whose source file no longer exists fails as an orphan, so deleted code can't leave a ghost map behind.
The removed-shape check. When a type or branch that existed before the change is gone from the source but the spec still names it, the gate fails and says which name - the fingerprint tells you that the map went stale; this tells you what lie it would have told.

None of those failures is something an AI reviewer can wave through - a deterministic signal overrides every softer opinion in the pipeline - so catching a stale map never depends on a human noticing it. A semantic pass behind the gate reads for the subtler drift a checksum can't catch: wording that's now misleading, a claim the code no longer keeps.

Second, regeneration is anchored: we keep the previous wording wherever behavior is unchanged and re-describe only what actually moved - so specs don't churn on every refactor, and when the spec and the code disagree, the code always wins.

And we still read the code. The spec is the default review surface, not a cage. When a change is gnarly, security-sensitive, or just unfamiliar, we drop into the actual source and do a deep dive. That's the point, not an exception to it: we ceded the cheap, line-by-line reading so we could afford to spend real attention exactly where a human is worth it.

Some files don't get a spec at all - and that's the same principle, not a gap in it. A presentational component's meaning is how it looks; a paragraph describing its spacing and color would be a worse map than the component itself. So we don't spec those - we look at them, in browser QA. Only the big, logic-heavy containers - real state, real branching, real gating - earn a .cs.md, and even then it's stripped of visuals: the contract, not the CSS. Spec what you'd reason about; look at what you'd eyeball. The whole point is to put each kind of understanding where it actually lives.

A note on the machinery, to head off the obvious question of who runs all this: the specs are auto-generated, never hand-written. They're refreshed as the work happens: when an agent edits a file, it regenerates that file's spec before it commits. And they feed a gate a human still owns - a person approves the merge.

There's a deliberate cost choice underneath that. A spec system that regenerates on every change is the natural thing to run against a metered, per-token model API - every regeneration is tokens you pay for, and the bill grows with your codebase. We wanted the opposite: a way to run the same approach on a subscription. So we generate the specs as a skill inside Claude Code, on the flat subscription our engineers already work in, not a metered per-token API. Regenerating a spec on every change is cheap by design - you can run it on the agent tooling you already have, with no new vendor and no per-token meter.

If you want to try it, the bootstrap is smaller than it sounds - ours was three steps, no new tooling:

Point your agent at CodeSpeak and ask it to build the generator. That's not a simplification - it's what we did. We pointed Claude at the CodeSpeak docs and asked it to write a skill that produces a .cs.md in that format from a source file. The format is documented plain English, and "describe this file in this shape" is exactly the kind of task the model nails on the first pass. Alternatively, run CodeSpeak's own codespeak takeover on your codebase - fully compliant specs, straight from the tool that defined the format.
Wire the skill into your dev pipeline. Regenerate the spec for every file an agent edits before it commits, remember to anchor the new file with the previous one, and add the drift gate - the fingerprint alone (hash the source bytes into the spec's footer, re-hash on every change) is a small script and catches most of the rot.
Start narrow. Your stack doesn't matter - the spec is plain English, and plain English describes any codebase. Generate specs for your highest-churn module, fail the build when one drifts, and review the next pull request from the specs instead of the diff. One module is enough to feel whether you're holding more of the system or less.

The next altitude

Today our specs are per-file: one .cs.md next to each source file. That already lets a reviewer hold a whole change in their head at a level the raw diff never allowed. But a file is still a low rung, and "intellectual control of the system" is a promise a stack of per-file specs doesn't quite keep on its own.

So our next experiment - and it is an experiment, not something we've shipped - is specs a level up: for modules and subsystems, a higher-altitude map than the per-file ones. The goal is the full-system control that always used to sag: a human who can hold what the whole thing does, not just what each file does, and who reads down into the detail only where it earns the attention.

Notice what that is and isn't. It is not less control - it's the same scarce attention, re-spent and aimed higher. A reviewer working from good specs understands more system per unit of attention than they did back when they read every line - which makes this, oddly, more of a grip on the whole than the all-human world ever managed, not a retreat from it. That's the real deal on offer, if you take it on purpose: not "stop understanding your software," but "stop spending your understanding on the parts a model now holds, and spend it on the whole that no model will."

Trust is the side effect

We didn't build any of this to manufacture trust - and, honestly, not even for the big reason this whole piece is about. We built it because code review had become a bottleneck and we wanted reviews to go faster. Taking intellectual control of the whole system, and the trust that came with it, were what we found once we had it - not the plan.

In a June 2026 essay, Kent Beck named the dynamic better than we could. "We're accumulating code faster than we are accumulating trust", he wrote - and the reason it matters is that "software is bipedal-code & trust go together. One without the other just hops along awkwardly." Trust, he notes, "accumulates slowly & evaporates in an instant." A bug you can usually repair; trust, in his telling, is "irreversible."

You can't bolt that kind of trust on at the end. It's the residue of understanding. Keep a real grip on what the system does and trust comes along for free; lose the grip and no amount of green checkmarks buys it back. And it's concrete, not a mood: the reviewer who can actually say what a change does; the engineer six months from now who inherits the system and finds a current map of it, not a codebase whose theory left with whoever wrote it; the team that can hand work to an agent and still answer for what it built. We kept our grip on the thing that still needs a human - the whole system - and trust came as the side effect. Willison's rule survives intact: don't ship what you can't explain. We just moved where the explaining happens. Let the models have the code. Take the system for yourself.

Comparing switch-like operators in 14 different programming languages

Aleks Verein — Sat, 11 Sep 2021 10:00:22 +0000

We are going to look at Javascript, Typescript, Java, C#, Swift, Objective-C, Python, PHP, Ruby, Kotlin, ReasonML, Dart, Go and Elixir.

At Avo (avo.app) we work with 12 languages, and I decided to do a series of quick comparisons of those languages, plus 3 languages we are going to support soon.

First feature we are going to look at is the switch-like constructs. We are interested in 3 features related to switches - ability to use switch as an expression (so it returns a value), whether the switch construct is exhaustive (you need to handle all cases to compile the code) and if the fall-through logic disabled (so you don't need to break out of each case explicitly).

Language	has switch expression	is exhaustive	no need to break	reference
javascript	limited, only if wrapped in a function https://stackoverflow.com/a/55944296	-	-	https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch
typescript	limited, only if wrapped in a function	limited http://ideasintosoftware.com/exhaustive-switch-in-typescript/	-	same as JS
java	starting java 12	expression is, statement is not	additional syntax starting java 12	https://openjdk.java.net/jeps/354
c#	starting C# 8.0	- (expression will give a compile warning)	need to break in the statement	https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/switch-expression
swift	-	+	+	https://docs.swift.org/swift-book/LanguageGuide/ControlFlow.html
objc	-	+	-	🤷‍♂️
python	no switch in python :)
php	called match, introduced in php 8	match is, switch is not	match , switch is not	https://www.php.net/manual/en/control-structures.match.php
ruby, called `case`	+	-	+	https://ruby-doc.org/core-3.0.1/doc/syntax/control_expressions_rdoc.html#label-case+Expression
kotlin, called when	+	expression is, statement is not	+	https://kotlinlang.org/docs/control-flow.html#when-expression
reasonml/rescript	+	+	+	https://rescript-lang.org/docs/manual/latest/pattern-matching-destructuring#switch-based-on-shape-of-data
dart	-	+	-	https://dart.dev/guides/language/language-tour#switch-and-case
go	-	-	+	https://tour.golang.org/flowcontrol/9
elixir (called case)	-	- (runtime error CaseClauseError)	+	https://elixir-lang.org/getting-started/case-cond-and-if.html#case

How to set up `git bro` command with git alias

Aleks Verein — Fri, 16 Jul 2021 11:49:38 +0000

Have you seen people use the git bro command in terminal and always wondered how they do it?

It's actually very easy and I'm going to teach you now. Moreover, after mastering this technique you'll be able to use any command your imagination comes up with, like git cmon or git brunch.

I'll also share my own commands config in the end (quite conservative tbh).

You have git set up

First of all, you need git. I assume you already have it, if not, check this out.

Add the command

All you need to add a command is to define an alias, like this

git config --global alias.bro `branch`

Manage the aliases

To see all the aliases run

git config --list

To remove one run

git config --global --unset alias.bro

My aliases

As I promised, in the end I share my setup

alias.co=checkout
alias.cm=commit
alias.st=status
alias.bro=branch
alias.br=checkout -b
alias.pushit=push -u origin HEAD

Thanks for tuning in

That's it, now you can update your CV stating that you are bros with git!

👋

ReasonML & Rescript in 5 minutes

Aleks Verein — Fri, 23 Apr 2021 16:46:57 +0000

What is this language about?

It's a functional language that compiles to JavaScript (or to OCaml). We use it widely at avo.app.

What is ML in ReasonML?

Nowadays ML usually stands for Machine Learning, but in the old days there was a programming language called "Meta Language" which is the ancestor of ReasonML, or Reason Meta Language.

Why rename?

ReasonML is compatible with both JS and OCaml, but lately it was mostly used in the JS ecosystem.
Rescript takes JS-related things from Reason and stops being limited by OCaml support.

What are the good things?

Immutability

All references are actually constants. Shadowing is widely used. Standard library functions are non-mutative and produce new instances if any changes are made. There is a workaround to create a mutable reference if needed but deliberate enough to be discouraging.

Piping and currying

Rescript is a functional language with no methods on objects, but you can call and chain functions in a familiar way with piping and currying, like
myList->List.length
or
myArray->Array.map(item => item * 2)

Sound type system and type inference

This is probably the main reason to choose rescript. It has strong type system and powerful type inference, so you are rarely required to explicitly define types, but the compiler always knows what the types are.

No folder requirements and no imports

This is a case in many languages, but coming from Java I really appreciate this feature. And Javascript developers love the no imports thing!

Full support of algebraic data types

It's very easy to describe any domain with the custom types
You can create type aliases like type eventId = string or complex types like

type event = {
  id: eventId,
  name: string,
  uniqueName: option<string>,
  description: string,
  properties: list<property>,
  types: list<eventType>
}

The main construction in the language is the exhaustive switch optimized for pattern matching

It's accompanied by an empowered kind of enum called variants. There are options of variants with and without duck typing. Better to see it in action

Simple syntax

It's possible to start writing code after just a few hours of learning if you already know another programming language.

Relatively safe refactoring

The combination of a rigid type system and exhaustive switches make the compiler very efficient in finding bugs in the compile time.

What are the not so good things?

Simple syntax means it's verbose

There is not much syntax sugar, for example to unwrap an optional constant you'd have to write maybeSomething->Option.map(something -> something->performOperation) instead of maybeSomething?.performOperation() in some other languages.

You have to define functions before using them

Yes, like in good old C.

You can still have type-related bugs

Having a powerful compiler that catches 99% of the type bugs can be too relaxing and it becomes easier to miss that one occasional bug that slips through the compiler checks. 😉

Bonus

We are maintaining a public code style guide for ReasonML, contributions are very welcome!

Kotlin vs Swift: implementing a method that accepts a limited set of polymorphic equitable types

Aleks Verein — Tue, 23 Mar 2021 18:47:34 +0000

At Avo we work on code generation based on tracking plans.
Recently we added a new interface for calling events - before we were generating a method for each event in the tracking plan, i. e. there were methods Avo.userSubscribed(userType, subscriptionType) and Avo.commentAdded(authorId, mentionedUserIds).
With the new interface we create a type for each event, i.e. UserSubscribed with userType and subscriptionType as fields and CommentAdded with authorId and mentionedUserIds fields, and a new method called track that expects instances of those types, like this Avo.track(UserSubscribed(userType, subscriptionType))

Why?

This change makes Avo more flexible to use in large codebases, for example you can build the UserSubscribed events in different parts of you app gradually and pass it around.
You can also build a simple test implementation of the new track interface that does not require mocking.

What are the challenges?

Firstly, we don't want users of the generated code to pass unexpected things to the track method. Only the events defined in the tracking plan are expected.
Secondly, we want the events to be meaningfully comparable.

Solution

Let's see what both languages can offer us to solve this little challenge.

1. Defining the event types.

The ways of choice to define a limited set of types are:

In Kotlin - sealed classes. Sealed classes are abstract classes and you can define their child classes only in the same file. User's won't be able to create their implementation of our sealed class, exactly as we want. This also makes the compiler know the exact set of descendants of our sealed class.

sealed class AvoEvent {
    data class UserSubscribed(val userType: String, val subscriptionType: String): AvoEvent()
    data class CommentAdded(val authorId: String, val mentionedUserIds: List<String>): AvoEvent()
}

In Swift - enums. Enums in Swift are more powerful than in most other similar languages. Each enum case can have any number of variously typed parameters, which is nice for our case. User's are not able to add cases outside of the enum.

public enum AvoEvent: Equatable {
    case userSubscribed(userType: String, subscriptionType: String);
    case commentAdded(authorId: String, mentionedUserIds: [String]);
}

Here things are quite even, since classes are a bit more flexible (more on it in the next section) and also in Kotlin you use common class interface for most things, while in Swift you have to use different entities - classes / structs and enums. On the other hand Swift code looks cleaner.

2. Making the types equitable

In Kotlin we use data classes. Every data class automatically gets equals method implementation without the need to write any code based on the primary constructor values.
In Swift we set our enum to conform the Equitable protocol. In modern Swift if all the used types of a thing we add Equitable protocol to are Equitable you don't need to write any implementation. This is similar for both languages.
Everything is great until we get a enum member with an Any type parameter.
The problem in Swift is that the Any type is not Equitable. And once it appears you have to implement the compare method (==) manually. Moreover, once you have the compare method you have to manually implement comparison of each enum case. (In Kotlin for example we can implement the equality method on a separate single child class of our sealed class, that's the advantage of sealed classes over enums I mentioned in the previous section).
In Kotlin Any type is equitable out of the box. Since it's has equals method it is designed to be.

This point is won by Kotlin.

3. Picking what to do based on the provided parameter

Here everything is quite simple:
In Kotlin we use when statement.
In Swift we use switch statement.
The good thing about the switch statements in Swift is that they are required to be exhaustive. This makes perfect sense in a statically typed languages - I want to be sure that if I add a new case to my enum and not add it to the switch I'm alarmed by the compiler.
Unfortunately it is not the case in Kotlin. When you use when as a statement, not assigning it's result to a variable or using it in some other way, which is a default way for those who come from Java and many other C-like languages, it is not required to be exhaustive. You can use when as expression and then it becomes exhaustive, but that's not enough. Here is a bit more on that topic.

In this part I give the point to Swift.

Results

All in all, it is a draw in out little face off, Kotlin is a winner on the data structure design side and Swift wins in the operator design.

What are great developer docs? Looking at Stripe here, let's discuss

Aleks Verein — Tue, 16 Mar 2021 09:43:30 +0000

Recently I had a chance to work with one of the most honored developer experiences out there - with Stripe, https://stripe.com/docs
Here are a few things I really liked about the docs there and a few flaws I found.

But to be clear, overall I rate Stripe docs very high.

(+) First of all, it's awesome. Human readable prefixes in the API keys, omg, why does not everyone do it?!! I.e. price_****** for a price key and sub_******* for a subscription key
(+) Docs are user story based, which is very cool. It's easy to go with the flow and find what you need. Would totally adapt that. Search is also good, but it is a must nowadays
(-) The subject area is huge, some specific things are hard to find though, i.e. subscription statuses are teased here and there, but the whole list is only in the API docs
(-) Some cherry picked dev docs/references are available through the main docs entry point, but others live at https://stripe.dev and there are no easily findable direct links to the server sdks from the main docs
(+) Server (at least Node.js I worked with) SKDs are exactly like the API reference. This is insanely convenient. I suspect this is one of the reason why the server SDKs are not featured in the main docs

What do you like and dislike about developer docs, for Stripe or any other product? Share some examples!

Public ReasonML Code Style Guide @Avo

Aleks Verein — Tue, 27 Oct 2020 08:58:54 +0000

Just released a blog post about our Code Style Guide approach.

Last week we've open sourced the guide itself on GitHub.

Contributions are adoptions are more than welcome, let's build a canonical ReasonML & ReScript code style guide together!