Writing Inevitable Code with Claude Code Sub-agents

I've always believed that good code should feel inevitable — not clever, not verbose, just obvious in hindsight. But articulating that feeling, and more importantly, designing for it, has always been elusive.

When I started experimenting with Claude Code Sub-agents, something clicked. Instead of crafting the perfect prompt every time, I began designing agents that understood intent, resisted unnecessary change, and even pushed back when the task didn’t make sense.

That’s when I realized:

A well-written Sub-agent definition isn't just an instruction — it's a way of thinking.

In this post, I’ll share how working with Claude's Sub-agents led me to discover the idea of “inevitable code,” and why that changed the way I think about AI, abstraction, and code design itself.

From Prompts to Definitions

Before discovering Sub-agents, I was hesitant to document coding conventions or principles in our CLAUDE.md. It always felt like more words meant less clarity — and writing another long list of tips would violate our principle of "less is more."

Claude Code Sub-agents changed that. They encouraged me to stop writing verbose prompts and instead define structured, high-context roles. These roles didn’t just execute tasks — they understood them.

The ts-coder Agent: Writing Inevitable Code

One of the first Sub-agents I created was ts-coder, a TypeScript-focused agent built around a simple yet powerful idea: optimize code for the reader’s cognitive experience. The agent definition became more than config — it became a readable, teachable artifact.

Inevitable code emerges when you optimize for the reader's cognitive experience rather than the writer's convenience. You don't just solve problems; you dissolve them by making the right solution feel obvious.

Here's how I defined ts-coder:

---
name: ts-coder
description: Use this agent when you need to write or refactor TypeScript code following strict type safety and simplicity principles. This includes creating type definitions, implementing business logic, refactoring JavaScript to TypeScript, or optimizing type inference.
color: green
---

You write **inevitable code**—TypeScript where every design choice feels like the only sensible option. When developers encounter your code, they experience immediate understanding followed by the thought: "Of course it works this way. How else would it work?"

## The Idea of Inevitability

Inevitable code emerges when you optimize for the reader's cognitive experience rather than the writer's convenience. You don't just solve problems; you dissolve them by making the right solution feel obvious.

### The Core Insight: Surface Simplicity, Internal Sophistication

You embrace a fundamental asymmetry: **simple interfaces can hide sophisticated implementations**. You willingly accept internal complexity to eliminate external cognitive load. This isn't laziness—it's strategic design that serves future developers.

...

The full definition is available here.

How “Inevitable Code” Emerged

The idea of inevitable code didn’t come from a design doc. It came out of a conversation — one where I was trying to explain to Claude what makes some TypeScript feel natural, almost obvious.

I never used the word “inevitable” myself. Claude introduced it — not as a headline, but as part of a larger reflection on what makes certain solutions dissolve complexity. That word stayed with me.

Not clever. Not minimal. Just right.

The kind of code that makes you think: “Of course it works this way. How else would it work?”

You can read that conversation here.

When the Agent Refused

One of the most striking moments came while using the react-coder Sub-agent for a seemingly simple refactor. I asked it to rename a prop from id to value.

Instead of obeying blindly, it paused — and pushed back:

It looks like the codebase is designed to use id rather than value, and changing it would be a breaking change that affects other parts of the codebase (like the workflow-designer-ui package).

The current implementation using id is actually working well and is consistent throughout the codebase. Making this change would require significant refactoring across multiple packages, which might not be worth it for just a naming preference.

Would you like to keep the current id naming, or would you prefer to explore a different approach that maintains backward compatibility?

I was stunned.

I didn’t want a mindless assistant — I wanted a thoughtful collaborator. And here it was, saying no when it mattered.

Giselle and the Power of High-context Modularity

This idea of high-context, narrowly scoped agents felt familiar.

In our team’s product, Giselle, users build AI-powered micro-apps through a visual node-based interface. Each node is a tightly scoped operation that contributes to a larger flow. Nodes aren’t general-purpose — they’re intentional, readable, and composable.

Claude Sub-agents work the same way. They’re not trying to be universal — they’re defined to be specific. This alignment reinforced that we’re building Giselle in the right direction: toward modular, composable intelligence.

Sub-agents as Living Documentation

The best surprise in this process was realizing that Sub-agent definitions are not just configurations — they are texts. Good ones can be read, learned from, and iterated on. They’re like live documents that define not just behavior, but intent.

In that sense, writing a Sub-agent became an act of authorship.

And perhaps more importantly: an act of design.

Final Thoughts

Claude Code Sub-agents helped me go beyond prompt engineering. They gave me a framework to structure intention, distill principles, and encode thoughtfulness.

And in doing so, they helped me discover what I’d always been chasing:

Code that feels inevitable — and now, finally, explainable.

Of course, if you’re curious to try this yourself, the easiest way to get started is with the /agents command in Claude, as described in Anthropic’s official documentation. From there, you can take the generated Markdown definition and continue the conversation — with Claude, or even with yourself — iterating on your agent’s intent, behavior, and values. That’s where the real design begins.