@kentcdodds: This is a great article and is exactly the kind of thing I'm talking about in my most recent YouTube video https://yout…

This is a great article and is exactly the kind of thing I’m talking about in my most recent YouTube video https://youtu.be/kbmv3HIuKyk?is=ch2mysu8YMEY8whK…

TL;DR: The quality of a programming agent’s output depends on the design of the system’s primitives. By providing the agent with well-crafted, composable building blocks and narrowing its action space, you get reliable results.

Why Are Your Agent Outputs Terrible?

If you feel like the code, UI, or logic your agent generates is “garbage,” the problem likely isn’t the agent itself — it’s the system you’ve asked it to work within. The better your system is designed, the higher the quality of the agent’s output. Here, “system” essentially means a set of primitives — the smallest meaningful units your system exposes, like composable building blocks. The more the agent has to guess or create its own primitives on the fly, the lower your chances of getting satisfactory results.

In the past, tech leads were responsible for building systems for individual contributors. Now, every developer is a tech lead, because we all have agents working within the systems we design. For product engineers, system design is now the most scarce and valuable work. Your goal is to build a safe playground for the agent and give it the tools to get things done efficiently.

What Are Primitives? Primitives in Different Domains

Primitives are the smallest composable units your system exposes, eliminating the need to reimplement how each individual piece works. Here are common system domains and their corresponding primitives:

UI & Design Primitives

Components and design tokens, e.g., buttons, text fields, spacing. Without them, the agent can only “make things up as it goes,” resulting in UIs with inconsistent colors, spacing, etc.

API & Backend Primitives

Resources and the operations that can be applied to them, e.g., POST to an orders endpoint, cancel a subscription. Without these, logic gets duplicated everywhere, the system becomes unreliable, and chasing down bugs or rework becomes the norm.

Data Primitives

The entities and their relationships, e.g., Users, Orders, Order Line Items. Without them, the agent will cobble together ad-hoc data structures and have to guess relationships.

Infrastructure & Platform Primitives

Scheduled tasks, data storage, distributed system hosting, deployment locations, secret management, etc. Without these, the agent might “accidentally delete the production storage volume — database gone.”

Agent & Tool Primitives

If the agent doesn’t have well-crafted callable tools, it will fall back to writing one-shot bash scripts — inefficient and hard to reproduce.

Workflow & Reusable Module Primitives

Built-in retry capabilities, workflow orchestration, etc. Good primitives mean the agent doesn’t have to write all that logic manually.

Authentication & Trust Primitives

Permissions, RBAC (role-based access control), audit trails, etc. Without these, you might hand over “god-mode” keys to different agents and have no way to audit what they did.

Managing the Lifecycle of Primitives: Create, Compose, Merge, Delete, Extend

Having primitives is not enough. Throughout your project’s lifecycle, you need to continuously manage them: determine whether a new requirement is a variation of an existing primitive; merge two primitives when they are essentially the same thing; delete a primitive when it’s no longer used; extend a primitive to cover more scenarios.

Concrete Example: When a Primitive Is Missing, the Agent Finds Workarounds

Recently I was adding community packages to Kodi — allowing packages to be created inside Kodi and published to a public registry for others to reference and fork. During implementation, I realized a key primitive was missing: the distinction between admin and normal users. I needed the ability to review packages, remove them, etc., so I had to have different roles and permissions. At the time I recorded this video, multi-user functionality didn’t exist yet, but community packages are a crucial part of user engagement. Instead of having the agent responsible for community packages also implement RBAC on the side, I created a brand new agent dedicated to building this primitive because it’s foundational to the entire system. I’ve made the mistake before of having one agent do too many things at once, but this time I decided, “let that agent focus on this one thing.”

Example of Merging Primitives: PayPal’s Combo Box

A long time ago when I worked at PayPal, I was responsible for cross-border transactions. When you typed an email address, a selection box would pop up — in UI terms, a combo box. I looked through the codebase and found we had three different implementations: one for selecting the sending country, one for currency, and one for entering a friend’s email (non-cross-border). This was unfriendly to both human developers and agents. So I sat down and implemented a really good combo box primitive, which eventually became the open-source library downshift. After merging, we only needed one concept, and everyone was more productive.

Example of Merging Primitives: Cody’s “Skills” and “Packages”

In Cody (my AI assistant MCP server), I originally had a concept called “skills”: Cody would write code, I’d approve it and save it to a D1 database, and later I could call that “skill” to repeat the execution. Then Cloudflare released artifacts (essentially a Git repository inside Cloudflare), which was clearly better and could do more (packaging, using durable objects, etc.). So I built a new “package” primitive and merged the “skills” into it. I also merged Cody’s existing “saved apps” (apps with UIs and endpoints) into “packages”. Now there’s just one primitive — very efficient.

Example of Deleting Primitives: Instagram’s Transformation

Instagram started as a Foursquare clone called Bourbon, focused on alcohol check-ins. They observed user behavior and found that only photo sharing was truly popular. So they deleted everything else and focused solely on photo sharing. We all know what happened next. Deleting primitives reduces the set of things an agent can do, which in turn reduces the chance of the agent misusing something.

Delete then Extend: Cody’s Email Handling

Previously, Cody had the ability to receive emails and process them using all its MCP tools (execute, etc.), which took several agent rounds before replying. I found this too rigid and specific, so I deleted it and replaced it with a simple event system: when Cody receives an email, it simply fires an event, and your package can subscribe to that event. This way, the previously large email-handling primitive was shrunk down to just “emit an event,” while the package primitive was slightly extended to support event subscription. Now anyone using Cody can create any number of packages to handle emails — e.g., “ignore if the subject is wrong” or “process the body and do something.” It’s more flexible, even though at first it seems like “less help” (inversion of control). Ultimately it’s more powerful. For code, since we’re not really doing most of the work anyway, it works great.

Homework: Let Your Agent Evaluate Your Codebase

Now, I want you to ask your agent: “What primitives exist in the current system? Which ones should be created, merged, deleted, or extended? What’s missing? What looks the same? What needs a little more polish?” Since the agent is the one playing in the playground, you might as well ask how it feels: “How well do you work in my codebase?” Then apply your own judgment, combined with product direction, to evolve the system. By consciously managing primitives, you narrow the agent’s action space, letting it compose reusable modules instead of improvising on the fly. Auditing also becomes much easier.

Source: Kent C. Dodds’ YouTube video (https://www.youtube.com/watch?v=kbmv3HIuKyk) (video title: @kentcdodds: This is a great article and is exactly the kind of thing I’m talking about in my most recent YouTube video)