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 thanvalue
, 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.