Your .claude/ Folder Is a Production Agent

You already know how to build production AI agents. You just didn't know it counted.

Last week I ran a spike. Same CLAUDE.md, same skills, same MCPs, same hooks I write every day in Claude Code — pointed at a Next.js app. Shipped a working Knowledge Chatbot in an afternoon. No new framework. No Claude Managed Agents. Zero files I hadn’t written a dozen times before.

Everyone's covering agents helping you build or do knowledge work. The pattern nobody's shipping: the same primitives are the production runtime.

What you’ll learn:

• The Claude Code primitives that double as a production runtime

• When to pick the Agent SDK over Claude Managed Agents or a framework

• The architecture — one function call replaces an n8n-style workflow

• A full working demo: source code, build prompt, hosting notes

• The gotchas that silently break things

• How to host your Claude agents in production

---

1. The Missing Pattern — Agent as A Callable Component

Two narratives dominate right now:

• Agents as products. Claude Code, Lovable, Cursor. You use them to code or to do your work.

• Agents as infrastructure. Claude Managed Agents, LangGraph, n8n. You adopt a platform to build them.

The pattern sitting between those two is agent as a callable component inside your app.

How does it work?

Your web app handles routing, auth, CRUD, form validation. When a request needs reasoning, you call the agent — which runs in a sandbox with its own CLAUDE.md, skills, and MCP servers.

This is how microservices work. Nobody builds a monolithic agent. You build an app that calls an agent when it needs one.

The part that surprised me: the same .claude/ folder I've been editing every day for months is the deployable unit. There is no translation layer between dev and prod. The CLAUDE.md that guides Claude Code in your terminal is the exact same CLAUDE.md format that runs in production.

---

---

2. The Primitives You Already Use

Five key things. We've discussed most of them in the previous posts about Claude Code and Cowork:

• CLAUDE.md — the agent’s identity in markdown. Tone, rules, constraints. In dev it shapes how Claude Code behaves in your terminal. In prod it loads as the system prompt of your production agent. Edit the file, ship the behavior.

• Skills (.claude/skills/) — reusable behaviors, also markdown. “When the user asks for a summary, use Glob + Read, produce a structured overview.” Same file format in dev and prod. Same loader.

• MCPs (.claude/mcp.json) — servers that extend the agent’s tool surface. Your dev config probably talks to Chrome and your filesystem. Your production agent’s config talks to your search API and your database. Different servers, identical contract.

• Hooks — functions that fire on tool events. PreToolUse can block dangerous operations (reading .env, path traversal). PostToolUse can log everything the agent read so you can show it in the UI. Five lines of code replace an IF-node-per-tool in any workflow builder.

• Sub-agents (.claude/agents/<name>/) — each directory is a self-contained agent: its own CLAUDE.md, its own skills, its own MCP config, its own docs. Adding a second agent to your product is a new folder.

Sub-agents in Claude Code

Everything is files. Everything is version-controlled. Everything diffs cleanly in a PR. If you've onboarded to Claude Code, you've already onboarded to the production stack.

In case you wondered, here’s a more comprehensive overview:

Claude Code projects

---

---

3. Why This Matters in Production

Here’s how it stacks up against the alternatives most posts point you to:

Agent SDK vs. Managed Agents vs. LangGraph vs. n8n

Four things fall out of this that I didn't expect going into the spike:

• Nothing new to learn. The CLAUDE.md you wrote in dev is the CLAUDE.md that ships. Your muscle memory is already the production runtime.

• You can skip Claude Managed Agents unless you actively need a hosted runtime. For request-response agents inside an app you already host, the SDK is a smaller dependency than a whole platform.

• Full observability without a new vendor. Hooks give you live per-response metadata — cost, duration, files read — for your UI. OTEL exports full traces to Langfuse or any OTLP backend when you want dashboards.

• Same loop, dev → prod. The config you tested in Claude Code is the config running in production. If it worked in your terminal, it works in your app. No mental translation.

For PMs: this is what lets you prototype and ship agent features without becoming a bottleneck. Changing the agent's behavior is editing a markdown file — not a sprint, not a code review, not a redeploy cycle. You iterate on AI behavior at the speed you iterate on a Notion doc.

Now the part most people skip — how you actually wire it up.

---

Keep reading for:

• The full build prompt that scaffolds the app — paste into an empty repo, Claude Code builds the rest.

• The lib/agent.ts wrapper with the TypeScript pitfalls the SDK docs skip

• The postbuild trick that stops production from inheriting your repo’s CLAUDE.md.

• A cloneable demo — Knowledge Chatbot, streaming responses, per-message cost metadata. Full source code.

• The limitations I hit in the spike and the workarounds for each.

• How to host this in production.