MOST PEOPLE USE CLAUDE CODE LIKE A CHATBOT. IT'S ACTUALLY A FULL OPERATING SYSTEM FOR AI AGENTS.

Cover image

I watched a developer build an entire project in Claude Code on stream. No slides, no theory. Just the terminal. And at some point I realized: I've been using maybe 15% of this tool for six months.

Not because the features are hidden. They're right there. It's just that most of us install Claude Code, type a prompt, get an answer, and never go deeper. We treat it like a smarter autocomplete. Meanwhile the actual architecture underneath is six layers deep, and each layer you turn on changes what the tool can do in a way that's hard to overstate.

Here's every layer, what it does, and why skipping it costs you more than you think.

If you're into dev tools, AI and the kind of setups that give you a real edge before everyone else catches on, follow me. I share alpha on this stuff regularly.

Layer 0: The loop

Before the features, understand the engine.

Claude Code is not a chatbot. It's a while loop. It gets a task, picks a tool (file read, bash command, web search, MCP call), runs it, looks at the output, decides what to do next, and keeps going until the task is done or it needs your input.

That loop is the reason everything below works. Skills, hooks, subagents, MCP servers. They all plug into different stages of that loop. If you think of Claude Code as "I type, it responds," you'll never see why these features matter. If you think of it as "I give it a job, it runs a loop until the job is done," the whole architecture clicks.

Layer 1: CLAUDE.md. Your project's constitution.

This is the file Claude reads at the start of every session. It lives in your project root. It tells Claude who it is, what rules to follow, and how your project works.

Most people either skip it entirely or dump everything they can think of into it. Both are wrong.

A good CLAUDE.md is short. Under 500 tokens. It contains only the rules Claude would otherwise get wrong. If Claude already does something correctly without being told, don't write it down. You're wasting context.

What belongs here:

Language and framework conventions ("we use Pydantic v2, not v1")
File structure rules ("never edit files in /generated")
Testing requirements ("run pytest before saying done")
Style constraints ("all functions need type hints")

What doesn't belong here:

Long workflows (put those in skills)
Automation rules (put those in hooks)
Research procedures (put those in subagents)

The practical test is simple. If the instruction must be true for every single turn of every session, it goes in CLAUDE.md. If it only matters sometimes, it belongs somewhere else.

One more thing. If your CLAUDE.md is longer than ~60 lines, Claude starts ignoring parts of it. Not because it can't read. Because important rules get lost in the noise. Prune ruthlessly.

Layer 2: Skills. Domain knowledge that loads on demand.

A skill is a SKILL.md file inside .claude/skills/<name>/. It has frontmatter (name, description, optional tools allowlist) and a body with instructions, patterns, or checklists.

The key difference from CLAUDE.md: skills load only when relevant. Claude reads the description, decides if the current task matches, and pulls in the skill body only when it needs it. This is progressive disclosure. Your context stays clean until the moment domain knowledge is required.

Examples of good skills:

A deployment checklist ("here's how we ship to production")
A migration guide ("here's how we handle database migrations")
A PR review template ("check these 8 things before approving")
A debugging playbook ("when tests fail in CI, check these things first")

The rule of thumb: if you've typed the same instructions to Claude twice, that should have been a skill the first time. Skills are reusable knowledge. CLAUDE.md is permanent rules. Don't confuse them.

You can also invoke skills explicitly with slash commands (/skill-name), or let Claude pick them up automatically based on the task description. Both work.

Layer 3: Hooks. Automation that never forgets.

This is where most people's setup stops. And it's where things get interesting.

A hook is a script that fires automatically at specific points in Claude's workflow. Before a tool runs. After a tool runs. When a session starts. When Claude is about to stop. When a subagent finishes.

The critical difference between hooks and CLAUDE.md instructions: CLAUDE.md is advisory. Claude might follow it, might not. Hooks are deterministic. They run as code. If you write a hook that blocks writes to /migrations, that directory is locked. Period. No amount of prompt engineering can override it.

Three hooks worth setting up on day one:

**1. Auto-format after edits.**Every time Claude edits a file, the hook runs your formatter (prettier, black, rustfmt). You never review unformatted code again.

**2. Block dangerous commands.**A pre-tool hook that intercepts bash commands and blocks anything matching a pattern (rm -rf, DROP TABLE, force pushes). Safety net for auto mode.

**3. Run tests before "done."**A stop hook that runs your test suite before Claude declares a task complete. If tests fail, Claude keeps working. This single hook eliminates the most common failure mode: code that looks right but doesn't run.

You can set hooks up manually in .claude/settings.json or just ask Claude to do it: "Write a hook that runs eslint after every file edit." Claude writes the hook for you.

There are 17 hook events total. Most projects need 2 or 3. Don't overthink it. Start with the three above.

Layer 4: MCP servers. Connecting Claude to everything else.

MCP (Model Context Protocol) is how Claude Code talks to external tools. A GitHub MCP server lets Claude read issues, create PRs, check CI status. A database MCP server lets Claude query your tables directly. A browser MCP server lets Claude scrape pages and read documentation.

The setup is one command:

claude mcp add <name> <url>

That's it. The MCP server appears as a set of tools Claude can use in its loop. Read issues from Linear. Post to Slack. Query your Postgres database. Check monitoring dashboards. Pull designs from Figma. The tool landscape is expanding fast because MCP is an open protocol and every serious product is shipping a server.

The practical impact: Claude stops being a tool that only sees your local files. It becomes a tool that sees your files, your tickets, your database, your CI pipeline, your documentation, and your monitoring. All in the same context. All in the same loop.

What matters here is not any individual integration. It's the compound effect. Claude reads the failing test, queries the database to check the schema, looks at the relevant GitHub issue for context, fixes the code, runs the tests, and posts a summary to Slack. One prompt. One loop. Five tools.

Without MCP, you're alt-tabbing between all of those yourself. Sound familiar?

Layer 5: Subagents. The context window problem, solved.

This is the feature that changed how I use Claude Code.

Here's the problem: context windows fill up. After an hour of research, writing, and editing, Claude has consumed so much context that it's forgotten what you researched at the start. Auto-compaction helps but it's lossy. Important details disappear.

Subagents solve this by splitting the work. A subagent gets its own fresh context window, its own tool access, its own instructions. It does a bounded task and returns a result. Your main conversation stays clean.

Claude Code ships with three built-in agents:

Explore (uses Haiku, fast and cheap, read-only, fires when you ask "where is X?")
Plan (inherits your model, read-only, used in plan mode for research)
General-purpose (full tool access, for complex delegated tasks)

But the real power is custom agents. They live as markdown files in .claude/agents/:

---
name: researcher
description: Deep web research on any topic
tools: WebSearch, WebFetch, Read, Glob, Grep
model: sonnet
mcpServers:
  - perplexity
  - firecrawl
---

You are a research specialist. Search thoroughly,
cite sources, and return structured findings.

Now when you say "research the latest changes to the OAuth 2.1 spec," Claude spawns the researcher agent in its own context. The research happens in isolation. Your main context stays clean. The findings come back as a structured report.

The mental model: subagents are specialists you hire for specific jobs. The main Claude Code session is the manager that coordinates them. The manager doesn't need to hold all the research, all the reviews, and all the implementation details in its head at once. It delegates.

When to use subagents:

Research tasks that would consume too much context
Code review (let a review agent check the diff in isolation)
Security audits
Documentation generation
Any task where the intermediate work is bulky but the result is compact

Layer 6: Plugins. Everything bundled together.

Plugins are the newest layer. A plugin bundles skills, hooks, subagents, and MCP servers into one installable unit. Run /plugin to browse the marketplace.

Instead of manually configuring each layer for a common workflow, you install a plugin and get the whole stack. A code intelligence plugin gives Claude precise symbol navigation and automatic error detection after edits. A deployment plugin gives Claude the skills, hooks, and MCP connections to ship your code.

Think of plugins as "best practice bundles." Someone figured out the right combination of skills, hooks, and agents for a specific workflow, packaged it, and shared it. You install it in one command.

The pattern that ties it all together

The real workflow isn't "type a prompt, get an answer." It's this:

Research  →  Plan  →  Execute  →  Review  →  Ship

And every Claude Code feature maps to one of those stages:

Stage        Feature
Research     Subagents (isolated context, web search, docs)
Plan         Plan mode, CLAUDE.md constraints
Execute      Skills, MCP servers, bash, file editing
Review       Hooks (auto-test, auto-lint, auto-format)
Ship         Hooks (pre-commit checks), MCP (CI/CD, PRs)

Most people only use the Execute stage. They type "build this feature" and let Claude go. That works for small tasks. For anything non-trivial, you need the full loop. And the full loop only works when the layers are set up.

Where to start if you've been using Claude Code "naked"

Don't try to set up everything at once. Here's the order that gives you the most impact per minute invested:

Week 1: Write a short CLAUDE.md (under 60 lines). Add your project conventions, testing requirements, and file structure rules.

Week 2: Add three hooks. Auto-format after edits. Block dangerous commands. Run tests before stopping.

Week 3: Connect 1 or 2 MCP servers. Start with GitHub and whatever your team uses for tickets.

Week 4: Create one custom subagent for research. Point it at a web search MCP server. Use it instead of doing research in your main context.

After that: Build skills for any workflow you've explained to Claude more than once. Install relevant plugins. Iterate.

Each step takes 10 to 15 minutes. The compound effect after a month is dramatic. You go from "chatbot in a terminal" to a fully orchestrated agent system that researches, plans, executes, reviews, and ships. On its own. While you focus on the decisions that actually need a human.

Conclusion

Claude Code is powerful when configured. It's also easy to over-configure. A bloated CLAUDE.md that Claude ignores. Twelve MCP servers you never use. Subagents for tasks that fit in the main context just fine. Hooks that slow down every edit.

The right setup is the smallest setup that solves your actual problems. Start lean. Add a layer when you feel the pain it solves. Not before.

And one more thing: Claude Code is not magic. It's an agent with tools. It makes mistakes. It hallucinates file paths. It writes code that compiles but doesn't do what you asked. The hooks and review layers exist precisely because the execution layer isn't perfect. The value isn't that Claude gets everything right. The value is that the loop catches errors before you do.

The alpha is here before it's everywhere else.