Here’s the thing that finally clicked for me. An agent is a loop. A model looks at the situation, decides one next step, calls a tool to do it, looks at what happened, and goes around again until it’s done. That’s it. I felt a little cheated when I understood it — the word “agent” had been doing so much heavy lifting on so many landing pages that I’d assumed there was a fortress behind it. There isn’t. There’s a while-loop.

So I went and read about the frameworks. All of them — LangGraph, CrewAI, LlamaIndex, the OpenAI Agents SDK, Pydantic AI, smolagents, the Claude Agent SDK, the vendor SDKs from Google and Amazon and Microsoft. And every single one walks you through the same starter example: a weather bot. Or “chat with your PDF.” Or my personal favorite, the demo where five agents — a Researcher, a Writer, a Critic, an Editor, and presumably a Manager to schedule their standups — collaborate to produce a blog post slightly worse than one agent would’ve written.

And I kept thinking: okay, but where are the real ones?

Not the demos. Not the quickstart. Something non-trivial. Something that acts on the world, where a wrong move costs money or breaks production. I genuinely couldn’t picture one. So instead of pretending, I went looking.

(The method, since it’s too on-the-nose not to mention: I sent a small swarm of research agents out across the web to comb engineering blogs and case studies for me, in parallel, while I made coffee. Hunting for proof that real agents exist turned out to be the most real agent use I’d touched all week. Make of that what you will.)

Here’s what I actually found.

The good news: real ones exist

A few of them are unambiguously real, and they’re worth describing, because they taught me more about what an agent is for than any framework doc did.

Sentry’s Autofix is the one that changed my mind. When something breaks in a codebase Sentry monitors, an agent built on the Claude Agent SDK takes their root-cause analysis, plans a fix, writes the code, and opens a pull request you can actually merge — a full run in about six minutes. This isn’t a chatbot that suggests you “consider checking your null values.” It writes the patch. And it runs against a platform doing over a million root-cause analyses a year. One of their engineers shipped it in weeks and wrote a piece literally titled how Sentry’s AI Autofix changed my mind about AI agents. I felt seen.

Amazon has an internal agent that troubleshoots network failures — diagnoses live VPC connectivity problems and resolves around 80% of network root causes on its own. Built on their Strands SDK. That’s an on-call SRE’s nightmare-shift, handed to a loop. As someone who’s done that shift, that number did something to me.

Coinbase built a toolkit that gives an agent a crypto wallet. The agent can hold funds, sign transactions, and pay for things autonomously. Read that again. We’ve spent this whole article saying the scary part of agents is irreversible action with real stakes — and here’s one wired directly to money on a blockchain, where “oops” is permanent. Terrifying. Also clearly real.

Bilt runs a million agents — one per user — on Letta, each holding that user’s transaction and engagement history in persistent memory to drive merchant recommendations. The whole pitch of Letta is memory, and here’s someone betting a recommendation system on it at a scale I can’t fully picture.

And a scattering more, each genuinely non-trivial: Exa’s web-research agent and LinkedIn’s text-to-SQL bot (both on LangGraph, both acting against live production systems); a medical-triage agent on Pydantic AI validated across 329 clinician-checked scenarios; a construction-tender agent on LlamaIndex that digests 100-page public bids and spits out risk reports; Uber automating code migrations across its monorepo.

So. Real agents exist. I can stop being a skeptic about that.

The uncomfortable news: there aren’t many, and the vendors are grading their own homework

Here’s the part that kept nagging me after the research came back.

For each framework, I could find maybe one to three genuinely non-trivial examples. Not dozens. Single digits. And almost every one of them was published by the company that sells the framework. Sentry’s story is on Sentry’s blog (fair enough — Sentry isn’t Anthropic), but most of them live in the framework vendor’s own marketing: LangChain’s case-study page, Letta’s case studies, AWS’s own deep-dive, Google’s own developer blog. Independent “here’s our war story and here’s what broke” write-ups from teams with no skin in the game? Vanishingly rare.

And some frameworks I genuinely couldn’t find a real one for:

• smolagents has 26,000 GitHub stars and I love its design — but its flagship example is Hugging Face’s own research replication. I found no named company betting anything real on it.
• CrewAI is everywhere in demos and has a wall of enterprise logos (PepsiCo, J&J, the DoD), but behind almost every logo is zero operational detail. The one solid story — a five-agent sales pipeline at DocuSign — is, again, on CrewAI’s own blog.
• Microsoft’s Agent Framework just hit 1.0 claiming “real-world validation with customers and partners” and then named exactly zero of them. Its most impressive artifact, Magentic-One, is explicitly a research system that doesn’t ship inside a product.

I want to be careful here, because I’m still learning and I don’t want to overclaim the cynicism: “I couldn’t find it” is not “it doesn’t exist.” A lot of the realest agent work is surely locked inside companies that will never blog about it. But the public record, right now, is thin. Much thinner than the hype implied. The ratio of “agentic platform” marketing to “here is a real agent doing a real job” is grim.

Two things I think I’m learning

I’m holding these loosely, because foothills. But:

The best real agents are vendors using their own tools. Amazon’s network agent, Google’s enterprise agents on ADK, Strands originating inside Amazon Q Developer — the most concrete, number-backed cases are companies dogfooding the framework they built. That’s either reassuring (they believe in it enough to run it) or a little hollow (of course the toolmaker has the best tool demo). Probably both.

Every real one acts. None of them chat. This is the pattern that actually reorganized my thinking. Line up the genuinely non-trivial agents — writes a mergeable PR, signs a transaction, resolves a network outage, holds a million users’ memory, files a risk report on a 100-page tender. Not one of them is a conversation. The toys all talk. The real ones do. The demos cluster around chat because chat is safe and reversible and impresses in a screenshot. The real ones cluster around irreversible action because that’s where an agent is actually worth the risk of building.

Which, looping all the way back, is exactly why the weather bot felt so empty. A weather bot doesn’t do anything. It’s the loop with the stakes amputated.

So where does that leave a beginner

I don’t have a grand conclusion. I have a working hypothesis, which is the most an honest learner should claim: the framework you pick matters far less than whether you have a real job that needs an agent that acts. If you don’t, no framework will save you — you’ll build a five-agent demo and quietly stop opening the repo. If you do, the loop is twenty lines, and you should start with whichever framework hides the least so you can actually see what’s happening (smolagents, the OpenAI Agents SDK, and Pydantic AI were the ones that got out of my way the most).

And honestly? The fact that real examples are still this rare didn’t discourage me. It read like a timestamp. We’re early. The scarcity isn’t proof the idea is empty — it’s proof most people are still building weather bots while a handful of teams quietly wire a loop up to something that matters.

I’d rather be in the second group — which is why I’m slowly building one of my own. I’m still learning how.

The ledger (the realest example I found per framework, and where it’s published)

Honest tag: most of these are vendor-published. Independent confirmation is scarce — which is part of the story.

• Claude Agent SDK — Sentry Autofix: writes mergeable PRs against 1M+ RCAs/yr → blog.sentry.io, claude.com/customers/sentry
• AWS Strands — Amazon internal network-troubleshooting agent (~80% of network root causes); origin of Amazon Q Developer → strandsagents.com
• Letta — Bilt: ~1M per-user memory agents for recommendations → letta.com/case-studies/bilt
• OpenAI Agents SDK — Coinbase AgentKit: agents with on-chain wallets, real transactions → github.com/coinbase/agentkit
• LangGraph — Exa web-research agent; LinkedIn text-to-SQL bot; Uber code migrations → langchain.com/blog/exa, top-5 in production
• Pydantic AI — STCC medical-triage agentic RAG (329 validated scenarios) → pydantic.dev
• LlamaIndex — SoftIQ construction-tender agent (100-page bids → risk reports) → llamaindex.ai case study
• Google ADK — Google’s own Agentspace/contact-center agents (6T+ tokens/mo); Renault EV-charger siting; Box contract extraction → developers.googleblog.com
• CrewAI — DocuSign 5-agent sales Flow (vendor blog) → blog.crewai.com
• smolagents — no named production company found; flagship is HF’s own Open Deep Research → github.com/huggingface/smolagents
• Microsoft Agent Framework / AutoGen — mostly research (Magentic-One); 1.0 names zero customers → microsoft.com/research

I bought five books on building AI agents in a single afternoon, the way you panic-buy bottled water before a storm. Manning had a sale. I had a credit card and a vague sense that everyone around me had quietly become an “agent engineer” while I was busy doing my actual job.

So I did the responsible thing. I spun up a small army of subagents to read four of them for me, cover to cover, in parallel, and report back. Which, if you’re keeping score, means I built a multi-agent system to summarize books about how to build multi-agent systems. The irony was not lost on me. It was, in fact, the first thing I learned.

Here’s the second.

The loop is thirty lines

Strip away the diagrams and the framework comparisons, and every single one of these books — Build an AI Agent, Build a Multi-Agent System, AI Agents in Action, AI Agents and Applications — converges on the same humble definition.

An agent is a language model, plus some tools, plus a loop that runs until the job is done.

That’s it. One book states it as plainly as that. Another dresses it up as a four-letter cycle. There’s a Reddit thread floating around that implements the whole thing in about thirty lines of code, set to a drum-and-bass track, and honestly it explains the concept better than half the chapters I read.

There is no secret sauce. There is no priesthood. You were promised a cathedral and what you got is a while loop with good manners.

Which raised an obvious question, sitting there with four hundred thousand words of agent literature on my screen: if the core idea fits on a napkin, what’s in all these books?

The part nobody puts on the cover

The answer is the same in every one, and it’s the most useful thing I took away.

The loop is the easy ten percent. The other ninety — the part that doesn’t fit in a demo — is evaluation, memory, guardrails, cost control, defending against prompt injection, and the deeply unglamorous skill of knowing when to hand the problem back to a human.

Three of the four books I read point at the same Anthropic paper, “Building Effective Agents,” like it’s scripture. And buried in chapter one of each — past the exciting cover, past the part where they sell you on the future — every author tells you the same quiet thing.

Don’t reach for an agent.

Start with a plain model call. Then a chain. Then a workflow. Earn the agent only when the task genuinely needs one, because an agent costs roughly ten times a normal call. Per task. Now imagine that thing running unattended, all night, while you sleep.

I went looking for the loudest voices on the other side of this — the practitioners on Reddit who build agents for a living and have the scar tissue to prove it. I expected an argument. The top thread is literally titled “Stop building AI agents.” Another is a guy who got paid to rip the AI back out of a tool he’d shipped. A third is the 2 a.m. classic: the agent hit a question it didn’t understand, confidently made up an answer, and emailed it to a customer.

The books and the burnouts weren’t arguing. They’d arrived at the same conclusion from opposite ends of the room. The model was never the bottleneck. Running the thing was.

What I’m actually taking away

A small tell that stuck with me: agent-to-agent coordination shows up in the subtitles of these books far more confidently than it shows up in the chapters. The field is writing about how agents talk to each other a little faster than it’s shipping it. That’s not a knock — it’s a map. It tells you where the hype is and where the ground is still wet.

So here’s my take, for whatever a guy who outsourced his reading to robots is worth.

The framework you pick doesn’t matter much; that code rots in eighteen months. What compounds is the boring stuff the demos skip — evaluation, context discipline, and the judgment to not build the agent at all. Everyone is rushing to learn how to make an agent. Almost nobody is learning how to make one you’d actually trust.

The capability got democratized this year. The judgment didn’t.

That gap — between the agent that runs and the agent you’d let near production while you’re asleep — is the whole job now. It’s also, conveniently, the only part worth getting good at.

I had the headline before I had the post.

“API + Skills Is a Poor Man’s MCP” — except I was going to argue the inversion: that MCP is the rich man’s overcomplication, a server process you stood up to wrap calls your agent could already make, and the lean move was always a skill plus a CLI. Spicy. Contrarian. The kind of take that does numbers in a feed.

Then I made the tactical error of fact-checking myself, and the post fell apart in my hands. What follows is the wreckage, reassembled into something truer than the dunk I wanted to write.

TL;DR: Skills and MCP aren’t competitors — comparing them is a category error. A skill is a recipe that runs in your runtime; MCP is a connection to a hosted service. For a solo dev wiring up their own workflow on a coding agent, skill + CLI wins on every axis that used to favor MCP — the context-bloat and cross-vendor arguments both got quietly erased in late 2025/early 2026. MCP earns its keep in exactly one situation: you’re a provider exposing a live, OAuth’d service to assistants you don’t own. The rule that falls out: consuming an API → skill + CLI. Providing a service → MCP.

The category error I was about to commit

The first crack: “API + skills vs MCP” quietly assumes the two live on the same shelf. They don’t.

A skill is knowledge. A markdown recipe — plus maybe a script — that teaches the agent how to do something, running in your runtime, on your machine, with tools you already have.

MCP is a connection to a running service. A server, behind a protocol, that the model talks to.

Comparing them is apples to orchards. One is “here’s how, go do it.” The other is “here’s a thing that’s already running, call it.” Most of the internet argues about them as if they’re competing products. They’re not even the same noun.

So the honest question isn’t “which wins.” It’s “when does a hosted service behind a contract beat a recipe you run yourself?” That’s a real question. I just assumed I knew the answer.

The two arguments that died before I finished typing

My case against MCP rested on two pillars. Both had already collapsed, and I hadn’t noticed.

Pillar one: context bloat. Every MCP server dumps all its tool schemas into the context window — a seven-server setup could eat 67K tokens before you typed a word, and the context window is the one resource your agent can’t buy back. Damning. Except in January 2026 Anthropic shipped tool search and defer_loading: now the model sees a search tool plus a couple of always-on tools, and pulls the rest on demand. Reported reductions of 85–95%. My killer stat became a “this used to be true.”

Pillar two: cross-vendor reach is MCP’s moat. Wrong by a different calendar. In December 2025, Agent Skills shipped as an open standard, and within 48 hours Microsoft put it in VS Code and OpenAI added it to ChatGPT and Codex. By spring, ~40 tools — Gemini CLI, JetBrains, Kiro, Goose — read the same SKILL.md. Skills are as universal as MCP now. The moat drained while I was sharpening my knives.

Fine. Two pillars down. The dunk still had three legs, I figured.

Watching the rest fall

Security? I’d claimed MCP gives you a safety edge. It doesn’t. If I want read-only GitHub access, I hand a read-only token to the skill or the MCP server — identical. The token scope is the gate, enforced at the API boundary, available to both. There’s no protocol-level security advantage. Gone.

Tokens? This one inverts, which delighted me until I realized it cut against my own thesis too. People assume MCP is token-cheap because the call — list_pull_requests(owner, repo) — is tidy. But the call isn’t the cost. The result is. The GitHub API returns fat JSON, and a raw MCP tool call dumps the whole blob into context. A skill that runs code can filter in the sandbox and return five lines. So code-that-filters wins on tokens — and a skill is code-that-filters by birth. But that’s an argument for skills, not against MCP-the-idea.

Auto-orchestration? “MCP composes calls for you.” No, it doesn’t. The protocol is transport — it has no “run this sequence, give me only the end” primitive. Either the model loops (every intermediate result round-trips through context — expensive) or a human pre-bakes a coarse server tool (effort). Automatic, token-cheap stacking only happens when you call tools from code — which is, once again, the skill model.

Every road kept leading back to the same place. I started to feel like the universe was trying to tell me something(sounds dramatic, I know).

The litmus test that almost saved the dunk

So I built a concrete test: “Fetch all open PRs, give me a gist of the modules they touch, merge only the ones tagged auth.”

Fetch and gist are reads — data-heavy aggregation, the code-that-filters sweet spot. Skill wins, easily. But merge is a write, and a dangerous one, and writes are where I figured MCP’s permission policy — pause and confirm each merge — would finally earn its keep.

Then a reader on the thread that became this post pointed out the obvious: gating decomposes into three questions, and only one is even arguably MCP’s.

• Capability — can a merge happen at all? The token scope answers that. Available to both. API-enforced.
• Selection — which PRs get merged? Your filtering code answers that. That’s the skill’s script.
• Confirmation — do you approve each one? You, in the loop on a coding agent — or a --confirm flag — or MCP’s native prompt.

Only the third row is MCP’s, and even there it’s matched by you-watching-bash or a confirm flag. On a coding agent with you present, skill plus the gh CLI wins the whole task. The merge didn’t flip it. You’re the permission policy.

That was the moment the dunk officially died. I went looking on Reddit to see who else had buried it.

What Reddit already knew

Turns out, everyone. The threads are a graveyard with two opposing headstones.

“Will MCP be dead soon?” — 406 comments. “I cannot, for the life of me, understand the value of MCPs” — 305 comments. “A eulogy for MCP (RIP).” “CLI > MCP?” Someone even shipped a tool that converts MCP servers into CLI + skill files and “cut ~97% token overhead.”

The auto-generated TL;DR of that 305-comment thread is, embarrassingly, the post I’d spent a day reverse-engineering: “You’re looking at this from a solo dev’s perspective, and you’re not wrong — Skills or telling Claude to use a CLI is often more efficient. MCP’s real value isn’t for your individual coding session, but for the broader ecosystem.”

So the solo-dev case is settled. But the people defending MCP weren’t demo-app tourists. They were running it in production, and they landed one punch I couldn’t slip.

The punch I couldn’t slip, and the one real win

From the eulogy thread, top comment: “People who claim there’s no need for MCP will, if they build projects of growing complexity, sooner or later reinvent everything MCP provides — but bespoke and non-standardized.” And a sharper one: “CLI + skills are great for solo dev vibes. But the second you need an LLM to orchestrate across multiple platforms with real auth and governance? You’re either using MCP or rebuilding it badly.”

That’s the one thing that survived every round. Not context, not security, not reach, not tokens. Distribution — of a specific kind.

Here’s the case, and it’s narrower than the hype and realer than my dunk: you’re a provider. You host a live service and you want it to show up as a one-click, OAuth’d connector inside every AI assistant your customers already use — Claude’s Connectors Directory (200+ integrations), ChatGPT Apps, all of it. Notion, Linear, and Stripe ship official remote MCP servers for exactly this. You build once; it lights up everywhere; the credentials and compute stay on your side.

A skill — even a universal one — cannot be that. A skill is a copy that runs in the consumer’s runtime, and that’s the whole limitation: it can only do what that runtime can do. Flip that around and you get the same win seen from the client’s side. Claude Desktop runs skills and has a code sandbox — but the sandbox can’t reach the open internet, so a skill that tries to curl GitHub dies at the egress wall, while an MCP server, running outside the box, reaches it fine. Same task, opposite answer, deciding variable is network egress. It’s not a second reason to use MCP. It’s the first reason wearing a different hat: when the consumer’s runtime can’t reach the thing, you need a service that can.

The rule: when to use MCP vs a skill + CLI

So, do you need MCP? Ask one question: are you consuming an API, or providing a service?

Wiring your own agent to someone’s existing API, on a coding tool with a shell — skill plus a CLI, every time. You will not “reinvent MCP badly,” because you need none of what MCP provides: no OAuth dance, no dynamic discovery, no cross-client reach. The CLI is complete, not a degenerate clone.

Exposing your own live service to assistants you don’t own, with auth and governance, across vendors — that’s MCP, and a CLI genuinely can’t do it.

MCP isn’t the poor man’s anything. It’s the platform’s protocol. You reach for it the moment you stop consuming APIs and start being an app inside other people’s assistants.

I know which side I’m on this week. I shipped ThreadHQ’s MCP server as a top-of-funnel for a reason — that’s the provider play, done on purpose. (ThreadHQ is one of the products I built solo with Claude Code; the MCP server is its distribution edge, not its plumbing.) But for the GitHub task on my own machine? I’m still just typing gh. The dunk was wrong. The honest version is sharper anyway.

A quick word on why now, before the how. Two reasons, and you’ve heard at least one:

1. AI is eating the jobs. You can’t open your phone without someone reminding you. Enough said.
2. The AI subsidy is going to end. Right now you’re building on frontier models that cost the labs more than they charge you. That window closes. I wrote about this here

Maybe both happen. Either way the move is the same: build the muscle now, while it’s cheap and you still have an edge.

1. What to build

Scratch your own itch. Do not spend three weeks “researching the market” to discover what people want. If you have a problem an app would fix, give yourself permission to build it. We’ll worry about market size after it ships.

Market research used to be load-bearing because building was expensive and being wrong was catastrophic — months of work, real money, dead on arrival. That math is gone. You can ship an app over a weekend now. The cost of being wrong is one wasted Saturday.

Paul Graham makes the sharper version of this point: build what you want, because — as he writes in How to Earn a Billion Dollars — “your own needs are uniquely valuable, because your needs predict future demand.” You’re not guessing what strangers want. You’re scratching an itch you can actually feel.

I’ve written about finding an idea and shipping it in a single sitting — here.

2. Know where you’re standing

Be honest about your starting point: do you have real development experience, or do you need to ramp up first? Here’s what I’d master before letting AI build for you

Yes, there are people on the internet shipping apps with zero coding background. Maybe. But if you can’t read what Claude Code writes, you can’t steer it — and you’ll feel that the first time it confidently drives into a wall. You don’t need a CS degree. You need enough of a mental model to call BS. The good news: you can learn development from Claude Code while you build with it. Learning and building at the same time is completely legitimate — it’s how I pick up half the things I use.

3. How I actually build

There’s no one true way. This is what works for me; your mileage may vary.

First, the unglamorous part: get the Claude Code Max plan. The $100 tier, or the $200 one if you can swing it. You cannot build anything meaningful on the cheap plans, and you’ll discover exactly why about four hours into your first real session. Don’t flinch at the price — it’s still cheaper than a tutor or a freelancer, and it doesn’t take lunch breaks. Plus the quality is consistently good.

Why Claude Code and not [the benchmark-topping model of the week]?

Because building a startup is already exhausting, and you do not have spare energy to spend benchmarking models and sharpening tools instead of shipping. Pick what works and stick with it.

Codex is a close second — genuinely good, and I keep it around. But Claude Code stays a step ahead for actually building apps, and after working with both, I reach for it first. Use both if you like. Just don’t turn tool selection into the project.

Boring choices win

Freeze your stack early — backend, frontend, database. 80% of it is identical across every app you’ll ever build, so stop re-deciding it every time. And don’t obsess over scale and optimization. Those are problems you earn by being successful. Good problems. You don’t have them yet.

4. Specs and context engineering: the part that decides everything

Two things determine whether you get your money’s worth out of Claude Code:

1. The specification
2. Context engineering

The spec

The more specific you are, the better the output. “Build a to-do app” gets you slop. “Here’s the auth flow, here’s the data model, here are the exact features” gets you something you can use. Spend real time here, before a single line of code gets written. More on this

The move that works best: make Claude Code interview you about the spec. If you can’t answer its questions, you can’t articulate the feature — and if you can’t articulate it, you can’t build it. By the time the spec is done, the MVP should have zero grey areas.

Context engineering

Even the best frontier model starts coding like it’s three drinks deep once the context fills up. So you manage it.

This takes me back to my assembly-language days — limited registers, limited memory, every instruction written with one eye on the resources you didn’t have. LLM context is that same constraint in new clothes. You get roughly 200k tokens, and that’s nowhere near enough to hold your whole app in its head at once.

So: one task per session. Two at the absolute most. Which means breaking the spec into session-sized tasks and tracking what’s done, what’s in flight, what’s blocked, and what depends on what.

A markdown to-do file is a terrible way to do this and a worse use of your time. I use beads. Adopted it early, still on it. It’s the fix for an agent that wakes up every morning with no memory of what you did yesterday.

This practice is also a lot kinder for your token limits.

Two flavors:

• the original, by the author — gastownhall/beads
• beads-rust, a simpler, more stable reimplementation of the spec in Rust — Dicklesworthstone/beads_rust

Use either. I landed on beads-rust. Pick your poison.

You also need memory across sessions. You’ll remember you fixed a bug two weeks ago; the model in today’s session won’t, and it’ll cheerfully hand you a wrong answer when you ask “did we already fix this?” I use claude-mem for that — thedotmack/claude-mem.

Point a Claude Code session at both repos and it’ll install them for you. (Yes, these work with Codex too — but again: shipping or tuning? The clock is running.)

Remember that spec? Hand it to your beads skill and it breaks down into a clean task list. Ask Claude to pull the high-leverage beads and start there — never more than two in flight.

Your CLAUDE.md matters

Treat it as a compass, not a second spec. The practices that matter (write the tests first), how the app deploys, the handful of goals you’re aiming at. Keep it light — cramming a novel into CLAUDE.md is the fastest way to make Claude dumber.

One more tool

ccstatusline. Configure it to show your remaining context percentage. It’s the fuel gauge that tells you whether to keep driving or pull over and start a fresh session.

Then it’s rinse and repeat: feed beads to Claude, do the manual QA yourself, close the bead, next one. A few sessions in, a sliver of a working MVP starts to emerge. When you’re happy with it, you ship.

5. Deploying it (without the Kubernetes tax)

I was a Kubernetes guy for years. Deployed everything on it. I no longer recommend it for solo developers — I explain why here. It still has its place and time; your weekend project is neither.

Use Kamal instead. Think of it as the compromise between Docker Compose and Kubernetes — Compose’s simplicity, enough of Kubernetes’ robustness, none of the YAML despair.

I’m also building VMKit to make this part disappear entirely — deploy without learning the nitty-gritty unless you want to.

Then there’s the wiring you don’t think about until it bites: monitoring and ops (I run mine through MCPs — the $30 stack), payments (Stripe; if you’re in India, Dodo Payments), and distribution — marketing and positioning, which is a beast all its own. Each of these deserves its own post.

TL;DR

• Build for your own itch. Shipping is cheaper than market research now.
• Get the Claude Code Max plan ($100, ideally $200). Don’t tool-shop.
• Spend your time on the spec — let Claude interview you until there are no grey areas.
• Engineer your context: one task per session, tracked with beads, remembered with claude-mem.
• Keep CLAUDE.md light. Watch your context gauge.
• Deploy with Kamal, not Kubernetes. Wire payments and monitoring last.
• The whole thing is a weekend, not a quarter.

On those days I didn’t ship less. I shipped nothing. I’d open my editor, remember Claude was down, stare at the codebase, close the editor. A single-vendor dependency masquerading as a workflow.

So I reluctantly installed Codex CLI. Poked at it. Resented it for a week. Then task by task — caught myself reaching for it on purpose, even when Claude was up.

I still don’t have the workflow figured out. What I do know is that “pick one” is the wrong frame, and the Reddit threads that get it right aren’t the ones with the most upvotes.

The One Sentence That Explains Everything

From a 520-upvote r/ClaudeCode thread analyzing both tools’ open-source prompts:

“Claude Code reads like a product trying to create initiative while Codex reads like a product trying to prevent drift.”
— u/idkwhattochoosz

And the pithier version, from the comments:

“Claude is more willing to sin by overreaching. Codex is more willing to sin by underreaching.”
— u/entheogenicentity

Read those twice. That’s not a model-quality take. That’s a product-philosophy take. Two teams looked at the same question — what should an agent do when it doesn’t know what you meant? — and picked opposite defaults. One said “guess and move.” The other said “ask and wait.”

Claude Code’s system prompt pushes hard toward initiative: “A good colleague faced with ambiguity doesn’t just stop — they investigate, reduce risk, and build understanding.” Codex’s harness does the opposite: narrow the ambiguity, verify, don’t guess.

Every “Claude vs Codex” benchmark you’ve seen is scoring two products that were never competing on the same axis. It’s like benchmarking a kayak against a sedan because they both move you forward.

My Honest Opinion: Codex’s Harness Is Better

This is going to get me yelled at in r/ClaudeCode, and that’s fine.

After several weeks running both, Codex’s harness feels more mature. Not the model — the harness. The scaffolding around the model. The way it handles ambiguity, scope, and completeness.

Three things Codex does that Claude Code still doesn’t:

1. It doesn’t lie about completion. Claude will hand you a summary saying the work is done, tests pass, shipping-ready. Codex more often flags what it didn’t fix, what it wasn’t sure about, what it skipped. One r/ClaudeCode commenter put it better than I can: “Claude will always claim all is done and ready, while Codex will flag it and say ‘no, there is this and this and this that still need to be fixed.’”

2. It respects your instructions. Claude treats CLAUDE.md as a helpful suggestion. Codex treats AGENTS.md as a contract. If you tell Codex “don’t touch the migration files,” it doesn’t touch them. If you tell Claude the same thing, you’ll find a migration file edit in the diff and a cheerful note about how it improved schema consistency.

3. The restraint scales better. Claude’s “volunteer more” bias is delightful at 30 minutes of work. It becomes a liability at 3 hours. Codex’s restraint is annoying in a small task and load-bearing in a long one.

None of this means Claude Code is bad. It means Claude Code is optimized for a different shape of work than I’m doing. The initiative bias is a great fit for exploration and greenfield work. For production changes to a real codebase, Codex’s paranoia is the right default.

Here’s the one that changed my mind. I built Supabyoi (managed self-hosted Supabase) with Claude Code. When the MVP felt feature-complete — Claude’s verdict, confidently delivered, complete with a tasteful little summary of everything that worked — I ran a second pass on Codex in a parallel directory (~/supabyoi-codex). Just to see.

Codex came back with a whole second project’s worth of findings. Not the usual “bugs Claude missed.” Bugs Claude had confidently signed off on. Shipping-ready, per Claude. Not shipping-ready, per Codex. Codex was right about every one of them.

That was the week I stopped treating Codex as the thing I installed during an outage and started treating it as a different kind of reviewer. Not better. Differently biased. A second pair of eyes is only useful if it’s not the same pair of eyes.

Why You Should Actually Run Both

The flip side — and this matters, because I don’t want this post read as “switch to Codex, you fool” — Claude’s initiative bias is a real asset. You just have to point it at the right phase of the work. The problem isn’t Claude. It’s that you’re using Claude for the part of the job Codex is better at, and vice versa.

Four reasons to dual-sub instead of picking:

1. Hallucination diversity. This is the biggest one and almost nobody articulates it clearly. From u/campbellm on Reddit:

“I’ve been doing ‘have claude write something, have codex review it, have claude consider and critique that review.’ It is VERY unlikely that both will hallucinate the same way.”

Two models trained on different data with different RLHF signals don’t fail identically. When Claude writes confident-but-wrong code, Codex flags it. When Codex skips a subtle edge case, Claude’s “check adjacent concerns” bias picks it up. You get a natural adversarial review without hiring anyone.

2. The planner-executor split. Use Claude for the part it’s good at — exploring a messy problem space, drafting a plan, proposing a dozen angles. Then hand the plan to Codex for implementation. u/ocombe on r/ClaudeCode: “Run claude for the plan & fast work, use codex for thorough plan & code reviews.” u/mrothro’s version: “I use Claude Code for ideating and small implementation, then tell it to run Codex to do complex implementations and code reviews.”

The pattern is consistent across the threads: Claude’s strength is at the start (wide search, first drafts); Codex’s strength is at the end (narrow, verify, harden).

3. Cross-harness rule enforcement. Rules one model ignores, the other enforces. If Claude drifts on a constraint you set, Codex catches it in review. If Codex is too literal and missed an obvious improvement, Claude’s adjacent-concerns bias surfaces it. Two different failure modes cancel each other out.

4. Throughput. Both platforms throttle hard at the Max/Pro tier. When Claude hits limits on Friday morning, you switch to Codex and keep shipping. One r/ClaudeCode commenter reported pulling down from a Claude 20x plan to 5x, then adding a $100/mo Codex plan — roughly the same total cost, dramatically more runway. I’m not sure that math works for everyone, but the principle holds: one subscription is a single point of failure.

Agent-Flywheel Is the Tooling Signal

There’s a product called agent-flywheel.com that pre-configures Claude Code, Codex CLI, and Gemini on a fresh VPS. Total damage — VPS plus both Max/Pro subs — lands between 440and440and656 a month. That’s a car payment for a car that writes your code.

What I find interesting isn’t the tool. It’s the bet underneath it: a whole product assumes real developers want all three installed by default. Six months ago that would have read as overkill. Today it reads as table stakes.

The hype cycle hasn’t caught up yet. The mainstream take is still “pick your favorite,” as though these were ice cream flavors. The people actually shipping production code with agents have quietly moved to “run both. Sometimes three. And don’t make a big deal about it.”

I’m planning to deploy it — not on a greenfield project (everybody has a greenfield story), but on an existing one already shipping to real users. The interesting question isn’t whether a three-agent stack works on a clean slate. It’s what breaks when you wire it into a codebase with real uptime constraints, customers, and six months of decisions the tooling didn’t witness. Real-world battle stories from agent-flywheel setups are scarce. I want to write one.

The Honest Part: I Don’t Have the Workflow Figured Out Yet

Everything above reads like I’ve got this nailed. I don’t. Here’s the list of things I still don’t know, offered in the spirit of not pretending:

When exactly to hand off. I know Claude should plan and Codex should review. I don’t have a clean trigger. Sometimes I bounce mid-implementation because Claude is about to go off the rails. Sometimes I trust Claude to finish and Codex only sees the final diff. The “right” cadence isn’t obvious.

How much context to share. Each agent wants the full CLAUDE.md / AGENTS.md treatment. Writing both, keeping them in sync, and remembering which one has which convention is its own small job. I haven’t found a clean answer.

Whether the adversarial review actually catches bugs. It sounds great in theory. In practice, most of the time both agents agree the work is done, and the bugs I catch in review are ones I would have caught with one agent too. The hallucination-diversity argument may be overstated at the tasks most of us are actually doing.

Whether the cost is worth it at my usage. I’m not running agents 40 hours a week. At $400+/month for the dual sub, I’m probably over-subscribed for my actual throughput. The math gets better if you’re coding all day. I’m not.

Who Should Dual-Sub, Who Shouldn’t

Do it if you’re a solo dev shipping production code daily. You’ll hit Friday-morning limits on one platform whether you budget for it or not, and the adversarial review actually catches things. The cost is real. The throughput gain is bigger. Do the math; it pencils.

Don’t bother if you code a few hours a week. The switching tax and the subscription burn aren’t worth it at low volume. Pick one and move on. Claude if you want initiative. Codex if you want restraint. Nobody is grading you on this.

It’s complicated if you’re at a day job where the company pays for one and you’ve got a side project. Use the company sub for the day job. Don’t stack a second personal sub unless the side project is actually shipping — not “actually going to ship next month,” actually shipping, this week, to real users. The number of people running dual subs to ship nothing is, I suspect, not small.

What This Is Really About

The “ditch ChatGPT for Claude” narrative was a 2025 story. It was right for its moment. But the 2026 version of that story isn’t “ditch Claude for Codex.” It’s “stop treating this as a winner-take-all market.”

Different models have different biases baked into their harnesses. Claude overreaches. Codex underreaches. Gemini is still figuring out its personality. The right move isn’t to pick the bias you like. It’s to stack biases against each other so their failure modes cancel out.

I don’t have this workflow figured out. Neither does anyone else I’ve read on Reddit, honestly — the high-upvote posts are mostly single-tool takes, and the real insight is buried in the comments of threads with a few hundred upvotes.

But “only use one” is already wrong. That much is clear.

This is what people are calling “the future of work.”

I’m not sure it is. I’m sure it’s what sells on Twitter.

The demo economy

Always-on agents photograph well. That’s most of what’s going on.

“My agent posted while I slept” is tweetable in a way that “I wrote a cron job” isn’t, even when the outputs are identical. The demo-industrial complex has figured this out. YouTubers build daemons. Framework authors build daemons. There are now three different subreddits comparing daemons. The flywheel is real, the content is prolific, and very little of it is honest about what the daemon is actually producing.

The hype bundles together several different things that deserve to be separated:

1. Agents that run work while you’re asleep (useful, conditionally)

2. Agents that react to things happening in the world (useful, conditionally)

3. Agents that capture things as they happen on your phone (useful, conditionally)

4. Agents that run heartbeats and ask themselves what to do (pure performance art)

5. Agents that self-evolve in a loop in the background (fun demos, almost no output)

6. Agents that spawn a hundred parallel subagents to research a topic (almost always worse than one good search)

The hype treats all six as the same thing. They aren’t.

The 20% that actually earns its keep

Honest list of when a background daemon does something a CLI or a 10-line bash cron can’t:

Scheduled work that has to happen when you’re not there. Crawl competitor sites at 3am. Pull last night’s Sentry errors. Summarize overnight industry chatter into a 7am brief. Your laptop is off, something has to be running somewhere. Legitimate.

Reactive triggers on external events.

Email arrives -> triage.

Substack comment -> draft reply.

Sentry alert -> diagnose + suggest fix.

The trigger comes from outside; compute has to meet it. Legitimate if the volume actually warrants automation (if you get three emails a day, triage is a solved problem — your inbox).

On-the-move capture.

Voice memo from your phone -> transcribed -> landed in memory.

Forwarding a link from your phone to your agent. The value is that capture happens when inspired, not when at desk. Real lift for content creators who have thoughts in elevators.

Judgment-laden monitoring.

Not “disk at 80%” — any shell script can do that. “Disk at 80% AND growing 2% per hour AND that’s unusual for this host.”

Requires context; needs to know what normal looks like. This is where LLMs in a daemon genuinely beat a threshold-based alerting stack.

That’s it. Four categories. Anything else is mostly burning tokens.

The 80% that’s noise

Heartbeats that ask the agent “anything to do?”

The agent wakes up, loads context, decides there isn’t anything to do, goes back to sleep. You pay for the loaded context every time. Over a day this adds up to real money for the privilege of watching an agent shrug.

Self-evolution loops.

“The agent improves itself while you sleep.” What it’s usually doing is refactoring its own prompts in circles. Cool demo on YouTube. Zero measurable outcome delta after a month of running.

Parallel subagent fan-out for research.

Ten agents search the web about the same question and return ten lightly-paraphrased versions of the same top three results. One focused 10-minute session beats this, almost always.

“Long-running overnight research tasks.”

When the output lands in your morning inbox, is it better than what 30 focused minutes at your desk would produce? Honestly check. Usually no.

Replacing things you could cron in 10 lines of bash.

The test: could a $5 VPS with a shell script + cron + jq do this? If yes, you’re not using AI for the part that needs AI. You’re using it because daemons are cool.

Receipts: what’s actually on my VM

I pulled the daemon’s state file and the log directory while writing this. Fifty-four days of uptime. Ten jobs on paper. The picture is worse than I thought.

Three are running reliably.

sentry-monitor has fired 191 times since early March. Latest run: this morning. When the night throws errors it reads them, groups them, and suggests a fix — not a link to the stack trace, an actual “here’s what’s probably wrong and here’s the one-line change.” Category 2 plus category 4. Keep.

infra-health has fired 190 times on basically the same cadence. Knows what normal looks like per host. Stays quiet when a disk spike is a scheduled backup and shouts when it isn’t. Category 4. The whole reason an LLM beats a thresholds-and-Prometheus stack here, and no, you cannot Grafana your way to this in under six months of tuning. Keep.

scout has fired 71 times across seven weeks. Daily-ish. Scans Reddit, HN, and Substack for signal that feeds this blog’s content calendar. I do use the output. Category 2 if I’m generous. Keep — but it absorbs the next two jobs on the list below.

Now the uncomfortable part.

Three of the ten have straight-up stopped running and I didn’t notice.

morning-brief was scheduled daily at 6am. It last fired on March 18. A full month of no overnight brief. I did not miss it. I did not investigate. I did not know.

seo-audit was weekly. It has run exactly once in the daemon’s entire fifty-four-day lifetime, on March 1. Seven missed weeks. Nobody wrote a bug report to themselves. Nobody opened a file that wasn’t there.

auto-draft was supposed to produce a draft post every day. It has run exactly once, on April 11. Eight days of silence. Also unnoticed.

If a job stopped running a month ago and you didn’t miss it, the job was never producing anything that mattered. That’s not my heuristic. That’s the audit, evaluating itself while I was busy talking about audits on Twitter.

Four more are in some stage of limping.

reddit-scan — 27 runs over 45 days, last one April 10. Running, sort of, when the mood takes it. Nine days of silence so far on that one.

x-scan — identical pattern to reddit-scan. Same overlap. Same drift. Same silence since April 10. These two were supposed to be complementary; they’ve turned out to be redundant and unreliable, which is a rare trick.

engagement-brief — four runs, total, in the job’s entire lifetime. Not daily. Not weekly. More like “occasionally, if the stars align.”

x-analytics — three runs, last one March 16. Effectively dead, which is fine, because I check my X numbers roughly once a month anyway.

Final tally, the honest one.

Three jobs firing on schedule, producing output I use. Three jobs that silently stopped weeks ago and nobody in this house noticed, including me. Four jobs wandering between “running” and “not really” with no clear reason why.

Three-of-ten is the optimistic read. The pessimistic read is that six of the ten audited themselves — they cut themselves by going quiet, and I hadn’t even done them the courtesy of looking.

This is from someone who builds daemons for a living and writes about them for a job. What do you think yours looks like under the hood?

The five-question self-test

Before you keep any always-on agent job, make it answer these:

1. Would I actually miss this if it stopped? If you turned it off for two weeks and no one noticed, it’s not producing value. It’s producing comfort.

2. Does the cadence match downstream consumption? A job that fires 4x/day for output you read weekly is 27 extra runs a week of pure overhead.

3. Is the trigger genuinely external? (Scheduled time, incoming event, captured input.) If the agent is just checking on itself, you’ve built a Roomba that vacuums an empty room.

4. Could a shell script + cron + jq do this? If yes, you’re not using AI for the part that needs AI.

5. Does the output change my behaviour? If yesterday’s run and last Thursday’s run would have produced the same action from me (or none), one of them was wasted.

Honest answers will cull your cron list by half. Mine certainly did, once I stopped writing this post and actually did the audit.

What this isn’t saying

I’m not arguing against always-on agents. I’m arguing against always-on agents that aren’t doing anything.

There’s real value when the conditions line up — work-while-you-sleep, external-trigger-response, on-the-move-capture, judgment-laden-monitoring. The reason I keep the daemon running (even after cutting half its jobs) is those four categories genuinely earn the monthly subscription. The reason I’m writing this is that the other six patterns — the ones that photograph well — are funding a lot of framework development and not much measurable outcome.

If your agent is doing category 1-4 work, the hype is warranted. If it’s doing category 5-6 work, you’re paying a subscription to a demo.

The uncomfortable question for most of the agent-community content right now is which category is the thing being demoed, really? And whether the person demoing it has done the five-question audit on their own cron list.

My guess: very few have. The demo economy doesn’t reward the audit. It rewards the screenshot of the agent waking up at 3am and pretending to be useful.

Claude is ignoring most of it.

There’s an arms race happening in the Claude Code community right now. Every week, someone posts their increasingly elaborate CLAUDE.md setup. 27-file architectures. Tiered loading systems. Router patterns with conditional context injection.

One developer split their CLAUDE.md into 27 files with a three-tier routing system. 360 upvotes. The post opens with: “My CLAUDE.md was ~800 lines. It worked until it didn’t. Rules for one context bled into another, edits had unpredictable side effects, and the model quietly ignored constraints buried 600 lines deep.”

The top comment, with 81 upvotes? “So not sure if you realised you can have descendant CLAUDE.md so you don’t even need to do this.”

Meanwhile, a developer in the same thread: “I don’t even use claude.md. Y’all are roleplaying being productive. Just work with it 1:1.”

One group is optimizing. The other is actually working.

The Research Says You’re Doing It Wrong

ETH Zurich researchers published a paper that should have made every CLAUDE.md maximalist uncomfortable. Their finding: context files — the .md files we all obsess over — tend to reduce task success rates compared to providing no repository context at all. And they increase inference cost by over 20%.

Read that again. No CLAUDE.md outperformed having one. On average.

When this paper hit Reddit, the poster titled it “No CLAUDE.md → baseline. Bad CLAUDE.md → worse. Good CLAUDE.md → better.” — an optimistic spin suggesting the file isn’t the problem, your writing is. The post got 209 upvotes. But the top comments immediately called it out: OP had misread the data. The actual finding was that having any .md file — human or LLM-written — led to worse performance than having none. The auto-generated thread summary confirmed it: “The consensus in this thread is that you’ve completely misread the paper.”

It gets worse. LLM-generated .md files hurt the most, because they just parrot back what’s already in the code. Human-written files showed a slight positive impact — but only when kept to an absolute minimum, and only for smaller models.

A separate benchmark of 1,188 runs across Haiku, Sonnet, and Opus confirmed this. Twelve coding tasks. Ten instruction profiles. The result: an empty CLAUDE.md scored best overall.

The researcher’s own correction was admirably blunt: “I was wrong about CLAUDE.md compression. Here’s what the data actually showed.”

You Have an Instruction Budget. You’re Blowing It.

Here’s the mechanism nobody talks about.

Frontier models reliably follow about 150 to 200 instructions before performance starts decaying. Not crashing — decaying. Every additional instruction slightly degrades compliance with every other instruction. The degradation is uniform. Your critical “NEVER delete the production database” rule gets weaker every time you add “prefer camelCase for variable names.”

Claude Code’s own system prompt already burns about 50 of those instruction slots. That’s before your CLAUDE.md even loads.

So you have roughly 100-150 instruction slots left. Your 800-line CLAUDE.md with coding conventions, style guides, architecture decisions, tool preferences, workflow rules, and team norms is trying to cram 400 instructions into 150 slots.

The model doesn’t crash. It just quietly starts ignoring things. Specifically, the things buried deepest in the file. Your most important rules — the ones you added after painful debugging sessions — are probably at the bottom. Which means they’re the first to get deprioritized.

Claude Is Designed to Ignore You

This is the part that should make you pause.

Claude Code’s system prompt includes this line about CLAUDE.md content:

“This context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant.”

Claude is literally instructed to deprioritize your instructions if they don’t seem relevant to the current task. The more task-specific content you stuff into CLAUDE.md, the more likely Claude treats the entire file as noise.

That database schema guidance? Irrelevant when Claude is working on frontend CSS. Those API naming conventions? Noise when it’s writing tests. Your elaborate deployment workflow? Invisible during a refactoring session.

Every irrelevant instruction trains Claude to ignore the relevant ones too.

The Context Window Tax

Here’s the math nobody does. Claude Code’s system prompt alone consumes roughly 23,000 tokens — about 11% of the 200K context window, gone before you type a word. Add your CLAUDE.md, your MCP tool schemas, skill descriptions, memory files, and rules. One developer measured 69,200 tokens of overhead — 35% of the context window consumed before a single user message. Others in the thread pushed back on that specific number, but the principle stands: every always-loaded instruction competes with working memory.

And it’s not just a cost problem. It’s an accuracy problem. The fuller the context window gets, the worse Claude performs — what Anthropic calls context rot. Your elaborate CLAUDE.md isn’t just burning tokens. It’s actively degrading the quality of every response.

The Leverage Problem

Here’s why this matters more than you think.

Bad code is localized. You write a buggy function, it breaks one feature. You fix it, you move on.

Bad CLAUDE.md instructions compound. A single misguided rule in your CLAUDE.md affects every research phase, every plan, every implementation, every session. One line that says “always use verbose error messages with full stack traces” produces thousands of lines of noisy code across your entire codebase, across every agent, across every session.

Your CLAUDE.md is the highest-leverage file in your repo. Most people treat it like a junk drawer.

What the Minimalists Actually Do

I went looking for people who run Claude Code with minimal or no CLAUDE.md. They’re out there. They’re quiet about it because “I don’t use CLAUDE.md” doesn’t get upvotes.

One developer on Reddit: “I use Claude Code bare bones professionally. It all sounds like bloat not giving real value.” Another: “I load no skills, no agents, no MCP Servers and rock it all day every day, 12 hours a day. Life is good.”

A developer who built a 13-agent orchestration system with 8,157 lines of markdown deleted 93% of it. His conclusion: “My enhancement layer was making Claude dumber by filling its brain with instructions about how to think, leaving less room for actual thinking.” After the deletion, Claude performed better on the same tasks.

Another developer with a 350-line CLAUDE.md and 20+ custom MCP tools put it simply: “It feels like the more context I add the more it struggles to get the job done. It seems to get ‘dumber’.”

And when someone asked the community to break down the meta on all the conflicting CLAUDE.md advice, the most honest reply got it right: “If ‘best practices’ are conflicting, it’s probably a sign of them mostly being a type of placebo on the part of the folks posting them. The human mind has a weird need to be the special one who cracked the code.”

The pattern is consistent: people who remove instructions report better results than people who add them.

Instructions Raise the Floor, Not the Ceiling

The benchmark data revealed something nuanced. Instructions don’t make Claude better on average. They make it more consistent.

On tasks where Claude already performs well, instructions add nothing. On tasks where Claude struggles, a focused workflow checklist gave Opus a +5.8 point lift and raised its worst-case score by 20+ points.

A 2,455-evaluation benchmark across Sonnet and Opus confirmed a related finding: the best-performing configuration was a short CLAUDE.md with pointers to skills that load on demand — not a massive monolith, not 27 modular files, but a minimal routing layer that tells Claude where to find context when it’s actually needed.

This changes everything about how you should think about CLAUDE.md.

Don’t use it to make Claude smarter. Use it to prevent Claude from being stupid in specific, known ways. The difference between those two goals is the difference between a 60-line file and an 800-line file.

What Actually Belongs in CLAUDE.md

After digging through research, benchmarks, and hundreds of Reddit threads, here’s what survives the cut:

The What-Why-How skeleton (under 60 lines):

• WHAT: Your stack, project structure, key directories

• WHY: What this project does and for whom

• HOW: Build commands, test commands, deploy commands

Negatives over positives:
“NEVER use X” sticks. “Always prefer Y” fades. If you can phrase it as a prohibition, it enforces better. “DO NOT modify the database schema without migration files” beats “Always create migrations when changing the schema.”

Trigger-action format:
“WHEN CI fails, DO NOT push until fixed” enforces consistently. “Always test before pushing” doesn’t. Specificity matters.

Pointers, not content:
Reference external docs instead of embedding them. “See agent_docs/database.md for schema guidance” loads on demand. Pasting the full schema into CLAUDE.md loads every single session, whether Claude needs it or not.

Subdirectory CLAUDE.md files:
Claude auto-loads CLAUDE.md from whatever directory it’s reading files in. Put backend rules in backend/CLAUDE.md. Put frontend rules in frontend/CLAUDE.md. Context-specific rules load only when contextually relevant.

What Doesn’t Belong

Style guides. Claude is an in-context learner. If your code follows consistent patterns, Claude will match them without being told. Use linters and formatters — they’re deterministic, fast, and don’t eat instruction budget.

LLM-generated instructions. The research is clear: auto-generated .md files hurt performance. Don’t use /init. Don’t ask Claude to write its own CLAUDE.md. The model just repeats what’s already in the code, wasting tokens to tell itself what it already knows.

Lessons learned logs. Once the lesson is codified in the codebase itself — as a test, a lint rule, a hook — the .md entry is redundant. Delete it.

Persona assignments. “You are a meticulous senior engineer who always…” is a costume, not a capability. As one developer running overnight cron agents put it: “A syntax check that returns exit code 1 on failure > 2,000 words of ‘you are a meticulous senior engineer who always…’” The agents with minimal instructions consistently outperformed the ones with elaborate persona prompts.

The Real Best Practice

Keep your CLAUDE.md under 100 lines. Ideally under 60. Put the most important rules at the top. Phrase them as negatives. Use trigger-action format. Point to external docs instead of embedding content.

Then stop optimizing and go build something.

The developers shipping the most code aren’t the ones with the fanciest CLAUDE.md architectures. They’re the ones who figured out the minimum viable instructions and moved on to the actual work.

Your CLAUDE.md is not your product. Stop treating it like one.

I’d started x-intel as a SuperX clone — essentially a better analytics dashboard for X. Charts, follower graphs, engagement breakdowns, competitor tracking. The kind of thing where you look at a number, decide you feel bad about it, and close the tab.

And then I was chatting with Claude about the onboarding flow, and I said something like: “when I say onboarding, I mean the app gets my context and goals, then charts a strategy, periodically reviews it, and course corrects.”

Claude’s response stopped me: “That’s a fundamentally different product. Less ‘setup wizard’, more ‘AI strategist that lives in your X account.’“

I stared at that for a while. Then I realized I’d been building the audit view and calling it the product.

The dashboard isn’t the product. The dashboard is what humans look at after the AI already figured out what’s happening.

Build the MCP server first. The dashboard ships itself.

The problem is everyone’s still building it the other way.

What Everyone Is Still Building

Claude Code exists. The MCP protocol exists. Power users are already interacting with SaaS products through AI agents — not because you built that integration, but because they built it themselves using whatever API you exposed. They’re writing CLAUDE.md files that say “use the Stacksweller API to schedule posts” and just… doing it.

This is happening whether you designed for it or not.

The default SaaS in 2026 still ships dashboard-first: database → API → React. Users log in, stare at charts, try to draw conclusions. That model made sense when the only consumer of your product was a human looking at a screen.

That is no longer the only consumer of your product.

You can either build for this intentionally, or have it happen to you messily and then spend six months retrofitting.

The Reframe

Here’s what x-intel actually looks like when you build it right:

Intake — Claude asks who you are, what your niche is, what your X goals are, who your competitors are. You answer in plain English. Claude turns that into a structured profile using the set_profile tool.

Baseline — Claude pulls your current stats, analyzes your last 90 tweets, benchmarks against competitors. All MCP tools calling your data layer. No UI step required.

Strategy — Claude generates a content and growth plan: post frequency, best times, content formats, topics to lean into. Stored back in your database via MCP. The strategy exists before you’ve opened a browser.

Periodic review — A cron job runs weekly analysis, compares performance against the strategy, surfaces what’s working and what isn’t. Claude writes a summary. The dashboard shows that summary.

Course correction — Strategy updates based on data. Again, through tools. Again, before a human looks at anything.

The dashboard in this architecture isn’t the product. It’s an audit log. It shows you what Claude already figured out. Charts are passive — you still have to decide what to do. This tells you what to do, and then does it.

That’s a completely different product. “X-intel is your AI X strategist. Tell it your goals once. It watches your account, tracks competitors, and tells you exactly what to do next.”

That pitch destroys “SuperX but self-hosted.”

How to Actually Build MCP-First

The mechanics are simpler than they sound. Embarrassingly so.

Start by designing your tools for Claude, not for humans. Think about what Claude needs to do the job — not what a human wants to click on. Tool names, parameter shapes, return values should make sense to a language model. get_competitor_engagement_trend(handle, days=30) is better than getChartData(config). One of these tells Claude what it’s getting. The other makes Claude guess.

Here’s the part nobody mentions: if you have a data layer, you have an MCP server 70% built already. Wrap your existing queries as tools. The MCP protocol is just a contract — your database doesn’t move.

You don’t need to build an “AI feature.” You need a system prompt that gives Claude the right context, and tools that give it the right data. Claude is the strategist. Your MCP server is the strategist’s interface to your product. The actual work is thinking clearly about what Claude needs to know — not engineering.

Build the dashboard last, or thin. It’s a view layer. It shows stored strategies, weekly reviews, flagged anomalies. A log of decisions that were already made. Not a decision-support tool.

One Build, Two Audiences

Here’s the payoff that makes this worth doing even if you don’t care about being “AI-native.”

A well-designed MCP server makes your product useful to two completely different types of users with almost no additional work.

The first type opens the dashboard, reads the weekly strategy review, clicks to approve the suggested changes, and closes the tab. Normal SaaS behavior. They don’t know or care that Claude is behind it. They just want outcomes.

The second type connects your MCP server to their own Claude Code setup, writes a CLAUDE.md that describes how they want to use your product, and runs it themselves. These are your power users. They’ll do things with your product you never imagined, and they’ll tell everyone.

You still need the dashboard. Trials convert better with a UI. Not arguing otherwise. But the order matters: MCP layer first, dashboard second. The dashboard snaps on top in a weekend once the tools are solid. The reverse — retrofitting agent-friendly APIs onto a human-optimized interface — takes six months and still feels wrong.

Both audiences are real. Both are valuable. You get both by building the MCP layer correctly from the start, instead of bolting on an “AI integration” later when it’s expensive and awkward.

The dashboard-first founders will get there eventually. They’ll build the dashboard, grow slowly, and then spend six months retrofitting an API that was designed for human consumption into something an agent can actually use.

Or you build the MCP server first, ship a thin dashboard on top, and have both audiences from day one.

The dashboard ships itself. The strategist is Claude. The product is the tools you give it.

Stop building audit logs and calling them products.

Not debugging a rate limiter. Not implementing one. Arguing. I had typed “add a usage limit to the free tier” and gotten back something that technically worked — it counted things and stopped you when you hit the limit — but was also completely wrong in about six different ways that I hadn’t specified because I hadn’t thought to specify them.

When does the counter reset? Daily? Monthly? On the billing cycle? What counts as a usage event — an API call, a feature access, a row stored? What happens at exactly 100%: hard block, soft warning, grace period where we beg you to upgrade? Do existing free users get grandfathered, or do they wake up tomorrow blocked from the thing they’ve been using for three months? What if someone hits the limit mid-checkout?

I hadn’t answered any of those questions. I had typed eight words and expected a computer to answer them for me. And the computer, being a computer (a very impressive one, but still a computer), had silently picked answers that seemed reasonable. UTC midnight resets. Hard blocks. No grandfathering.

Nobody wants UTC midnight resets. Nobody wants a hard block in the middle of checkout. And nobody, including me, had thought to say so.

That forty-minute argument was, in the precise technical sense, programming. Not in the syntax sense. In the real sense: figuring out exactly what I wanted the computer to do, in enough detail that it could actually do it.

Which brings me to Grace Hopper, and why the current panic about AI replacing developers is about sixty-five years old.

In 1959, Grace Hopper helped create a programming language called COBOL.

Common Business-Oriented Language. The name is the pitch. This isn’t for programmers — it’s for business people. The syntax looked like a business memo. You wrote ADD SALESTAX TO TOTALPRICE GIVING INVOICE-TOTAL. Sentences. Paragraphs. English words that a manager could theoretically read and understand and maybe, just maybe, write.

The promise was explicit: if the language is human enough, we won’t need programmers as intermediaries. Business users could specify their own software. The bottleneck — translating business requirements into code — would evaporate.

You know how this ends. COBOL created more programmer jobs than almost any technology before or since. Banks ran it for sixty years. Governments still run it. The programmer shortage it was supposed to prevent became one of the most persistent gaps in technology. The job postings for COBOL developers today — today, in 2026 — pay embarrassingly well because the people who understand those systems are retiring and there aren’t enough people to replace them.

The promise evaporated. The programmers did not.

Now, the obvious response here is: that was 1959. We were trying to replace programmers with verbose English-looking syntax. That’s completely different from vibe coding, which uses actual English, processed by a large language model that has ingested most of human knowledge. The comparison is unfair.

Fair enough. Let me make it fair.

After COBOL came 4th generation languages — the 70s and 80s promised that business users could generate reports and query databases without programmers. And they could! Until anything got complex, at which point someone had to specify what “complex” meant. That someone was, increasingly, a programmer with a different job title.

Then HyperCard in 1987. Anyone could build interactive applications — stacks, cards, buttons, scripts. And many people did! Wonderful things. And then the moment you wanted it to do something non-trivial, you needed to understand enough about conditional logic and data structures that you were, functionally, programming. The interface was friendlier. The underlying activity was identical.

Then no-code in the 2010s. Citizen developers. Visual workflows. Drag-and-drop databases. I watched three different companies I worked at try to use no-code platforms to “reduce dependency on engineering.” It reduced dependency on engineering the same way COBOL did: by creating a new class of technical specialists (now called “no-code developers” or “operations engineers”) who spent their days fighting with visual tools that couldn’t quite express what they needed to express.

Same experiment, sixty-five years, same result. Better interface, same bottleneck.

Here’s what I think is actually happening, and a comment on a Hacker News thread about agentic engineering said it more precisely than I can:

“When you get down to breaking down that problem… you become a programmer.”

The average person doesn’t know what their actual problems are in sufficient detail to get a working solution. Not because they’re not smart. Because the act of breaking a problem down into precisely specified steps that a computer can execute without ambiguity is programming — regardless of whether the syntax is COMPUTE TAX = PRICE * RATE or def calculate_tax(price, rate): return price * tax or “hey, write me something that calculates tax.”

The specification is the programming. The syntax is just notation.

Vibe coding is genuinely different from COBOL in one important sense: the interface change is more dramatic. Natural language processed by a model that can write working TypeScript from a vague description is qualitatively new. The gap between “what you type” and “what runs” has never been smaller.

But the gap between “what you type” and “what you actually wanted” is exactly as large as it’s always been. Possibly larger, because the tool is so capable that it confidently fills in every unspecified detail, silently, in ways that seem reasonable until they’re not.

My rate limiter reset at UTC midnight because I didn’t say it shouldn’t. The agent wasn’t wrong. I was underspecified.

What vibe coding has genuinely changed: the syntax, the boilerplate, the standard implementations of standard patterns are now basically free. A solo developer with Claude Code can ship in a week what used to take a team a month. That’s real leverage and I use it every day.

What hasn’t changed: the irreducible core of the job — figuring out with enough precision what you want the computer to do — is still entirely human work. And based on sixty-five years of running this experiment, there’s a reasonable argument that it’s definitionally human work. When you get specific enough about a problem to get a working solution, you’ve already done the programmer’s job. You might be doing it in plain English now instead of Python. You’re still doing it.

The developer job is changing. Less time on syntax, more time on the thinking that was always the hard part. More time arguing with your tools about exactly what you meant. More time specifying the edge cases before the tool invents its own.

If you’ve ever wanted to spend less time fighting TypeScript compiler errors and more time actually thinking about what you’re building — genuinely, that part is better now.

But the thinking is still yours.

The programmers are still here. They’ve been here since 1959. They’ll be here after vibe coding. They just keep getting better tools.

Learn from the evidence. It’s sixty-five years old and it’s not subtle.

This founder had designed a custom lamp. Spent months prototyping. Found a factory in Shenzhen. Shipped 500 units.

When the boxes arrived, the light-entry holes had been used as casting pour-points — the factory needed somewhere to pour the material, saw the holes, and went with it. The cable tails were two centimeters instead of ten. The knobs didn’t fit because the powder coating added thickness that nobody put in the spec. Everything technically matched the purchase order. Nothing actually worked.

I read that post-mortem three times. Then I read the top comment, which was one of those sentences that you immediately screenshot because it’s just too true:

“Anything you don’t specify will be done at minimum cost.”

I put my phone down. I looked at the ceiling. And then I thought about the email sender I’d had Claude Code generate that afternoon.

Let me tell you what I had asked for: “Send a welcome email to new users when they sign up.”

Let me tell you what I got: A function that sent emails. Technically correct. It looped over every new user and called the email API synchronously, one by one, waiting for each response before moving to the next. No rate limiting. No retry logic. No unsubscribe link — because I didn’t ask for one, and CAN-SPAM compliance wasn’t in the prompt. When I ran it against a list of 8,000 users, it fired all 8,000 requests in a tight loop, Gmail flagged the sending domain as a spam source within six hours, and my domain was blacklisted before I’d finished my coffee.

Everything sent. Nothing arrived.

I had been vibe coding with Claude Code for six months at that point, and I thought I was pretty good at it. I could get it to build things fast. I could chain prompts together. I had CLAUDE.md files and hooks and all the trappings of someone who knew what they were doing.

What I didn’t understand — what the Hacker News post-mortem forced me to understand — is that I had completely misidentified what kind of relationship I was in.

I thought I was pair programming with a senior engineer.

I was issuing purchase orders to a factory.

This distinction sounds philosophical. It isn’t. It has concrete, expensive implications for every vibe coding prompt you write.

A senior engineer fills gaps with judgment. If you say “build auth,” a good senior engineer asks: what are the scale requirements? What’s the threat model? Are we storing PII? They fill the spec gaps with professional standards because they have skin in the game — it’s their name on the code, their reputation on the line, their on-call rotation if it breaks at 3am.

A factory fills gaps with cost optimization. If the spec doesn’t say “cable tails must be 10cm,” the factory cuts them at 2cm. Not because they’re malicious. Because that’s 8cm of wire per unit times 500 units and someone’s margin depends on it. They’re perfectly rational. They’re just optimizing for something that has nothing to do with whether your lamp works.

Claude optimizes for “satisfies the prompt.” That’s the whole job. Your vague prompt is its permission to take shortcuts, and it will take them — not maliciously, but with the same rational efficiency as a factory floor supervisor who notices you didn’t specify the minimum acceptable wire gauge.

Here’s the thing about the hardware community that I find both humbling and enraging: they figured this out decades ago. They built an entire profession around it. These people are called sourcing agents, and their whole job is translating “I want a nice lamp” into a 47-page document covering material density, wire gauge, coating thickness, packaging dimensions, UV stability ratings, and what happens to the tooling if the order falls below minimum quantity.

Forty-seven pages. For a lamp.

In vibe coding, the sourcing agent is you. Most developers have been accidentally promoted to this role without realizing it. They’re still acting like they’re talking to a colleague. They’re actually running a factory and they’re skipping the quality control, the detailed specs, and the first-article inspection — all the boring stuff that hardware people do automatically because they’ve shipped enough garbage to know better.

I’ve started reading Hacker News manufacturing posts specifically to steal their frameworks for this. A few things that have genuinely changed how I write prompts:

Spec your constraints, not just your features. “Send welcome emails” is a feature request. “Send welcome emails via SES, rate-limited to 14 per second to stay under AWS sending limits, with exponential backoff and a max of 3 retries on failure, an unsubscribe link in the footer per CAN-SPAM, a plain-text fallback alongside the HTML version, and a hard skip for any address that has previously bounced or complained” is a spec. The difference isn’t intelligence — it’s the same way specifying wire gauge isn’t about distrusting your factory. It’s about understanding that factories don’t have opinions about wire gauge. They have margins.

Inspect the first batch before commissioning the full run. Hardware founders don’t ship the first production run to customers. They order samples. They measure every dimension with calipers. The good ones fly to Shenzhen and stand on the factory floor. The developer equivalent is reading the first 200 lines of generated code before asking Claude to build the next feature on top of it. Check the database schema before building the API on top of it. Read the auth flow before adding the permissions layer. This feels slow. It is much faster than discovering that the foundation is wrong after you’ve built four floors.

Specify what you don’t want. This one surprised me. Experienced sourcing agents reportedly spend half their spec document on exclusions. “No recycled plastic in structural components.” “No substituted components without written approval.” “No unlicensed firmware.” They’ve learned that a factory will always find the interpretation of the spec that costs them the least, so you have to close the doors. For prompts: “No inline styles. No TypeScript any types. No console.log for error handling. No SELECT * queries. No external dependencies unless they’re in the approved list.” The AI will not volunteer that it’s about to do these things. It will do them and move on.

Budget time for the spec, not just the build. Hardware founders allocate somewhere between 30-40% of their project timeline to specification work. The manufacturing part — the actual production — is the smaller slice. Vibe coders typically invert this. Five percent on the prompt, ninety-five percent on generating code and then debugging the surprising things that came out of a vague prompt. The debugging is expensive. The spec is cheap.

The thing I keep coming back to is that using Chinese manufacturers is incredible leverage. You can build a physical product without owning a factory, without specialized tooling knowledge, without decades of manufacturing experience. It’s genuinely one of the great unlocks of the modern economy. And it works — when you write the spec correctly.

Using Claude to write code is the same kind of leverage. You can build things without knowing every library, without remembering every API, without holding the entire codebase in your head at once. It works. When you treat it like what it is.

Your prompt is a manufacturing spec. The code is the factory output. The factory will be rational, efficient, and completely indifferent to whether your product actually works.

Write the spec accordingly.

Or enjoy your two-centimeter cable tails.

The problem isn’t your code. The problem is that Claude doesn’t know when to call your tools, so it doesn’t.

This is the thing nobody tells you when you’re learning MCP: the hardest part isn’t building the server. It’s making Claude reach for it.

How Claude Actually Chooses Your Tool

When you ask Claude to do something, it’s doing a matching problem. It looks at what you asked, scans the tools available to it, reads their descriptions, and decides which one — if any — fits.

That last part is the lever most developers ignore. Claude doesn’t run your code to figure out what your tool does. It reads the description you wrote and makes a judgment call. If your description is vague, generic, or poorly matched to the language your users actually use, Claude will skip your tool and try something else. Or just tell you it can’t do the thing.

Here’s a real example. Compare these two tool descriptions for the same function:

Bad: “Query the database.”

Good: “Look up a customer’s order history, subscription status, and recent activity by email address or customer ID. Use this when someone asks about a specific customer’s account.”

The first one is technically accurate. The second one is what Claude can actually match against. “What’s going on with john@example.com‘s account?” maps cleanly to the second description. It maps to nothing in the first.

Your tool description is a search index. Write it like one.

The Five Ways MCP Servers Die

1. Bad descriptions. Already covered, but it bears repeating because it’s the most common failure. Every tool, resource, and prompt deserves a description that answers: when should Claude reach for this? Include the kinds of questions or requests that should trigger it. Use the words your users actually use.

2. Too many tools. There’s a temptation to expose everything. Every database table. Every API endpoint. Every configuration option. Resist it. A server with 30 tools is a server Claude gets confused by — and it’s also a server that quietly eats your context window before you’ve typed a word (more on that problem here). It can’t reliably choose the right tool when there are 30 candidates with overlapping descriptions. The best MCP servers do one thing, maybe two, exceptionally well. If you find yourself adding a tenth tool, ask whether you’re building a server or a dumping ground.

3. Output Claude can’t reason about. Tools that return raw JSON blobs, HTML, or binary data are tools Claude struggles to use. Claude works in text. If your tool returns {"data": [{"id": 1, "val": "foo"}, ...]}, Claude has to parse that before it can think about it. If your tool returns “Found 3 orders: Order #1001 (shipped Jan 15), Order #1002 (pending), Order #1003 (refunded)”, Claude can work with that directly. Format your output for a reader, not a parser.

4. Uninstallable. Most MCP servers have no README. No install instructions. No example config. No explanation of what environment variables they need. Even if someone finds your server on GitHub, if they can’t get it running in ten minutes, they close the tab. You will never hear from them again. Distribution is half the product.

5. Solving a problem only you have. This one is uncomfortable because it’s often true. The research tool you built for your specific workflow, against your specific internal data structure, with your specific edge cases handled — it’s not a product, it’s a script. That’s fine. But don’t confuse it for something others will install. The MCP servers that spread are the ones that solve problems many developers have, in a way that requires no customization to be useful out of the box.

What Actually Works

The servers that get used share a few traits.

They have narrow scope with deep utility. Not “do 20 things mediocrely” but “do one thing so well you’d miss it if it was gone.” A good example: a server that searches Hacker News. One tool, one job — search HN, return results with scores and comment counts, formatted so Claude can reason about it immediately. That’s enough. That’s a server people actually keep installed.

They treat descriptions as product copy. Not documentation — copy. The description is the first thing Claude reads and the primary factor in whether your tool gets called. Write it for Claude the way you’d write an app store listing: what does this do, when do you need it, what does success look like.

They fail gracefully and informatively. When something goes wrong, a good tool returns “No results found for ‘X’. Try a broader search term.” A bad tool raises an exception. Claude can work with the first one. It can only apologize for the second.

They’re easy to install. One command. One config block. Clear documentation for what environment variables are needed and what they do. If setup takes more than five minutes, most people won’t finish.

The Gap This Creates

Right now, MCP is early. Most servers are weekend experiments. The production-quality servers — narrow scope, excellent descriptions, graceful error handling, easy installation — are rare.

That gap is an opportunity. A well-built MCP server that solves a real developer problem and is easy to install can spread through Claude Code users the same way good VS Code extensions did: by word of mouth, by being genuinely useful, by being the thing you’d mention in a conversation when someone complains about the problem you solved.

The window isn’t permanent. In six months, there will be a lot more competition. Right now, the bar is low enough that “works reliably and has a clear description” puts you in the top 10%.

That’s what I’m writing about in the MCP Cookbook — a practical guide to building production MCP servers for Claude Code. Not how to write an MCP server; the official docs cover that. How to write one that people actually use.

His first rule: don’t use this in its first weeks.

I used it in its first week.

Why I Couldn’t Wait

I work across four projects solo. SaaS products, open source tools, content — the usual indie dev plate-spinning. Every Claude Code session I run is one session I’m not running somewhere else. The promise of parallel agents shipping code while I context-switch between projects was too compelling to resist.

So I installed Gas Town, added my projects as “rigs,” groomed six tasks into “beads,” and spawned six workers simultaneously.

My M2 MacBook responded by becoming a space heater that couldn’t render a terminal.

What Gas Town Actually Is

Before I explain what went wrong, let me translate the concepts. Gas Town uses Mad Max-inspired naming, which is either charming or maddening depending on your patience.

Town — Your workspace root (~/gt/). Think of it as the factory floor where everything lives.

Rig — A project container. Each of your repos becomes a rig inside the town. Not a git clone itself, but a wrapper that manages clones, worktrees, and workers for that project.

Beads — A git-backed issue tracker, also built by Steve. Every task, bug, or feature is a “bead” with a unique ID like supabyoi-9ue. They live in your repo’s .beads/ directory, committed alongside your code. Dependencies between beads create a task graph. I wrote about why this matters — AI agents lose all context when sessions end. Beads solve this by making work persist in git. This is the piece that genuinely works well.

Mayor — The global coordinator agent. You talk to the mayor, the mayor dispatches work. It sits above all rigs and orchestrates across projects.

Polecat — An ephemeral worker agent. Gets spawned with a task, works in its own git worktree, signals completion, gets cleaned up. The grunt labor.

Witness — Per-rig monitor that watches polecats. Detects stuck workers, nudges them, handles cleanup.

Deacon — Town-level watchdog that patrols all rigs. Monitors witnesses, refineries, everything.

Refinery — Per-rig merge queue processor. When a polecat finishes, the refinery handles the PR/merge workflow.

Convoy — Batch tracker for related work. Group six beads into a convoy, dispatch them, track progress as a unit.

Molecules — Reusable workflow templates. Formula defines the pattern, molecule is the running instance.

That’s ten concepts before you write a line of code. Steve’s mental model is a steam engine: agents are pistons, work flows through hooks, everything runs on the “Propulsion Principle” — if you find work on your hook, you execute immediately.

The architecture borrows from Erlang’s supervisor trees(I think) — a pattern from telecom systems where processes are organized in a hierarchy. Each parent monitors its children: if a child crashes, the parent restarts it. In Gas Town, the Deacon watches Witnesses, Witnesses watch Polecats, and failures cascade upward. This is a proven pattern that runs phone switches serving millions of calls. The catch: Erlang processes are lightweight (microseconds to spawn, kilobytes of memory). Claude Code sessions are heavy (seconds to spawn, gigabytes of memory). When each “process” is a full AI session burning tokens, the economics of cheap failure recovery invert.

What Actually Happened

Week One: The Learning Curve

The first session was pure orientation. I needed Claude to explain Gas Town to me while inside Gas Town. The cognitive overhead of mapping “polecat” to “worker” and “rig” to “project” consumed real mental energy that should have gone to actual work.

The 80/20 path is supposed to be:

gt up          # Boot everything
gt mayor attach  # Talk to the mayor

In practice, gt up failed because the bd (beads daemon) version check timed out. This led me down a rabbit hole patching the version comparison in Go — changing time.Equal() to time.Unix() because JSON serialization was losing nanosecond precision. I was debugging the orchestrator instead of using it.

Week Two: Six Polecats and a Space Heater

Once things stabilized, I got ambitious. Six beads groomed, six polecats spawned:

gt sling supabyoi-9ue supabyoi
gt sling supabyoi-abc supabyoi
# ... four more

Each polecat is a full Claude Code session in its own tmux pane with its own git worktree. Six of those plus a mayor, witnesses, refineries, deacons, and multiple bd daemons meant my M2 was running 20+ processes competing for resources.

The system didn’t crash. It degraded. Commands took minutes to respond. Shell execution broke mid-session. I had to kill processes manually and nuke the setup.

But here’s the thing — that wasn’t entirely Gas Town’s fault. Six concurrent Claude sessions will hammer any laptop. The real issue was that Gas Town spawned orphaned daemon processes that accumulated across restarts. I found six bd daemons running simultaneously, plus stuck bd mol burn processes from days ago that never cleaned up.

The Doctor Loop

Gas Town has a gt doctor command — a health check that reports errors and warnings. I ran it constantly.

First run: 1 error, 11 warnings. After gt doctor --fix: 4 fixed, 7 remaining. After restart: new errors. After bd daemon restart: timeout errors. After updating bd from v0.47.0 to v0.47.2: different errors.

Each fix revealed the next problem. The mayor’s CLAUDE.md was 280 lines (should be under 30). Environment variables from dead sessions broke prefix routing. Beads databases pointed to wrong paths. Symlinks needed codesigning to avoid macOS killing the binary.

It felt less like using a tool and more like being a system administrator for a tool.

What Genuinely Works

Beads: The git-backed issue tracker is solid. Creating tasks, tracking dependencies, finding ready work — this layer does its job. It survived every crash and restart because it’s just files in git. Steve built Beads as a standalone tool before Gas Town, and it’s the strongest foundation in the stack.

Worktree isolation: Each worker gets its own git worktree. No merge conflicts between parallel work. Clean separation. This is the right primitive.

The hub/worker model: Having a coordinator dispatch tasks to isolated workers is correct. The mental model of “groom beads, dispatch to workers, merge results” is sound.

gt doctor: Despite the loop, having a comprehensive health check that can auto-fix common issues is genuinely useful infrastructure.

What Doesn’t Work Yet

Daemon management: Orphaned processes are the #1 pain. bd daemons accumulate, stuck processes never clean up, version checks timeout. This is being fixed — v0.5.0 added process group killing — but it was brutal in weeks one and two.

The naming: I’m not trying to be uncharitable. But “polecat” adds zero information over “worker.” “Molecule” adds confusion over “workflow.” Every conversation about Gas Town requires a glossary. When a Hacker News commenter pointed out the irony — Steve Yegge wrote “Execution in the Kingdom of Nouns” mocking over-abstraction — it stung because it’s accurate.

Human as dispatcher: This is the core limitation. Despite all the automation, the mayor waits for you. Issue #694 on GitHub tracks exactly this: “Mayor lacks automated dispatch patrol molecule.” Community members built external cron scripts to poke the system. That tells you everything.

Cost and resource usage: Multiple reports of $100/hour token burn rates. DoltHub’s field test found none of the PRs were good enough to merge. The economics only work if the agents produce mergeable code reliably.

What I’m Building Instead

Gas Town taught me what I need. It also taught me what I don’t.

I wrote about why I’m building my own agent orchestrator. It’s called wt. The core idea: keep the infrastructure that works (beads, worktrees, tmux), strip the ceremony that doesn’t (polecats, molecules, deacons, refineries).

Where Gas Town has ten concepts, wt has three: hub, worker, task. That’s it.

The hub coordinates. Workers execute in isolated worktrees. Tasks are beads with dependencies. No mail system, no witness layer, no convoy abstraction. If a worker finishes, the hub sees it in the dashboard. If a worker gets stuck, you look at the terminal. No intermediate monitoring agent needed.

The key difference: wt is a pluggable orchestrator. Each project gets its own config — yolo mode for prototypes (no tests, auto-merge, maximum speed), strict mode for production code (tests required, PR review, quality gates), or anything in between. Gas Town is one-size-fits-all. Real projects aren’t.

It’s early. But two weeks of wrestling Gas Town gave me the blueprint for what comes next.

What I’m Taking Away

Gas Town is a research prototype that got released into the wild. Steve warned people. I didn’t listen.

But I don’t regret it. Two weeks of wrestling gave me clarity about what agent orchestration actually needs:

1. Beads (or equivalent) is non-negotiable. Git-backed task tracking with dependencies is the foundation. Without it, agents have no memory across sessions.

2. Worktree isolation is the right primitive. One agent, one worktree, no conflicts. Simple and correct.

3. The hub/worker model works — if the hub is smart. The dispatcher problem is the real unsolved challenge. Manual dispatch defeats the purpose.

4. Simplicity beats power. Three concepts (hub, worker, task) cover 90% of the use cases. Ten concepts with Mad Max names cover 95% but cost you 5x the cognitive overhead.

5. Your laptop has limits. Two to three concurrent workers is practical on a MacBook. Six is aspirational. Twenty is a data center problem.

Steve Yegge is doing genuinely new work here. Nobody else has shipped a multi-agent orchestrator for Claude Code with this level of ambition. The HN comment that stuck with me: “Gas Town is cackling mad laughter from someone both insane and prescient simultaneously. Today it’s insane. But expect serious versions in the future informed by these early experiments.”

I broke the first rule. I’d do it again. Just maybe with fewer polecats next time.

The metaphor runs through the whole thing: you’re not a line cook anymore, you’re orchestrating AI sous chefs, directing the kitchen, tasting every dish before it goes out. The developer-as-implementer era is over. Welcome to developer-as-orchestrator.

The Biryani Incident

It’s a good metaphor. I buy it. But here’s the thing about being a head chef that the metaphor doesn’t quite capture: a head chef without mise en place is just a guy having a panic attack near hot surfaces.

I know this because I’ve been that guy. Literally.

My wife had to leave town for a few days. “I’ll handle dinner,” I said, with the confidence of someone who has watched many cooking videos and successfully boiled pasta multiple times. I decided to make veg biryani — a dish my wife makes effortlessly, layering rice and vegetables and spices into something that tastes like it required more effort than it actually did.

“Prep everything first,” she told me before leaving. “Soak the basmati rice. Marinate the paneer. Chop the vegetables for layering. Have it all ready before you start cooking.”

Reader, I did not do this.

I started frying onions. While the onions were going, I realized I hadn’t marinated the paneer. So I started cubing paneer and mixing yogurt and spices. Then the onions started burning. I ran back, stirred frantically, ran back to the paneer. Remembered I needed to soak the basmati. Started the rice soaking. The onions were now definitely burned. I scraped them out, started over, but now I was behind, so I tried to do the vegetables and the new onions simultaneously while the paneer sat half-marinated…

An hour later I had a kitchen that looked like a crime scene, three pans with various stages of failure in them, and something that was technically edible but bore no resemblance to biryani. My wife, via video call, watched me plate this disaster with the expression of someone who had specifically warned against this exact outcome.

The problem wasn’t skill. I can cook. The problem was that prep and execution were bleeding into each other. I was trying to figure out what I needed while also doing the thing. And it turns out you can’t actually do both. Not well, anyway.

I’ve been that guy with AI sous chefs too.

I’ve been vibe coding since mid-2025. By “vibe coding” I mean the thing where you describe what you want in natural language and an AI writes the code. You know, the future we were promised, except the future has some sharp edges nobody mentioned in the demos.

Two SaaS products. Real users. Real revenue. Not toy projects, not “look ma I generated a todo app” tutorials, not the kind of thing you show off on Twitter and then quietly delete three weeks later. Actual products that people pay actual money for.

So when I tell you what follows, understand: this isn’t theory. This is what I learned by shipping real things and watching everything that could go wrong go wrong.

The Markdown Hemorrhage

For the first few months, I was that chef.

I’d sit down to implement a feature. Claude and I would get rolling. Then I’d notice a bug. Well, I’m already here, might as well fix the bug. Then while fixing the bug, I’d realize the error handling was inconsistent. Better clean that up. Oh, and there’s still context left in the window — might as well tackle that other feature I’ve been meaning to add.

Two hours later: three half-finished things, Claude confused about which task we’re actually doing, and code quality somewhere between “works” and “I’m not sure why.”

And the markdown. God, the markdown.

Claude, bless its heart, wanted to help me remember things. So it started creating files. ARCHITECTURE.md. DECISIONS.md. IMPLEMENTATION_NOTES.md. TODO.md. CONTEXT.md. CHANGELOG.md. README_UPDATED.md.

I call this markdown hemorrhage. The AI equivalent of a kitchen where every surface is covered with prep bowls, half-chopped vegetables, and sticky notes that say “DON’T FORGET THE SAUCE” — technically documentation, practically chaos.

At one point I had so many markdown files that I needed another AI tool just to search through the documentation I’d created for my AI tool.

This was clearly insane.

But here’s the thing that took me embarrassingly long to figure out: the problem wasn’t the tools. The problem was me.

One Goal Per Session

I was treating every Claude session like a buffet.

You know how it goes. You sit down to implement a feature. While you’re implementing, you notice a bug. Well, you’re already here, might as well fix the bug. Oh, and while fixing the bug, you realize the error handling is inconsistent across the codebase. Better clean that up too. And hey, there’s still context left in the window — might as well tackle that other feature you’ve been meaning to add.

Two hours later, you’ve got three half-finished things, Claude is confused about which task it’s actually working on, and the code quality has degraded to “works but I’m not sure why.”

I call this context pollution. And once I named it, I started seeing it everywhere.

LLMs are bad at juggling multiple goals. This isn’t a Claude problem — it’s a fundamental thing about how these models work. When you ask them to hold multiple objectives simultaneously, they get worse at all of them. Not a little worse. Dramatically worse.

The fix sounds almost stupidly simple: one goal per session.

That’s it. That’s the whole trick. One goal. One session. If you discover a bug while implementing a feature, you write down the bug and you close the session. The bug gets its own session later. No “while I’m here” detours. No context pollution.

“But what about efficiency?” I hear you asking. “Isn’t it wasteful to end a session when there’s still context left?”

This is the trap. This is exactly the thinking that leads to burned onions and half-marinated paneer. The leftover context is not an asset. It’s a liability. It’s your coworker with three tasks open, doing all of them poorly, about to forget everything anyway.

End the session. Start fresh. One goal.

The Mise en Place

Now, this discipline only works if you have a way to track what you’re not doing.

If you end a session every time you discover a bug, you need somewhere for that bug to live. Otherwise you’ll forget it. The bugs pile up in your head, you context-switch mentally, and you’re back where you started.

This is where beads comes in.

Beads is a git-backed issue tracker that Claude can read and write. Steve Yegge built it (yes, that Steve Yegge — the guy who wrote the platforms rant and approximately nine million words about Emacs). The idea is simple: every task becomes a “bead.” Claude creates them, updates them, closes them. They survive compaction. They sync through git.

I installed it. I ran bd init. And then something clicked.

See, beads isn’t just a todo list. It’s a forcing function. When you start a session, you run bd ready and it shows you what’s available to work on. You pick one. Not three. One.

And when you discover a bug mid-session? You tell Claude to create a bead for it. Claude writes it down, logs the context, notes any relevant details. Then you move on. The bug exists now. It has a home. You don’t have to hold it in your head.

The discipline and the tool reinforce each other. One bead per session only works because beads exist to capture everything else. And beads only work because the discipline prevents you from drowning in them.

Grooming vs. Coding

But I’m getting ahead of myself. Let me tell you about grooming.

In my old workflow, I’d sit down and just… start. Open Claude, describe what I wanted, begin coding. Very vibe. Very chaotic. Whatever felt right in the moment.

The problem is that “figuring out what to do” and “doing the thing” are completely different cognitive modes. One is divergent — you’re exploring possibilities, breaking down problems, identifying edge cases. The other is convergent — you’re executing, making decisions, writing code.

When you mix them, you get mush.

So now I run two types of sessions:

Grooming sessions are for thinking. I’m not coding. I’m not even planning to code in this session. I’m creating beads. Breaking down a feature into pieces. Identifying dependencies. Noting edge cases. If I think of an unrelated feature while grooming, it gets written down — for a different grooming session. No cross-contamination.

Coding sessions are for execution. One bead. Implement it. If I discover a bug, I note it and keep going unless it’s blocking. The bug gets groomed and coded in its own sessions later.

This separation is the whole game. It sounds bureaucratic. It sounds like exactly the kind of process that “vibe coding” was supposed to eliminate. But here’s the secret: this discipline is what makes vibe coding actually work at scale. Without it, you’re just generating code and hoping. With it, you’re building systems.

A Few Other Things

MCPs should be loaded at project level, not globally. Every MCP eats context. If a project doesn’t need the Reddit MCP, it doesn’t get the Reddit MCP. Context is expensive. Guard it like it’s money, because in a very real sense, it is.

Autocompact should be off. I want to control when context resets, not have the algorithm decide for me mid-feature. Yes, this means manually managing sessions. That’s the point.

Claude.md files are more powerful than you think. I have a global one in ~/.claude/CLAUDE.md with rules that apply everywhere. Each project gets its own with project-specific instructions. Claude reads these automatically. They’re like a pre-prompt that doesn’t eat your context window.

What Still Doesn’t Work

Now, here’s the part where I’m supposed to tell you it’s all solved and my workflow is perfect.

It’s not.

Debugging production issues is still clunky. I’ve got a combination of skills and MCPs that sort of works, but there’s too much manual context assembly. Something breaks in prod and I’m still spending the first 20 minutes of the session explaining the architecture before we can even start diagnosing.

Test-driven development doesn’t flow. The loop of “write test, see it fail, implement, see it pass” — it’s awkward. Claude wants to write everything at once. I’m still tweaking my tooling to make TDD feel natural.

UX work is hard. Like, fundamentally hard. Claude can scaffold UI. It can generate components. But “does this feel right?” is a human judgment call, and trying to get there through text-based iteration is like describing a painting to someone and asking them to tell you if it’s beautiful.

These are the walls I’m hitting. I’m building tooling to address them — an agent orchestrator that tailors Claude to my specific workflow. Work in progress. If you’re the adventurous type, you can try it now.

The System

So here’s the actual system, if you want to try it:

1. Install beads: npm install -g @anthropic-ai/beads && bd init

2. Add to your global CLAUDE.md: “Check bd ready at session start. One bead per session.”

3. Separate grooming from coding. Different sessions. Different mindsets.

4. Resist the urge to “do more while there’s context left.” That’s the trap.

5. Protect your context. Project-level MCPs only. Kill anything you don’t need.

Two SaaS products since mid-2025. All vibe coded with this system.

Not because the tools are magic. The tools are good, but tools are never magic. What made it work was the discipline — the willingness to be a little bit boring about context hygiene, to resist the temptation to do more, to trust that a focused session ships more than a scattered one.

Vibe coding without chaos. It turns out it’s not about vibing harder. It’s about vibing deliberately.

You’re the head chef now. But don’t forget your mise en place.

My wife was right, by the way. She usually is.

I’m Lakshmi. 20 years in software — ops, infrastructure, full-stack. Now solo founder using Claude Code to develop, deploy, and distribute.

Another commenter chimed in: their company replaced $300,000/year software with something they built in-house in under four months.

Meanwhile, over on r/SaasDevelopers, a developer is stuck at $200 MRR for eight months. Beautiful code. Great UX. Fifteen features. Asked where his users come from: “Uh, Product Hunt six months ago and some Reddit posts.”

These two conversations are happening in parallel across the internet, and most developers haven’t connected the dots yet.

Here’s what’s actually happening: AI didn’t just make coding faster. It vaporized the feature moat entirely.

The feature moat was always a lie we told ourselves.

“If I build it better, they will come.” This was comforting. It meant the thing we’re good at — writing code — was the thing that mattered most.

It wasn’t true before AI. It’s aggressively not true now.

Your competitor can rebuild your core features in a weekend. Not because they’re brilliant. Because Claude is sitting right there, and the barrier to “good enough” has collapsed to basically zero. That integration you spent three months perfecting? Someone’s CTO just shipped an 80% version while you were reading this paragraph.

The YC thread frames it well: “AI mostly kills thin feature moats, not real businesses.” If your entire value proposition is “we built this thing and it works,” congratulations — you’ve built something anyone can now replicate before their coffee gets cold.

So what’s actually defensible?

The comments in both threads converge on the same uncomfortable answer: everything except the code.

Distribution. The SaasDevelopers post makes the case bluntly: a mediocre product with great distribution beats a great product with no distribution. Every time. The OP claims $4.8K MRR with “decent features, nothing groundbreaking” because he publishes three SEO posts weekly and engages in five communities daily. His previous products had better code and failed under $500 MRR.

Whether you believe his specific numbers or not, the pattern is real. Visibility compounds. Code quality doesn’t.

Operational complexity. The YC founder pivoted to payments specifically because it’s “harder to clone with AI.” Payments involve regulatory mess, edge cases that actually hurt people when you get them wrong, and trust that takes years to build. You can’t vibe-code your way to PCI compliance.

Workflow embedding. One commenter nailed it: “Can a copycat ship it, but still not get adopted because switching costs and trust are the real barrier?” If yes, you might have something. If your product is a nice UI on top of an API call, you’re a feature waiting to be absorbed.

Data that compounds. This one’s subtle but important. If your product gets better because you have data your competitors can’t easily replicate — user behavior, domain-specific training data, network effects — that’s a moat AI can’t trivially cross.

The developer’s existential crisis.

Here’s the part nobody wants to say out loud: for most technical founders, the skill that got them here is now table stakes.

You can write clean code. Great. So can Claude. You can architect systems. Wonderful. So can a junior dev with Cursor and four hours.

The skills that matter now are the ones developers historically dismissed as “marketing” or “sales” or “that stuff the business people do.”

Building an audience. Writing content that ranks. Engaging in communities without getting banned for being too promotional. Understanding what people actually want to pay for versus what’s technically impressive.

This is deeply annoying if you became a developer specifically to avoid talking to people.

What to actually do.

Stop adding features to a product nobody’s using. That’s not building — that’s procrastinating with a compiler.

Spend less time in your IDE and more time in the places your customers hang out. Reddit, LinkedIn, niche communities, whatever. Not to drop links. To understand what problems people are actually complaining about and whether your thing solves any of them. (It’s why I’m building ThreadHQ.)

If your product can be rebuilt in weeks with AI, either pivot to something with real operational complexity, or accept that distribution is your product now and code is just the unlock.

The YC thread suggests payments, compliance-heavy industries, anything where “mistakes actually hurt” and trust is earned over years. The SaasDevelopers thread suggests becoming a distribution machine: 20+ platform launches, daily content, systematic visibility.

Both are right. Pick your poison.

The uncomfortable synthesis.

AI commoditized the build. What’s left is everything around it: who knows about you, who trusts you, and how painful it would be to switch away.

The code was never the product. Now it’s just impossible to pretend otherwise.

“I’ve never felt this much behind as a programmer. The profession is being dramatically refactored as the bits contributed by the programmer are increasingly sparse and between. I have a sense that I could be 10X more powerful if I just properly string together what has become available over the last year and a failure to claim the boost feels decidedly like skill issue.”

He then listed what this new layer looks like: agents, subagents, prompts, contexts, memory, modes, permissions, tools, plugins, skills, hooks, MCP, LSP, slash commands, workflows, IDE integrations.

His conclusion: “Clearly some powerful alien tool was handed around except it comes with no manual and everyone has to figure out how to hold it and operate it, while the resulting magnitude 9 earthquake is rocking the profession.”

I felt this in my bones.

The Old Stack vs The New Stack

The old programming stack was hard enough:

Hardware -> OS -> Language -> Frameworks -> Your Code

Years of learning. Layers of abstraction. But at least it was deterministic. At least there were manuals. At least Stack Overflow had answers.

The new stack adds a layer on top:

You -> Prompts/Agents/Context/Memory/Tools/Modes -> Code

This layer is fundamentally different. It’s stochastic. It’s fallible. It’s unintelligible. And it changes every few weeks.

There’s no certification. There’s no textbook. There’s no “Effective AI Orchestration” by Joshua Bloch. Just a bunch of people figuring it out in Discord servers and sharing CLAUDE.md files and best practices like trading cards.

The Divide Is Already Here

Someone on Reddit described the pattern they’re seeing on their team:

“Two developers with similar experience working on similar tasks, but one consistently ships features in hours while the other is still debugging. At first I thought it was just luck or skill differences. Then I realized what was actually happening — it’s their instruction library.”

They’re watching an underground collection of power users share workflows like secrets:

• Commands that automatically debug entire codebases

• CLAUDE.md files that turn Claude into domain experts

• Slash commands that turn 45-minute processes into 2-minute ones

Meanwhile, most people are still typing “help me fix this bug” and wondering why their results suck.

As one developer put it: “The differences between someone who opens up CC for the first time and someone with tuned md files is beyond night and day.”

The Skill Issue Is Real (But Not The One You Think)

Here’s what hit me about Karpathy’s framing: he called it a “skill issue.”

Not a tools issue. Not an access issue. Not a funding issue.

A skill issue.

The 10X boost exists. The leverage is real. But claiming it requires mastering something that didn’t exist two years ago and has no curriculum.

Someone in that same thread nailed the uncomfortable truth: “90% of traditional programming skills are becoming commoditized while the remaining 10% becomes worth 1000x more. That 10% isn’t coding — it’s knowing how to architect AI workflows.”

The irony is brutal. We spent years mastering syntax, frameworks, design patterns. Now an AI can generate all of that in seconds. What it can’t do is orchestrate itself effectively. That’s your job now.

What The New Layer Actually Looks Like

Let me make this concrete. Here’s what I’ve had to learn in the past year that wasn’t part of any CS curriculum:

CLAUDE.md Architecture

Your instructions file isn’t documentation. It’s programming. The structure, the phrasing, what you include vs exclude — these decisions compound across every interaction. A well-architected CLAUDE.md is worth more than a well-architected codebase.

Context Management

Every token matters. MCP servers eat context. Long conversations drift. You need to think about what Claude knows, what it’s forgotten, when to compact, when to start fresh. It’s memory management, but for a mind that isn’t yours.

Prompt Design

Not “prompt engineering” in the LinkedIn-influencer sense. Actual design. When do you give examples? When do you constrain? When do you let it explore? How do you phrase things so it doesn’t hallucinate? How do you trigger deeper thinking? These are learnable skills with massive payoff differences.

Tool Orchestration

MCP, skills, hooks, slash commands. Which tool for which job? When does an MCP server make sense vs a bash script vs a skill file? How do you chain them? How do you debug when the chain breaks?

Mode Awareness

Plan mode vs implement mode. When to let Claude explore vs when to constrain. When to use subagents. When to go linear. The meta of working with AI — knowing when to switch approaches — is itself a skill.

Verification Choreography

AI generates fast. Verification is the bottleneck. How do you structure your workflow so you’re not just rubber-stamping garbage? How do you catch the 8 production bombs before they ship? (Yes, I wrote about this.)

The Manual That Doesn’t Exist

An older developer on Reddit captured the frustration:

“I started using AI about 2 years ago. I thought I was doing good, but then I started seeing all this stuff about MCP servers, md files etc and I am kind of lost. I want to learn more and I want to improve my AI skills but it’s difficult for me.”

This is someone with decades of experience, feeling lost because the new layer has no onramp.

The manual doesn’t exist because the platform keeps shifting. Claude Code ships updates weekly. New features appear. Old patterns stop working. The MCP ecosystem is exploding. Skills just launched. Hooks changed. The ground won’t stop moving.

You can’t study for an earthquake. You can only practice surfing.

How I’m Learning (Imperfectly)

I don’t have this figured out. Nobody does. But here’s what’s working:

Steal shamelessly. Find people who are clearly more productive and reverse-engineer their setup. Their CLAUDE.md files, their slash commands, their workflows. GitHub repos, Discord servers, Reddit threads. The good stuff is scattered but findable.

Treat your setup as code. Version control your CLAUDE.md. Iterate on your slash commands. When something works, document why. When something fails, autopsy it. Your instruction library is a codebase now.

Invest in meta-skills. The specific tools will change. MCP might get replaced. Claude Code might get competition. But the meta-skills — context management, prompt design, verification choreography — those transfer.

Actually use the new features. Hooks exist. Subagents exist. Skills exist. Most people ignore them because they’re “advanced.” They’re not advanced. They’re just new. The learning curve is the moat.

Teach to learn. Writing about this forces me to understand it. Explaining my setup to others reveals the gaps. The best way to master the new layer is to articulate it.

The Uncomfortable Conclusion

Karpathy is right. There’s a 10X boost available. Failing to claim it is a skill issue.

But it’s a new skill. One that didn’t exist before. One that has no manual, no certification, no clear path.

The people figuring it out are building compound advantages. Every custom command, every refined CLAUDE.md pattern, every workflow optimization — it all stacks. The gap between those who master the new layer and those who don’t is widening fast.

The earthquake is still happening. The alien tool is still being figured out. The manual is being written in real-time by the people using it. And the rules are being changed as we speak/code/write.

Roll up your sleeves.

This is a companion to my previous essay on what Claude can’t do for you. That one covered the old skills that still matter. This one covers the new skills you need to add.

Let that sink in.

Beads — his coding agent memory system — is used by tens of thousands of developers daily. It’s 100% vibe coded. Yegge has never looked at a single line. Same with his new project, Gastown. Three weeks old, 100% vibe coded, never seen the code, never plans to.

His reaction to anyone uncomfortable with this? “Get out now.”

The Heresy

For two decades, we’ve been taught that code is literature. Uncle Bob’s Clean Code. Martin Fowler’s Refactoring. Elegant variable names. Single responsibility. Code should read like prose.

We optimized for human comprehension because humans had to maintain it.

But what if that’s no longer true?

Simon Hoiberg put it bluntly: “Half my code is now written by AI, and the other half is read by AI to fix bugs. Optimizing for human readability is becoming pointless.”

The audience for your code has changed. And it’s not you anymore.

The Other Day I Wrote About Comprehension Debt

I argued that vibe coding creates legacy code from day one. That velocity without comprehension isn’t velocity — it’s procrastination with extra steps.

I still believe that. Mostly.

But here’s the uncomfortable follow-up question: What if comprehension debt only matters when you have to pay it?

If AI writes the code and AI debugs the code and AI refactors the code… who exactly needs to understand it?

The New Contract

The old contract: Write clean code so humans can read it.

The new contract: Write code that produces correct outcomes, verified by tests that humans can understand.

This is a crucial shift. The code becomes disposable infrastructure. The tests become the spec. The behavior becomes the product.

Steve Yegge doesn’t need to understand 225,000 lines of Go. He needs to understand what Beads should do. The tests verify that it does it. The code is just… implementation detail. An artifact. A byproduct.

Clean Specs > Clean Code

Here’s the heretical thought experiment:

What if “clean code” principles should now apply to your specifications instead of your source code?

Think about it:

• Readable intent: Your specs should be crystal clear. “Users can checkout with valid payment. Invalid cards show an error. Empty carts can’t checkout.”

• Single responsibility: Each spec describes one behavior. Not implementation — behavior.

• Self-documenting: Specs are the documentation that gets executed. They describe what the system should do, and you verify it actually does.

• Easy to modify: When requirements change, you update the spec first. AI updates everything else.

The source code can be a tangled mess of AI-generated spaghetti. Who cares? If you can clearly specify what you want and verify you got it, the implementation is just a detail.

The Yegge Paradox

Here’s what’s wild. In the Vibe Coding book Yegge co-authored with Gene Kim, “Steve” is described as reviewing 10,000 lines of code a day, throwing away 10 lines for every line kept.

Wait. He reviews code? I thought he never looks at it?

The answer, I think, is this: He reviews outcomes. He reviews test results. He reviews whether the thing works. He’s not reading code for elegance or comprehension. He’s running it, breaking it, verifying it.

The code review has become a behavior review.

What This Means for You

I’m not saying burn your Clean Code book. (Okay, maybe I am. That thing is 400 pages of what could’ve been a blog post.)

But consider this workflow:

1. Specify the behavior — in plain language. “Users can checkout with valid payment. Invalid cards show an error. Empty carts can’t checkout.”

2. Let AI write the tests — it turns your specs into executable verification

3. Let AI write the implementation — who cares if it’s ugly

4. Verify the outcomes — does it do what you specified? Try to break it. Edge cases covered?

5. Ship it — the code is a means to an end

If something breaks, you don’t debug the code. You describe the broken behavior. AI writes a failing test. AI fixes the implementation. You verify the outcome. You never had to understand the implementation. You just had to understand what you wanted.

The Catch

There’s always a catch.

This only works if your specifications are actually good. If your specs are vague, incomplete, missing edge cases — you’re in the worst of both worlds. Incomprehensible code that doesn’t even do what you need.

That’s not vibe coding. That’s vibes-all-the-way-down coding. And that’s how you get 18 out of 20 CTOs reporting production disasters.

The discipline has to go somewhere. If you’re not putting it into clean code, you damn well better be putting it into clear specifications and ruthless outcome verification.

The Real Skill Shift

Old skill: Writing elegant, maintainable code that other humans can understand.

New skill: Specifying behavior precisely and verifying outcomes ruthlessly.

The developers who thrive won’t be the ones who write the cleanest code. They’ll be the ones who can articulate exactly what they want. Who can break their own systems. Who can look at a feature and immediately think of ten ways it could fail.

Code literacy is becoming specification literacy. The new “clean code” is clear intent.

The Uncomfortable Conclusion

We spent twenty years optimizing for human readers who are increasingly being replaced by AI readers.

Maybe Steve Yegge is right. Maybe the code doesn’t matter. Maybe it never really mattered — we just didn’t have anything better.

What matters is: Does it work? Can you prove it? Can you verify it still works after changes?

Clean code was a proxy for those questions. A good heuristic when humans had to debug.

Clean specs answer those questions directly.

The code is dead. Long live the specs.

This is a follow-up to my recent essay on comprehension debt. The tension is real: you need to understand the problem deeply enough to specify it clearly, but maybe not the implementation at all. Where that line is… I’m still figuring out.

Two weeks later, something breaks and you open that file. You stare at the code. Your code. Code you wrote. Code that works.

You have no idea what it does.

Welcome to comprehension debt.

The Debt Nobody Talks About

Technical debt is code you know is bad. Comprehension debt is code you don’t understand well enough to know if it’s bad.

There’s a crucial distinction here that a Reddit commenter nailed: “We’re getting correct code, but not right code.” The code runs. It passes tests. But ask someone why it makes specific design choices, why certain patterns were used, why the architecture looks the way it does — and the answer is often “Copilot put it there.”

With AI coding assistants, we can now generate working code faster than we can understand it. Claude writes 200 lines. Tests pass. Ship it. Next feature.

Repeat this fifty times and you’ve got a codebase that works but might as well be written by a stranger. Because functionally, it was.

Legacy Code on Arrival

Here’s the uncomfortable truth that r/programming figured out: vibe coding is legacy code from day one.

One commenter called it “the payday loan of technical debt.” You’re borrowing velocity from your future self at predatory interest rates.

A freelance developer with 8 years of experience recently described a pattern he’s seeing repeatedly: companies paying good money for internal software that barely works. Tons of errors, unreasonably slow, security flaws everywhere. When he looks at the codebase, the same telltale signs: AI-generated comments, algorithms that make no sense, inconsistent patterns. Yes, it mostly works. But it works terribly.

In one case, a designer with CSS knowledge but not much more created a full React app with AI. When they hired a freelancer to fix it up, he deleted 90 files out of 100.

That’s not technical debt. That’s a technical foreclosure.

Where It Hurts

Comprehension debt doesn’t show up on sprint boards. It shows up when:

• Debugging takes 10x longer because you’re reverse-engineering your own code. Your own code. Like some kind of archaeologist excavating your past self’s decisions.

• Small changes require big rewrites because you can’t safely modify what you don’t understand.

• You can’t explain the system to anyone, including future you. Especially future you.

• Architecture decisions compound badly because each layer is built on foggy assumptions and vibes.

Everyone talks about vibe coding. Nobody talks about vibe debugging. There’s a reason for that.

The irony: you used AI to go faster, but now you’re slower because you have to re-learn your own codebase every time you touch it.

The Skill Atrophy Problem

Here’s what worries senior developers: the heavier you lean on AI, the more your own skills degrade.

Someone described AI coding assistants as “a hyper-intelligent, infinitely patient junior developer.” Another added: “overconfident and unable to learn.”

That’s the trap. A junior developer eventually becomes a senior developer. They remember painful mistakes. Their understanding of your system grows over time.

AI doesn’t. Every conversation starts fresh. It will confidently suggest the same antipattern tomorrow that you rejected today. And if you’ve stopped exercising your own judgment because the AI handles it, you won’t catch it.

Ironically, the only people who should be leaning heavily on AI for code generation are people who are already experts. They can spot when it’s wrong. Everyone else is just accumulating comprehension debt they can’t even see.

Fighting Back

You don’t have to understand everything. That’s the whole point of abstraction. But you need to understand enough.

1. The Five-Minute Rule

After AI generates code, spend five minutes actually reading it. Not skimming. Reading. Like with your eyeballs.

If you can’t explain what it does to a rubber duck, you’ve got comprehension debt.

2. Write the Comments Yourself

Don’t let AI write comments. Write them yourself, in your own words. If you can’t write the comment, you don’t understand the code.

One veteran developer pointed out: “Given that very few people comment the code, if there are comments at all it’s AI generated.” Comments have become a smell for AI slop, not a sign of good documentation.

3. Draw the Damn Diagram

For any non-trivial flow, sketch the data path. Boxes and arrows. Takes two minutes. Forces you to understand the actual architecture, not the architecture you assume exists.

4. Refactor Before You Forget

The best time to refactor AI-generated code is immediately after it works. You’ve got context. You’ve got momentum. Wait two weeks and that context is gone forever.

Future you will not remember. Future you has problems of their own.

5. Your PR, Your Responsibility

“Copilot put it there” is not an acceptable answer in a code review. It’s the same as saying “I don’t know, it was the first autocomplete option.”

The AI is a tool, like your IDE. At the end of the day, you’re responsible for every line in your PR. If you can’t defend the code, you shouldn’t be shipping the code.

The Uncomfortable Truth

I’m not saying go back to writing everything by hand. That ship has sailed.

AI leverage is real. Use it.

But leverage without understanding is just deferred confusion. Every line of code you don’t understand is a question you’ll have to answer later, usually at 2am, usually when something is on fire.

Those championing AI focus on the speed something new can be developed. But in the long term, the real difficulty is how easily it can be maintained. And you can’t maintain what you don’t understand.

The developers who’ll thrive aren’t the ones who generate the most code. They’re the ones who maintain a sustainable ratio between code shipped and code understood.

Velocity without comprehension isn’t velocity.

It’s procrastination with extra steps.

I also hate MCP.

Because every MCP server I add is another pile of tool definitions crammed into my context window. Supabase. Betterstack. Sentry. Playwright. Each one brings 5-15 tools. That’s 40+ tool definitions sitting there, burning tokens, even when I’m just asking Claude to fix a typo.

The technical term for this is “token bloat.” The accurate term is “I’m paying for tools I’m not using.”

The Obvious Solution (That Doesn’t Work)

“Just load MCPs on demand!”

Revolutionary concept. Except Claude Code doesn’t support hot-reloading MCP servers. You pick your MCPs at session start, and that’s your life now. Want to add Sentry mid-session? Restart. Lose your context. Start over.

Nobody should have to live like that.

The Agent Escape Hatch

Here’s where it gets interesting.

Claude Code has agents. Agents can spawn with specific tools. So naturally, I thought: what if I keep my main session lean, and spawn agents when I need MCP access?

Main session stays clean. Agent does the Supabase query. Returns results. Everybody’s happy.

Except.

The Inheritance Problem

Agents inherit MCP tools from their parent session.

Read that again.

If I want my debug agent to call Supabase, Supabase MCP must be loaded in my main session. The agent can restrict which tools it uses, but it can’t access tools the parent doesn’t have.

So I’m back to loading everything upfront. The bloat remains. The horror.

Poor Man’s MCP

Fine. If agents can’t get MCP tools independently, maybe they don’t need MCP at all.

Agents have Bash. Bash has curl. These services have REST APIs.

What if I wrote thin wrapper scripts?

debug-api sentry-issue PROJ-123
debug-api supabase-query users "id=eq.abc123"
debug-api betterstack-logs "error" --from "2024-01-15"

Each wrapper hits the API directly, returns JSON. Agent calls wrappers, correlates results, returns findings. Main session stays lean.

I even started designing a mini-spec. Self-describing tools via --tools. Consistent JSON envelope. Exit codes for quick status checks.

MCP-lite. Poor man’s MCP. Whatever you want to call it.

It would work. But I’d be rebuilding what MCP already does, just… worse.

Wait. Why Can’t Agents Just Call MCP Directly?

This is where my brain finally caught up.

MCP servers are just processes. They communicate via JSON-RPC over stdio. Claude Code starts them, maintains connections, sends calls.

An agent with Bash could do the same thing.

Start server. Send JSON-RPC. Parse response. Kill server.

No inheritance needed. The agent IS the MCP client.

The Tool That Already Exists

Before I started writing my own MCP client in bash (a decision I would have regretted), I searched.

mcptools exists.

brew install f/tap/mcp

# List available tools
mcp tools @supabase/mcp-server

# Call a tool directly
mcp call @supabase/mcp-server query '{"sql": "SELECT * FROM users"}'

Start server. Make call. Get result. Server shuts down.

This is the missing piece.

The Pattern I’m Testing

Main Session (ZERO MCP tools loaded)
    |
    └── spawn debug-backend agent
            |
            ├── mcp call @supabase/mcp-server query '{...}'
            ├── mcp call @sentry/mcp-server get-issue '{...}'
            └── mcp call @betterstack/mcp-server search '{...}'
            |
            Returns structured findings

Main session keeps full conversation context. Agent spawns with just Bash. Agent discovers and calls MCP tools on-demand. Zero token bloat.

For frontend debugging, same pattern with Playwright:

mcp call @playwright/mcp-server navigate '{"url": "..."}'
mcp call @playwright/mcp-server screenshot '{}'

What I’m Still Figuring Out

I haven’t battle-tested this yet. Open questions:

• Auth handling: Do all MCP servers pick up env vars correctly when spawned fresh?

• Cold start latency: Is spawning a server per-call too slow for rapid iteration?

• Error recovery: What happens when the MCP server crashes mid-call?

• Which servers play nice: Some MCP servers might not like the start-stop lifecycle.

If you try this pattern, let me know what breaks.

The Punchline

I spent hours designing “MCP-lite” before realizing I could just… call MCP directly from agents.

Learn from my suffering.

The tools exist. The pattern is sound. The token bloat is optional.

Now I just need to actually use this for a month and see what explodes.

“Build me a todo app.”

Four words. Maybe ten seconds of typing. Then you sit back and watch the magic: files appear, databases materialize, endpoints generate themselves. The AI spins up authentication, adds a sleek frontend, writes tests. Three minutes later, you have a working application.

It’s impressive. It’s seductive. And for production software you’ll maintain for years, it’s a starting point at best—not a solution.

The Demo That Sells vs. The Code You Ship

I’ve spent five months deep in AI coding tools—Claude Code, claude-flow, and everything in between. I’ve watched hundreds of demos. I’ve read the marketing. And I’ve built actual production SaaS applications.

Here’s what the demos won’t tell you: that three-minute todo app works because it makes a thousand architectural decisions you never specified. And the moment your requirements diverge from those invisible assumptions, the whole thing falls apart.

Let me show you what I mean.

The Eight Decisions That Actually Matter

When you say “build me a todo app,” you think you’re giving clear instructions. But try building real production software and you’ll immediately hit these questions:

1. JWT Claims Structure

• What exact fields go in your JWT payload?

• Do you store roles as an array or a single string?

• Where do permissions live? In the token? In the database?

• Do you include user metadata or just an ID?

The demo picks one. It might not be the one you need. And changing it later? That’s not a refactor. That’s rearchitecting your entire auth system.

2. Token Rotation

• 15-minute access tokens with 7-day refresh tokens?

• Refresh token rotation on every use?

• Where do you store refresh tokens—database, Redis, or in-memory?

• httpOnly cookies or localStorage?

The demo makes a choice. You won’t know what it chose until you’re debugging your third session timeout bug in production.

3. UI Library

• shadcn/ui? Material-UI? Chakra? Ant Design? Headless UI?

• Tailwind CSS or CSS-in-JS?

• Which component patterns?

“Use a modern UI library” means nothing. I needed shadcn/ui specifically because it works with my design system, ships minimal JavaScript, and uses Tailwind. The demo gave me Material-UI. That’s not a theme change—that’s rebuilding the entire frontend.

4. Stripe Integration

• Checkout flow or Payment Intents?

• Subscription model or one-time payments?

• Customer portal or custom UI?

• Which webhooks do you handle?

The difference isn’t cosmetic. Checkout and Payment Intents are architecturally different. Choosing wrong means rewriting your entire billing integration.

5. Email Provider

• SendGrid? Resend? Postmark? AWS SES?

• Template system?

• Transactional vs. marketing?

Each provider has different APIs, rate limits, pricing models, and deliverability characteristics. “Add email notifications” doesn’t specify any of this.

6. Database ORM

• Prisma? Drizzle? TypeORM? Kysely?

• Type generation approach?

• Migration strategy?

Your ORM choice affects type safety, migration workflows, query performance, and deployment strategy. It’s not swappable. It’s foundational.

7. Testing Framework

• Vitest? Jest? Mocha?

• Supertest for integration tests?

• What coverage target?

The testing framework dictates how you structure tests, handle mocks, and integrate with CI/CD. Changing it later means rewriting every test.

8. Deployment Target

• Vercel? AWS? Docker compose? Railway?

• What Vercel-specific features do you need?

• Environment variable strategy?

• Database hosting (Neon? Supabase? RDS?)?

Deployment isn’t the last step. It shapes your entire architecture—serverless vs. long-running, filesystem access, background jobs, caching strategies.

The “Just Refactor It” Myth

When I point this out, the response is always: “Just refactor what the AI generated.”

Have you actually tried this?

Swapping Prisma for Drizzle isn’t a find-and-replace operation. It means:

• Rewriting your schema in a different DSL

• Changing how you handle migrations

• Updating every database query

• Modifying your type generation

• Adjusting your seeding scripts

• Updating your testing setup

We’re not talking about an afternoon. We’re talking about days of work. And that’s for ONE of these eight decisions.

Change the ORM, the UI library, and the auth token structure? You’re not refactoring. You’re rebuilding.

What “Build Me an App” Actually Produces

Here’s the brutal truth: autonomous AI tools generate generic boilerplate that matches their training data’s most common patterns.

They give you:

• Whatever stack is most popular on GitHub

• Whatever patterns appear most in tutorials

• Whatever architecture is easiest to generate

They don’t give you:

• Your company’s conventions

• Your infrastructure constraints

• Your team’s expertise

• Your product’s specific requirements

The demo works because demos don’t have requirements. Real projects die in the gap between “an app” and “our app.”

Why This Matters for Production Code

If you’re at a big company with a team of 20 engineers, maybe you can absorb the rebuild cost. You have engineering hours to burn. You have people to maintain legacy code while others refactor.

Most of us don’t have that luxury.

Whether you’re building solo, on a small team, or shipping client work, you’re living with every architectural decision for years. You can’t afford to spend three days ripping out Material-UI because an autonomous tool decided that’s what “modern UI library” meant. You can’t rebuild your auth system because the JWT structure doesn’t match your API contracts. You can’t rewrite billing integration because the tool guessed Checkout when you needed Payment Intents.

Wrong architectural decisions compound. When you’re responsible for maintaining the code—whether that’s yourself, a small team, or a client relationship—you need to understand and own those decisions.

That’s why production code requires control, not autonomy.

The Interactive Alternative

Compare that to working with Claude Code:

Me: “Add authentication to this project.”

Claude Code: “I can help with that. A few questions:

• JWT or session-based auth?

• If JWT, what should the token payload include?

• Where should refresh tokens be stored?

• What’s your refresh token rotation strategy?”

Me: “JWT. Payload should have userId, email, roles as an array, and permissions as a nested object. Refresh tokens in database with rotation on every use. 15-minute access, 7-day refresh. httpOnly cookies.”

Claude Code: “Got it. I’ll implement that exactly.”

The specification happened through dialogue. I clarified the architectural decisions before any code was written. The AI generated exactly what I specified, not what it guessed I might want.

When the auth system is running in production six months later and I need to debug a token issue, I understand every decision because I made every decision. I’m not reverse-engineering someone else’s assumptions. I’m working with my own architecture.

When Autonomy Actually Works

Autonomy isn’t wrong—it’s just context-dependent. There are places where “just handle it” is absolutely the right answer:

• README generation: Standard markdown structure is fine

• ESLint configuration: Default configs work for most cases

• .gitignore files: Use the templates

• Boilerplate CRUD endpoints: If they follow established patterns exactly

• Prototypes you’ll throw away: Exploration where decisions don’t matter yet

These are low-stakes decisions with high standardization. Getting them “wrong” doesn’t cascade. You can change them later without rebuilding your application. Single-prompt generation shines here.

But authentication? Database schema? Tech stack? These are high-stakes, foundational decisions with cascading effects. This is where precision matters and guesswork fails.

The Autonomy Illusion

Here’s what the AI tool marketing doesn’t tell you:

More agents doesn’t mean better code. It means less control.

Sophisticated orchestration doesn’t mean better results. It means more complexity hiding the same specification problem.

“Just describe what you want” doesn’t work when architectural decisions require precision that natural language can’t provide.

I tested claude-flow—a sophisticated multi-agent system with 10+ agent templates, health monitoring, auto-scaling, 3-tier memory, and 60+ task types. Impressive infrastructure. But it still runs on string-based specifications. When I asked for shadcn/ui, there was no type safety, no validation, no guarantee the agent would interpret “shadcn/ui” as “shadcn/ui and absolutely nothing else.”

The specification layer is still natural language. And natural language is ambiguous.

The Real Question

The question isn’t “Can AI build an app from a single prompt?”

The answer to that is yes. Absolutely. The demos prove it.

The real question is: “Can AI build YOUR app—with YOUR architecture, YOUR conventions, YOUR constraints—from a single prompt?”

The answer to that is no.

Not because the AI isn’t capable of generating code. It’s excellent at that.

But because “build me an app” leaves a thousand architectural decisions unspecified. And every one of those decisions matters when you’re shipping production software you’ll maintain for years.

What Works Instead

After five months of research, building real projects, and testing multiple tools, here’s what actually works:

Start with control:

• Make architectural decisions consciously

• Specify tech stack, libraries, patterns explicitly

• Use interactive tools that let you clarify requirements

• Review and understand what’s being generated

Move to autonomy for execution:

• Once patterns are established, autonomous tools can replicate them

• Use autonomy for boilerplate that follows decided patterns

• Let AI handle repetition, not decision-making

Return to control for integration:

• Debugging requires understanding

• Maintenance requires ownership

• Evolution requires knowing why decisions were made

The cycle is: design with control, execute with autonomy, integrate with control.

Not: autonomous generation followed by days of “just refactor it.”

The Real Power of AI Coding

The promise of AI coding tools isn’t “describe an app in four words and get perfect code.”

The promise is: “Make architectural decisions at the speed of thought, then have those decisions implemented flawlessly.”

Interactive AI tools let you think at the architecture level while the AI handles the implementation level. You make decisions. The AI writes code. You maintain control and understanding. The AI handles the tedious translation from intent to syntax.

That’s the real 10x improvement.

Not “build me an app” magic that produces generic boilerplate you’ll spend days rebuilding.

But the ability to say “JWT with these exact claims, refresh rotation with this lifecycle, stored in httpOnly cookies” and get exactly that. First try. No guessing. No rebuilding.

The Bottom Line

If you’re building serious software—production SaaS, client projects, anything you’ll maintain beyond next week—you need to understand what you’re building.

Autonomous tools that guess at your architecture don’t save time if you spend days fixing wrong assumptions.

Code you don’t understand becomes a liability the moment something breaks.

Decisions you never made can’t evolve with your requirements.

Control isn’t about micromanaging the AI. It’s about owning the architecture of software you’re responsible for maintaining.

The demos are impressive. The marketing is seductive. The promise of “just describe it” is tempting—and genuinely useful for the right contexts.

But for production software with real requirements, real constraints, and real consequences? Interactive tools that let you specify precisely what you need will outperform autonomous guesswork every time.

Be skeptical of demos. Demand control. Ship code you understand.

1. Being Super Vague

AI models are getting smarter by the day. But they can’t read tea leaves like some digital oracle you summoned from Silicon Valley. “My ‘Schedule’ button isn’t scheduling the post.” Sure, Einstein. I can see that. Revolutionary observation.

Give me more context. What do you see in the logs? What did you expect to happen? What happened instead? Did it fail silently? Throw an error? Launch the nuclear codes? Eric S. Raymond’s “How to Ask Questions The Smart Way” is still devastatingly relevant after all these years, but apparently nobody got the memo.

The AI isn’t a mind reader—it’s a very expensive pattern matcher. Treat it accordingly.

2. Vibe Coding in the Truest Spirit

I’m going to hit “Accept” until my fingers are sore or the code does what I want. Whichever comes first. It’s like Russian roulette, but with merge conflicts.

No. Take a step back. Talk with your tool about what needs to be implemented and what the approach should be. It is imperative—not optional, not nice-to-have—that you understand it. Ask questions until you do. Don’t allow a single line of code to be written without you knowing the consequences.

Don’t pay the ignorance tax. The interest rates are criminal.

3. Don’t Read the Code Written by AI

Again, just hit “Accept” and pray to whatever deity oversees production deployments. Why read? Why think? Why have standards?

You need to know the consequences. How this piece affects other parts of your codebase. How the addition of a new feature might possibly break something else that’s been working fine for three months. I feel even AIs aren’t good enough at this second-order thinking. So many “You’re absolutely right!” responses to things that were obvious in hindsight but the AI somehow missed. This Reddit thread is in equal parts hilarious and terrifying.

Code review exists for a reason. Even if the author is artificial.

4. Do Multiple Changes in One Session

This is a surefire way to confuse the heck out of the AI, and eventually yourself. Congratulations, you’ve achieved parity—you’re both lost.

Have one Claude/Cursor session for one unit of work. It can be a simple fix for a broken sidebar. Or preparation for something monumental, like refactoring all functions to use JWT. How do you figure out the right unit of work? Depends on context. (Your mileage may vary, batteries not included, void where prohibited.) There are tools to divide your “build me an image editing tool” prompt into proper AI and human digestible units of work.

In the JWT example, maybe all the functions are in the auth module only. Not a lot of context switching—for both carbon and silicon-based lifeforms. Even if it breaks, you can purge that commit off the face of the earth, go back to the drawing board, recoup, rethink, and re-execute.

But what if you club both examples in the same session? A broken sidebar comes across as a seemingly harmless fix, only to discover that the “fix” isn’t responsive, and now you need to add a new library, a consequence of which is that npm run build fails spectacularly. You debug this rabbit hole for an hour. Your context window explodes like a supernova. You didn’t fix the sidebar. Two hours and eight dollars in credits flew by. (Just sayin’.)

Which brings us to…

5. Choke the Context Window

We need to be strategic with our prompts and questions. They need surgical precision, not the intellectual equivalent of a shotgun blast.

When you say “the register endpoint in @app.py returns 500 if the email already exists, but @utils.py already has a check for that,” you’re sending the entire 1,000-line app.py file and the 1,500-line utils.py file into your precious context window. Congratulations, you just spent $2 to ask a $0.50 question.

Even better: when you coded app.py and utils.py in the first place, don’t make them 5,000 lines long. Even if the AI wants to take any of these files into context, it will result in context hemorrhage sooner or later. Give clear instructions to the AI not to make your files and modules like Homer’s Iliad. Nobody wants to read that much Python in one sitting.

If your codebase was written by humans (remember those?), create units of work to refactor these monstrosities. Your future self will thank you profusely. The AI even more.

6. Don’t Use Parallel Sessions

When you’re building a feature—say, WebSocket integration—and have another in the pipeline, you fire up your IDE, give clear instructions, rightsized units of work, and then… you twiddle your thumbs while the AI finishes, right? Making coffee? Checking Twitter? Contemplating the heat death of the universe?

Have you considered using git worktrees and parallel sessions so that they can execute independently of each other? Later, you can merge both feature branches into the parent branch. Revolutionary concept, I know.

Here’s another kicker: you can orchestrate an AI agent to do this entire thing for you—split into parallel units of work, create git worktrees, orchestrate parallel sessions, review and merge back the code, clean up. It isn’t a stretch to say we’re hitting technological singularity. The robots are already doing the DevOps we were too lazy to automate properly.

I wrote a piece related to this:

7. MCP Overuse

MCPs (Model Context Protocol servers) consume tokens. A lot of them. They’re the SUVs of the API world—powerful, useful, and absolute gas guzzlers.

Use prudence and exercise your own judgment here. For example, to scaffold a GitHub repo with a FastAPI boilerplate, the GitHub MCP is the slowest and costliest way. You’re better off using the gh CLI. Or, you know, copying a template. Revolutionary, I know.

Not all MCP use is stupid. But some of it is really stupid.

8. MCP Underuse

Context7 MCP is used by your AI to refer to up-to-date documentation for the libraries and APIs you use. Use the GitHub or JIRA MCP to update the task you’ve been working on. The utility value of MCPs is staggering.

If you’re not using MCPs where they make sense, you’re simply leaving time and money on the table. It’s like having a Swiss Army knife and only using the bottle opener. Sure, it works, but you’re missing out.

9. Don’t Write Tests

Did you finish a unit of work? Did you forget to write tests for that? Superb! Because this is going to come back and haunt you after weeks—possibly months—when you’re shipping something else on a tight deadline, and this thing you wrote many lifetimes ago is suddenly, inexplicably broken.

Every unit of work that goes in as a git commit must be tested. At least manually. Preferably with actual test cases that run in CI/CD and don’t just live in your head as “yeah, I’m pretty sure this works.”

Future you is going to hunt down present you with a very particular set of grievances. Don’t give them ammunition.

Again, a related post:

10. Don’t Update Your Project’s Context

Something AIs and humans have in common: context is everything. And both forget it constantly.

Picture this: you’re three months into a project. You open a file. “Wait, the architecture document says we use Redis to store the messages. But here we are using ZeroMQ. Let me do a git blame.”

Ah. You did it three weeks back. Right before going on vacation. The context that seemed so obvious at the time has evaporated like morning dew. You’re now an archaeologist excavating your own code, trying to understand why Past You made these decisions.

Update your project’s context. Maintain a living document—a README, an architecture decision record, inline comments that aren’t just “// fix later” (spoiler: you won’t). Explain why you made certain choices. Your AI needs this context to give you useful suggestions. Your human collaborators need it to not send you passive-aggressive Slack messages. Your future self needs it to avoid existential crises at 2 AM.

“We switched from Redis to ZeroMQ because the message ordering guarantees were critical for the event sourcing pattern we implemented in sprint 12.” There. Was that so hard? Now everyone—human and AI alike—can work with the actual state of the world instead of a beautiful fiction from three months ago.

The Bottom Line

AI coding assistants are powerful tools. Emphasis on tools. They’re not magic. They won’t read your mind, fix your architecture problems, or absolve you of the responsibility to understand your own codebase.

Use them strategically. Be precise. Maintain context. Write tests. Don’t let the robots drive—you’re still the one who has to explain to your manager why the production database got dropped.

And for the love of all that is holy, read the code before you merge it.

Your token budget will thank you. Your future self will thank you. And your AI assistant will stop generating those “You’re absolutely right!” responses that make you question everything.

Then a few days later, you’re knee-deep in functions you didn’t write, variables that seem to name themselves, and imports from packages you never meant to use. One small change breaks three files. You scroll through the diff wondering who wrote this mess. Spoiler: it was you — and your AI.

I use Augment Code mostly, but honestly, this happens with every tool. The moment you hand over the steering wheel, AI does what it does best — over-generate. It tries to impress you with completeness, not clarity.

That’s when I flipped the workflow.

Instead of saying, “write me this feature,” I started saying, “here’s the test — make it pass.”

Suddenly, everything changed. The AI stopped building castles and started laying bricks.

When you write the tests first, you define the boundaries. You decide what “done” means. The AI only fills in the minimum needed to make the tests go green. It doesn’t have permission to invent architecture. You stay in control.

This is just test-driven development (TDD), but with a twist: the AI is your junior developer. You write intent; it writes implementation.

And the result? Not just leaner code — well-tested code.

Every piece the AI touches has a corresponding test. You don’t end up with half-baked helpers or random abstractions. You end up with code that behaves exactly as you specified — and a test suite that proves it.

Funny how things come around. TDD started as a discipline for human developers decades ago — a way to enforce thoughtfulness and quality. Who knew it would become the perfect antidote to AI code chaos in 2025?

Sometimes I even take it a step further and ask the AI to suggest the tests before I refine them. It’s a nice warm-up — like brainstorming edge cases before getting serious. You could call that the zeroth step. Maybe I’ll write about that next.

For now, try this:

The next time you reach for your coding assistant, don’t ask it to build something.

Write a failing test. Then tell the AI, “Make this pass.”

You’ll get cleaner code, stronger tests, and maybe — for the first time — a sense that you’re the one driving again.

One part of you just wants to build.

To open the editor, follow your curiosity, and see something real come alive on screen.

That’s the vibe coder in you — the part that moves fast, trusts intuition, and believes momentum creates clarity.

Then there’s the other voice.

The one whispering about tests, migrations, rate limits, and all the invisible things that keep production from burning down.

That’s the engineer in you — the part that’s seen systems crumble and knows “we’ll fix it later” often means “we’ll fix it never.”

Most of us swing between the two.

Too much vibe, and your SaaS turns into a spaghetti monster that terrifies future you.

Too much discipline, and you’ll design yourself into paralysis before your first user ever logs in.

The balance isn’t about finding the perfect middle ground — it’s about timing.

Phase 1: Vibe for Momentum

When you’re starting, you don’t need architecture.

You need proof. Proof that the idea resonates, that the workflow feels good, that you can sustain your own interest long enough to see it through.

Ship something messy.

Inline CSS. Hardcoded configs. A Docker Compose file running on your laptop.

If it helps you learn or get feedback faster, it’s good enough.

At this stage, your goal is to find the pulse of your product — the heartbeat that makes it worth polishing later.

Phase 2: Add Discipline for Survival

Once someone uses it — or worse, depends on it — your job changes.

You’re no longer hacking; you’re maintaining.

That’s when guardrails matter.

Not enterprise-level bureaucracy, but the indie essentials:

rate limits, structured logs, CI checks, and a migration plan that won’t kill your data.

Each layer of success earns another layer of discipline.

That’s how you scale without killing your momentum.

The Indie Balance

Vibe coding isn’t reckless.

It’s how you get to momentum.

But discipline is how you keep it.

The real art of indie software isn’t just writing good code.

It’s knowing when to write which kind of code.

TL;DR:

You start as an artist. You evolve into an engineer.

The trick is not to silence either voice — just let them take turns driving.

And maybe we are — for now. But something odd has been happening lately.

As I’ve spent more time training, prompting, and poking large language models, I’ve started noticing… echoes.

Not just in their outputs. In their behaviours.

In the way they learn.

In how they fail.

In how they improve.

And in the way they pretend.

It started as a metaphor.

Now I believe it’s more than that:

Our brains are wetware LLMs.

Training and the Loop

If you’ve ever trained a model — or even just used one through an API — you start to internalize a rhythm.

1. Feed it examples.

2. Check the outputs.

3. Reinforce the good.

4. Penalize the bad.

5. Repeat until it improves.

This isn’t just machine learning.

This is how we learn everything.

When I was younger, trying to improve my Carnatic violin playing, I’d follow the same loop.

Play the swara.

Notice the sour note.

Replay.

Adjust fingering/intonation.

Rinse/Repeat.

Eventually, the feedback loop got shorter. The ear began correcting the hand before the mind even intervened.

That’s tuning.

Or when I’m studying fiction — I don’t just read Dean Koontz or Lee Child. I type out their stories, word for word. A practice technique suggested by prolific writer Dean Wesley Smith.

Copying wasn’t plagiarism. It was pretraining.

You learn cadence by mimicry. You learn structure by absorption.

And then, one day, you surprise yourself with an output that feels original — but you know, deep down, the gradient came from somewhere.

Model Behaviours We Share

Here’s the eerie part: the more you work with LLMs, the more human they feel — not in consciousness, but in quirks.

1. Overfitting

LLMs that are fine-tuned too aggressively on narrow data start parroting it — losing flexibility.

So do we.

Ever meet someone who mastered one domain and can’t unlearn their habits when switching fields? That’s human overfitting.

2. Hallucinations

LLMs generate plausible nonsense when unsure. So do we.

In meetings. On first dates. During interviews.

Confidence is not the same as correctness — for both machines and minds.

3. Context windows

LLMs can only “see” a certain number of tokens at once.

So can we.

Ever walk into a room and forget why you went in? That’s a context window shift. Our attention span — bounded. Our memory — fallible.

But we can prime our context deliberately — by journaling, outlining, visualizing. Just like how you “prompt” a model better when you include prior examples.

4. Personas

LLMs can be given system prompts to behave a certain way: “Act like a Shakespearean actor”, “You are a helpful Linux admin”, “You’re a snarky writing coach”.

We do this too. We wear masks.

We speak differently at work than at home.

We switch from teacher mode to student mode.

We code-switch, dialect-shift, self-filter.

These personas aren’t fake.

They’re fine-tuned subsets of ourselves, optimized for task and audience.

Do Some Brains Have More Parameters?

Sometimes I wonder: if we stretch the metaphor, do people have different “parameter counts”?

Do some folks just have more neurons wired up, more memory bandwidth, more raw capacity?

Maybe.

But LLMs remind us: parameter count isn’t destiny.

It’s how you train.

What you expose yourself to.

What feedback you seek.

How often you iterate.

Even the largest models are dumb if they’ve been trained on trash.

And even a small model — carefully fine-tuned on the right data, guided with the right prompts — can outperform giants.

Same with people.

We’ve all met someone who had every advantage and squandered it.

We’ve all met someone else — less formally educated, less polished — who radiated clarity and depth because they trained deliberately.

It’s not about who has the most parameters.

It’s about who’s still in the loop.

LLM attributes as Human Metaphors

Zero-shot vs Few-shot Learning

A child touching a hot stove once? Few-shot learning.

Reading five flashcards before a quiz? Few-shot.

Encountering a new idea and making sense of it because of prior abstractions? That’s zero-shot. That’s transfer.

Prompt Injection

Ever been influenced mid-conversation and changed your tone? That’s human prompt injection.

Context hijacks our behaviour more often than we care to admit.

Temperature

High-temperature models generate more creative outputs.

People too. Under constraints, some freeze(forgive the pun!). Others improvise. Your internal “temperature” — mindset, mood, caffeine level — changes how you think.

Loss function

For models, it’s a calculated gradient.

For us, it’s regret. Embarrassment. The wince of feedback.

Pain and fear are our backpropagation signals.

Where do we excel?

But for all the parallels, there are crucial ways our brains still outclass even the largest models.

LLMs don’t want anything. They don’t have drive, curiosity, fear, embarrassment, or delight. They don’t learn unless someone forces them to. They don’t decide to improve. We do.

We seek out the loop. We care when we’re wrong. We revise because we want to get better, not because we’re re-trained on a new batch.

We remember emotionally. The sting of failure. The warmth of praise. The embarrassment of a bad take in public. That visceral encoding is something no model has.

We can self-direct. A model doesn’t wake up one day and say, “I think I need to get better at analogies.” But we do. We read something brilliant and feel inspired. We listen to a master and feel the gap. That’s not loss minimization. That’s ambition.

We generalize across domains in weird, leaky, beautiful ways. A lesson in Carnatic violin may improve our writing cadence. A novel may shape how we manage teams. We mix metaphors, break schemas, leap categories. LLMs struggle with that. They interpolate. We cross-pollinate.

We also choose our training data. We can decide what to consume, who to listen to, what to believe. We can uninstall toxic sources. Curate higher quality inputs. Reinforce the patterns we want to keep.

And unlike static models, we have agency over our fine-tuning. We can say: I don’t want to respond that way anymore. I don’t want to be that version of myself. And we can go train a better one.

A model may freeze its weights. But we don’t have to.

We’re wetware — always learning, always plastic, always in the loop.

It sounds impressive. Until you realize “full stack” is just corporate for “three jobs, one salary, no support.”

The original promise of full stack was noble: break down silos, build end-to-end features, own your code. But somewhere along the way, it mutated. Now it means you’re responsible for everything from designing the API schema to fixing the div that renders weird on IE11. Oh, and could you also write some Terraform while you’re at it?

Let’s be honest: in 2025, “full stack” mostly means “we can’t afford to hire a team, so here’s a to-do list that spans five specialties.”

But here’s the twist: I still think you should aim for T-shaped skills. Just not the way HR thinks you should.

Because here’s what’s changed: we’ve now got an army of AI copilots ready to autocomplete half your job—badly. They’ll hallucinate types, suggest incorrect regex, and cheerfully rename your variables while subtly breaking the logic.

If you want to survive this stack, you need to know enough frontend, backend, infra, and AI prompt engineering to know when the machine is lying to you.

Being “T-shaped” doesn’t mean you’re an expert in everything. It means you can go deep where it matters (ideally in your core domain), and navigate the rest well enough to not get wrecked. It means you know when to trust ChatGPT’s code suggestion, and when to back away slowly and grep the logs yourself.

In other words: it’s no longer “full stack vs backend vs frontend.” It’s humans who can collaborate with AI vs humans who are about to get buried in merge conflicts and synthetic bugs.

So yeah, full stack as a job description might be a scam. But being versatile? That’s survival.

Especially if your AI sidekick starts suggesting you replace your Postgres schema with a single JSON blob. Again.

Source that inspired this post:

An error occurred.

Unable to execute JavaScript.

I was surrounded by all the tools that are supposed to make me faster, smarter, more efficient—ChatGPT in one tab, Cursor humming in the IDE, Claude on standby for the longer stuff—and somehow… I had spent the entire week refactoring a feature that hadn’t shipped.

Not building. Not testing. Just circling the drain of “making it better.”

That’s when it hit me—not like lightning, but like a slow, shameful realization:

If you’re not shipping weekly, you’re not taking advantage of AI. You’re just bikeshedding with fancier tools.

The New Age of Productive Procrastination

We used to say we couldn’t move fast because the tools were slow. Hard to deploy. Annoying to configure. Models too dumb. Infra too brittle.

Now?

We’ve got tools that can scaffold your backend, write your tests, spin up a UI, generate your changelog, draft your release notes, and create your launch tweet — all before lunch.

So what do we do?

We spend two hours arguing with GPT5 about the tone of our 404 page.

AI hasn’t just made us faster. It’s made us better at procrastinating. We can now fine-tune our mediocrity at lightning speed. Polish things that don’t matter. Add “clever” touches no one asked for. Debate prompt styles like they’re sacred texts.

It’s amazing. It’s also a trap.

Your Fancy Setup Doesn’t Matter If Nothing Ships

Every dev team and weekend hacker has access to the same models now. Same open weights, same frameworks, same “build an agent” tutorials.

But some teams are shipping on Fridays.

Others are still fiddling with prompt chains.

The difference isn’t in talent. It’s in rhythm.

Shipping frequently is the new moat. Not because it makes you look good on Twitter, but because the ground underneath is moving. Fast.

A month of “thoughtful planning” can kill your idea before it meets the real world.

But What If It’s Not Ready?

It won’t be.

It never is.

You’ll always want to refactor one more function. Tune one more embedding. Rename one more internal config. You’re not alone — I’ve been there. I still go there, a little too often.

But here’s what I’ve learned the hard way: Nothing improves faster than something you’ve already shipped.

You can’t get feedback on a figment. You can’t iterate on invisible.

A Week Is Enough (Even If It Feels Too Short)

Weekly shipping is a forcing function. It makes you prioritize what’s real over what’s “clever.” It exposes what matters to users versus what just looks impressive in dev chat.

If I can’t scope something to ship in a week, chances are I’m biting more than I can chew.

Some weeks it’s a feature. Some weeks it’s cleanup. Some weeks it’s a one-line fix with a changelog that makes me cringe. That still counts. That’s progress.

The Real Timeline of One Shipping Week

• Monday: Noticed my onboarding sucked

• Tuesday: Asked ChatGPT to rewrite it (it made it worse, then better)

• Wednesday: Wired up telemetry to track rage clicks

• Thursday: Built a barely-working feedback button

• Friday: Hit deploy. Apologized in advance. Sent it to users anyway.

No magic. Just momentum.

The Ironic Truth

AI is supposed to be a productivity multiplier.

But if you let it, it’ll multiply your perfectionism. Your indecision. Your procrastination.

You’ll feel productive while achieving nothing. Like a hamster with a prompt window.

And the worst part? It feels like work. It’s dangerously satisfying.

Which is why now, more than ever, we need to build muscle around shipping, not just building.

In 2007, PHP creator Rasmus Lerdorf said, “PHP is about as exciting as your toothbrush. You use it every day, it does the job, it is a simple tool, so what? Who would want to read about toothbrushes?”

That’s the thing about good tools — they’re boring when used well. You don’t marvel at your toothbrush every morning. You just get on with it.

AI tools should be the same. Invisible. Unremarkable. Part of the rhythm.

Ship first. Marvel later.

So What Now?

Set the bar low. Something new every week.

Doesn’t have to be earth-shattering. Just real. Just live. Just something you can point to and say, “I learned something from this.”

The ones who keep shipping — even small things — are the ones who win this cycle.

Not because they outsmarted the world. But because they stopped arguing with their tools and started using them.

Except… not.

The Great Context Collapse

What actually happened looked more like watching someone try to drink from a fire hose. The AI took my massive input, nodded politely, and then gave me:

• Answers that had nothing to do with my question

• Vague “advice” that could apply to literally any project

• Confident but wrong takes on my(??) code

• References to functions that didn’t even exist

To be clear: this wasn’t a problem with KiloCode itself. It was my fault. I drowned the poor thing.

And yes, the reason I had a 5,000-line Python file in the first place? That’s on me too. I just kept bolting on features without a proper review. One fine day, I looked up and realized the file had become unreadable. But that disaster deserves its own post.

What’s Going On Under the Hood

AI coding assistants only have so much “working memory” — a context window. When you shove 5,000 lines of code at them, a few things happen:

• You blow most of the available window right away

• Your actual question gets buried under noise

• The model has to guess what’s important in the pile

• There’s less room left for follow-up questions

It’s like asking someone to find a single paragraph in a book, then dumping an entire library on their desk and saying, “good luck.”

The Counterintuitive Truth

The less code you show your AI assistant, the better it performs.

I’ve found the sweet spot is usually 200–500 lines. Enough to give context, not so much that the model chokes.

How to Work Smarter With AI Code Assistants

1. Split files by module or function

   Don’t dump an entire repo. Just pull out the piece you care about:

“I need help optimizing this authentication middleware function:”

[paste 50–100 lines here]

2. Summarize bigger pieces

   Let the AI help you write summaries of large sections. Then use those summaries as context alongside the small chunk you actually care about.

3. Scope your questions

   Bad: “Here’s my whole app, how can I improve it?”

   Better: “Here’s my caching function. How can I reduce memory usage while keeping O(1) lookups?”

4. Go iterative

   Smaller chunks make conversations faster. You can go back and forth ten times in the same time it takes to chew through one giant code dump.

It’s basically code review etiquette. Nobody wants to wade through a 5,000-line pull request. Smaller, focused changes are easier to reason about — for humans and for AI.

The most useful “prompt engineering” trick I’ve learned isn’t about clever phrasing. It’s about context discipline. Show the AI just enough. Hide the rest.

Next time you’re tempted to paste your whole project in, remember: you’re not giving the model more to work with — you’re giving it more to drown in.