Simon's Blog

Five years ago, writing some software in an unfamiliar language in my spare time might have had some value beyond hobbyism. I’d learn new syntax, new idioms, and hopefully some best practices. Now I'm reconsidering where to focus my efforts. AI agents can write better code than I can in most languages. Churning out working code isn’t anything special. The skills that seem to matter most now are architecture and judgement: the things that make an engineer senior¹. You learn these skills best from complex projects with real production users.

In this post, I’m exploring the idea that using AI agents to map out the development of prominent open-source codebases can develop judgement in ways that would have required becoming a long-time contributor in the past. The kind of judgement I’m looking at is:

• Which interfaces and abstractions earn their place as a project evolves?
• Where do the trade-offs lie, even for sound decisions?
• How does the concurrency model hold up as things get complex and scale?
• What automation and processes can tame a project’s complexity?

This is the thesis I’m testing: While AI agents take with one hand by making hobby coding even less valuable, they can give with the other by helping us glean wisdom from open-source projects.

I chose to look at a Go project because while I’m not very familiar with the language, it's relevant to my current role as a platform engineer. Most of the technologies I use daily are written in Go. Notably: Docker, Kubernetes, OpenTofu (Terraform fork), and the OpenTelemetry collector. I’ve written some Go on weekends: Advent of Code and the kind of low-stakes projects that don't seem to matter now. I may have nearly a decade of commercial software engineering experience, but I lack Go-specific battle scars. For instance, I've never had someone complain that a Go interface I wrote years ago is now causing them problems, as I have with the public API of Python modules.

Below I ask an agent to summarise the state of etcd (the distributed key-value store underpinning Kubernetes) at key versions, then synthesise it into a narrative of how the system developed in response to user needs and production scale. This is a jumping-off point for exploration and thinking. I acknowledge the risk of regurgitating AI-generated text without truly understanding it, so I endeavour to explore the threads I write about independently.

What I Learned from etcd

I started with some AI-assisted git archaeology. I prompted² Claude Code (Opus 5) to generate a report on each of four etcd versions, v0.1.0 to v3.7.1. I read the individual reports, which were overwhelming because they contained more plausible observations than I could ever hope to verify. To find a thread running through all versions, I used a second prompt³, along with the reports, to generate a summary. The only thing I’ll directly quote from the summary is this table. It shows, at a high level, how the project grew and when each API version arrived and left.

Non-test, non-generated, non-vendored Go lines, measured per tag (git ls-tree -r <tag> filtered to *.go, excluding _test.go, *.pb.go, and third_party/, Godeps/, cmd/vendor/, */vendor/):

	v0.1.0	v2.0.0	v3.0.0	v3.7.1
Whole tree	3,204	16,909	57,860	110,019
Consensus library	3,798 (vendored go-raft)	2,034 (raft/)	3,666 (raft/)	0 (external module)
v2 keyspace state machine	1,203	1,907	2,212	2,231 (no API)
v3 keyspace state machine	—	—	3,346	3,962
Watch	129	434	988	1,180
Lease / TTL	(inside store)	(inside store)	651	1,522

What stands out most in this table is that the Raft consensus implementation has had three homes: first as a vendored library, then in the repository, and finally spun out into a separate repository.

Spinning Out a Pure Raft library

Raft⁴ is the consensus algorithm that keeps the keys and values stored in etcd consistent across multiple nodes. Raft means production Kubernetes clusters can deploy their data store across multiple nodes in a highly available configuration. Raft also underpins many of the guarantees etcd provides.

A thread Claude identified from the initial v0.1.0 release to the recent v3.7.1 was the Raft consensus seam, which, as of today, connects the etcd server to a pure logic Raft library that leaves I/O to the consuming system. The same library, extracted from etcd, is used by other distributed databases including CockroachDB and Dgraph.

In v0.1.0, there was a different external Raft library, and its interface wasn’t as clean. Raft wrote to the file system to update the log; it also called time.Sleep. By v2.0.0, this was replaced with an in-repo implementation: the I/O was factored elsewhere and time was represented as a logical tick rather than interacting with a system clock. (When attempting to understand the new Raft library, my puny meatbag brain found the simplified key-value store example code more helpful than current etcd source code.)

At the time of writing, the Raft library README says:

Most Raft implementations have a monolithic design, including storage handling, messaging serialization, and network transport. This library instead follows a minimalistic design philosophy by only implementing the core raft algorithm. This minimalism buys flexibility, determinism, and performance.

When writing software professionally, I try to extract business logic so it doesn’t contain side effects and I/O, favouring pure functions and dependency injection. Even in commercial software, this can be hard to achieve, and the payoff is often limited. For something like Raft, which has a PhD thesis devoted to it, I can imagine it was much harder. The payoff is greater too, as other distributed databases can and do use the system regardless of how they implement I/O.

Not all software components can be pure, however. In etcd, they didn't delete the messy parts; they moved them to the etcd server.

The Messy Details

In version 0.1.0, etcd passed go-raft a directory path to write log entries to. This was paired with a callback function that applied log entries to etcd’s state.

type Log struct {
 ApplyFunc   func(Command) (interface{}, error)
 file        *os.File
 path        string
 entries     []*LogEntry
 results     []*logResult
 commitIndex uint64
 ...
}

Source code here.

The first external Raft library owned I/O and also owned the messy business of ensuring that all log entries were applied to the store. This is simpler in some ways because go-raft could commit changes to the log and apply them to the data store in the same function, managing concurrency with the same mutex.

From version 2.0.0, even before it became a separate library, the Raft component contained only the business rules for keeping multiple nodes’ state consistent. The etcd server was now responsible for ensuring that the database’s state reflected the WAL entries. At this point, though, not much could go wrong. As in version 0.1.0, the state lived in memory, so if a node died, it would rebuild the state from a combination of a snapshot and the WAL.

In version 3.0.0, the database state became durable. The release notes mention “new storage engine”. The part of this engine that stored key-value data on disk was Bolt (a fork of. While this change gave etcd better transaction isolation (the I in ACID) with MVCC, it also created a new durable record on every node: the key-value store in addition to the existing Raft WAL. This introduced a new problem when rebuilding an etcd node’s state: the etcd server needed to track the WAL offset that had so far been committed to the node’s key-value store. etcd committed to Bolt in batches (every 100ms or 10,000 writes), so after a crash the database could lag behind the log, and if it replayed already-applied entries, it could apply them twice.

This is the commit message for saving that offset to Bolt: “etcdserver: save consistent index into v3 storage […] This helps to recover consistent index when restart in the future.” Consistent index doesn’t mean that the index is consistent, so much as that it’s the index of the latest committed Raft WAL entry that’s been written to the etcd server’s on-disk state. At this point, the design is sound: the index is written in the same Bolt transaction as the data, so after a crash both are at the same point, and etcd knows exactly where to resume. From v3 onwards, data consistency rests on this being true in all situations.

Version 3.0.0 burdened the etcd server with ensuring that the consistent index agreed with what WAL entries had in fact been applied. It introduced a new class of potential bug which eventually manifested, resulting in error reports like this one. It is every Kubernetes user’s nightmare: “Some keys exists on node x and y but not on node z, and some on z but not on the other two, e.g. different pods list would be returned from different servers.” The root cause turned out to be this PR, which aimed to ensure the consistent index was saved on each commit. Unfortunately, there were a couple of unintended consequences:

1. The in-memory consistent index value was shared state, read by any commit, not just the one carrying the matching data.
2. This in-memory value was updated before the transaction was committed to the key-value state (Bolt), creating a window in which a concurrent commit could persist it (e.g. the periodic commit that runs every 100ms).

Saving the index and saving the data it pertained to no longer comprised an atomic operation.

Postmortem, Pragmatism and Priorities

The refactor that caused the bug was merged in May 2021 and shipped in v3.5.0 a month later. The first report of diverging etcd nodes arrived in December 2021. A maintainer confirmed the corruption in March 2022; the maintainers sent a public statement to the etcd and Kubernetes mailing lists, and the fix shipped in v3.5.3 in April 2022.

This wasn't the first time this class of bug surfaced. In August 2016, two months after 3.0.0 shipped, a maintainer fixed the same failure mode in a different place (#6247). A snapshot routine could save the consistent index to disk after apply had updated it, but before apply had written the matching data. Their commit message describes the 2022 bug almost exactly, and ends by noting there were other places that needed the same care, “but let us fix this first”. A 2020 bug in the auth store (#11652) was another variation on the theme. The danger was known and named for five years. Each fix patched a particular symptom. Nothing turned “the index is only saved alongside its data” into something the code enforced.

The 3.5.3 fix (#13854) finally did that. It split the in-memory value in two: an applying index for the entry currently in progress, and a consistent index updated only while holding the transaction lock, so it can reach disk only with the data it describes.

The postmortem says the maintainers were “not aware [of] any cases of users reporting a data corruption in production environment”. They took the issue seriously all the same; databases survive on being trustworthy. What’s interesting about the postmortem is that most of the issues they identified were related to people and processes rather than code. Processes around releases had grown lax. Maintainers had moved on. The automated test suite was flaky and incomplete. They reproduced the bug partly by luck, because one maintainer's /tmp was mounted to a real disk rather than memory. The fix took over a week and involved multiple attempts.

The work that followed the postmortem is what I find most instructive. They haven't undertaken a grand refactor of the EtcdServer god struct, which survives to this day, nor any of the other code smells the agent identified in its reports. I think this is because they had more important priorities. Instead, they built machinery for confidence. They reworked corruption checking. A robustness suite now injects failures and checks every run's history for linearisability. The suite’s README lists known correctness bugs, including those it has caught.

Conclusion

This post ended up being more about software engineering than Go. I think that's fine. The judgement I was hunting for is mostly language-agnostic.

Some of this journey was reassuring in a way. Even a high-profile open source project that many depend on has TODO comments in the codebase, and fossils of old implementations that haven’t been cleaned up. Even here, it took a critical bug to restore release discipline and reliable tests. There was no instant fix. It took careful, coordinated work, much of which was later automated.

I don’t want to overstate what I’ve learned. The initial raw AI reports were hard to follow and simply covered too much ground. I was out of my depth, and all I had were reams of plausible observations. The meat of this post came from a dialogue with Claude, where I tried to cut away everything but the most essential threads of etcd’s story. Without that, this post would likely never have been published.

In domains I’m paid to work in, I guide the agent as much as it guides me. While jumping into an unfamiliar domain and relying heavily on the agent is fine for an experimental piece of writing like this, I wouldn’t feel comfortable being so far out of my depth if I were building software for others. Domain expertise still matters. After reading this, you wouldn't hire me to build a new database in Go. You’d pick a database engineer who can recite Designing Data-Intensive Applications from cover to cover and has shipped Go in production. I’ve gained some second-hand wisdom, and some trivia to bore people with. More valuably, I’ve gained a lasting suspicion of any invariant that lives only in tribal knowledge. Such invariants are even more dangerous now that agents can be dropped into a complex codebase with none of that context.

Was it more useful than a toy coding project? Yes, but not by much. There are no shortcuts to expertise. Real fluency in a language still means working up from basic to advanced material until one can read unfamiliar code and run its logic in one's head, rather than relying on a maintainer's postmortem or an AI agent to explain it. That skill matters more now, not less. We're shipping more code we haven’t read, and sooner or later, even teams running fully automated software factories will need someone who can dive into an unfamiliar codebase and understand what it's doing. The scarcer that skill becomes, the more it will be worth.

So the premise I started with was only half right. Hand-written side projects haven’t entirely lost their value. They're just less impressive. They’re like low-intensity cycling: nobody’s excited by it, but it builds the cardiovascular base that makes the hard sessions possible. Digging through a codebase like etcd is the hard session. Without the base, AI was my e-bike. I covered the distance, but my legs didn’t do most of the work. That’s fine for getting somewhere, but not ideal for getting fitter.

---

1. I’ve chosen the word senior because “expert” is hard to pin down. For instance, managers regularly judge seniority in the industry, though the technical bar for “senior” differs by org; some levelling frameworks try to formalise it. These frameworks cover much more than technical skill, but insofar as they cover the technical side, this from the senior (L50) section of this framework is a good example: “Has the skills to proficiently work on complex and unknown problems under pressure (e.g. debugging complex production issues at speed, or leading the resolution of critical or major incidents)”. Notice it doesn’t mention writing code. This kind of skill isn't automatable yet (though with enough telemetry, an agent can help investigate production issues).

2. The first prompt, run at v0.1.0, v2.0.0, v3.0.0 and v3.7.1: “Explore this codebase and outline its public APIs, its fundamental architecture and software design choices in a Markdown document: etcd-0.1.0.md. References to source code should support all points; priority should be given to where important abstractions are declared/implemented and where they earn their place and, if relevant, where they break down.”

3. The second prompt, used to generate a summary: “Read the markdown documents in the working tree. These all outline the design and trade-offs of etcd at a particular point in time. Generate another document that traces the development of the five most important systems or abstractions over the lifetime of the project. Once one area has been chosen, the source code at the four documented versions should be double-checked and referenced. Pay attention to trade-offs, management of complexity and how abstractions break down as well as design successes.”

4. I’m not a distributed systems expert, so I’m not going to try to summarise Raft beyond saying all nodes maintain write-ahead logs from which state can be built, all writes go through a single leader, and it employs a leadership election mechanism to survive faults. For a more detailed discussion of the Raft algorithm, you can read the original paper. To get some intuition of how leadership and elections work, there’s a web-based simulation here.

Today I'm borrowing a 46-year-old philosophical idea and applying it to contemporary generative AI. I’m curious about what happens to this idea when applied to AI that, unlike what was speculated about in Searle’s time, has actually been built.

John Searle devised his famous Chinese Room thought experiment in response to what he called strong AI. This wasn’t the idea of human-like or superhuman artificial general intelligence (AGI) tech CEOs rave about, but the idea that machines that behave as though they think truly think. One reason these ideas were entertained at the time was that the frontier of artificial intelligence was symbolic rather than numerical, meaning that systems were structured according to formal grammar and logic¹. A scholar who thinks about rules underpinning language all day may be attracted to the idea of a rule-based system that itself thinks. It’s less compelling to imagine that a concatenation of matrix multiplications and other computations understands the sequences of tokens it builds.

I won’t go into detail about the thought experiment, though I’d encourage you to read it in the original article. The basic idea is that someone can produce convincing text-based answers to questions in a language they know nothing about without understanding the questions or answers. All they need are exhaustive formal rules in a language they do know about, on how to respond to sequences of — to them — meaningless symbols.

Because software that lived up to Searle’s room was never actually built², it benefits from an undefined scale. A single person can plausibly follow the potentially vast set of rules because no one formalised them. Due to the number of computations involved in frontier LLM inference and the limited speed at which people can perform arithmetic operations, the subject would need to live for around 380,000 years to generate a token in a conversation with a chatbot. ³ Constrained by human lifetimes, the computation would need to be carried out by a deeply rigid and dogmatic civilisation organised around the purpose of ingesting and producing holy numbers. Even such a dystopia, similar in size to 19th-century England, using telegraph to communicate would produce only five tokens a year. ⁴

I'm not the first to scale this idea up to population size. Ned Block got there before Searle even wrote his paper: his 1978 “China Brain” imagined the entire population of China, linked by radio, simulating a brain neuron by neuron. Searle himself later answered the connectionists with a “Chinese Gym”: a hall of monolingual English speakers hand-cranking a neural network. So the move I'm making here is a well-worn one. What's changed is that the machine on the other side of the analogy now actually exists, which means the scale is no longer a matter of taste: we can put numbers on it.

Let's circle back to Searle's point about incomprehension. I'll try to sketch it out. The scribes or human computers carrying out the calculation wouldn't know what the numbers meant or what they corresponded to. Those privileged few who could access the vaults where the consecrated weight numbers and numbers for divined and generated tokens were stored would not know what symbols the numbers mapped to. The high-ranking bureaucrats who organised inference computation would blindly follow a kind of bureaucratic scripture: their command and control infrastructure operating in the spirit of the Soviet factories that, graded on tonnage, produced chandeliers heavy enough to tear down ceilings, and nail plants that met their quotas with a handful of railway-spike-sized nails.

Scientists caught researching the inference process or building mechanical computers would be publicly executed as heretics. Those who pursued their research in secret would live lonely lives, questioning the consistency of the system they were enmeshed in but lacking a solid basis for any conclusions. Even during the great conjunctions that occur once a generation, the seers who divined new input token numbers from the entrails of sacrificial animals would not know what the numbers meant.

So there it is: an updated Chinese Room, in all its absurdity. It works better as an illustration of just how big large language models are than as a thought experiment. Searle's room has the advantage of not being a closed system, where questions and answers can simply pass under the door. My civilisation has to smuggle its inputs in through an oracle: the divination.

---

1. This is now known as GOFAI: good old-fashioned AI, a term coined by the philosopher John Haugeland in 1985. Think of SHRDLU, which parsed typed English commands to manipulate a virtual world of coloured blocks; MYCIN, which diagnosed blood infections by chaining through roughly 600 hand-written if-then rules; or Cyc, a decades-long attempt to hand-code common sense as millions of logical assertions. Or ELIZA, the 1966 chatbot that parodied a Rogerian psychotherapist using simple pattern-matching rules, fooling some users into feeling understood, which is precisely the illusion Searle was attacking.

2. This kind of symbolic AI Searle was talking about didn’t make it past R&D, let alone being deployed commercially on a planetary scale like generative AI is today. Despite some early hype, research into expert systems and the like was eventually abandoned, leading to the second AI winter starting in the late 1980s.

3. GPT-4.5, which passed the Turing test most of the time in a 2025 study, had hundreds of billions of parameters; OpenAI never disclosed a figure, but following an educated guess let’s say 600 billion active parameters. Assuming two computations for each parameter to generate a token, it would take an immortal, tireless human 3,169 years to complete a single layer of the transformer that drove GPT-4.5. A single token would take at least 380,000 years. This is based on 0.1 arithmetic operations per second for a human scribe.

4. A significant amount of computation that a transformer does is embarrassingly parallel: the vanilla feed-forward neural network that follows the self-attention magic. This could be parallelised across a galaxy if it weren’t for the speed of light nullifying any parallel gains with a huge communication cost. Barring a mega-structure like a Dyson sphere, the distances signals would need to travel within a solar system for each layer of a transformer would be prohibitive. Within a single small landmass, however, batches of computation can be sent by telegraph to outlying population centres very quickly. A core city of 1 million scribes working around the clock in two 12-hour shifts, 10 million more spread across the land, could generate a GPT-4.5 token in just over two months. See the diagram below for an illustration of this. See also this website for a useful illustration of how transformers and LLMs work.

=====================================================================================

                    O N E   T O K E N   B Y   T E L E G R A P H

             the forward pass at city scale: a capital, its towns, a wire

=====================================================================================

  model      600 B parameters, 120 sequential layers, d_model 20,412
  payload    one hidden state = 20,412 values x 16 bit  ~=  327 kbit
  the wire   100 bit/s telegraph, signals at 0.7c -- the 300 km costs a
             millisecond and a half of flight and hours of keying; at this
             scale bandwidth is the tyrant, never the distance


         _
        /_\       +
   +   |(+)|     _|_
  /_\  | : |    /   \      +                ~ 300 km of wire ~
  | |  | : |   /     \    /_\   ~        ,       ,       ,       ,          +
  | |  | : |  /       \   | |  ~        -+-------+-------+-------+-        /_\
 _| |_ | : | |         |  | |   _  _     |       |       |       |   /\    | |   /\
 | : | | : | |  :: ::  | _| |_|    |     |       |       |       |  /__\  _| |_ /__\
 | : | | : | |  :: ::  | | : || [] |     |       |       |       |  |[]|  | : | |[]|
_|___|_|___|_|_________|_|___||____|_____|_______|_______|_______|__|__|__|___|_|__|_

            C A P I T A L                     the telegraph            T O W N S
       1,000,000 core scribes         100 bit/s, signals at 0.7c   10,000,000 scribes


-------------------------------------------------------------------------------------
                     ONE LAYER  --  k of 120, strictly in order
-------------------------------------------------------------------------------------

  clock         CAPITAL (core)                             TOWNS (periphery)
            1e6 scribes, 10 km wide                     1e7 scribes, 300 km out
    .                  |                                           |
 +0.0 h    +-----------+-----------+                               |
    .      | SELF-ATTENTION        |                               |
    .      | half the city on duty |                               |
    .      | (two 12-hour shifts)  |                               |
    .      | core only: every desk |                               |
    .      | may read the whole    |                               |
    .      | token census          |                               |
    .      |  9.4 h arithmetic     |                               |
    .      | +1.8 h keying across  |                               |
    .      |  the city's own wires |                               |
+11.3 h    +-----------+-----------+                               |
    .                  |                                           |
    .                  |          MLP inputs for layer k           |
+11.3 h                |------- 327 kbit ~ 0.9 h of keying ------->|
    .                  |       (300 km of light-lag: 1.4 ms)       |
    .                  |                                           |
+12.2 h    +-----------+-----------+                 +-------------+-------------+
    .      | MLP: capital's share  |                 | MLP FEED-FORWARD          |
    .      | the on-duty half joins|     .  .  .     | ten million desks, each   |
    .      | 0.9 h                 |     in step     | on its own slice; no town |
    .      |                       |     .  .  .     | consults another  (0.9 h) |
+13.0 h    +-----------+-----------+                 +-------------+-------------+
    .                  |                                           |
    .                  |          MLP outputs for layer k          |
+13.0 h                |<------ 327 kbit ~ 0.9 h of keying --------|
    .                  |                                           |
+13.9 h    +-----------+-----------+                               |
    .      | residual add + norm   |                               |
    .      | file the layer record |                               |
    .      | (negligible)          |                               |
    .      +-----------+-----------+                               |
    .                  |                                           |
    v                  v                                           v
             hidden state to layer                       towns sit idle until
             k+1: back to the top                      the next dispatch keys in


-------------------------------------------------------------------------------------
  THE BILL
-------------------------------------------------------------------------------------

  one layer     9.4 + 1.8 + 0.9 + 0.9 + 0.9   =   13.9 hours
  one token     13.95 h  x  120 layers        =   69.7 days
  the split     74% labour / 26% communication

  the capital keys and computes around the clock: two 12-hour shifts, half a
  million desks always lit. the towns need no relief -- each works 0.9 h in
  every 13.9, and the wire itself schedules their rest.

  every communication hour is serialization -- a fist tapping 327,000 bits
  onto the wire at 100 per second. propagation never shows up on the bill:
  the light-lag budget for the whole token is about a third of a second.

=====================================================================================