I've Been Building Dev Tools Wrong: When UX Gets In the Way

I spent last week redesigning the onboarding flow for a CLI tool I've been working on. Beautiful loading spinners, a multi-step wizard, helpful ASCII art, color-coded success messages—the works. I showed it to a colleague, proud of the experience I'd crafted. He looked at me and asked: "But how does an agent use this?"

That question hit different. I realized I was optimizing for the wrong user entirely. The human developer testing my tool might see that onboarding flow once, maybe twice. But an AI agent running my CLI a hundred times a day? It doesn't care about the experience. It just needs to parse the output and move on.

This distinction—between building for humans and building for agents—has quietly become one of the most important design decisions in developer tooling. And I think I've been approaching it backwards.

The SaaS Instinct Is Hard to Unlearn

I came up obsessing over onboarding. Figma's first-run experience. Linear's clean flow. Notion's progressive disclosure. These are masterclasses in product design—every pixel and interaction designed to delight the human using it.

That muscle memory doesn't just disappear when you shift to dev tools. I catch myself designing CLI help messages like they're marketing copy. Adding unnecessary verbosity. Over-explaining things. It's the SaaS instinct: convince the user they made the right choice by making the experience feel good.

But here's the thing: my actual users—the developers—aren't primarily experiencing my tool through the UI. They're experiencing it through agents. Cursor. Claude. Custom automation scripts. The human-facing part is maybe 10% of the problem.

What Dev Tools Actually Optimize For

When an agent integrates with your tool, it's not navigating through screens. It's reading documentation, parsing CLI output, and building workflows. The three things that actually matter become obvious pretty quickly:

Documentation is your UX. Not because it's nice to have, but because it's the interface. When an LLM reads your docs to understand how to use your tool, you've created a human-readable spec that the agent can learn from. Ambiguous docs aren't a minor problem—they're a hard blocker for agent integration.

CLI design matters at a different level. I'm not optimizing for beautiful terminal output anymore. I'm optimizing for parseable, predictable output. Structured formats (JSON over pretty-printed tables). Exit codes that mean something. Flags that compose logically. The agent needs to be able to call your tool reliably, hundreds of times, and extract meaningful signal from the response.

Setup needs to be idempotent. A human runs your setup wizard once and moves on. An agent might run it in different environments, might need to re-run it, might need to integrate it into a larger workflow. If your setup has side effects or requires user interaction, you've created a problem for automation.

My Take: It's Still Early, and We're Making Mistakes

I agree with the core insight—dev tools have crossed a line where human UX is no longer the primary design constraint. But I think we're still figuring out what that means practically.

Here's what I'm wrestling with: how much do we optimize specifically for agents versus optimizing for developers using agents? A developer using Cursor with your tool still cares about clarity and speed. The agent just makes their intention executable. So is the right answer to design for the agent's constraints, or to trust that good design for agents translates to good design for developers?

I'm landing on this: optimize for agent integrations relentlessly, and the human experience follows. Bad docs hurt the human almost as much as they hurt the agent. Confusing CLI output confuses both. The difference is that agents will simply abandon your tool if it's frustrating, while humans will muddle through.

Practical Example: What This Looks Like

Here's the shift I'm making in my own tool:

# Before: Pretty output, hard to parse
$ mycli integrate
✨ Integration wizard
  Enter your API key: ••••••••
  Configuring... done!
  All set! You're ready to go! 🎉

# After: Structured, agent-friendly
$ mycli integrate --api-key=$KEY --format=json
{
  "status": "success",
  "integration_id": "int_12345",
  "ready": true,
  "next_steps": ["set_webhook", "verify_permissions"]
}

The second one gives agents something they can actually work with. The human running this can read the JSON. The agent can parse it reliably.

What's Your Reality Check?

I want to hear from people actually shipping this. Are you designing dev tools for agents? How are you thinking about the split between human and agent UX? And be honest—are we overcorrecting away from UX design, or were we overweighting it to begin with?

Source: This post was inspired by "SaaS agentic onboarding vs dev tool agentic onboarding" by Dev.to. Read the original article