This one of the biggest blockers to the company making progress in any meaningful way.

Now, I should clarify that I am not blindly anti-doc. For the majority of non-technical employees, a document is the appropriate format for communication. The product managers I have worked with communicate largely through specification documents and various tickets, epics, and other project abstractions. The human resources specialists I have collaborated with maintain sets of documents with policies and other relevant information. This is appropriate as these people, for the most part, do not possess the necessary training or skills to create any other type of artifact. As a contrast, designers are producing and consuming mocks or flows of some sort, the same way that engineers and other technical employees (engineering managers, engineering directors, VP of engineering, CTO, etc.) should be producing and consuming code.

Documents on their own do not create problems, and have a wide range of use cases for which they are appropriate. The problem arises when an organization's culture shifts to encourage technical discussion through documents rather than code.

Programming languages were invented to allow human beings who predominantly communicate in natural language to express intent in a clear and specific enough manor to avoid ambiguity. Without programming languages, it is impossible to specify technical details in a way that isn't subject to misinterpretation. As a result, in order to contribute positively, a computer scientist must become fluent in these languages, so that they can express themselves to both the computer and other human contributors in a way that is both understandable and does not leave details to the imagination.

This is not to say that abstract conversations about computer science are not productive. These conversations are generally required for education and the building of a shared understanding, but they are never the definitive source of truth. That honor is reserved for the software artifact created as a result of the discussion, rather than the discussion itself.

Unsuccessful engineering orgs lose sight of this principal in favor of the "design document".

What is the design document?

This can vary from org to org, but for most a design document is typically supposed to describe the following:

1. The top down architecture of the system being built and it's components (the classic boxes with arrows).
2. The interfaces for which the system will interact with it's dependencies and customers.
3. The structure of the code that will be written and how it will be organized.
4. How the system will be tested.
5. How the code will be deployed.
6. Logging, alerting, and metrics that will support the system.
7. Justifications and research to support the above.

The theory behind this concept is sound: "software is complicated and expensive to build, requiring the manpower of multiple people and serious time and commitment, if we don't have a plan for it then how can we ensure it will be built properly?". Or more practically, if multiple people are supposed to collaborate on a project, how will they know what to do without a document describing what needs to be done?

These two challenges (needing a plan and building a shared understanding for collaboration) are why most people building software accept and support the writing and sharing of a design document, and are stubbornly afraid to push forward without it. For these people, the design document represents a safe and paved road through the dark and forboding jungle of possible constraints, tradeoffs, and design decisions as well as a bulwark to cower behind in the event that something goes wrong.

Security issue? The security review of the design doc will catch it.

Scaling concern? The system design panel reviewing the design doc will catch it.

System inconsistent with the product specification? Just make sure the design doc matches the product spec, and you are all set.

These are the promises of the design document, and the foundation of sand on which modern software is built.

The allure of the design whispers in the ears of developers, middle management, VP's, and executives alike and convinces them that all of these problems can be solved through review and writing.

After the n'th review of the document, everyone feels satisfied. The debates have been had, concerns have been heard, revisions have been made, and a few months after the ideas conception, engineers can finally begin programming, it should be easy now seeing as all the hard problems have already been solved, after all we have an ironclad design document to refer to.

As anyone who has participated in this process before will tell you, this is not what happens in practice. Unforeseen blockers arise, progress is delayed, new tradeoffs must be made, and in the event of success, someone is still paged in the middle of the night to allocate more nodes to handle demand.

Why does this happen? We went through the design document thoroughly, everyone reviewed and signed off on it, was the entire engineering org wrong?

No, everyone was right. That is the problem.

The design document was written in natural language, which is far too abstract to express the real issues that will arise from the implementation of whatever complex system is being described.

The situation described above where actual software is written is the best case scenario. In most cases, the document serves to block progress rather than enable it.

A design document allows all of the planning and ideas to take place in the world of abstraction, and as it is abstraction through natural language there are infinite ways to prove, disprove, undermine, or overwrite the various ideas contained in the document. A developer who wants to block the document can say "this won't scale because of x", a security engineer who doesn't want to be responsible for a new vulnerability can say "we don't support that type of connection here, so you can't build it that way", a product manager can say "this won't match arbitrary requirement a, because it first needs to do b" and all would be right, because no software has actually been written. In each contributor's head, there is a narrative describing the final outcome based on their own interpretation of what is written, and for each of these people that narrative will be different. In many cases drastically so.

As each individual maintains their own idea and interpretation of the system, there is inevitable conflict and confusion over what the document is actively describing, and this is where progress breaks down.

First, some relevant context about where I work. I am currently a senior software engineer at a very late stage (series F) software as a service startup of about a thousand people. Of these thousand there are about two hundred and fifty engineers managed by engineering managers, directors, and a vice president of engineering. Per directive from the CEO and the CPO (Head of Product), it is the responsibility of the VP and the directors to harness the latent potential of these new generative tools to obtain the fabled "LLM Productivity Boost" that they are hearing about at various conferences, interactions with peers, and social media.

LLM Productivity Boost

I define the "LLM Productivity Boost" as a hype cycle where various teams claim to complete herculean tasks by properly organizing their team with agentic development in mind, then relying heavily on the agent to generate vast amounts of complex code incredibly quickly. Some examples include: the Claude C Compiler, the Eight Person Bedrock Rewrite, and Stripe's Minions. The reason I say claim here being that the Claude C Compiler cannot compile hello world and the eight person Bedrock rewrite has been debunked by numerous AWS employees. Stripe Minions appear to be effective, at least they seem to be from the internal tools we have built replicating their described workflow, but are limited to small tasks.

To achieve these productivity gains, the VP and their directors are dutifully studying the tools and appointing individual contributors (deemed "expert in generative AI") to carry out the task of equipping the other engineers with the environment needed to facilitate fully agentic development. The nature of the tasks needed to accomplish this goal are anyone's guess, but have at least started with a series of debates on how productivity itself should be measured.

Hypotheses of Agentic Development

There are a multitude of proposed paradigms circulating for how to efficiently use LLMs to build software, but the majority can be distilled into the following two hypotheses:

1. Autonomous LLM agents will increase the rate at which I can ship features.
2. The bottlenecks I previously faced in my engineering org can now be automated away.

Alone, each of these statements appears reasonable, especially with the overwhelming marketing campaigns enacted by the model providers (OpenAI, Anthropic, etc.) themselves. It is evident from the marketing example A and example B, that billions of the bubble dollars are being allocated towards driving adoption that will increase the bubble's size.

When building a video game, teams employ the "player fantasy" to inform design decisions. The player fantasy refers to "core emotional experience or power trip a player wants to feel when playing a game". Generative and agentic tools are marketed with the same mechanism, but instead of game mechanics, agentic tools promise the hypotheses above: I can ship faster, and my bottlenecks will be automated away. Or worded differently: I am no longer dependent on people with skills I do not possess to accomplish my goals.

The reality is, predictably, much messier.

Let's take a new settings menu as an example. The current agentic tools are geared towards generating code, and a functioning enterprise organization has multiple parts before and after implementation that also take time. Product must create a spec for what settings will be available and what the knobs will change, design must create the flows for the UI, multiple system design reviews are conducted to ensure the implementation of the knobs will not break the rest of the application, a security review must take place to ensure customers can't change anything dangerous. Once this is all finally complete, a single developer with an agentic tool might finish the implementation in a day, but two months have already gone by since the ideas conception.

This all takes place under the generous assumption that the org's procedures were properly followed.

Human nature is much more dynamic, and while some organizations have a strong culture and process, the majority do not. Rather than waiting for the design reviews the developer implements without a plan. The UI is added on top later once design is finished, and product decides the designs don't match their specification when everything is revealed at an unrecorded ad-hoc meeting. Engineers from another team on which the feature depends block various pull requests, then go on vacation. Nobody will remember the security team's existence until there is a P0 security incident months in the future.

The culmination of this dysfunctional process is a feature released months after it's conception, but the actual programming work (especially with the agentic tools) only took a few hours.

So then how do we actually speed things up?

It is undeniable that if properly prompted, a model can take days worth of engineering work and spit out average quality code that eighty percent of the time accomplishes the intent described. Additionally, the models shine within the realms of interpolation and repetition. By narrowing the scope and providing the model with a closed and complete system, teams can automate large amounts of work in ways that were previously impossible.

LLMs and agentic tools are multipliers, not creators. Given a well written codebase with minimal debt, most models can duplicate the patterns defined by the code and teams can and should automate small and menial tasks within these closed systems.

Due to their nature as multipliers, these models lift up the rock that covers most engineering orgs. If the org has inefficient processes, bottlenecks, or other issues that hinder productivity, these will not be magically fixed by the multiplying agent, they will exponentially worse than they were before.

LLMs and agentic tools hold up a mirror to previously functional orgs, and highlight imperfections that were previously invisible.

An organization that is purely blocked by implementation speed will feel the effects of agentic development instantly. For everyone else, things are going to get a lot slower before they get any better.

Further reading: Every layer of review makes you 10x slower

To begin, create a new directory and initialize it as a node module:

npm init -y

Then, add the required dependencies to the package.json

"devDependencies": {
    "clean-webpack-plugin": "^4.0.0",
    "electron": "^16.0.5",
    "html-webpack-plugin": "^5.5.0",
    "ts-loader": "^9.2.6",
    "typescript": "^4.5.4",
    "webpack": "^5.65.0",
    "webpack-cli": "^4.9.1"
}

Once the dependencies are set, install with

npm i

Next up we will create a tsconfig.json file which will tell the TypeScript compiler to put our compiled code in the ./dist directory

{
    "compilerOptions": {
        "outDir": "./dist/",
        "noImplicitAny": true,
        "module": "es6",
        "target": "es5",
        "allowJs": true,
        "sourceMap": true,
        "moduleResolution": "node"
    }
}

Having created a tsconfig.json, we can now create a ./src directory for three files: an index.html, electron.ts, and client.ts. First index.html is the root html page that the electron app will serve.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport"
        content="width=device-width,
        user-scalable=no,initial-scale=1,
        maximum-scale=1,minimum-scale=1">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>TS & Webpack</title></head>
<body>
</body>
</html>

The second file electron.ts is the electron process. This file is repsonsible for creating the browser instance, serving it in a window, and for loading the root html document ./index.html.

import { app, BrowserWindow } from "electron";

function createWindow() {
    // Create the browser window.
    let win = new BrowserWindow({
        width: 800,
        height: 600,
        webPreferences: {
            nodeIntegration: true,
        },
    });
    // and load the index.html of the app.
    win.loadFile("../dist/index.html");
}

app.on("ready", createWindow);

It is important to note that the path for index.html is ../dist/index.html and not ./index.html. Finally, client.ts is the entry point for clientside functionality inside the chromium instance being served by electron.ts.

window.addEventListener("load", () => {
    const header = document.createElement("h1");
    header.innerText = "Webpack & TS";

    const body = document.querySelector("body");
    body.appendChild(header);

    let div = document.createElement("div");
    div.innerText = "Hello World!";

    body.appendChild(div);
});

With our ./src directory implemented, the final step is to use Webpack to package our code so that it can run in electron's browser instance. To acomplish this we will create two Webpack config files in the root directory: webpack.config.js and webpack-cli.config.js. The first config, webpack.config.js, is for the server side code in electron.ts.

module.exports = [
    {
        mode: 'development',
        entry: './src/electron.ts',
        target: 'electron-main',
        module: {
        rules: [{
            test: /\.ts$/,
            include: /src/,
            use: [{ loader: 'ts-loader' }]
        }]
        },
        output: {
        path: __dirname + '/dist',
        filename: 'electron.js'
        }
    }
];

This module finds our electron.ts entry point for our electron process and builds it using our tsconfig.json. The second Webpack config file webpack-cli-config.js is responsible for building client.ts using tsconfig.json, and packaging it into browser code so that it runs inside the electron browser instance.

const HtmlWebpackPlugin = require('html-webpack-plugin');
const {CleanWebpackPlugin} = require("clean-webpack-plugin");
const path = require('path');

module.exports = {
    mode: "production",
    entry: path.resolve(__dirname, './src/clientmain.ts'),
    module: {
        rules: [
            {
            test: /\.tsx?$/,
            use: 'ts-loader',
            exclude: /node_modules/,
            },
        ],
    },
    resolve: {
        extensions: ['.tsx', '.ts', '.js'],
    },
    // <- ensure unique bundle name
    output: {
        filename: 'bundle.[hash].js',
        path: path.resolve(__dirname, 'dist'),
    },
    plugins: [
        new CleanWebpackPlugin(),
        new HtmlWebpackPlugin({
            template: path.resolve(__dirname,
            "./src/index.html")
        })
    ]
};

Now we update our package.json to run and build properly:

"scripts": {
"start": "npm run build && electron dist/electron.js",
"build": "webpack --config ./webpack-cli.config.js &&
          webpack --config ./webpack.config.js"
},

and run our application using

npm start

An example repo containing this code can be found here.