The Limits of Upfront Specification

Building large systems involves a great many small design decisions, and these cannot all be known in advance or driven entirely from a high-level spec. A specification is at best a starting hypothesis: the real constraints, trade-offs, and edge cases are discovered iteratively, as we proceed with the implementation. We discussed this at length in an earlier article, where we called it Upfront Specification Impossibility. The point is not that specs are worthless, but that the first one is a hypothesis to be revised, never a finished blueprint.

The natural response is to iterate: refine the spec, generate code, review what comes back, and feed what we learn into the next round. That loop works well when each round produces a small, reviewable change.

Design Is Discovered Through Implementation

Reviewing code, particularly while we are still discovering the design, is not the same as writing it. While reviewing the generated code, we review through the chunks validating if it maps to our intent and looking for possible pitfalls. But reviewing rarely forces us to wrestle with the design decisions. Writing code, by contrast, forces us to think through concrete decisions—such as where a responsibility belongs or what boundaries should be exposed so the design can be extended further. It is in making those decisions that a design most fully reveals itself.

The programming language and paradigm we code in shapes the design insight we get. A functional design approach or an object-oriented design approach reveals different aspects of the design, along with idioms and patterns that are natural to the paradigm.

So where do LLMs fit in? I see LLMs playing two roles. They are a great help while we shape the design and its vocabulary, acting as brainstorming partners to help us explore the design space and discover the right abstractions. Once the vocabulary is established, LLMs work as an excellent natural language interface to it.

Domain Abstractions and DSLs

A useful way to frame this is through Domain Driven Design. Its core insight is building a shared conceptual model of the domain in code, and then using that model - which DDD calls a Ubiquitous Language - both to evolve the codebase and to give the team a vocabulary to think and communicate in. Often, it is highly effective to build a domain specific language on top of that model: a constrained syntax for expressing the domain's concepts and operations. Seen this way, most development is the process of building a domain model and using it to evolve the system. The LLM plays two distinct roles depending on whether the domain model already exists. In this article, I will focus on how Domain-Specific Languages (DSLs) work with LLMs.

Why DSLs work so well with LLMs

It is a common experience that DSLs work well with LLMs. PlantUML, Mermaid, and Graphviz are domain specific languages for visual modeling; SQL is a DSL for querying databases; Kubernetes YAML is a DSL for describing cloud infrastructure. These are not general-purpose programming languages — they are deliberately constrained, designed to express a narrow set of concepts in one domain. And it is no surprise that LLMs are remarkably good at generating Mermaid diagrams, SQL queries, or Kubernetes manifests from a plain English description.

My observation is that DSLs make LLMs more reliable because they respond so well to a few in-context examples. A general-purpose language like Java offers lots of valid ways to express the same intent. A DSL strips the variation away. Giving the model a few examples is enough to reliably generate the correct syntax. It's worth noting that frontline models are already heavily exposed to PlantUML or Java fluent interfaces during training, so they aren't starting from scratch. It will be curious to see how smaller, more constrained models perform when tasked with a truly novel DSL.

For an agent — an LLM running in an autonomous generate-and-check loop rather than a single shot generation — there is one more benefit. A DSL almost always ships with a deterministic validator: a parser, a JSON schema, a type checker, or a compiler. The agent can generate a candidate, run it past the validator, and repair it from the error, all without a human in the loop. Crucially, the errors are phrased at the level of the domain — “you cannot select an action before choosing a client” — rather than as a stack trace buried deep in generated code. DSL's toolset itself acts as an excellent harness. We will see it concretely in the Tickloom examples below, where the DSL's grammar is enforced by the host language's compiler and the resulting runs are checked automatically.

It is important to note that this is not a one-size-fits-all solution. The advantage holds while the DSL stays small and constrained enough that a few in-context examples can convey its usage. There is also a real upfront cost in designing and maintaining the language and its semantic model. The payoff is therefore concentrated in well-factored, genuinely constrained DSLs backed by a validator.

Example: Using LLMs to generate diagram rich powerpoint presentations

LLMs make it really easy to build custom tools. While teaching distributed systems, I frequently need to create presentations which mostly have diagrams explaining distributed operations in a cluster. UML Sequence diagrams have been great for that but showing a full sequence diagram while explaining the flow of messages through the cluster is not very useful. I needed a tool to show a sequence diagram step by step in a powerpoint presentation. With the help of LLMs I was able to build a tool which processes a YAML describing the presentation structure with references to the PlantUML diagrams and generates a powerpoint presentation. The PlantUML diagrams are marked with steps, and the tool generates a separate slide for each step. This made it really easy to create diagram-rich presentations.

Generate a PlantUML sequence diagram showing a cluster of three nodes athens, byzantium and cyrene. Put a box to mark the cluster. Actor Alice sends a message “title”, “After Dawn” to athens, Athens sends message to itself. Put a note to show state 'title: After Dawn'. Athens sends message to byzantium which fails. Athens sends to cyrene. Put a note placed to the right of cyrene. athens then checks with isQuorumReached and returning a synchronous Success arrow back to Alice. Put a '[step] marker after each message.

This prompt generates the following PlantUML code with step markers:

@startuml
actor Alice

box "Cluster" #lightblue
participant athens
participant byzantium
participant cyrene
end box

'[step]
Alice -> athens: "title", "After Dawn"

'[step]
athens -> athens: save()

note right of athens
  state:
  title: After Dawn
end note

'[step]
athens -[#red]x byzantium: "title", "After Dawn"

'[step]
athens -> cyrene: "title", "After Dawn"

note right of cyrene
  state:
  title: After Dawn
end note

'[step]
athens -> athens: isQuorumReached()

'[step]
athens --> Alice: Success

@enduml
          

I used it to create a series of slides in a powerpoint presentation. For doing that, I developed a small YAML specification to describe the presentation structure and the diagrams to be used in each slide. This allowed me to use LLMs to create presentations describing complex distributed systems concepts, without having to manually create animations on the slides. An example prompt to generate a slide YAML spec is as simple as following.

Create a slide YAML referring to the diagram 'quorum-write' with a title 'Quorum Write Example'

This generates a slide spec YAML like following:

          - slide:
              title: "Quorum Write Example"
              diagram: "quorum-write"
        

It's important to note that even if the prompt is saying create a slide YAML, it's not any random YAML spec. Because the tool to generate the powerpoint presentation and the YAML specification understood by the tool is used as a context in the prompt, the LLM is able to generate the correct YAML spec which can be directly used by the tool to generate the powerpoint presentation.

The full YAML spec can be viewed at this Github repo

Notice that the LLM played two different parts in this single example. First it was a co-designer — helping shape the step-marked PlantUML extension and the slide YAML on top of existing PlantUML tooling. Then, once that small DSL existed, it became the natural-language interface that turns an English request into a valid spec. We will come back to this division of labour at the end of the article.

Building the Semantic Model

The example we covered in the previous section was straightforward. The YAML was used as a carrier syntax, and I process its parsed syntax tree directly, effectively using the syntax tree itself as my Semantic Model (though this couples the syntax to the execution semantics). But in more complex domains, like distributed systems, we need more complex semantic models to represent the concepts in the domain and the design decisions we have made in the codebase. Let's look at an example based on a small framework I built to quickly build and test distributed systems.

Example: Tickloom — a semantic model for distributed systems

Implementing distributed systems such as quorum-based key-value stores or consensus protocols like Raft and Paxos is a daunting task. Even if implementation is guided incrementally through prompts, specifications, or carefully constructed .md skill files, the asynchronous runtimes still expose an overwhelming space of possible implementation decisions. Threading models, networking patterns, storage coordination, retry behavior, and timing semantics all remain entangled within the generated code. The problem is not merely code generation complexity, but verification complexity. The resulting state space created by all possible interleavings across thread scheduling, network delays, process pauses, and clock skew becomes so large that systematically reviewing and validating correctness across all interacting behaviors is nearly impossible. This is the reason we see that Jepsen tests find bugs even in the most battle-tested distributed systems.

This is exactly where a semantic model is beneficial. Tickloom is a small framework I built to construct and test distributed algorithms. Its abstractions are not a generic runtime; they are a set of design decisions about how a distributed process behaves. Every node runs in a single-threaded tick loop: each call to tick() advances a logical clock by one and processes pending work in a fixed, deterministic order (network, then message bus, then process, then storage). Time is measured in ticks, not milliseconds. Messages are plain Java records. Coordination across replicas is expressed through a Replica base class that already knows about peers, broadcasts, and quorums.

Threading, timing, network delivery are no longer open questions to be re-decided in every prompt. What remains for the algorithm author is the actual protocol logic. A quorum replica, for instance, is just a set of message handlers expressed in the framework's vocabulary.

Because the framework supplies the vocabulary — Replica, quorumRequest , countResponseIf, MessageType, Handler — a prompt can stay at the level of the protocol rather than the plumbing:

Using the Tickloom Replica abstraction, implement a quorum-based key-value store. A client GET should collect values from a majority and return the one with the highest timestamp (last-writer-wins). Apply a write locally only if its timestamp is newer than the stored one.

This high level description produces code like following:

@Override
protected Map<MessageType, Handler> initialiseHandlers() {
    return Map.of(
            LWWMessageType.CLIENT_SET_REQUEST, this::handleClientSetRequest,
            LWWMessageType.CLIENT_GET_REQUEST, this::handleClientGetRequest,
            LWWMessageType.INTERNAL_SET_REQUEST, this::handleInternalSetRequest,
            LWWMessageType.INTERNAL_GET_REQUEST, this::handleInternalGetRequest,
            LWWMessageType.INTERNAL_SET_RESPONSE, this::handleInternalSetResponse,
            LWWMessageType.INTERNAL_GET_RESPONSE, this::handleInternalGetResponse
    );
}

private void handleClientGetRequest(Message message) {
    var req = deserializePayload(message.payload(), ClientGetRequest.class);
    var internalReq = new InternalGetRequest(req.key());

    this.<InternalGetResponse>quorumRequest(LWWMessageType.INTERNAL_GET_REQUEST, internalReq)
            .countResponseIf(r -> true) // any response is fine, just need a majority
            .send()
            .whenComplete((responses, error) -> {
                if (error != null) {
                    send(createMessage(message.source(), 
                                       message.correlationId(), 
                                       new ClientGetResponse(req.key(), null, false),
                                       LWWMessageType.CLIENT_GET_RESPONSE));
                    return;
                }

                byte[] highestValue = null;
                long highestTimestamp = -1;

                for (InternalGetResponse r : responses.values()) {
                    if (r.value() != null && r.timestamp() > highestTimestamp) {
                        highestTimestamp = r.timestamp();
                        highestValue = r.value();
                    }
                }

                boolean found = highestValue != null;
                send(createMessage(message.source(), 
                                   message.correlationId(), 
                                   new ClientGetResponse(req.key(), highestValue, found),
                                   LWWMessageType.CLIENT_GET_RESPONSE));
            });
}

source

The semantic model itself acts as a context. The prompt names concepts that exist as concrete types in the codebase, so the LLM is not inventing a threading model or a networking layer — it is filling in protocol logic against a fixed, well-understood substrate.

Even good abstractions help — without a DSL

A DSL is one end of the spectrum, and it is not easy to build. Before reaching for a language of your own it is worth noticing that a clean set of abstractions is already a lighter version of the same idea — and, just as the framework supplied the vocabulary for the quorum store above, a library's named types and methods are themselves a vocabulary the model can be grounded in. Tickloom's semantic model is really just four such seams — Process/Replica for compute and message handling, Network for communication, Storage for persistence, and a logical Clock for time — and that decomposition does most of the work with no new syntax at all.

This is why abstractions, not just DSLs, pair well with LLMs. A prompt to “implement Raft as a Tickloom Replica” has limited state space to explore. The existing QuorumReplica can be used in context as a worked example.

Example: Building a DSL for testing distributed system scenarios

Implementing the algorithm is one thing; exercising it is another. The subtle bugs in distributed systems live in specific orderings: a write that replicates to one node before a reader's quorum shifts, a partition that heals at just the wrong moment, two coordinators whose clocks have drifted apart. Writing such a scenario directly against the testkit involves juggling futures, and manual tick() loops. Here is a clock-skew scenario written that way:

Cluster cluster = new Cluster()
        .withProcessIds(Arrays.asList(ATHENS, BYZANTIUM, CYRENE))
        .useSimulatedNetwork()
        .build(QuorumReplica::new);

cluster.start();

try {
    cluster.tickUntil(cluster::areAllNodesInitialized);

    cluster.setTimeForProcess(ATHENS, 1000L);
    cluster.setTimeForProcess(BYZANTIUM, 2000L);

    QuorumReplicaClient alice = cluster.newClientConnectedTo(ALICE, ATHENS, QuorumReplicaClient::new);
    QuorumReplicaClient bob = cluster.newClientConnectedTo(BOB, BYZANTIUM, QuorumReplicaClient::new);
    QuorumReplicaClient reader = cluster.newClientConnectedTo(READER, ATHENS, QuorumReplicaClient::new);

    TickCompletableFuture<SetResponse> bobWrite = bob.set(KEY.getBytes(StandardCharsets.UTF_8), "B".getBytes(StandardCharsets.UTF_8));
    cluster.tickUntilComplete(bobWrite);

    TickCompletableFuture<SetResponse> aliceWrite = alice.set(KEY.getBytes(StandardCharsets.UTF_8), "A".getBytes(StandardCharsets.UTF_8));
    cluster.tickUntilComplete(aliceWrite);

    TickCompletableFuture<GetResponse> read = reader.get(KEY.getBytes(StandardCharsets.UTF_8));
    cluster.tickUntilComplete(read);

    assertEquals("B", new String(read.getResult().value(), StandardCharsets.UTF_8));
} finally {
    cluster.close();
}

source

The intent — “Bob writes through Byzantium, Alice writes through Athens, a reader sees Bob's value because Byzantium's clock was ahead” — is buried under mechanics. This is also a hard to verify code: there are dozens of incidental decisions (when to tick, how to encode bytes, which factory overload to call) for an LLM to get subtly wrong, and a reviewer must check every one of them.

So on top of the semantic model I built an internal DSL whose vocabulary is the vocabulary of the scenario itself — servers, clients, who is connected to whom, what each client does, and which faults are in effect while it does it. The same scenario becomes:

        Scenario<QuorumReplicaClient> scenario =                        
                        QuorumStepBuilder.scenario("LWW lost update via server clock skew")
                        .servers(ATHENS, BYZANTIUM, CYRENE)
                        .clients(ALICE, BOB, READER)
                        .client(ALICE).connectedTo(ATHENS)
                        .client(BOB).connectedTo(BYZANTIUM)
                        .given(g -> g.serverTimeAt(ATHENS, 1_000L)
                                     .serverTimeAt(BYZANTIUM, 2_000L))
                        .steps(s -> {
                            s.client(BOB).writes(KEY, "B").expectSuccess();
                            s.client(ALICE).writes(KEY, "A").expectSuccess();

                            s.client(READER).reads(KEY)
                                    .expectResponse(v -> "B".equals(v));
                        });

source

The DSL is a thin, declarative surface that compiles down to a pure intermediate representation — a Scenario made of Steps, where each step carries an Action (a read or write) and optional ClusterEvents (faults like partitions and message delays). Faults read as English too: partition(BYZANTIUM).from(CYRENE), reconnect(BYZANTIUM), delay(INTERNAL_SET_REQUEST).from(ATHENS).to(BYZANTIUM, CYRENE).byTicks(100). The grammar is enforced by the type system through progressive interfaces — you cannot declare a step before the topology, or an action before selecting a client — so whole classes of malformed scenarios simply do not compile. Because the DSL is an internal DSL built in Java, the host compiler validates the grammar for free, and a malformed generation comes back as a compile error pinned to exactly the illegal step rather than a runtime surprise.

Once the DSL exists, a natural language description of a failure scenario maps almost directly onto it. A prompt like:

Using the Tickloom scenario DSL, write a scenario reproducing the DDIA §10.6 non-linearizable quorum read. A writer connected to Athens sets the key, then updates it while replication from Athens to the other replicas is delayed. Alice, reading through Byzantium, is forced onto a quorum that includes Athens and sees the new value; Bob, reading later through a quorum of Byzantium and Cyrene, still sees the old value.

yields a scenario that stays entirely within the DSL's constrained vocabulary:

Scenario<QuorumReplicaClient> scenario =
        QuorumStepBuilder.scenario("Non-linearizable quorum read")
                .servers(ATHENS, BYZANTIUM, CYRENE)
                .clients(WRITER, ALICE, BOB)
                .client(WRITER).connectedTo(ATHENS)
                .client(ALICE).connectedTo(BYZANTIUM)
                .client(BOB).connectedTo(BYZANTIUM)
                .steps(s -> {
                    // Writer sets the key to VOLD initially and it replicates fully
                    s.client(WRITER).writes(KEY, VOLD).expectSuccess();

                    // Writer updates to VNEW, but replication from Athens is delayed
                    s.client(WRITER).writes(KEY, VNEW)
                            .whileClusterEvent(delay(QuorumMessageTypes.INTERNAL_SET_REQUEST)
                                    .from(ATHENS).to(BYZANTIUM, CYRENE).byTicks(100))
                            .expectSuccess();

                    // Alice reads through Byzantium. Force quorum to include Athens by partitioning Cyrene.
                    // She will read VNEW from Athens.
                    s.client(ALICE).reads(KEY)
                            .whileClusterEvent(partition(BYZANTIUM).from(CYRENE))
                            .expectResponse(v -> VNEW.equals(v));

                    // Bob reads later through Byzantium. Force quorum to include Cyrene (and exclude Athens).
                    // The delayed VNEW replication hasn't arrived at Cyrene, so Bob reads VOLD.
                    s.client(BOB).reads(KEY)
                            .whileClusterEvent(reconnect(BYZANTIUM))
                            .whileClusterEvent(partition(BYZANTIUM).from(ATHENS))
                            .expectResponse(v -> VOLD.equals(v));
                });

ScenarioResult result = scenario.run();

source

Because the surface is so small — and the space of valid code it can generate is so much smaller than the space of valid Java programs — the LLM has very little room to hallucinate, and a reviewer can read the result as a description of an experiment rather than as code to be audited line by line. Even if LLM hallucinates, the internal DSL will fail to compile allowing LLM to correct the errors made.

Two phases working with LLMs

A pattern emerges from the examples discussed above: in every one of them the LLM was useful in two quite different ways.

The first phase is designing the abstraction or DSL itself. Here the LLM is best treated as a brainstorming partner rather than a code generator. As argued at the start of this article, the design decisions that make up a semantic model cannot all be specified upfront — we discover the constraints, trade-offs, and edge cases as we implement them. So this phase is inherently iterative and feedback-driven: you propose a structure, try it against a real case, see where it turns out awkward, and feed what you learned back into the next round. The LLM speeds that loop up — it sketches alternatives, critiques a design, ports an idea from one language to another — but you stay firmly in the driver's seat, because these are exactly the decisions you need to understand and own. The structures that make a DSL pleasant to use, like progressive interfaces that make an illegal scenario fail to compile or a semantic model kept separate from the builder that produces it, are the kind of thing you converge on by iterating, not by writing a specification and generating code.

The second phase begins once the abstraction or DSL is in place. Now what the LLM does changes: it becomes a natural-language interface to what you have built. The prompts in this article are examples — “implement a quorum store as a Tickloom Replica”, “write a scenario reproducing the DDIA §10.6 read”, “create a slide YAML for this diagram”. In each case the English description maps almost directly onto the vocabulary you defined, and the LLM is a dependable generator precisely because the abstraction supplies both the context that grounds the prompt and the harness that checks the result.

The DSL as the Source of Truth

There is a growing trend of treating prompts as the primary source of truth. A well-designed DSL fundamentally changes this dynamic. One of the key advantages I observe of working with DSLs is that the generated program itself often becomes the artifact that humans maintain. Because a DSL is dense, expressive, and largely free of incidental boilerplate, it captures the essential intent of the solution in a form that remains readable long after generation. If an LLM generates a Tickloom failure scenario from a natural language request, the resulting scenario is already expressed in the vocabulary of the domain. If the scenario needs to change next month, there is no need to recover the original prompt and regenerate everything. The DSL has enough context for LLM to know the intent and work with it. The enduring asset is not the prompt, but the DSL and the semantic model.