Advanced Claude Code: CLAUDE.md, Sub-Agents, MCP, and Atomic Prompts

The most expensive tool is the one you use wrong

When I tell someone I cut per-task costs in Claude Code by ~60% without sacrificing quality, the first thing they ask is whether I switched models or capped usage.

No. I learned how to configure it properly.

Claude Code is one of the most powerful AI agents for software development out there today. But most developers use it like a chat with superpowers. That's like buying a Ferrari and driving it in second gear.

In this tutorial I'll show you exactly how I set it up, with real examples from the setup I use in my projects.

---

1. CLAUDE.md: Your permanent context

This is the single biggest difference between a casual and an advanced Claude Code user.

The problem: Every Claude Code session starts from scratch. Without saved context, the agent has to guess or ask you things it should already know: your stack, your architecture, your conventions, your business rules. That's wasted tokens before a single productive line of code gets written.

The solution: A CLAUDE.md file at the root of your project.

# Create the file
touch CLAUDE.md

This file is automatically loaded in every session. It's your permanent context. Everything Claude needs to know about your project lives there.

What to include in your CLAUDE.md

A good CLAUDE.md answers these questions before the agent even asks:

# CLAUDE.md

## Tech stack

- Framework: Next.js 16 with App Router
- Styling: Tailwind CSS + shadcn/ui
- Package Manager: pnpm
- Database: PostgreSQL with Drizzle ORM

## Architecture

- Feature-based with Atomic Design
- Strict SOLID principles
- Server Components by default, Client only when necessary

## Key commands

- `pnpm dev` → development server
- `pnpm build` → production build
- `pnpm db:migrate` → run migrations

## Critical conventions

- NEVER use dangerouslySetInnerHTML
- Always validate inputs on the server
- Adapters abstract external libraries (see /src/adapters)

## Directory structure

src/
├── adapters/ # External library wrappers
├── components/ # Atomic Design (atoms/molecules/organisms)
├── features/ # Feature-based modules
└── hooks/ # Custom React hooks

Real-world impact: With a well-configured CLAUDE.md, every session starts with the agent already oriented. No unnecessary questions, no wrong assumptions, no tokens wasted "discovering" what it already knows.

CLAUDE.md for the user directory

You can also have a global ~/.claude/CLAUDE.md with preferences that apply to all your projects:

# Global preferences

## Communication style

- Concise, direct responses
- No emojis unless I use them
- Code references in file:line_number format

## Language

- Code and technical comments: English
- Communication: Spanish

## Preferred tools

- Package manager: pnpm (never npm or yarn)
- Tests: Vitest + Testing Library

---

2. Sub-agents: Divide and conquer

This is the most important paradigm shift when you scale your use of Claude Code.

The "giant prompt" problem: Asking Claude to research, implement, refactor, and test everything in a single message is inefficient. Context gets polluted, the agent loses the thread, and errors cascade.

The solution: Specialized sub-agents using the Task tool.

Claude Code can launch sub-agents that work autonomously on specific tasks. Each agent gets its own clean context and a defined responsibility.

How sub-agents work

Your main task
    ├── Explorer Agent → Investigates the codebase, maps dependencies
    ├── Implementer Agent → Writes the code based on the plan
    └── Reviewer Agent → Verifies there are no errors or regressions

Each agent works in parallel when tasks are independent, or sequentially when there are dependencies.

Practical example

Instead of writing:

"Investigate how the authentication system works, then add support for OAuth with Google, make sure the tests pass, and update the documentation."

Structure it like this:

1. Task 1 (Explore): Map the current auth system, identify key files, and return a summary.
2. Task 2 (Plan): With the Explore context, design the OAuth implementation.
3. Task 3 (Bash/Implement): Implement the approved plan.
4. Task 4 (Bash): Run the tests and validate.

Result: Fewer tokens wasted on re-orientation, more concrete output per session.

---

3. Custom Skills

Skills extend what Claude can do. You create a SKILL.md file with instructions and Claude adds it to its toolkit. You can invoke them manually with /skill-name, or Claude uses them automatically when it considers them relevant to the context.

Structure of a Skill

Each skill is a directory with a SKILL.md as its entry point. There are two scopes:

# Personal skill — available across all your projects
mkdir -p ~/.claude/skills/create-component

# Project skill — this repository only
mkdir -p .claude/skills/create-component

The SKILL.md has two parts: YAML frontmatter between --- that configures when and how it's invoked, and the markdown content with instructions Claude will follow.

# .claude/skills/create-component/SKILL.md
---
name: create-component
description: Creates React components following Atomic Design. Use when the user asks to create a new UI component.
disable-model-invocation: true
---

Create a React component following the project's Atomic Design architecture.

1. Determine whether it's an Atom, Molecule, or Organism based on complexity
2. Create the folder in `src/components/[level]/[Name]/`
3. Required files:
   - `ComponentName.tsx` → Main component
   - `index.ts` → Barrel export
4. Server Component by default. `'use client'` only if you need state or browser APIs
5. Always import external dependencies via adapters: `@/adapters`

Do not import directly from `lucide-react`, `next/image`, or `next/link`.
Do not use `dangerouslySetInnerHTML`.

Now you simply type /create-component instead of explaining all of this every time.

The disable-model-invocation field

By default, Claude can invoke a skill automatically when the context suggests it. disable-model-invocation: true tells it that only you trigger it manually. Use this for skills with side effects like /deploy, /commit, or /send-message — you don't want Claude deciding to deploy because the code "looks ready."

Skills with arguments

Use $ARGUMENTS to pass parameters when invoking the skill:

# .claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: Fixes a GitHub issue by number
disable-model-invocation: true
---
Fix issue $ARGUMENTS following the project's conventions.

1. Read the issue description
2. Implement the fix
3. Write the tests
4. Create a commit

You invoke it with /fix-issue 123 and Claude receives "Fix issue 123 following the project's conventions."

---

4. MCP: Connect Claude to your real systems

MCP (Model Context Protocol) is the protocol that lets Claude connect to external systems: databases, APIs, third-party tools, your own code.

Without MCP: Claude has to imagine the context. It asks you to paste your database schema, copy an API response, or show it the error logs.

With MCP: Claude reads directly. It queries your DB, calls your API, checks your logs.

Setting up MCP

The configuration file lives in ~/.claude/claude_desktop_config.json (Claude Desktop) or in the Claude Code settings:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost/mydb"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

MCPs I use in production

For web development:

• @modelcontextprotocol/server-filesystem → Reads and navigates the project
• @modelcontextprotocol/server-postgres → Queries the DB directly
• @modelcontextprotocol/server-github → Manages issues, PRs, code review

For productivity:

• Notion MCP → Claude can read and write to your Notion workspace
• Linear MCP → Manages tickets directly from Claude Code

If you're already using LLMs in production and want to understand how to properly integrate them into enterprise workflows, I recommend reading Integrating LLMs into enterprise workflows.

Real-world use case

With the PostgreSQL MCP configured, instead of telling it:

"I have a users table with these columns: id, email, created_at, role... I want you to help me..."

You simply say:

"Check the users table schema and create an optimized query for..."

Claude queries the DB, sees the actual schema, and works with real information instead of assumptions.

---

5. Atomic prompts: One task, one prompt

This is the golden rule with the biggest impact on per-task cost.

The problem: Vague or compound prompts generate long responses, retries, and corrections that double token consumption.

The solution: One prompt = one clear, scoped task.

Anatomy of an atomic prompt

[Necessary context] + [Specific action] + [Success criteria]

Before (vague prompt):

"Fix the bugs in the login component and improve the design."

This generates:

• Clarification questions
• Unexpected scope changes
• Possible regressions from unsolicited changes

After (atomic prompt):

"In src/features/auth/components/LoginForm.tsx line 47, the onSubmit handler doesn't clear the error state when the submit succeeds. Add setError(null) at the beginning of the try block. Don't touch any other file."

This generates:

• A precise change
• No side effects
• No unnecessary questions

Atomic prompt checklist

Before sending a prompt, verify:

• Is there a specific file and line? If you can point to exactly where, do it.
• Is the action a single thing? "Fix Y" is atomic. "Fix Y and improve Z" is not.
• Did you say what not to touch? Adding "don't modify any other file" prevents unsolicited changes.
• Is it clear when it's done? "Test X should pass" or "the component should render without errors" are concrete criteria.

---

The compound effect

None of these techniques alone gives you a 60% reduction. It's the combination:

• CLAUDE.md eliminates the orientation cost at the start of every session
• Sub-agents eliminate context pollution in complex tasks
• Skills eliminate repetition of complex instructions
• MCP eliminates the cost of copy-pasting external context
• Atomic prompts eliminate iterations caused by ambiguity

With everything configured, every token you spend is a token that produces value.

---

Where to start

If all of this feels like a lot, here's an implementation order with the best impact-to-effort ratio:

1. Week 1: Create your CLAUDE.md. Just documenting your stack and main conventions already makes a noticeable difference.

2. Week 2: Identify the 3 task types you repeat most and create a Skill for each one.

3. Week 3: Set up 1 or 2 MCPs. The filesystem one is actually included by default. Add the one for your database if you have access.

4. Week 4: Experiment with sub-agents on the next complex task you have.

The result isn't just paying less for the same output. It's delivering 10x more with the same budget.

---

Resources to keep going

• Official Claude Code documentation
• Official MCP server repository
• CLAUDE.md guide

---

Have you set up your CLAUDE.md yet? Are you using sub-agents, or still asking for everything in a single message? Let me know on LinkedIn.

---

If you want to keep growing as an engineer in the AI era, don't miss the list of the 12 books that separate the programmer AI replaces from the one AI empowers.