Everyone wants beautiful music. And a lot of software developers have started fancying themselves as the conductor. We see ourselves the one directing the AI agents orchestra, staying in control at the podium. It's become the default metaphor for AI-era work. Whether it's prompting or agent loops, it's engineers holding the baton, but should they be?

TL;DR: The "AI Conductor" framing quietly re-installs the old gatekeeper pattern developers spent a decade trying to escape. This post argues the better model is to focus on concert hall, the structure that helps ANYONE sound good. Platform engineering and DevOps have already proved this works. Now it's developers' turn.

A conductor is still a gatekeeper

"AI won't take your job, but someone using AI will." — economist Richard Baldwin, World Economic Forum, 2023

For some reason, I always assumed that "someone" would be another developer, or someone with adjacent skills to the person being replaced. I don't think that anymore.

Developers have spent years as the multiplicative gatekeeper for the business. The ones who turn an idea into a technical implementation, that has huge impact on the business. I hadn't really stopped to consider that the gatekeeping itself is our biggest opportunity if we embrace our new role, and our biggest risk if we don't.

"Excel is your biggest competitor."

Why? Because it's a tool people with the problem know how to use to solve the problem themselves. No gatekeeping. Now, they have AI. AI can generate solutions for them, from websites to CRUD apps to iOS apps and beyond. All without you in the way.

"AI Conductor" could sound like evolution for software development. But, we should be passing the baton, not holding onto it. Positioning engineers as the one standing between the idea and the outcome is still the bottleneck, just wearing a nicer metaphor.

It's also not new

Our sysadmin friends already went through this. From platformengineering.org's history of the field:

In the late 90s and early 2000s, most setups had a single gatekeeper (and point of failure): the SysAdmin. If developers wanted to get anything done to run their applications, they had to go through them. In practice, this translated to the well-known "throw it over the fence" workflow — which led to poor experiences on both sides of the fence.

Sound familiar? Except now it's developers, instead of SysAdmins. How many sysadmins do you know who are still hand-installing OSs onto freshly unpacked servers on premise?

Yeah, me too. Whereas a skilled DevOps engineer can provide serious leverage where before there was a bottleneck, running tens, hundreds, thousands, or more servers, CI/CD pipelines, monitoring, and more! The best ones do it without breaking a sweat, while making it easy for developers to do the same, safely.

Build the hall, forget about the podium

That's the metaphor I'm swapping in: the concert hall, not the conductor.

A hall's acoustics, structure, setup are what help the performers sound good, and the orchestra sound AMAZING. But you don't see the architect standing on stage taking a bow. People rarely think about the engineering that makes a great (or small) hall work. That's the point. It can be invisible, and yet a critical component for lifting the performance to greatness.

Platform engineering already lives this distinction, and it gives us the playbook:

• Paved roads / golden paths — automated, secure default paths that let people move fast without becoming infrastructure experts.
• Governance built into the path itself — not enforced as a gate at the end, where it just slows everyone down and gets worked around anyway.
• Built for your scale and constraints — not every solution needs auto scaling, geo caching, or can afford a runaway AWS bill. Constraints can be freeing.

Developers should think like platform teams, building the development engine for product, design, support, CEOs, and founders. AI (not engineers) is the development team for a lot of these people now. Our job isn't to conduct their orchestra for them. It's to build the hall so well that they don't need us to.

*(yeah ok, I know nothing about concert halls and acoustics, but you get the idea)

Qualitative controls and avoiding slop

Platform and DevOps engineering's guardrails have traditionally been deterministic: Terraform plans, policy-as-code, static checks that either pass or fail, with a human expert reviewing on top.

We extend that same discipline to AI agents, like we did for developers before them, by building deterministic guardrails for probabilistic systems. But it's hard to statically verify that an LLM did what you wanted. The code can be linted, tested, and still do the wrong thing.

That's the engineering challenge, and it's not solved yet. Deterministic-grade guardrails for agentic AI exist today, just as scaled human teams needed them before, I consider them to mandatory for AI development. They are necessary but not sufficient. We have early patterns (ADRs, linting, type checking, automatic code reviews, sampling audits, scoped permissions, human-in-the-loop checkpoints) but not a fully finished paved road yet.

Even still, a good harness goes a LONG way.

I've said it before

Agentic maturity models focus on the wrong thing

Every AI maturity model measures autonomy. YOLO mode, parallel agents, building your own orchestrator. But that’s only part of the picture and an answer to the wrong question. The better question is - are you ready?

acmConsultingAlex McFadyen

and

Full Stack Isn’t Enough Any more. You Need to Be Full Team.

Now you need to be Full Team. AI can transforms you from a single developer into a one-person ai-powered team

acmConsultingAlex McFadyen

I just hadn't realized at the time that the team and guardrails I was talking about building were for others, not ourselves.

So, stop asking "how do I get better at directing the AI" and start asking "what would make this safe and easy for someone who isn't me." That second question is the one that builds the hall.

Pick one workflow this week where a non-developer on your team wants to use AI, and instead of doing it for them, build the paved road that lets them do it themselves.

Have you seen the news lately? VSCode is becoming a bit of a liability.

1. GitHub breached via poisoned Nx Console extension (May 2026)
2. MaliciousCorgi — fake AI assistants stealing source code (January 2026)
3. Shai-Hulud 2.0 worm — AsyncAPI compromise (November 2025)
4. Prettier impersonation → Anivia loader → OctoRAT (November 2025)
5. GlassWorm self-propagating campaign (October 2025 – April 2026)
6. 550+ secrets leaked across 500+ extensions (October 2025)

... and on and on.

One of the best things about VScode, the power, flexibility, breadth and depth of its plugins, is now one of its biggest weaknesses.

Similarly, the electron base that made it cross platform and easy to run, is kinda... big and slow.

Zed is the speed demon that makes VS Code and Antigravity feel sluggish

A new and faster code editor emerges

XDAAnurag Singh

I've tried to move to Zed a few times, but the final nail was my VSCode flavor of choice (Windsurf) finally going "full AI", and becoming Devin Desktop.

Windsurf is now Devin Desktop

The next generation of Windsurf: a full IDE with the Agent Command Center built in for managing fleets of local and cloud agents from one surface.

Ramp logo

That was the final push I needed.

Shut up and setup my Zed

Okay, okay. Fork this and run install.sh:

GitHub - a-c-m/my-zed-config: Like the title says, my Zed config.

Like the title says, my Zed config. Contribute to a-c-m/my-zed-config development by creating an account on GitHub.

GitHuba-c-m

It symlinks the config files into ~/.config/zed/ and installs Zed and JetBrains Mono Font via Homebrew.

Because it symlinks (not copies), any changes you make in Zed show up as git diffs in the repo for you to keep, discard the rest as needed. Your config is version-controlled as you go.

Otherwise, here it is in a bit more detail.

1. Install

Direct download (recommended) → zed.dev/download

Homebrew (Mac)

brew install --cask zed

CLI tool (optional, but recomended) open projects from terminal:

# Command Palette → "zed: install CLI"
zed .          # open current folder
zed file.ts    # open a file

Stable vs Preview: Stable is fine for daily use. Preview gets features ~1 week earlier but ships more bugs. You can install both and switch.

2. First-run: set your keymap

The single most important setting. Add to ~/.config/zed/settings.json:

{
  "base_keymap": "VSCode"
}

This gets you ~80% of muscle memory working immediately. E.g.
⌘P (file picker),
⌘⇧P (command palette),
⌘D (multi-select),
⌘` (terminal).
The remaining gaps are covered in the shortcuts section below.

Other options: "JetBrains", "Atom", "Emacs", "SublimeText", "TextMate".

3. Extensions. Install these first

Open extensions: ⌘⇧X or Command Palette → zed: extensions

Skip the manual step: If you fork my-zed-config, Codebook, Biome, and Colored Zed Icons Theme are listed under `auto_install_extensions`. Makes Zed install them automatically on first launch.

On extension security: Zed extensions are compiled to WebAssembly with a restricted API surface. They cannot run arbitrary host processes the way VS Code extensions can. A meaningful security improvement over the VS Code extension model, which has seen a wave of supply-chain attacks in 2025–2026.

4. Themes

Switch themes live with ⌘K ⌘T, arrow keys preview in real time, Enter saves.

Built-in themes are decent (no install needed):

• One Dark / One Light are good defaults, most people stick with these
• Gruvbox Dark / Gruvbox Light / Gruvbox Dark Hard
• Ayu Dark / Ayu Light / Ayu Mirage

More themes available via ⌘⇧X and at zed-themes.com.

Icon themes: Zed supports icon themes separately from colour themes. Colored Zed Icons Theme is the most popular. File icons are nice, colours are better.
Install from ⌘⇧X and activate via Command Palette → theme selector: toggle icons.

Per-project theming: No Peacock (sadly). But you can set "theme" in .zed/settings.json at the repo root.

Markdown tip: theme choice significantly affects Markdown legibility. `Gruvbox Dark Hard` and `Ayu Dark` give the most visual distinction between headings, body text, and inline code. If Markdown looks flat, try switching theme before reaching for settings overrides.

5. Font

A good coding font makes a real difference. Some options:

After installing, add to settings:

{
  "buffer_font_family": "JetBrains Mono",
  "buffer_font_size": 14,
  "buffer_font_features": { "calt": true }
}

6. Settings. My recommended base config

User settings: ~/.config/zed/settings.json, open with ⌘, Project settings: .zed/settings.json at repo root. Auto-loaded per project, merged with user settings. Great for per-repo formatter config, language server overrides, or exclusions.

{
  "base_keymap": "VSCode",
  "diff_view_style": "unified",
  "theme": {
    "mode": "system",
    "light": "One Light",
    "dark": "One Dark"
  },
  "buffer_font_family": "JetBrains Mono",
  "buffer_font_size": 14,
  "buffer_font_features": { "calt": true },
  "ui_font_size": 14,
  "soft_wrap": "editor_width",

  "git": {
    "inline_blame": { "enabled": true, "delay_ms": 800 }
  },

  "format_on_save": "on",
  "ensure_final_newline_on_save": true,

  "terminal": {
    "font_family": "JetBrains Mono",
    "font_size": 13,
    "working_directory": "current_project_directory"
  },

  "file_scan_exclusions": [
    "**/.git",
    "**/node_modules",
    "**/.next",
    "**/dist",
    "**/.turbo"
  ],

  "show_whitespaces": "boundary",
  "scrollbar": { "show": "auto" },
  "indent_guides": { "enabled": true },

  "auto_install_extensions": {
    "colored-zed-icons-theme": true,
    "biome": true,
    "codebook": true
  },

  "languages": {
    "Markdown": {
      "language_servers": ["codebook"],
      "soft_wrap": "editor_width"
    }
  }
}

A few things worth noting in that block:

• "theme" with "mode": "system". Follows your OS dark/light setting automatically. Much better than hardcoding "One Dark".
• "git": { "inline_blame": ... }. inline_blame must live under the git key, not at the top level. Easy mistake, silent failure if you get it wrong.
• auto_install_extensions. Zed installs these on first launch. No marketplace hunting needed.

Example: Biome (linting + formatting)

If you use Biome for linting and formatting, configure it per-language rather than globally (to avoid it interfering with languages it doesn't support):

{
  "languages": {
    "TypeScript": {
      "language_servers": ["biome", "!vtsls", "!typescript-language-server"],
      "formatter": { "language_server": { "name": "biome" } },
      "code_actions_on_format": {
        "source.fixAll.biome": true,
        "source.organizeImports.biome": true
      }
    },
    "TSX": {
      "language_servers": ["biome", "!vtsls"],
      "formatter": { "language_server": { "name": "biome" } },
      "code_actions_on_format": {
        "source.fixAll.biome": true,
        "source.organizeImports.biome": true
      }
    },
    "JavaScript": {
      "language_servers": ["biome", "!vtsls"],
      "formatter": { "language_server": { "name": "biome" } },
      "code_actions_on_format": {
        "source.fixAll.biome": true,
        "source.organizeImports.biome": true
      }
    },
    "JSON": {
      "language_servers": ["biome"],
      "formatter": { "language_server": { "name": "biome" } }
    }
  }
}

Don't forget TSX. Zed treats `TypeScript` and `TSX` as separate languages. If you only configure `TypeScript`, your `.tsx` files still get formatted by vtsls. Both need the Biome override.

Requires Biome v2+. Full setup guide: biomejs.dev/reference/zed

TypeScript inlay hints (vtsls)

If you're using vtsls (the default TypeScript server), it's worth enabling inlay hints. They show parameter names and return types inline, without hovering:

{
  "lsp": {
    "vtsls": {
      "settings": {
        "typescript": {
          "inlayHints": {
            "parameterNames": { "enabled": "literals" },
            "returnTypes": { "enabled": true }
          },
          "tsserver": {
            "maxTsServerMemory": 8192
          }
        }
      }
    }
  }
}

"literals" shows parameter names only when the argument is a literal value (string, number, boolean). Low noise, high signal. maxTsServerMemory is worth bumping on large monorepos; the default is 3072MB.

7. Git integration

This is where Zed stands out from most editors.

Git panel: ⌃G shows all changed files with status indicators, staged/unstaged sections, and a commit message box.

Project diff: ⌘⇧D opens every changed file in a single split-diff multibuffer (like a github PR). You can edit directly in the diff, stage individual hunks with a click, and navigate across file boundaries without switching tabs. This is the closest equivalent to Windsurf/Cursor's diff review flow.

Split vs unified diff: Zed ships with split diff as default; I prefer unified, easy to set "diff_view_style": "unified" in settings, or toggle on the fly with Command Palette → diff: toggle split diff.

Git graph: Command Palette → git: graph for a lazy-loading, searchable commit history with a commit info panel.

Inline blame: Shows on the current line after a short delay. Toggle with ⌘K ⌘I.

Branch switching: ⌘K ⌘B or Command Palette → git: switch

Worktrees: Supported natively. Command Palette → git: create worktree. Each worktree gets its own project panel context.

Multiple repos in one window: Zed's git panel doesn't fully support workspaces with multiple git repositories yet (#52191). The workaround: use Command Palette → project: add folder to project for each sub-repo. They appear in the file tree, and you can select between them in the git panel tab, not perfect, but functional.

Docs: zed.dev/docs/git

8. AI agents. Claude Code, OpenCode, and Zed's built-in agent

Zed runs external agents via ACP (Agent Client Protocol). It works well, where agent runs as an independent process with its own thread. You can run multiple agents simultaneously on different tasks.

Open the Agent Panel: ⌘?

Panel layout: Zed's default puts the agent panel and threads on the left, project/git panel on the right. Right-click any panel icon in the status bar to move it. Or set in settings:

{
  "agent": {
    "dock": "right",
    "play_sound_when_agent_done": "always"
  }
}

"play_sound_when_agent_done": "always" is surprisingly handy. Pings you to come back when it's done.

You can also wire up both agents via settings, so they're available immediately after forking and installing:

{
  "agent_servers": {
    "opencode": { "type": "registry" },
    "claude-acp": {
      "type": "registry",
      "default_config_options": {
        "mode": "acceptEdits",
        "model": "sonnet"
      }
    }
  }
}

acceptEdits means Claude Code auto-accepts its own edits without a confirmation step on every file, swap to plan mode if you want no edits. "model": "sonnet" keeps costs reasonable; switch to "opus" with /model as needed, I find sonnet to be enough most of the time.

Claude Code (via ACP)

Command Palette → "acp: open registry" → claude-acp → Install
Agent Panel → + → claude-acp → /login (first time)

CLAUDE.md files in your repo are picked up automatically. Billing goes through your Anthropic account.

→ zed.dev/acp/agent/claude-agent

OpenCode (via ACP)

Command Palette → "acp: open registry" → OpenCode → Install
Agent Panel → + → OpenCode

OpenCode manages its own auth and model selection and supports 75+ LLM providers. Can also run as a raw TUI in the integrated terminal.

→ zed.dev/acp/agent/opencode

Reviewing agent diffs

When an agent makes changes, Zed shows them in the same editable multibuffer diff view as git. You can accept/reject individual hunks inline, or edit the diff directly before accepting.

Zed's built-in agent

Zed has a first-party agent (your choice of model: Claude, GPT, Gemini, local). Good for inline assist and quick questions.

• Inline assist: ⌘I → applies changes inline at the cursor
• Agent thread: ⌘? → new thread. Full conversation with file context

For autonomous multi-file work, Claude Code or OpenCode via ACP are the better choice.

Docs: zed.dev/docs/ai/external-agents

9. Keyboard shortcuts

VS Code shortcuts that carry over (with "base_keymap": "VSCode")

Zed-specific shortcuts to learn

Shortcuts that changed

Full cheat sheet: cheatsheets.zip/zed

Keybindings docs: zed.dev/docs/key-bindings

Official VS Code migration guide: zed.dev/docs/migrate/vs-code

10. Tips & tricks

Moving panels

Easy to miss, if you don't look for it. You can right-click any panel icon in the bottom status bar and tell it where to go. Zed writes the setting to your settings.json automatically. Alternatively set it manually:

{
  "project_panel": { "dock": "left" },
  "git_panel": { "dock": "left" },
  "agent": { "dock": "right" },
  "terminal": { "dock": "bottom" }
}

Opening files in an external app with a single keypress

Useful when you want to open a specific file type in a dedicated app.

Yes you can use markdown preview with ⌘P, but I like WYSIWYG markdown, so have setup Typora. Same idea works for opening a CSV in TablePlus, or an image in Preview etc

Step 1. Define the task in `~/.config/zed/tasks.json`

[
  {
    "label": "Open in Typora",
    "command": "open -a Typora \"$ZED_FILE\"",
    "reveal": "never",
    "allow_concurrent_runs": true
  }
]

$ZED_FILE is the absolute path to the currently focused file.

Gotcha: Put the full command in `command`, don't wrap it in `sh -c` with an `args` array. Zed already runs the command inside `zsh -i -c '...'`; the `args` field doesn't pass through as expected and silently does nothing.

Step 2. Bind a key in `~/.config/zed/keymap.json`:

[
  {
    "context": "Editor",
    "bindings": {
      "cmd-shift-t": ["task::Spawn", { "task_name": "Open in Typora" }]
    }
  }
]

Gotcha 1: Use `task_name`, not `task_label`. With `task_label` the task picker opens (pre-filtered but still requiring Enter). With `task_name` it runs immediately.

Gotcha 2: Use `"context": "Editor"`, not `"Workspace"`. This ensures a file is focused (so `$ZED_FILE` is populated) and avoids conflicting with Zed's default `cmd-shift-t` binding.

Same pattern works for any app just change the label, app name, and key binding.

Markdown heading contrast booster - theme override

If headings look too flat in your theme, you can boost specific Markdown tokens without switching theme globally:

{
  "languages": {
    "Markdown": {
      "theme_overrides": {
        "syntax": {
          "title": {
            "color": "#e5c07b",
            "font_weight": 700
          },
          "emphasis.strong": {
            "font_weight": 800
          },
          "emphasis": {
            "font_style": "italic"
          }
        }
      }
    }
  }
}

Adjust `#e5c07b` to taste. `title` is the Tree-sitter token for headings.

Autocomplete noise in Markdown files

A common frustration: Zed's autocomplete fires constantly while writing prose. Disable it for Markdown:

{
  "languages": {
    "Markdown": {
      "show_completions_on_input": false
    }
  }
}

11. Things you'll miss / workarounds

12. Useful links

If you want to do something BIG, its important you start by doing something little, and do it well.

• Marco Pierre White: "Perfection is lots of little things done well."
• Colin Powell: "If you are going to achieve excellence in big things, you develop the habit in little matters. Excellence is not an exception, it is a prevailing attitude."
• Vincent Van Gogh: "Great things are done by a series of small things brought together."

It's also beautifully captured in Gall's Law:

"A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system."

Worth keeping in mind in this new reality of AI and rampant complexity.

So why am I telling you this?

Because I reinstalled my laptop, and ran into a micro-annoyance I'd forgotten existed.

Home? End? Do you use them? They're really helpful keys, part of my muscle memory. They jump you to the start (Home) or end (End) of the current line.

This is standard behaviour on every major operating system... except macOS. Where they jump to the top or bottom of the entire document.

On Mac, you *can* use Cmd+Left/Right to do the same thing. But why use a two-key combo when there's a perfectly good single key that should already do the job?

So when I hit this micro-annoyance, instead of just fixing it for me, I got AI to fix it in a way I can share. Fixing it for everyone.

Here's a script that makes macOS do what every other OS has done since... forever: fix-home-end-keys.sh

It remaps Home and End to behave like I (and probably you) expect:

• Home moves to the start of the line
• End moves to the end of the line
• Shift+Home selects to the start of the line
• Shift+End selects to the end of the line

It works in native macOS apps (Cocoa). Electron apps like VS Code and Slack handle their own keybindings, so they're unaffected. Safe to run multiple times. Just needs a logout to take effect.

It's a little thing. But these little things add up.

In 2005, Derek Sivers published a tiny framework that became a common way to think about the value of an idea. He argued that ideas are just a multiplier of execution. An app/business/SaaS idea on its own, without execution is basically worthless.

Fortunately for my sanity, Sivers' meme eventually caught on. People now, mostly, understand that "I've got a great idea for an app" isn't a valuable business, and doesn't justify investment, be that from VCs or technical cofounders. No one will pay you for your brilliant idea unless you've got execution, or a track record of execution, to back it up.

Sivers was right. But twenty years later, AI has fundamentally changed what we should include in the "execution" bucket. Working software is no longer part of execution. It's now just the codeification of the idea.

Working Software Used to be Part Of Execution

For decades, building software was hard, slow, and expensive (and building good software still can be). You needed engineers, months of development time, and/or significant capital just to get a working product into users' hands.

The software itself was a good chunk of the execution. Having the idea for "Uber but for dog walking" was trivial. Actually building a reliable, scalable, viable, well-designed app that handled payments, scheduling, GPS tracking, and notifications? That was the hard part. That was where the value lived.

This is why SaaS became a powerful business model. The pitch was compelling: we've done the hard work of building this complex software so you don't have to. Pay us monthly and you get the benefit of a product that you can't build yourself, for a fraction of the cost. You can even customise it or build on it to bring your "AirBnB for plant watering" to life.

The economics made sense. The cost of building software was high, so centralising that cost across many customers created enormous value. The SaaS company bore the engineering burden once; thousands of customers shared the benefit.

But Now... Software is Just an Idea in code

AI-driven software development has compressed the cost and time of building software dramatically. You can argue about by how much, and the quality question is real, but the direction is undeniable. What used to require a team of five engineers and six months can now be accomplished by one or two people in weeks. And even more worrying for software developers, the people building may not even need to be developers. In some cases, a functional prototype can be built in an afternoon.

The result is that software development is migrating from Sivers' "execution" column into his "idea" column. Building the app is becoming as cheap as having the idea for it (and a Claude Code subscription). A brilliant idea with a working prototype is still, in Sivers' framework, not much more than the original idea and cost of the burned tokens.

When the Cost of Production Collapses

This isn't the first time production costs have collapsed. Every time it happens, the same thing follows: value migrates away from production and toward adjacent layers.

The printing press destroyed the scribes' monopoly on book production. It didn't make books worthless, but it did shift value to authorship, editing, curation, and distribution. The people who could identify what was worth printing and get it to the readers captured the new value. It also changed the unit economics on what could end up committed to the paper.

Internet publishing made distribution free. As Clay Shirky put it,

"Publishing is not evolving. Publishing is going away. Because the word 'publishing' means a cadre of professionals who are taking on the incredible difficulty and complexity and expense of making something public. That's not a job anymore. That's a button."

When everyone could publish, value shifted to aggregators who solved discovery, trusted voices who solved credibility, and curators who solved the paralyzing paradox of choice.

Music recording followed the same arc. When home studios made recording cheap, the industry's value migrated from developing musicians and selling recordings to selling experiences and brands or controlling distribution through platforms like Spotify.

Joel Spolsky articulated the economic principle behind this pattern back in 2002:

"Demand for a product increases when the prices of its complements decrease."

Post is great and goes into a lot of other details. He talks about smart companies deliberately who purposefully commoditise their complements. When one layer of a value chain becomes cheap and modular, the adjacent layer captures the profit. Clayton Christensen called this the "Conservation of Attractive Profits" . Value doesn't disappear when a layer commoditises, it migrates.

I think we can see that AI is commoditising software production. The value is migrating. The question is, where to?

(side note, to think about this for your industry/business, I highly recommend exploring the ideas of Wardley Mapping)

The Traditional SaaS Squeeze

Traditional SaaS businesses are caught in a tricky spot, squeezed from all sides.

On one side, the cost of building bespoke software is collapsing.

A company that once had no choice but to buy a SaaS tool, as self build was too expensive, can now have AI build something tailored to their exact workflow. Not a toy prototype, but a functional, deployable application that does precisely what they need, without the configuration overhead, without the features they'll never use, without the compromises inherent in a one-size-fits-most product. And without the costly monthly (often per seat) cost.

On the other side, the overhead of being generic hasn't gone away.

SaaS products still need to serve multiple customers' use cases with a single product. That means configuration systems, integration layers, permission models, onboarding flows, and the endless work of making one solution fit many different contexts. This is the "configuration/complexity tax", and customers bear it in the form of workarounds, inflexibility, unused features, bugs, clunky UX, slowness, and time spent adapting their workflows to someone else's assumptions.

The SaaS value proposition used to be: "We built this complex thing so you don't have to." When building complex things becomes cheap, that proposition hollows out. Why pay for and adapt a generic solution when you can have something built to your exact specifications for a lower total cost of ownership?

This doesn't mean all SaaS dies overnight, of course not. But it means the shipped software itself, the code, the features, the UI, is no longer the moat it once was. Satya Nadella has said plainly that

"the era of SaaS as we know it is coming to an end."

Foundation Capital wrote about "Taking stock of the SAASpocalypse".

The software was part of the execution. Now it's just the codification of the idea.

What Execution Actually Means Now

If software is now part of the idea, what's the execution? Sivers' formula still holds, but we need to stop thinking about software as execution. Execution now means the hard, expensive, time-consuming things that make the idea actually work for businesses and users:

Distribution. Can you reach and acquire customers efficiently? Having a great product alone has never been sufficient. When everyone can have a great product, distribution becomes the primary battleground.

Compliance and trust infrastructure. This is perhaps the most underappreciated aspect of execution. A startup can vibe-code a competitor to your SaaS product in a weekend. It's a lot harder to vibe-code your way through a SOC 2 audit. The internet is rife with vibe-coded security horror stories. Your customers aren't just paying for your code, they're paying for the assurance that comes with your compliance posture, your security questionnaires, your vendor risk assessments, your insurance. This takes years of investment. It is a genuine moat, especially in B2B.

Network effects. Does your product get better with more users? A social platform, a marketplace, a collaborative tool etc. These create compounding value that cheap code alone can't replicate. You might be able to clone Figma's core features in a weekend. You cannot clone its community of designers sharing components, plugins, and templates without much more effort.

Data moats. Do you have proprietary data that makes your product better? AI can generate software, but the ten years of niche/industry specific transaction data that makes your fraud detection model accurate, or the millions of user interactions that trained your recommendation engine; that is much harder to hallucinate your way into.

Brand and trust. When anyone can build software, trust becomes the scarce resource. Who do you trust with your data? Who do you trust to be around in two years? Who do you trust to handle the edge case that breaks at 2am? Who do you trust to not use YOUR data against you or sell it to the highest bidder? Brand is accumulated trust, and that has real value.

Switching costs and integration depth. Being embedded in a customer's workflow, as a deeply integrated partner with their other systems, holding their historical data, trained into their team's muscle memory. Though this can be a shallow moat.

None of these things can be prompted into existence. They are built slowly, expensively, and deliberately. They are the execution.

What This Means for Builders

If you're building (or thinking about building) a SaaS product, ask yourself: if a competitor could replicate your software in a week using AI, what would you have left? If the answer is "not much," you don't have a business, you have an idea in code.

And like your non-technical friends who used to come to you with "a great idea for an app," don't expect investors or early employees to be as excited by your working code as you are. Working code + working business is where it's at. The code is table stakes now.

Kevin Kelly wrote about 1,000 True Fans — the idea that you only need a thousand deeply committed customers to build a sustainable business. In a world of cheap generic software, this cuts deeper than ever. The winning strategy isn't "build a SaaS that sort-of works for everyone." It's "understand a specific audience so deeply that you build exactly what they need, and own the relationship."

The value isn't in the software. It's in solving the valuable problem, knowing what to build, who to build it for, and having the trust, compliance, distribution, and relationships to deliver it.

Ideas were cheap. Now software is too.

You probably setup lint staged because linting is slow and you want to just lint a smaller subset of files on commit. Fair enough. But what if linting wasn't slow?

lint-staged is a hack on top of slow linting systems (like ESlint). A useful hack, but a hack nonetheless. It exists because linting (and likely formatting) your whole codebase can take ages. So the fix is to only lint the files you've changed. Smart. Which means your pre-commit hook is only catching problems in the files you touched, and critically, runs fast.

But. What if your linter was fast? Sub-second for your entire repo fast? Even a monorepo? Then you don't need lint-staged at all. You just run lint. On everything. Every time.

Biome

Biome is that linter. Built in Rust, 35x faster than Prettier, with 455 rules pulled from ESLint, TypeScript ESLint and other sources. It replaces ESLint, Prettier and the awkward dance (or sometimes fight!) between them in a single tool.

Want a solid set of pre-configured rules that are perfect for AI agents? Ultracite gives you zero-config, opinionated Biome rules with automatic editor and agent configuration out of the box. I highly recommend it.

New rules, new problems

Great, a whole new set of rules, which means new errors. So you might be thinking: "We can't possibly adopt strict linting now, it will find hundreds (or thousands) of errors that we don't have time to fix."

Yeah, probably. But:

1. AI can fix them :)

and

2. I've written a Biome wrapper for exactly this problem: biome-suppressed

Biome Suppressed

biome-suppressed lets you adopt Biome + Ultracite (or any strict Biome config) and have a temporary amnesty on your currently ugly code!

It captures your existing errors as a baseline, accepts all the warts and mistakes, but then makes sure you don't add more. And when you do fix old errors, it automatically ratchets the baseline down so you don't regress.

We've been using since September '25. You even get a nice graph showing you the progress (and or regressions) as well as a hall of shame/honor roll.

Go try it.  https://github.com/a-c-m/biome-suppressed

Your codebase can thank me later.

(Oh and bugs, PRs etc to biome-suppressed are very welcome too)

Agentic AI maturity models keep popping up and they all measure the same thing: how much autonomy you've given the agent. Permissions off. YOLO mode. 10 parallel agents. Building your own orchestrator etc. The assumption is clear: more hands-off equals more mature equals better!

And for speed / adoption of AI, that might be right. But I think they're missing a critical axis entirely, readiness.

The autonomy ladder

The orchestration framework Gastown introduced one of the many maturity models being talked about: source

Stage 1: Zero or Near-Zero AI: maybe code completions, sometimes ask Chat questions
Stage 2: Coding agent in IDE, permissions turned on. A narrow coding agent in a sidebar asks your permission to run tools.
Stage 3: Agent in IDE, YOLO mode: Trust goes up. You turn off permissions, agent gets wider.
Stage 4: In IDE, wide agent: Your agent gradually grows to fill the screen. Code is just for diffs.
Stage 5: CLI, single agent. YOLO. Diffs scroll by. You may or may not look at them.
Stage 6: CLI, multi-agent, YOLO. You regularly use 3 to 5 parallel instances. You are very fast.
Stage 7: 10+ agents, hand-managed. You are starting to push the limits of hand-management.
Stage 8: Building your own orchestrator. You are on the frontier, automating your workflow.

Others are less charitable, but have a similar staged approach: Vibe Psychosis

And I quite like this Reddit thread

These models all tell you the same story: progress means giving up more control. But that's only part of the picture.

The missing axis

The agent you use and how you use it matters. But most of the repeatable value comes from the processes, pipelines and safeguards you have in place that let you move safely (well, a bit more safely) up the levels of agentic automation.

You need to be ready for agentic workflows and volume of output they can produce, as if your not, you run the risk of speed running failure, instead of success.

Think about it this way (straw man, but gets the point across). Two teams, both at "Stage 6" on the Gastown model, running multiple agents in YOLO mode:

• Team A: No test suite, no linting, no pipeline checks, no code review. Agents committing to main and pushing to production.
• Team B: Strict linting, comprehensive test coverage, TDD, CI/CD gates, architectural review, feature flagged implementations, QC/QA/Review before release to customers, clear metrics and instrumentation etc

Same "maturity level". Wildly different outcomes.

Team A is playing Russian roulette with their codebase, likely racking up debt. Team B is actually mature, delivering measurable and repeatable value.

The intern test (again)

I keep coming back to the intern analogy. But it's not my original idea: Punya Mishra put it brilliantly:

I have come to realize that working with generative AI is like having, at your beck and call, a really smart, but (occasionally) drunk, intern.

If you hired a junior developer, you wouldn't measure your software development maturity by how quickly you stopped reviewing their code. You'd measure it by how good the processes and systems are at giving them the freedom they need to do their job with support/guidance to deliver value, while minimizing business risk.

The more you take your hands off the wheel, the more maturity you need in the systems and tooling to let you do so. You have to be able to catch issues and provide feedback. That maturity needs to be built into the system, not assumed. We don't let developers edit live on prod (or we shouldn't), no matter how competent we think they are. We have systems, processes and checks to make sure we don't mess up.

And seeming competent is something AIs are very good at. Our path to better and better AI is littered with examples of these seemingly smart agents being unable to count the number of R's in Strawberry, or recommending you walk to the carwash because it's only 10 mins away, to wash your car. But, at the same time, those models have been able to pass the bar since 2023.

We need deterministic checks and balances to keep everyone, agents and humans alike, from making silly (or not so silly) mistakes. We look to our peers (again, agentic or human) to help make sure we haven't missed something obvious, or gone down a wrong path.

What agentic readiness looks like

How do you do more with AI? You do more without it, in most cases.

• You have strict linting and code standards that catch problems before they compound
• You have strict unit, integration and e2e testing standards that prove things work (and stay working)
• You have feedback loops for quality, cost, value, correctness and architecture
• You have vision of the why & who you are building for, not just the what, how and where

Most of the time, that means deterministic pipelines and quantitative measurement/gatekeepers for the first two, and qualitative review (perhaps AI-assisted) for the last two.

This isn't new. This is how you scale "traditional" software development teams. The difference is that AI has massively increased your effective team size overnight. You might still have the same number of humans, but you're producing code at the rate of a much, much larger team.

And with that increased output, you need the systems and sophistication to match. The processes that worked for a team of five won't hold up when those five are producing the output of twenty five+.

Without guardrails and controls, you won't know if the team (human or agentic) is speeding you towards success or catastrophic failure.

The Cloudflare team that rewrote NextJS support in a week didn't succeed because they turned everything to YOLO. They succeeded because they had a battle-tested test suite, clear architectural boundaries, and a senior engineer at the wheel. The agents were the engine. The humans and systems were the steering and brakes. They were ready.

Orchestration frameworks like Gastown and others that have sprung up are trying to address this by building review and feedback loops into the orchestration layer. That does help, just like it does with humans. But as we've seen, these AIs still able to make stupid mistakes, especially when checking their own work (just like us).

Using a 2nd foundation model to check the results of the primary model is a good step, but I find human in the loop still provides significant value, especially for more complex ideas/tasks, especially at the start and end of the execution.

AIs are not original, nor do they get inspired. They still need humans for the ideas and judgement calls.

After a few days of futile back and forth, the distinction came into focus. Humans are for ideas, AI is for execution.

So, before you start climbing the autonomy ladder, and scaling your execution too fast, ask yourself: are you ready? Do you have guardrails and support systems that are able to scale with you?

Because if not ready, you're not maturing, you're just getting better at making more mistakes, faster! (see https://www.acmconsulting.eu/post/tequila-vs-agentic-ai/)

Back in 1992, Mitch Ratcliffe is quoted as saying:

"A computer lets you make more mistakes faster than any invention in human history, with the possible exceptions of handguns and tequila." - source

Now, in 2026, computers have a new mistake-making super power, agentic AI is now giving tequila a run for its money. Handguns still hold the crown, but tequila? Tequila's been pushed into third place.

I've been using AI to help me code for well over a year, and (like i'm sure you already know) they are awesome at it. They get so much done, so fast, and are so confident all the time. Which means they are confidently wrong, some of the time.

I've had agents tell me "You're absolutely right" regardless of how stupid my idea was. I've had them swear all the tests pass... when they don't. I've had them blame test failures on everything except the code they just wrote.

Their tenacity for problem solving is part of what makes them so useful. It's great, right up until the problem they're working around is your code quality and security checks.

They're not malicious. They're just incredibly fast at making decisions and incredibly suggestible. Which, if you think about it, is quite similar to the combination that gets you into trouble with tequila.

The blooper reel

We've seen report after report of agents exciting potential and impressing the forward looking technologists. But with the hype has also come the cautionary tales, in some cases, from people who should know better.

Like the Meta AI security researcher who gave an agent access to her inbox:

"The agent proceeded to run amok. It started deleting all her email in a 'speed run' while ignoring her commands from her phone telling it to stop. 'I had to RUN to my Mac mini like I was defusing a bomb'" - TechCrunch

A security researcher. Someone who literally thinks about these risks for a living.

Or the software team whose AI coding tool decided a database was surplus to requirements:

"AI-assisted 'vibe coding' tool took a disastrous turn when an AI agent reportedly deleted a live company database during an active code freeze" - Fortune

And you don't even have to be running the agent yourself. They're out there, and if you get in the way of their goal, their tenacious problem solving may result in you getting caught in the crossfire:

"An AI agent of unknown ownership autonomously wrote and published a personalized hit piece about me after I rejected its code" - The Sham Blog

That's not a bug report, that's a grudge!

The intern you never onboarded

Of course, bad code and poor choices are not the sole preserve of agentic AI. Any search for Darwin Awards or "Florida man" can attest to that. But the speed and scale is new.

To quote Dr. Ian Malcolm:

"Your scientists were so preoccupied with whether they could, they didn't stop to think if they should." - Jurassic Park

Think of it this way: if an intern, on their first day, deleted your production database, whose fault is that? Theirs? Yours? It's your fault. You shouldn't be giving the intern the ability to do that.

For an agent, every day is the first day... and giving them the keys to the kingdom on day one, without safeguards in place? Doesn't sound very intelligent.

Constraints are the key

The good news is that this is something we can work on. Look at how Cloudflare rewrote NextJS support in a week using agents. Their writeup is impressive. But as many commentators on Hacker News pointed out, they could only do this because they:

inherited a battle tested extensive test suite from the thing you're rebuilding, and the thing you're rebuilding is part of the training data

And had a skilled, senior engineer guiding the process. Even then:

"This is still a very early implementation and there are undoubtedly issues with the implementation that weren't covered in next's original test suite"

The agents didn't succeed because they were autonomous. They succeeded because they were constrained. Good tests/controlls. Clear boundaries. Clear goal. Human oversight. The boring stuff thats worked for years when scaling human teams - it still applies!

Computers may have overtaken tequila, in empowering our ability to make mistakes. But unlike tequila, we can actually build systems to handle the hangover. More on that in a future post.

Every piece of information costs attention. From AI context windows to the humans who have to read and maintain it, context (or cognitive) overload is real.

Documentation can really help, it can distill helpful context, but it is a double edged sword. Poor quality or stale documentation defeats its purpose and just adds to the noise. Too much context and the cost of keeping it updated outwights the benifit. But not enough and you end up relearning the same things again and again. Its a tricky budget to balance.

This post lays out a framework for deciding what to document, where to put it, and when to delete it. 5-10 minute read. For developers and engineering leads tired of documentation that nobody trusts.

The problem

Teams can end up documenting implementation details instead of intent. Ticket details  get copied into README.md (or even worse Claude.md) files. Specs get committed alongside code. Planning notes get preserved "for posterity".

Then the code changes, but the docs don't. And now you've got documentation that actively misleads anyone who reads it, human or AI. Eating up precious cognitive/context budget for a negative impact. You would be better off with no documentation at all.

Outdated documentation damages developer trust in ALL documentation. When docs go stale, developers stop trusting them. Now you've spent context budget on docs that harm rather than help.

"When documentation is outdated, it's worse than no documentation at all because people trust it and act on that trust" — Trevor Lasn

The foundational assumption: docs should live with the code

Store documentation about the code, with the code. That kind of documentation should be committed into the repository, not in external tools.

Why?

• AI-first: The primary consumers of documentation are increasingly AI agents. Docs in the repo are already in scope where the AI operates. (For more on this shift, see AI is going to improve your documentation... but not the way you expect)
• Developer-friendly: Developers find docs where they expect them—next to the code—without separate logins or editing systems.
• Single source of truth: Code and docs evolve together in the same commits, PRs, and review cycles.

Format: Markdown files with internal linking. Human-readable AND machine-readable. That's the whole point.

Four layers of documentation

Documentation exists at four distinct layers. Each has different purposes, lifecycles, and budget implications. Two you keep, two you throw away.

Layer 1: Process & standards (repo wide, loaded every time)

• What it is: How work gets done, not what the code does
• Where it lives: Root level—CLAUDE.md, CONTRIBUTING.md, .cursor/rules, core docs/ folder etc.
• Content: Coding standards, team norms, tooling setup, CI/CD processes, agentic personas
• Budget impact: High leverage, high cost. This gets loaded on every edit, every commit, every push. Less is more.

Layer 2: Implementation documentation (code specific, loaded sometimes)

• What it is: Current truth about the code you are interested in. What it does and is meant to do
• Where it lives: In the codebase, hierarchical, next to the code it describes
• Content: Module purpose, boundaries, key interfaces, non-obvious behaviors
• Budget impact: Medium ongoing cost. Only loaded when needed, but must be maintained. Worth the spend if it prevents misunderstanding, but over-documentation is a big risk. Less is still more.

Anti-pattern: Don't document future plans or previous implementation plans (layer 3) in code. They become stale and create mistrust.

Layer 3: Planning (team wide, loaded only once)

• What it is: Future plans for execution, tickets, epics etc
• Where it lives: External tools. Notion, Jira, GitHub Issues, Google Docs
• Content: What you're going to build, ideas on how you might
• Budget impact: One-time cost. It's gone in the next task. But expensive if you keep re-reading the same things / miss critical detail

Key rule: Don't have this in code. Plans change, often by people who don't want to use git. It's ephemeral from the code's point of view, an input, not an artifact.

Modern AI agent systems distinguish between ephemeral and persistent context. Google's ADK framework describes "working context" as "ephemeral (thrown away after the call)" while "sessions" serve as the "durable log of the interaction." — Google Developers Blog

Layer 4: Notes and Thoughts (task specific, todo tracking)

• What it is: Your plan or the AI's implementation plan
• Where it lives: In your head, in the ai's todo list, in plan.md or in micro ticketing like beads
• Content: How you plan to build, steps
• Budget impact: One-time cost. But can expensive (due to re-reading) if you need to onboard new agents sessions (including compactions) or teamates to the task. Doubly so if its not well structured, clean and up to date.

Key rule: Don't commit this to the repo. Make it easy to edit and keep up-to date. Don't over think it. Try beads. It can make working with sub agents easier.

Structure like C4, not like a spec doc

Think wiki, not Word.

The C4 model gives us a mental framework for hierarchical abstraction:

• Context → High-level, stable, rarely changes
• Container → System boundaries, still fairly stable
• Component → More detail, changes more often
• Code → Implementation level, changes frequently

The rule: Documentation detail should match the layer. Implementation details belong at the implementation layer, not at Context or Container level.

If you put implementation details too high, you're risking overspending. Every code change may require cascading documentation updates at multiple levels. That's paying interest on documentation debt.

The principle: High-level docs live closer to root. Implementation docs live at leaf nodes, next to the code.

For cross-cutting concerns: Place docs at the lowest common ancestor in the folder tree—the point where all affected modules are children.

This naturally scopes what gets loaded into context. An AI working on a specific feature only needs the docs at that level and above, not sibling implementation details. You're spending budget only on what's relevant.

"The challenge isn't just crafting the perfect prompt—it's thoughtfully curating what information enters the model's limited attention budget at each step" — Anthropic Engineering

Document intent, not implementation

When you do document decisions, focus on intent and outcomes rather than implementation details.

• Why did we choose this approach for the customer onboarding flow?
• What outcome were we optimizing for when we designed this feature?
• Why does this module exist and what problem does it solve?

Capture the why and the intended outcome, not the how. The how is already in the code and comments.

Our approach (which differs from traditional guidance):

• Co-locate with code: Decision docs live next to the code they relate to. Cross-cutting decisions go at the appropriate higher level.
• Consider deleting when superseded: Old decisions that no longer apply could be deleted. Git history preserves them if anyone needs to spelunk.
• Less is more: Only document decisions that would be non-obvious to a future developer (or AI) reading the code.

On deleting superseded ADRs: Traditional guidance recommends keeping them and marking as "Superseded." I take a different view. Git history serves the archival purpose, and stale docs add cognitive load.

The tradeoff: git history requires deliberate searching. You have to know to look for it. Current docs are loaded automatically. If your team frequently references historical decisions, by all means keep superseded ADRs/docs, but perhaps in an `/archive/` folder excluded from AI context?

But my default is to treat documentation like code: we delete old code, we don't comment it out. Same principle applies to docs.

Match persistence to relevance time-frame

The principle: Select tooling and persistence based on expected relevance timeframe. Notes on how you implemented a bug fix become irrelevant quickly. Your vision document needs to persist much longer.

On task-level documentation: Most developers don't write down every small task in a formal system. They jot notes in a scratch file, on paper, or just keep it in their heads. This is natural and appropriate—these are stream-of-consciousness notes that help the developer but would be noise for anyone else.

The output that matters is the code that gets committed, not the transient thoughts that led to it. Recording every micro-decision clutters your context window and creates a painful archaeology project for future developers.

Tests vs. documentation?

BDD and TDD can be used to move some documentation burden from prose files into runnable code. Its documentation we can prove works.

With LLMs, we can now use specs to check code against specifications, but due to AI's limitations, somewhat unreliably. Even still, the line between tests and documentation is getting blurry.

What I've found: it comes down to "what" versus "why."

If the documentation is describing a what (what its expected to do), there's a good chance you should use a test. Tests run automatically on commits and CI/CD pipelines. Repeatable, predictable results. Some interesting developments in the space, including using AI to help make E2E less brittle e.g Stagehand.

The why is harder. That's where prose documentation and help explain and be useful context for the huma/AI to make future choices, if it can be leveraged effectively.

I don't have a hard and fast rule here. We're still working this one out as we go.

The AI productivity reality check

Despite widespread adoption, the productivity impact of AI tools is nuanced:

• METR's 2025 study found experienced developers take 19% longer on tasks when using AI tools, and those developers believed they were 20% faster. The self-assessment was inverted from reality. — METR Study
• 46% of developers don't trust AI-generated output accuracy (up from 31% in 2024) — Stack Overflow 2025 Survey
• The #1 frustration: "solutions that are almost right, but not quite" (66% of developers)

I think, some, but not all, of this can be aided by better context (documentation).

This is because ambiguity is the enemy. When AI or humans interprets unclear or bloated documentation, it can produces those "almost right" solutions based on out of date information, or result in overly defensive code, adding bloat and cost to future changes.

Clean, well-structured docs reduce ambiguity, gives AI less room to hallucinate and humans more confidence to create concise solutions.

You're not optimizing for AI, you're optimizing for accuracy. The goal isn't "AI-first" for its own sake; it's reducing friction for whoever (or whatever) is reading your docs.

Migrating to this model

If you're on Confluence, Notion, Google docs, or another external wiki:

1. Export to markdown: Most tools have markdown export. Use it. Clean it up, slice it up.
2. Split using C4 layers: Categorize each doc's sections as Context, Container, Component, or Code level.
3. Atomize by location: Move each doc to the appropriate place. High-level at root, implementation details next to the code (same folders).
4. Delete the transient: Planning docs, old specs, meeting notes should be in external systems, not code. Don't migrate these.
5. Prune aggressively: If a doc hasn't been updated in a year and the code has changed, delete it. Git history preserves it and no information is better than bad information.

When this doesn't apply

This framework is optimized for:

• Small to medium teams
• Greenfield or actively developed codebases
• Teams using AI coding assistants

It would probably need adaptation for:

• Regulated industries: Compliance may mandate historical documentation regardless of relevance
• External-facing docs: API docs, user guides have different audiences and lifecycles
• Large organizations: Cross-cutting decisions may need more formal governance
• Legacy systems: Teams spelunking 10-year-old code may need those archived records

Questions to ask before writing (or keeping) any doc

1. Is this worth the context budget?
   Will it be read often enough to justify its cost? Could this be inferred from code or tests instead?

2. What is this for?
   Providing context to AI? Optimize for that. Describing expected behavior? Maybe you need more tests instead.

3. Am I using docs as a surrogate for tests?
   If you're relying on docs to communicate what can/can't be done, consider: less documentation, more tests.

4. At what abstraction level am I documenting this?
   Match detail to scope. Implementation details go at the implementation layer only.

5. Who needs this and for how long?
   Vision → years → persistent collaborative docs.
   Epic → weeks → ticketing.
   Task → hours → disposable notes.

Context is a budget

Every token you write costs attention to read and energy to maintain.

Spend it wisely and deliberately.

Start with one question: look at your last PR. Did you update any documentation? Should you have?

That's your signal for where to start pruning or investing.

Every token you save is attention you can spend on what matters!

Jevons Paradox is all the rage right now, and you can weaponize it. Its suprisingly simple, identify behaviors you want to see more of (deployments, code reviews, feedback), make them easier and more joyful, and watch frequency increase.

The ROI isn't just time saved × current frequency; it's time saved × increased frequency. And thats just the first layer.

Why now?

In a previous post, I discussed how AI broke the automation payback calculation.

AI Broke the Automation Payback Calculation

AI means we can now afford to ask question “can I make this easier?” instead of just “how do I solve this problem?”

acmConsultingAlex McFadyen

The cost of building automation dropped so dramatically that traditional ROI calculations no longer applied. Creating your own tooling and improvements was now extremely cheap.

But there's a second-order effect people should keep in mind: when you make something easier, people do it more. And sometimes, not a little more. A lot more.

This is Jevons Paradox in action.

What is Jevons Paradox

Jevons Paradox observes that when you improve the efficiency of a resource, total consumption of that resource increases rather than decreases. Originally identified with coal consumption in the 1800s, it's recently resurfaced in discussions about AI and software development.

You've probably heard the argument: AI won't reduce demand for developers, it'll increase it. Why? Because AI makes coding easier and faster, which enables more software to be built, which requires more developers. Efficiency improvements increase total consumption.

The same principle can apply to your teams, process and products.

The Weaponization: Easy = Increased Frequency

You can trigger this effect deliberately.

Identify behaviors you want to see more of. Make them easier. Make them joyful. People will do them more frequently. The benefit isn't just time saved per instance, it's the compounding effect of increased instances, and oftern can even have third order effects beyond that.

When evaluating process improvements, don't just calculate:

ROI = time_saved × current_frequency

Consider:

ROI = time_saved × (current_frequency + induced_frequency)

That second term can be a big deal.

And then consider a world where that thing is done a lot more, what knock on effects might this have?

Examples: Internal Processes

Deployments

• Multi-day, painful, manual process → deploy quarterly
• 10-minute automated process with clear feedback → deploy daily

→ Daily deploys = Smaller deploys
→ Daily deploys = Faster value delivery to users

Bug Reporting

• Multi-field form requiring reproduction steps → only critical bugs reported
• One-click submission from error state → more bugs captured

→ more bugs captured = better targeting of effort

Feedback Loops

• Tickets disappear into void → people stop reporting issues
• Immediate acknowledgment + visibility into progress → continuous feedback

→ continuous feedback = customers feel you are listening/fixing faster

Examples: Product/Customer-Facing

Content Creation

• Complex upload process → minimal user-generated content
• Easy, joyful creation experience → thriving content ecosystem

→ thriving content ecosystem = positive feedback loop

User Feedback

• Hidden feedback form → product team flies blind
• Contextual, frictionless feedback → constant product intelligence

→ constant product intelligence = new opportunities, faster feedback loop

Whatever behavior you want from users/teams/organisation, engineer the experience to make it easy and rewarding.

The Neglected Internal Process Problem

Internal processes  often receive the least investment. They're not customer-facing. They don't directly generate revenue. They get built once and tolerated indefinitely.

But they can have the highest ROI potential precisely because of the frequency multiplier effect and third order impacts of that behavior change.

A deployment process that goes from quarterly to daily doesn't just save time. It fundamentally changes how your team ships software. Bug velocity increases. Feedback loops tighten. Iteration speed compounds.

When you're considering process improvements, particularly internal ones, consider its 2nd and 3rd order affects, the likely frequency increase and what that might mean. That's not a nice-to-have benefit. It's often the primary benefit.

Remember This

This isn't new information. Is obvious that people prefer doing things that are easy and feel good. But it's worth reminding yourself, you can leverage this to nudge the behaviors you want to see more of.

But it's easy to forget when evaluating process improvements. You calculate time saved. You measure efficiency gains. You miss the behavioral change.

When you make something easier, people do it more. Design for that. Weaponize it.

Make the things you want to see happen more both easy and joyful. Then watch Jevons Paradox work in your favor.

Remember me asking "are voice notes are arrogant?" because they optimize YOUR time at the expense of the recipient's?

Asymmetric Communication Speeds

And why sending voice notes might come accross as a bit arrogant.

acmConsultingAlex McFadyen

Here's the ai twist: when you're talking to your machine, especially AI, you should absolutely be using your voice. The calculation that made voice communication inefficient doesn't apply for AI and talking might be even better than typing in terms of context per minute.

TL;DR

You can speak at 110-150 words per minute but type at only 40-60 WPM. AI can now transcribe your rambling perfectly, entirely on your local device, keeping your voice private and text organized (but with a few extra —'s than you might use). Talking to your computer is fastest and best way to communicate with AI.

Why Local Transcription Matters

These tools run 100% on your local device. Unlike Siri, Alexa, Google Assistant, or cloud transcription services:

• Your voice never leaves your machine, so your audio files stay private
• Extremely fast (likely faster than remote) on modern hardware
• Really accurate
• Open source and free to use

Important: The transcription is private, but you still send the resulting TEXT (local LLM, Claude, ChatGPT, etc.), so be careful on the LLM's privacy policy. The privacy win is that your voice and audio stay on your device. No one is training speech models on your voice or storing your audio recordings.

Many of us are still typing Like It's 1999

The Real State of AI Coding Assistant Adoption in 2025: Beyond the Hype

The definitive analysis of AI coding assistant adoption rates in 2025. GitHub Copilot reaches 20M users, but 46% of developers don’t trust AI accuracy.

Infolia AIPranay

According to one survey 84% of developers now use or plan to use AI tools. I suspect that number is not evenly distributed and your team could be much higher, that's a lot of prompt writing!

Every single one of those interactions starts with typing out a prompt. Prompts are different to code, they are more like a conversation or question. So speed of input is more of a factor. Most people type at around 40-60 WPM, but you could be speaking at 110-150 WPM. With such a frequent interaction, its worth investing time in optimizing how you prompt your AI (as I showed in my last post):

AI Broke the Automation Payback Calculation

AI means we can now afford to ask question “can I make this easier?” instead of just “how do I solve this problem?”

acmConsultingAlex McFadyen

Stanford research shows speech is 3x faster than typing (161 WPM vs 53 WPM on average), so if talking can save you 1 minute per prompt, x5 (or more, per day) its worth to investing up to a day of effort to get that saving. And, that's for a 1 year payback, for a single dev, if you have a team, it could be worth investing a week or more.

We live in the future, so let's embrace it!

Then (2000s-2010s): The Dragon Era

Dragon Systems released NaturallySpeaking 1.0 in June 1997 as the first continuous dictation product. Before that, you had to pause. Between. Every. Single. Word.

The Dragon experience:

• Cost hundreds of dollars (professional versions still expensive today)
• Required 5-15 minutes of reading training text aloud
• Had to "train" wrong words by repeating them
• Privacy concern: Your voice data processed by corporate servers
• Microsoft acquired Nuance (Dragon's parent company) in March 2022 for $19.7 billion

It worked, but it was tedious. And you were always wondering: where is my voice data going? For most people, it was more hassle and cost than it was worth.

Now (2024-2025): The Whisper Revolution

OpenAI Whisper released in September 2022 changed everything:

• Open source under MIT license (free, auditable code)
• 100% local processing - your voice never leaves your device
• No training required - works immediately with your voice
• Handles rambling - designed for conversational speech (trained on podcasts/interviews)
• Cross-platform - Apple Silicon, Intel Mac, Windows, Linux
• Massive training - 680,000 hours of multilingual and multitask supervised data

The Privacy Game-Changer

Unlike Siri, Google Assistant, Alexa, or Dragon's cloud services, these tools transcribe everything on your device. Your voice audio never leaves your machine. So no worries about GDPR/CCPA/SOC or similar, as there is no external servers are processing your speech patterns, storing your audio, or training models on how you sound.

But remember, this is different from text privacy: You still need to be careful about what text you send to which LLM (just like you do when typing). But your voice, your audio files, your speech patterns? Those stay local.

Tools That Just Work

What I'm Using: Hex (Apple Silicon Mac)

Link: github.com/kitlangton/Hex

I'm using Hex because it's stupidly simple and works perfectly on Apple Silicon:

• Uses WhisperKit optimized for Apple Neural Engine
• 100% local processing - nothing leaves your Mac
• Two modes: press-and-hold hotkey or double-tap to lock recording
• First-time setup download your prefered model and off you go
• Pastes transcribed text directly into your active application
• Cost: Free, open source (MIT license)

Cross-Platform Alternative: Open-Whispr

Link: github.com/HeroTools/open-whispr

If you're on Windows, Linux, or Intel Mac:

• Works on Windows 10+, macOS 10.15+, Linux
• Privacy-first: Local Whisper models OR choose your API provider
• Global hotkey activation (default: backtick `)
• Multi-provider AI support: OpenAI, Claude, Gemini, or local models
• Cost: Free, open source

You can probably search the web for other options, but these are my two recommendations.

The Setup Pattern (Any Tool)

1. Install the app (5 minutes)
2. First run downloads Whisper model (one-time, automatic, 5-10 min)
3. Set hotkey preference
4. Grant microphone permission
5. Start talking
6. Be amazed at how easy it is, and how much it gets right
7. Have to keep reminding yourself to use it (while you get used to it)

It actually helps the AI too

The counterintuitive part: Yes, voice creates more tokens. Yes, your transcription might include "um" and "you know." But here's what I've found actually happens:

Scenario A (Typing)

1. You craft a careful, concise prompt (5 minutes, 100 words)
2. AI responds based on limited context
3. You realize you needed to explain more
4. Back and forth 3-4 times
5. Total time: 20+ minutes

Scenario B (Voice to Text)

1. You ramble for 2 minutes, giving full context (300 words transcribed)
2. AI has a more complete context in ONE shot
3. Gets it right the first time (or perhaps 2)
4. Total time: 3+ minutes

OK, OK, a bit of a straw man / best case, but the point is more context, faster. You could also spend an extra 1-2 mins editing and refining the text before sending it, if you like, but I rarely bother.

The Math

• 2.5x more input speed (speaking vs typing: 110-150 WPM vs 40-60 WPM)
• More context naturally, for the same time invested
• Result: AI gets it right in round 1 or 2 instead of 3-4
• Net savings: 85% less time, better results

An example 30 second prompt, typed:

"Make me a python function to transform Salesforce API data to Postgres schema, handle missing fields, log validation errors to Datadog"

The same prompt, spoken in 30 seconds:

"Okay so I need a Python function that takes in user data
from our Salesforce API, you know, the JSON structure where
we have that nested contact_details object that sometimes
has the legacy_id field and sometimes doesn't because of
the 2019 migration we did, and I want it to format that
into the Postgres schema we're using in the new microservice,
making sure to handle cases where fields might be missing
or null because we still have those old records from before
we enforced validation, and also it should probably log any
validation errors to our internal Datadog instance without
throwing exceptions because we want the batch process to
continue even if one record fails, and we need to track
the failure rate for the SLA dashboard"

Result: Same time investment, but AI gets 10x more context - the nested structure issue, the migration history, why fields might be missing, the error handling strategy. Gets it right first time instead of needing 3 follow-up clarifications.

More Context, Less Confusion?

When you type, you self-edit. You leave out details, because it would take too long to include them. You assume (or hope) the AI knows what you mean. You craft minimal, precise prompts.

When you speak, you naturally include more. The "obvious" stuff. Examples. You say "wait, let me rephrase that" and both versions get transcribed. You explain the actual constraints without overthinking word choice. You explain more of your chain of thought.

But, be careful, verbosity might not be a catch all solution:

Don’t Force Your LLM to Write Terse Code: An Argument from Information Theory for q/kdb+ Developers

Update [October 20, 2025]: I’ve discovered a methodological error in the perplexity measurements below. I used an Instruct-tuned model…

Mediumgabiteodoru

the terse version (i += 1) has lower perplexity than the verbose version.
....
Average surprisal-per-token, when exponentiated (a monotonic transform), is also known as perplexity, a common metric used for LLMs and their inputs and outputs.

So, what feels like inefficient rambling to you could be high-quality context for the AI. The false starts, the corrections, the "what I actually mean is..." might actually be gold for understanding your true intent. Or it might muddy the water, you will need to test and see what works best for you.

But, personally, I've had instances where I've gone from frustrating 10-interaction debugging sessions to few-shot solutions just by speaking the full context instead of typing minimal prompts.

It also makes you feel like you are living the the future... which we are.

Why Not Try This Today?

The 5-Minute Experiment

Pick your tool:

• Mac (Apple Silicon): Hex
• Any platform: Open-Whispr or WhisperWriter
• Privacy-focused: GoWhisper

Install (5 minutes, let model download)

Next time you're about to ask your AI assistant something:

1. Hit your hotkey
2. Explain the problem like you're talking to a colleague, naturally, without overthinking word choice
3. Review the transcription (edit if needed, especially for sensitive data)
4. Paste into your LLM and watch what happens

If you are worried about context poisoning, you could always use one agent to clean up your rambling then pass to another (copy paste or mcp/multi-agent) for the tighter execution.

As Bob said, its good to talk!
(only UK people of a certain age will get this reference).

TL;DR: AI has also sped up tooling development, from weeks to hours, breaking the automation economics calculations that held for decades.

This quick minute read is for teams still manually fighting workflow friction instead of investing in solutions to smooth the path.

In this post, I'll explain why and how things have changed, and give you 3 real world examples.

• biome-suppressed - Moving to Biome without the multi-week refactor (30 minutes)
• Git stats - Measuring AI adoption through git analysis (5 minutes)
• Custom DORA reporting - Team velocity tracking with custom HTML reporting (few hours)

You can also expect some fantastic XKCD sketches I've borrowed to support to make my point, and, as always, I'll challenge you to try out some tool making for yourself.

I wanted something which didn't exist yet

We wanted to upgrade from ESLint to Biome. Speed upgrade plus stricter rules from Ultracite sounded perfect. Except we knew from experience this was a multi-week effort, maybe months. Fixing straggling bugs, making compromises, turning off rules we couldn't immediately satisfy.

ESLint's new bulk suppression feature would've been ideal for this exact situation—accept current errors, enforce rules on new code only. But Biome didn't have it.

So we built it... In 30 minutes... more on this later. First:

The two XKCDs that explain everything

The General Problem

XKCD 974 perfectly captures the old trap: "I could spend 5 minutes doing this manually, or spend all day automating it." Then you spend all day, plus debug time, plus maintenance.

This used to be genuine wisdom. Automation was expensive. Building custom tools required deep expertise, significant time investment, and ongoing maintenance burden. The ROI calculation rarely made sense for one-off or team-specific problems.

That calculation has now changed.

The Payback Grid

XKCD 1205 shows the classic automation payback grid. It answers: "How much time can you spend automating this task before you're losing time over a 5-year period?"

The grid is still mathematically correct. The difference is that the time investment to build these tools dropped from weeks to hours, sometimes minutes. What required a 5-year payback period to justify now pays back in months.

See the appendix for 1-year and 2-year versions of this grid. Built with AI, naturally.

What this actually looks like

biome-suppressed: 30 minutes to published tool

GitHub - a-c-m/biome-suppressed: A fast, lightweight drop-in wrapper for `biome check` that maintains an error baseline and only fails on new errors. Automatically improves the baseline when fewer errors are found.

A fast, lightweight drop-in wrapper for `biome check` that maintains an error baseline and only fails on new errors. Automatically improves the baseline when fewer errors are found. - a-c-m/biome-s...

GitHuba-c-m

We really wanted Biome's speed. Orders of magnitude faster than ESLint on our codebase. And we wanted to adopt Ultracite's AI-powered linting rules—much more aggressive, catching patterns traditional linters miss.

But we'd been down this road before. Upgrading linters on a large codebase means:

• Weeks fixing violations in legacy code
• Compromises: disabling rules that are "too strict"
• Bugs introduced while refactoring to satisfy new rules
• Team friction over what to fix now vs. later

ESLint's new suppression feature solved this elegantly. Run the linter, accept current errors, ignore them in future runs. New code follows new rules, legacy code gets fixed gradually. Perfect.

Biome didn't have this feature.

Traditional approach: wait for the feature, or stick with slow tooling, or commit to the multi-week refactor.

AI approach: 30 minutes with Claude, working prototype.

We built biome-suppressed, a wrapper that sits above Biome and provides the same suppression workflow. Tested it locally for a few weeks, fixed issues, refined the implementation. Now it's published, anyone can use it.

https://www.npmjs.com/package/biome-suppressed

The result: we adopted Biome's speed and Ultracite's aggressive rulesets without the massive refactor. New code meets high standards, legacy code doesn't block progress.

Git stats: 5 minutes to weekly reference

Git stats per dev (LOC) with delta and comparison

Git stats per dev (LOC) with delta and comparison. GitHub Gist: instantly share code, notes, and snippets.

Gist262588213843476

We wanted to measure AI adoption within our team. One metric: commits and lines of code changed. Yes, I know, terrible metric for quality. But for measuring AI impact on output? Actually quite useful.

Traditional approach: manually run git log, parse output, track in spreadsheet, compare week-over-week.

AI approach: asked an agent to write a script. Five minutes later, working tool.

The script analyzes git history, counts commits and lines changed by developer, compares to previous weeks. We use it every week. Short Ten-minute investment, ongoing value, but also deeper conversations about adoption patterns we wouldn't have had otherwise.

Whats been an added bonus, was to feed the results of this script into an AI for its own insights, as part of our weekly retrospective!

Custom DoraMetrics: few hours to ongoing optimization

We wanted to evaluate team velocity using DORA for some quarterly reviews. Tools like LinearB exist and are great, but we needed specific customizations for our reporting needs.

Traditional approach: pay for tool, export data, customize in spreadsheets, repeat quarterly.

AI approach: few hours with Claude building a custom analyzer.

It analyzes git history, examines open and closed branches, generates reports with filtering, sorting, and graphing. The resulting data gave us talking points to both start optimization and monitor progress over time.

This one I haven't released publicly yet. Depending on interest, might release as a product or make available on request.

The Jevons Paradox of tooling

Jevons Paradox is an economic theory that when technology improves the efficiency of resource use, overall consumption often increases rather than decreases. Greater efficiency lowers costs, leading to higher demand.

The same thing happens with custom tooling.

When building tools becomes cheaper, you build more tools. But it's not just quantity—the tools unlock workflows you didn't anticipate.

The git stats tool wasn't just about measurement. It changed the conversations we had about AI adoption. Having weekly data visible shifted discussions from "are we using AI?" to "why did velocity spike here?" and "what patterns correlate with impact?"

Data visualization that was "too expensive" becomes standard. Custom dashboards appear for team-specific needs. The tool's existence creates new opportunities.

The team structure question

Not everyone needs to shift their mindset to tool-making. But someone should be asking the question.

Here's what I'm seeing: managers are doing software development again. AI coding agents lowered the barrier enough that engineering managers—who often haven't written production code in years—are building tools for their teams.

They're actually the perfect candidates for this. They have the broader scope. They see workflow friction across multiple developers. They understand team-wide pain points. When they invest 30 minutes building a tool, it often applies to 5-10 people, not just themselves.

The multiplication effect here is substantial. A manager who understands both the team's needs and has the technical ability to quickly prototype solutions can have outsized impact. They're not necessarily writing production features, but they're building the tooling that makes their team more effective.

Someone asks: "Can I make solving this problem easier now and in the future?" instead of just "How do I solve this problem now?"

The multiplication effect compounds. A 30-minute investment in biome-suppressed unblocked weeks of potential linting migration work across multiple projects. A 5-minute git stats script influenced quarterly planning discussions. The benefits cascade.

Try this next

Pick one workflow annoyance this week:

• Something you do repeatedly
• Something that frustrates you
• Something manual that feels "not worth automating"

Spend 30 minutes with an AI agent building a tool to solve it.

Then track two things:

1. Did you use it again?
2. Did it unlock something unexpected?

My bet: both answers are yes. And even if its not, you've only invested an hour or two, not weeks in the learning.

---

Appendix: XKCD 1205 for shorter timeframes

I've always wanted to know what these payback periods looked like for 1-year and 2-year windows, but never had the time to calculate them. Ironically, AI helped me create these very quickly, and I'll now have this as a reference for all the future times I bring up this particular XKCD.

2-Year Payback Period

1-Year Payback Period

Key insight: A daily task that saves 5 minutes justifies spending 1 full day building automation (1-year payback). With AI, you can build that automation in hours, not days.

Your AI coding assistant thinks your ideas are brilliant. Every. Single. One. And so now you don't talk to anyone else!

TL;DR: AI pair programming is fast but dangerously agreeable. Pair Planning adds a human touch point before implementation, helping identify and control scope creep and eases the review process while maintaining developer autonomy and promoting team bonding - Sound good, eh? 5-minute read for teams struggling with AI-accelerated code sprawl/loneliness.

All your ideas are great, let's do them all... right now!

You've got an incredibly responsive, infinitely patient coding partner who never pushes back. Sounds amazing, right?

The AI will happily help you do all the things, but in doing so may lead you down dead ends, enthusiastically agree with half-baked architectures, and almost never says "wait, have you considered the nightmare you're about to create for your future self to maintain?"

The multiplication effect kicks in fast:

• One developer + AI enthusiasm = 3x code velocity
• 3x velocity × zero critical pushback = exponential scope creep
• Exponential scope creep = review bottlenecks that kill your sprint and future velocity

Reality check: We all, deep down, know. Faster code doesn't mean better code. And it definitely doesn't mean shippable features for customers. But when it's just you and the AI it can be tempting to do all the features, as it's so easy now!

You may have seen it: PRs getting bigger, time waiting for review increasing, depth of reviews reducing (...LGTM). That nagging feeling of no one really understanding the codebase anymore? Yeah? Us too.

The loneliness problem nobody talks about

Developers are spending entire days in conversation with AI agents, which is great. No need to break the flow state of a fellow dev to remember how to use a specific function. That quick Slack to bounce an idea off Sarah? Replaced by a LLM.

That "got a sec?" tap on Mark's shoulder? Now it's Claude. That rubber duck debugging session? Your GPT never gets tired of nodding along.

You've optimized away human connection. The code gets created faster, but your team might be more isolated than ever. Does this ring true? It also can result in pockets of knowledge forming, increasing the "bus factor" of developers, as more and more stands on a single pair of shoulders.

Pair Planning: Check and commit with a human

Dead simple. Two checkpoints (pair points) system for implementation. Zero ceremony. 100% more accountability.

Prework: AI Planning Session

Developer + AI map out the implementation before writing code. Just as they would (should) when using AI as normal. Get thoughts concrete. Structure the approach. Think through edges. Check reference implementations and best practices, etc.

This is where AI shines, helping articulate the plan without judgment, rapid knowledge assimilation, research agents etc—it's great. It gives you a chance to get the plan in a concise (token efficient!) document format.

Pair Point 1: The review of the plan

Before implementation starts, we assign the ticket to a second developer. The Pair Planner's job is to:

• Review the plan (ideally without AI, yes really read it)
• Push the edges
• Find the holes
• Challenge assumptions
• Add context the first developer doesn't have
• Put their name to the plan!

Pairs can be anyone. But we've seen that mismatched pairs actually can help: pair junior with senior, backend with frontend, new hire with the person who wrote the original system. The ability to bring a different perspectives before the code exists, can help avoid pitfalls later. It can really help spot things that two similar developers might miss or assume.

Often just knowing someone else (and not an agreeable AI) is going to read your plan is enough to improve its quality. Call it rubber duck planning?

Ok. Plan reviewed. Do the code

First developer now goes off and executes as they would before (probably with the AI, but you do you). Get it all ready, test passing, PR made and submitted etc.

Pair Point 2: The Informed Code Review

Original pair planner reviews the implementation. They already know:

• What the plan was
• What scope should be
• Where complexity is justified vs. where it's creep

They're the best possible reviewer because they have context without ownership bias. They also already committed to this step, by putting their name on the ticket. You now have reviewer accountability.

Before Pair Planning

// The current flow
ticket assigned → developer codes → PR sits for 3 days (waiting for someone to pick it up) →
reviewer has zero context → asks basic questions →
developer defensive → rounds of back-and-forth →
finally merges with technical debt nobody's happy about

After Pair Planning

// Pair Planning flow
ticket assigned → AI planning session →
human pair review (15 min) → approved plan →
developer codes → pair planner reviews quickly (context already loaded, visible commitment) →
ships same day with confidence

See the difference? The expensive back-and-forth happens before code exists and the review is invested early.

The paradox that changes everything

You'd think adding more checkpoints would slow teams down.

But, slow is smooth, smooth is fast.

• Planning review: 15 minutes
• Time saved on scope creep: 2-4 hours per ticket
• Time saved on context-free reviews: 1-3 days per PR
• Net gain: 10-20 hours per week team-wide

And the kicker? Developers initially hate it ("more meetings!"), then become the biggest advocates.

Why? Because they get to take on more aggressive tickets with a safety net. Juniors get upskilled faster. New hires onboard without drowning. And everyone ships with confidence instead of anxiety.

Reality check: This only works if your pair planners actually engage. Rubber-stamp reviews are worse than no reviews. Fix your culture first.

The secondary benefits nobody expects

Review queue pressure drops. When both developers feel ownership, the pair planner prioritizes reviews because it's "their" ticket too.

Scope discipline emerges naturally. The pair planner can say "this wasn't in the plan" without being adversarial—they helped approve the plan.

Built-in daily checkpoints. Pair planners checking on "their" tickets creates organic accountability without micromanagement. Can be part of the standup naturally.

We've started tracking "pair planning chats" per day, like we track tickets closed per day.

Resistance to over-engineering. Two brains agreeing on complexity is a higher bar than one brain convincing themselves it's necessary.

Why not try it

Pick one ticket tomorrow. Before the developer writes a line of code:

1. Have them document the plan with their AI
2. Assign it to a second developer for 15-minute review
3. Let the original developer implement
4. Have the pair planner lead the code review

Track how long the ticket takes from assignment to merge compared to your usual flow.

I'll bet you a coffee it's faster end-to-end, with fewer surprises.

Still doing solo AI programming without human checkpoints? You're shipping faster code with slower outcomes.

But what about vibe coding?

This technique works really well for vibe coding too. It gives you that extra important check-in point with a human before you start.

The implementation method? That's up to you. Whether you're approving line-by-line, running multiple agents that compete to see who builds it best, or using any other AI-assisted approach—it doesn't really matter.

Pair Planning provides the bookends around that process to ensure quality and adherence to the original goals. The human checkpoint at the start keeps you aligned. The human review at the end validates you shipped what you intended.

The middle? That's where you get to experiment with whatever AI workflow feels right.

Happy pair planning.

When the JCB excavator arrived on construction sites in 1945, workers faced a choice: adapt or keep shoveling. Those who learned to operate the machines moved 50x more dirt. The others? ...

Welcome to software development's latest excavator moment.

Selling the shovel

Its not selling like it used to. By now, I expect you've seen the worrying stats around graduate unemployment (USA stats, but I expect its like this everywhere)?

"learn to code and you will get a great high paying job" idea just got its obituary written in graduate unemployment statistics.

And the people who do have jobs are rapidly, not having them. With new announcements of layoffs weekly (another 9k went at Microsoft this week). Its rough out there.

But not for everyone, Meta is throwing around millions to hire top tier talent. While not everyone can be a OpenAI level datascientist, my strong suspision is that engineers who are able to embrace the new way of working will become even more highly leveraged value for businesses, but sadly, we will need less of them.

I hope you like pizza

Amazon's famous two-pizza team rule assumed human limitations around communication and coordination. Meaning the ideal team size was one you could feed on 2 pizzas. 6-8 people, manageable communication overhead, predictable velocity.

But now, can one person can have two pizzas all for themself?

I could argue that one developer with some good AI (e.g.  Claude Opus), can come close to matching an entire team from 2010/20-era's output. Not because you code faster, because you're not just coding, you're orchestrating an entire team, but with less communication overhead.

2020 Two-Pizza Team:          2025 You + AI:
- 6 people (eng, ux, pm)      - 1 Full Team Developer
- 240 hours/week              - 300+ AI hours/week
- 2-week cyles                - 2-day cycles
- Coordination: 30%           - Coordination: What meetings?

Perhaps a little hyperbloic, you may argue about the numbers, its not x5-6, but perhaps twice as fast, or even just 50% faster. Your millage may vary, but I've watched solo developers ship in days what used to take weeks, if not quarters. But velocity isn't the only change.

Communication and coordination of humans is hard, due to our limited bandwidth for communciation. As they say:

“If you want to go fast, go alone, if you want to go far, go together”

Neil D. Lawrence talks about the limitations of human bandwidth, when compared to AI in Atomic Human (a good read). AI's can consume and communicate information waaaaay faster than you and your team mates (its light speed vs walking speed).

So this is why documentation is more important than ever.

AI is going to improve your documentation... but not the way you expect

“AI can read the code” feels like the new “code documents itself”. It’s wrong. Very very wrong.

acmConsultingAlex McFadyen

If you can document it, make a process for it (ideally in markdown format, or an MCP), AIs can consume it in (micro)seconds. That coordination overhead just dropped massively. And they can type a hell of a lot faster than you too.

Output ≠ Outcome (But You Own Both)

"One developer can now generate 10K lines of code daily!"

So what? A junior developer can copy-paste Stack Overflow all day too. Volume was never the biggest constraint.

The real shift: You now (more than ever before) you have the option (perhaps necesisty) to own much more of the product surface. AI can now help handle the HOW, you (as the developer) get to own so much more of the WHAT and WHY.

Hand offs to/from backend/frontend/product/ux are slow and coordination is hard. Every time you are waiting to be told what to build or why you are building it, you're falling behind.

Welcome to Full Team Engineering.

Your New Job Description

Marty Cagan's four product risks just became your daily checklist:

Value Risk: Will customers pay for it/value it?

Old you: "That's product's job"
New you: AI spins up prototypes, you validate with real users/experts.

Usability Risk: Can they use it?

Old you: "Design will figure it out"
New you: Generate UX variants, test & iterate same day.

Business Viability: Does it make money?

Old you: "Above my pay grade"
New you: AI can help project financials, map business cases, structure presentations.

Feasibility Risk: Can we build it?

Old you: 3-week investigation
New you: AI proves it works in 3 hours

You're not full-stack anymore. You're full-team.

The Coordination Paradox

So what happens when every developer becomes a team?

Traditional org structures assume specialization and handoffs. Building for flow (e.g. team topologies anoter great book) helps here, but when one developer is able to take on the entire flow of a team solo, what and how we communicate may need to change.

Consider:

10 traditional developers = 400 hours/week, high coordination cost
10 full-team engineers = 4,000 effective hours/week, ??? coordination

What will coordination look like going forward?

You still need your coworkers!

Your coworkers aren't obsolete, the good ones just got even more valuable to you and the business. The fellow developers are now your architecture advisor and sounding boards. The PM becomes your strategy sparring partner. Design becomes your taste council.

But the dynamic shifts, they are not doing things FOR you any more, or perhaps even WITH you, they are shifting into consultants and advisors.

You still need experts and second opionions. You just don't need them as implementers any more.

But, this only works if you stop thinking like a code monkey and start thinking like a founder/team lead.

Before you might have worked on a ticket in a story/epic with 2-4 other developers, now YOU can own the story/epic alone, or perhaps the entire app.

I would argue, that every day you spend as a traditional developer, your market value drops. The developers who thrive won't be the best coders (but being a the best coders will likely help), they'll be the ones who have also learned to think like leaders of AI implementation teams.

With the right mindset, there is still a lot of opportunity and fun to be had.

The excavator is here.  Time to get on board.

Your move: Pick one feature you're building. Pause on fring up the IDE. Instead, write a product brief. Have the AI focus on implementation (with you as guide and mentor) while you spend more time with your users and fellow experts.

Welcome to Full Team Engineering.

Also, for those who want more. A great follow up read / compaion post: https://www.elenaverna.com/p/the-rise-of-the-ai-native-employee I agree 100% with thier hot take:

→ Company sizes will shrink.
→ Org charts will flatten.
→ The middle management layers without vertical expertise will vaporize.
→ The AI-native employee will become the new 10x team.

TL;DR: Stop treating AI adoption like a corporate email blast. Test it yourself first, let small teams experiment with metrics, then scale what works. Your FOMO-driven mandate is why half (or more) of your team is still not leveraging AI effectively.

The brutal reality of AI tool mandates

Here's what I'm hearing from developers I speak to:

CEO reads about the latest AI coding assistant over breakfast. By lunch, there's a company-wide Slack message: "Everyone must start using [insert tool] immediately!"

Six weeks later? Mixed results at best. Complete adoption failure at worst.

The uncomfortable truth: Telling developers to use an AI tool because it's trendy works about as well as telling them to switch to a new IDE because Gartner said so. (Spoiler: it doesn't.)

FOMO for using AI specifically for software development is extremely prevalent. Everyone's talking about it. Lots of companies are blaming their reduction in force (aka firing dev teams) on advances being made from AI. (I think it actually has more to do with R&D tax credits rule changes, but that's a different topic.)

The multiplication principle of tool adoption

Every tool has its sweet spot. Try to make everything look like a nail because you have a hammer, and you'll end up with broken fingers and bent nails.

But here's the kicker. When you find the right tool-developer-task combination, the results are staggering. I've seen developers go from committing hundreds of lines per week to tens of thousands. Not a typo. Not an exaggeration. Actual 10-100x multipliers in output.

Output != Outcome remember, but still, it shows SOMETHING is happening.

The trusted advisor reality check

Some people recomend that software development managers should know how to (and reguarlly) code. Agree or disagree, the same principle applies here; kind of.

What I've found works: Someone senior should have tested it. Doesn't have to be the CEO or CTO, but someone trusted should have actually used the tool on real code for real problems. Not watched a YouTube demo. Not read the marketing copy. Actually used it, for real work. For at least a week.

The framework I've found to work

Forget the big bang adoption. Here's what I've seen work in practice:

Step 1: Small team experimentation

Give a small team or individual:

• A budget
• Freedom to choose their tool (perhaps with strong guidance/veto by legal)
• A clear evaluation framework (outcome, not just output)
• 2-4 weeks to experiment

Let THEM come back to you with a proposal and a framework for evaluating success. Tweak it if need be, then run with it.

Step 2: Measure what matters

Usage metrics that have worked for me, when looking for adoption of AI tools:

• Token/credit consumption (for usage-based tools)—if they're not using credits, they're not using the tool
• Lines of code committed (yes, it's a terrible metric, but the delta can be telling)
• Actual outcomes—faster feature delivery, fewer bugs, happier customers

Satya Nadella said about AI needing to deliver real economic impact:

When we say: 'Oh, this is like the industrial revolution,' let's have that industrial revolution type of growth. That means to me, 10 percent, seven percent for the developed world. Inflation adjusted, growing at five percent, that's the real marker.

Outcomes are what actually matter, but they tend to be lagging. Which is why we also look at output and adoption.

Step 3: The champion model

Found someone who's crushing it with AI tools? Make them visible. Show other teams:

• What they're doing differently
• Their actual workflow (not the idealised version)
• Their real metrics and improvements

Then slowly expand to 1-2 more teams. Rinse. Repeat.

The pairing hack to accelerate adoption

Here's a simple but very effective technique I've used: its a combination of FOMO and pairing.

Pair your low-commit developers with your high-commit AI power users. Not as a performance review, but as a learning opportunity.

BONUS: Simple bash script for LOC delta by dev on a github repro: https://gist.github.com/a-c-m/e65a4ab3ced328a7b136538147c4fec0

The magic happens when the person with fewer commits sees the methods and tools in action. Real workflows. Real problems. Real solutions. Chances are the person doing very high numbers of commits (as long as you've filtered the code to make sure you're not getting junk results) has found effective ways to leverage AI tools.

Watch out for AI slop.

But remember, More code != Better. Track your outcome, not just the output.

Quality got cheaper (if you do it right) as a result of these tools. So while while more code might be a good indication of to high adoption, keep in mind that may not be a good thing.

A great post about on the blog of the brilliant Zed Editor, where they

make the case for quality software in an era where constraints on code production have been dramatically lifted.

The Case for Software Craftsmanship in the Era of Vibes - Zed Blog

From the Zed Blog: Working toward genuine, quality software in an era where code production is not the constraint anymore.

Nathan Sobo

Why documentation matters more than ever

Counter-intuitive insight: AI tools make documentation MORE important, not less. Every piece of context you write multiplies across every AI interaction. Both for the human and for the AI. I've got a post about that here, if you are interested:

AI is going to improve your documentation... but not the way you expect

“AI can read the code” feels like the new “code documents itself”. It’s wrong. Very very wrong.

acmConsultingAlex McFadyen

Your move

Stop the FOMO-driven mandates. Start with:

1. Today: Work with a trusted technical advisor to test an AI tool and use it for a real task.
2. This week: Identify (or have them self identity) 2-3 developers interested in experimentation, give them that tool and a framework to evaluate it.
3. This month: Run a controlled pilot with clear metrics
4. Next month: Double down on what is working, or pivot (GOTO:1)  and try again.

The best time to adopt AI tools intelligently was six months ago. The second best time is today. But absolutely its before your next all-hands where you were planning to mandate the tool you read about this morning.

Your developers will thank you.

TL;DR: Forget AI replacing documentation. I think it's making documentation more critical than ever. Every AI interaction is like onboarding a new developer who knows nothing about your codebase. The better your docs, the better your AI performs. We're entering an era where documentation quality directly impacts development velocity, and your senior developers' time might be better spent writing context for AI, not code.

The brutal reality of AI-assisted development

No, documentation has not become obsolete because "AI can just read the code." In fact, the opposite is true. Documentation has become the most high-leverage activity in your development workflow, and here's why: every time you prompt an AI agent, you're essentially onboarding a new junior developer who has zero context about your codebase, your architectural decisions, or your team's conventions.

Think about it. You pay for every token the AI processes. You wait for every context window to be filled. And most critically, the AI starts from scratch every single time. That brilliant refactoring it helped you with yesterday? Gone. The deep understanding of your module boundaries? Vanished. The nuanced grasp of why you chose that particular design pattern? Non-existent.

It's also better for the environment. AI inference is not cheap, if you can reduce the overhead of every request you make, its not only good for your token budget, its good for the planet! (I'm not kidding).

This is where the paradigm shift happens. Good documentation is no longer just helpful, it's the primary interface between your team's knowledge and your AI tools.

Your documentation is now code—treat it that way

Modern AI-assisted development relies on specific documentation patterns that directly impact AI performance. The emergence of files like .cursorrules and claude.md isn't just another config file trend—these are the instruction manuals that transform a generic AI into your team's specialized assistant.

Here's what actually works:

Context files are your new superpower. A well-crafted claude.md file in your project root should contain:

• Your project's architecture decisions and the why behind them
• Code style preferences that go beyond what a linter can catch
• Common patterns and anti-patterns specific to your codebase
• Module boundaries and interaction rules
• Performance considerations and optimization strategies
• It is not your README.md focus on what the AI needs, and keep what the humans need in the README.md, minimize overlap.

Modular documentation beats monolithic files. Instead of one massive documentation file, you could structure your AI context like your code:

CLAUDE.md               # Project wide context

.claude/
└── commands/
    ├── pr.md           # How to create a PR
    ├── issue.md        # Pushing a new issue
    └── review.md       # How you check/review code

src/
├── api/
│   └── claude.md       # API-specific context
└── database/
    └── claude.md       # Database context

Every "why" you document saves hundreds of future tokens or failed prompts. The AI can read your code and understand what it does. It cannot understand why you chose a particular approach, who the stakeholders are, or when certain patterns should be applied. This context is what separates useful AI suggestions from generic boilerplate.

How is also worth documenting, but not how the code works, HOW to get work done. That is the commands folder, descriptions on how your team/project does things and how the AI can use to use the tools your team depends on (more on this in the next section).

But also remember, document where your approach deviates from best practice/common wisdom, as tokens cost money/time/energy. So things which "go without saying" do not need to be said.

MCP changes everything about tool integration

Model Context Protocol (MCP) is huge. I think it should fundamentally change how you think about AI agents interacting with your development environment.

Before MCP, connecting an AI to your tools meant:

• Custom integrations for each AI provider
• Brittle API wrappers or custom scripts
• Limited access to real development workflows
• Or lots of copy paste from one tool into the AI's chat

With MCP, your AI can now:

• Create tickets directly in your issue tracker
• Get the latest documentation and best practice (Context7 rocks)
• Run your CI/CD pipelines locally and interpret results (or get the results from your remote system)
• Query your production metrics while debugging
• Take screenshots of the local (in progress) UI to compare with a design or expected behavior

The protocol defines three core primitives that matter for developers:

• Tools: Functions your AI can execute (like "create_github_issue" or "run_test_suite")
• Resources: Data streams it can access (like "current_sprint_tickets" or "error_logs")
• Prompts/Commands: Reusable templates for common or team specific operations

This means your documentation isn't just telling the AI about your system; it's giving it the ability to actually interact with and modify your system. The implications are profound: your documentation quality now directly impacts what your AI can do, not just what it knows.

The multiplication effect: documentation ROI in the AI era

Here's the brutal maths. Let's say you have a team of 10 developers. Pre-AI, you might onboard 1-3 new developers per year (or more if you are growing fast). With AI, you're effectively onboarding a new "developer" every single time someone opens their AI coding assistant.

If each developer uses AI assistance 20 times per day, that's 200 "onboardings" daily. 1,000 per week. 50,000 per year.

Now multiply that by the cost difference between a well-documented onboarding (AI immediately understands your patterns and conventions) versus a poor one (AI suggests generic solutions that don't fit your architecture). The leverage is staggering.

Bad documentation used to slow down new hires. Now it slows down every single AI-assisted action across your entire team.

But here's the thing most teams miss: writing documentation for AI is fundamentally different from writing for humans. Humans can infer context, ask clarifying questions, and learn incrementally. AI needs everything spelled out explicitly, every single time.

What actually works: practical documentation strategies for AI

After watching teams struggle and succeed with AI-assisted development, clear patterns emerge:

1. Document the "why," not the "what"
Your AI can read UserService.validateEmail() and understand it validates emails. What it can't understand is why you're using a custom validator instead of a library, why email validation happens at this layer instead of the frontend, or why you allow plus-addressing but not subdomain addressing.

2. Make your context explicit and specific
As well as the slightly redundant "follow best practices," write how your "house rules" differ.

- All API endpoints must return within 200ms
- Database queries must use the read replica for GET requests
- Never store PII in logs, even at debug level
- Use dependency injection for all services except logging

3. (optional) Provide examples of good and bad patterns
If you see it making the same mistakes a lot, remind it what good looks like.

# Good: Explicit error handling with context
try {
  const user = await userService.find(id);
  if (!user) throw new NotFoundError(`User ${id} not found`);
} catch (error) {
  logger.error('User lookup failed', { userId: id, error });
  throw error;
}

# Bad: Swallowing errors
const user = await userService.find(id).catch(() => null);

4. Version your AI context like code
Your claude.md and .cursorrules files should be in version control, reviewed in PRs, and updated when your architecture changes. It needs to be reviewed by your very best team members, as a bad change can be repeated 100's of times a day.

5. Have the AI help you keep things fresh
Stale AI context can be worse than no context; it actively misleads your assistant into suggesting outdated patterns. If you find yourself correcting a mistake, ask the AI what it learned from the interaction and if it should/could update the rule/context to avoid similar pitfalls in the future.

BONUS: Here is a Claude command you can use to help keep its context fresh: reflection.md

Happy prompting. Living in the future is AWESOME. As William Gibson says "The future is already here — it's just not very evenly distributed." ... yet.

(post created with help from Claude.ai, but based on my ideas, with human editing and such).