Advanced Claude Code

Beyond Basics: Plan Mode, Sub-Agents, and Advanced Claude Code

Article 6 of 9 11 min read

You have installed Claude Code, written prompts that produce working code, and developed a rhythm for reviewing and iterating on AI-generated output. Now it is time to move past the conversational basics and into the machinery that makes Claude Code a genuinely different kind of development tool. This article covers the advanced features, hidden capabilities, and power-user workflows that separate casual usage from high-leverage mastery.

Everything here assumes you are comfortable with Claude Code fundamentals. If terms like context window, tool use, or agentic workflow feel unfamiliar, revisit the earlier articles in this series first.

Plan Mode: Architect Before You Build

Most developers jump straight into asking Claude Code to write or edit files. For small, well-defined tasks, that works fine. But for anything with architectural implications — a new feature spanning multiple files, a refactor that touches shared interfaces, a migration between frameworks — you want Claude to think before it acts. That is what plan mode is for.

Activate it by typing /plan inside a Claude Code session or by pressing Shift+Tab to toggle between plan and act modes. In plan mode, Claude will analyze your request, reason about the approach, and produce a structured plan — but it will not modify any files or run any commands. You get to review the strategy, ask questions, adjust scope, and only then switch back to act mode to execute. 

$ claude
> /plan Refactor the authentication module to use JWTs
  instead of session cookies. The app uses Express with
  a PostgreSQL database.

Claude will:
1. Analyze current auth implementation across middleware,
   routes, and database models
2. Outline the JWT token structure and signing strategy
3. Identify every file that references session-based auth
4. Propose a migration path that keeps the app functional
   at each step
5. List potential breaking changes and rollback strategy

[No files modified — review and approve before executing]

The critical insight is that plan mode does not just save you from bad edits — it changes the quality of the work itself. When Claude reasons through a problem before writing code, it catches dependency issues, identifies edge cases, and produces more coherent multi-file changes. Use plan mode any time a task involves more than two or three files, or when the consequences of a wrong approach would be expensive to undo.

Pro tip: After reviewing a plan, you can refine it by saying "adjust step 3 to preserve backward compatibility" or "add error handling to the migration steps." Iterate on the plan until it matches your intent, then execute.

Extended Thinking: Deep Reasoning on Hard Problems

Extended thinking is Claude's ability to spend more compute time reasoning through a problem before producing a response. In Claude Code, this activates automatically for complex tasks, but you can also influence it by structuring your prompts to demand careful analysis.

When extended thinking engages, Claude works through the problem step by step internally — considering multiple approaches, evaluating tradeoffs, and checking its own reasoning — before committing to an answer. You will notice this as a brief pause followed by a more thorough, considered response. For debugging subtle race conditions, designing system architectures, or reasoning about complex type relationships, extended thinking is the difference between a surface-level answer and a genuinely insightful one.

You can encourage deeper reasoning by being explicit about the complexity: "Think carefully about the concurrency implications before suggesting a fix" or "Consider at least three different approaches and explain the tradeoffs." Claude Code responds to these cues by allocating more reasoning effort to the problem.

Sub-Agents: Parallel Work Streams

One of Claude Code's most powerful features is its ability to spawn sub-agents — independent child instances that handle research, exploration, or isolated tasks in parallel with the main conversation. When Claude determines that a task would benefit from parallel investigation, it launches these agents automatically using its built-in tool capabilities.

For example, if you ask Claude to update a library across your project, it might spawn one sub-agent to search for every import and usage of the old API, another to read the migration guide for the new version, and a third to check your test suite for affected tests. These agents work concurrently, and their findings are synthesized back into the main conversation. 

> Upgrade the project from React Router v5 to v6 and
  fix all breaking changes.

Claude spawns sub-agents:
  ├─ Agent 1: Scanning all files for react-router imports
  │   and usage patterns (Switch, Route, useHistory...)
  ├─ Agent 2: Analyzing route configuration structure
  │   and nested route patterns
  └─ Agent 3: Checking test files for router-dependent
     test utilities and mocks

Main agent synthesizes findings, then executes the
migration with full awareness of every affected file.

You do not need to explicitly request sub-agents — Claude Code decides when to use them based on task complexity. However, you can encourage parallel exploration by framing your request to have naturally separable concerns: "Research the current implementation, check the test coverage, and then propose the refactor" gives Claude clear opportunities to parallelize.

Hooks: Automating Your Workflow

Hooks let you run custom commands automatically before or after specific Claude Code events. They are defined in your project's .claude/settings.json file and execute shell commands at key points in Claude's workflow — when a conversation starts, before a tool is invoked, or after a tool completes. 

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo 'File modification incoming: $CLAUDE_FILE_PATH'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null; exit 0"
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "command": "afplay /System/Library/Sounds/Glass.aiff"
      }
    ]
  }
}

The PreToolUse hook fires before Claude invokes a tool, letting you log, validate, or even gate certain operations. PostToolUse fires after a tool completes — the example above automatically runs Prettier on every file Claude edits, ensuring consistent formatting without Claude needing to think about it. The Notification hook fires when Claude wants your attention, which is useful for long-running tasks where you have switched to another window.

Hooks transform Claude Code from a conversational tool into an automated pipeline. You can run linters after every edit, trigger builds after file changes, send notifications when tasks complete, or enforce custom validation rules. The hook command receives environment variables with context about the event, including the tool name, file paths, and operation details.

Pro tip: Use a PostToolUse hook on Bash commands to automatically capture and log all terminal output to a file. This gives you a complete audit trail of everything Claude executed during a session.

Git Worktrees for Isolated Development

When working on a significant feature or experiment with Claude Code, you do not want to pollute your main working directory. Git worktrees let you check out a separate branch in a different directory while sharing the same repository history. Claude Code has first-class support for this pattern. 

# Create a worktree for your feature branch
$ git worktree add ../my-feature-branch feature/new-auth

# Start Claude Code in the worktree
$ cd ../my-feature-branch && claude

# Or use the built-in command inside Claude Code
> /worktree feature/new-auth

Working in a worktree means Claude can make aggressive changes, run experiments, and iterate freely without affecting your main branch. If the experiment fails, you simply remove the worktree. If it succeeds, you merge it back. This is especially valuable when you want Claude to try a fundamentally different approach to a problem — you can have one worktree for approach A and another for approach B, evaluate both, and keep the winner.

Managing Large Codebases

Claude Code's context window is large but finite. When you are working in a repository with hundreds of thousands of lines of code, you need strategies to help Claude focus on the right files without exceeding context limits.

The CLAUDE.md File

The single most impactful thing you can do for large projects is maintain a well-crafted CLAUDE.md file at your repository root. This file is automatically read by Claude Code at the start of every session and acts as persistent project memory. It should contain the information Claude needs to work effectively without reading every file in the project. 

# CLAUDE.md

## Project Overview
E-commerce platform — Next.js 14 app router, TypeScript
strict mode, PostgreSQL via Prisma ORM, Redis for caching.

## Architecture
- /src/app — Next.js app router pages and layouts
- /src/lib — Shared utilities, database client, auth helpers
- /src/components — React components (co-located with tests)
- /src/services — Business logic layer (never import from app/)
- /prisma — Database schema and migrations

## Conventions
- All components use named exports, no default exports
- API routes return { data, error } shape consistently
- Database queries live in /src/services, never in components
- Use server actions for mutations, not API routes
- CSS: Tailwind only, no inline styles, no CSS modules

## Commands
- `npm run dev` — Start dev server on port 3000
- `npm test` — Run Jest tests (--watch for dev)
- `npm run typecheck` — TypeScript strict check
- `npm run db:migrate` — Run Prisma migrations
- `npx prisma studio` — Open database GUI

## Current State
- Auth system uses NextAuth with Google + GitHub providers
- Payment integration is Stripe (test mode keys in .env.local)
- Search is backed by a PostgreSQL full-text index, no Elastic
- The /admin routes are behind middleware role checks

Notice that this file is concise and structured. It tells Claude the tech stack, where things live, what conventions to follow, and how to run common operations. A good CLAUDE.md eliminates entire categories of mistakes — Claude will not suggest CSS modules if you have told it the project uses Tailwind only, and it will not put database queries in components if the architecture section makes the service layer clear.

Nested CLAUDE.md Files

For monorepos or large projects with distinct subsystems, you can place additional CLAUDE.md files in subdirectories. Claude Code reads these when it navigates into that directory, layering the context on top of the root file. A /packages/api/CLAUDE.md might specify API-specific conventions, while /packages/web/CLAUDE.md covers the frontend patterns.

Directing Attention

When your codebase is too large for Claude to explore efficiently on its own, guide it explicitly. Instead of saying "fix the performance bug," say "the performance issue is in the query builder at src/services/search.ts — the buildFilterQuery function generates N+1 queries when filters include nested relations." The more precisely you point Claude at the relevant code, the faster and more accurate the result.

Cost and Token Management

Claude Code uses API tokens with every interaction, and costs can accumulate on complex sessions. Understanding the economics helps you work efficiently without self-censoring.

Every message you send includes your prompt, the conversation history, any files Claude has read, and the system prompt (including your CLAUDE.md). The response tokens are typically cheaper than input tokens, but long conversations compound quickly because the entire history is re-sent with each turn. A session that has gone through 50 back-and-forth exchanges is sending all 50 exchanges every single time.

Practical Strategies

Pro tip: Run /cost periodically during a session to see cumulative token usage and estimated cost. This builds intuition for which operations are expensive and which are cheap.

Advanced CLAUDE.md Strategies

Beyond basic project documentation, your CLAUDE.md can encode team conventions, enforce coding standards, and shape Claude's behavior in sophisticated ways. 

# CLAUDE.md — Advanced Patterns

## Code Review Checklist (apply to all changes)
- [ ] No console.log left in production code
- [ ] All new functions have JSDoc comments
- [ ] Error handling follows the Result pattern
- [ ] New dependencies are justified in the PR description

## Naming Conventions
- React components: PascalCase (UserProfile.tsx)
- Hooks: camelCase prefixed with "use" (useAuth.ts)
- Utils: camelCase (formatCurrency.ts)
- Constants: SCREAMING_SNAKE_CASE
- Database columns: snake_case
- API routes: kebab-case (/api/user-profiles)

## Testing Requirements
- Every new service function needs unit tests
- Integration tests for API routes that touch the database
- Use test factories from /src/test/factories for mock data
- Never mock the database in integration tests — use the
  test database with transactions that roll back

## Common Gotchas
- The Redis client auto-reconnects but silently drops pub/sub
  subscriptions. Always re-subscribe after a reconnect event.
- Prisma's `findFirst` does NOT throw on null — use
  `findFirstOrThrow` when the record must exist.
- Next.js middleware runs on the edge runtime. Do not import
  Node-specific modules (fs, path, crypto) in middleware.ts.

The "Common Gotchas" section is particularly powerful. Every team has tribal knowledge — things that are not documented anywhere but that every experienced developer knows. Encoding this in CLAUDE.md means Claude benefits from that institutional memory. It will avoid the Redis pub/sub mistake because you told it about the issue, saving you a debugging session.

Power User Tips and Keyboard Shortcuts

Once you are fluent with the core features, these shortcuts and patterns will tighten your feedback loop further.

Essential Keyboard Shortcuts

Session Management Patterns

Multi-Session Workflow

For complex projects, consider running multiple Claude Code sessions simultaneously in different terminal tabs. One session handles the main feature implementation, another runs in a worktree experimenting with an alternative approach, and a third is dedicated to writing tests. Each session maintains its own conversation history and context, letting you parallelize your own workflow across multiple lines of investigation.

Pro tip: Name your terminal tabs to match the task. When you have three Claude sessions running, "auth-refactor," "auth-tests," and "auth-experiment" is far more navigable than "zsh," "zsh," and "zsh."

Putting It All Together

The advanced features covered in this article are not isolated tricks — they compose into a workflow that is qualitatively different from basic Claude Code usage. A typical advanced session might look like this: you start by updating CLAUDE.md with the current sprint context, enter plan mode to architect a feature across multiple services, review and refine the plan, switch to act mode for execution, let hooks handle formatting and linting automatically, use sub-agents to research unfamiliar API surfaces in parallel, and manage token costs by clearing context between distinct phases of work.

The underlying principle is always the same: give Claude the right context, the right constraints, and the right level of autonomy for the task at hand. Plan mode for architecture, extended thinking for hard reasoning, sub-agents for parallel research, hooks for automation, worktrees for isolation. Each feature gives you a specific lever to pull, and knowing when to pull each one is what distinguishes advanced usage from simply typing longer prompts.

In the next article, we will explore MCP Servers — the protocol that lets Claude Code connect to external tools, databases, APIs, and services, extending its capabilities far beyond file editing and terminal commands.