Advanced Claude Code techniques

Advanced Claude Code techniques are five levers beyond everyday prompting: the effort level that sets reasoning depth, MCP servers that give the agent live access to GitHub and databases, a custom MCP tool for your own scripts, an automated pull-request review in GitHub Actions, and git worktrees for isolated parallel sessions. Each one needs its own verification gate.

This page is for developers who already use Claude Code daily, and for tech leads who want those habits to hold across a team. The situation is familiar: the agent answers a hard design question in two shallow paragraphs, the .mcp.json you copied from a blog post never connects, and four independent tasks wait in line because you run one session at a time.

What you get from these advanced Claude Code techniques

• A way to raise reasoning depth with /effort and --effort instead of guessing at magic words.
• A .mcp.json with GitHub, a read-only database and a browser that loads on the first try, plus the command that proves it.
• A tested custom MCP server that wraps one of your own scripts, with input validation.
• A GitHub Actions workflow that posts a Claude review on every pull request and answers @claude mentions.
• A worktree routine for three or four parallel sessions that cannot overwrite each other.
• A verification gate for each technique, so you check results through tests and checks rather than by reading every line.

Which advanced technique fixes which problem?

Symptom	Technique	Canonical deep-dive
Answers to hard problems are shallow	Raise the effort level	Deep reasoning
You paste issue text, schemas or logs into the prompt by hand	Connect MCP servers	MCP setup
No existing server wraps your deploy script or internal API	Build a custom MCP tool	Custom MCP development
Pull requests wait days for a first review	Claude review in GitHub Actions	Review automation
Parallel sessions edit the same files	One git worktree per task	Version control

The sections below cover the part of each technique that the vendor docs leave out: the order of steps, the traps, and how you verify the result.

Raise reasoning depth with effort, not prompt wording

Claude Code controls reasoning depth with an effort level: low, medium, high, xhigh or max (Claude Code v2.1.283). Opus 5.5 is the default model from v2.1.280 and runs at medium by default, as do Sonnet 5.5 and Haiku 5.5; Opus 4.7 defaults to xhigh and most other current models to high. For model defaults per plan and provider, see the models hub.

Set the level in whichever way matches how long you want it to last:

# In the terminal: one session at a chosen level
claude --effort xhigh

# In the terminal: every session in this shell (overrides the saved setting)
export CLAUDE_CODE_EFFORT_LEVEL=high

# At the Claude Code prompt: change it mid-session (saved per model)
/effort high

Two keywords work inside a prompt. ultrathink asks for deeper reasoning on that one turn and leaves your session effort unchanged. /effort ultracode turns on automatic workflow orchestration at the session’s current effort level (since v2.1.284) for the current session; see dynamic workflows before you use it, because it can start many agents. Phrases such as “think hard” are ordinary text and change nothing.

The rule this site follows throughout: tune effort before you switch model. Claude Code’s model-configuration docs state: “In Anthropic’s testing, Opus 5.5 at medium matches or exceeds Opus 5 at high on coding and knowledge-work evaluations.” (Anthropic’s own claim, checked 2026-09-26), so try high or xhigh on the default model before reaching for Claude Fable 5.1. Higher effort costs more tokens, so return to the default when the hard part is done; cost control shows how to watch that.

Effort sets how long the model reasons. The structure of the reasoning comes from your prompt, and the most useful structure ends with a check you can run.

Copy-paste prompt: a hard architectural decision at high effort

We are choosing between one multi-tenant Postgres database with
row-level security and a database per tenant. Before you recommend one:

1. List the failure modes of each at 10, 100 and 1,000 tenants.
2. Compare them on data isolation, noisy-neighbor risk, migration cost
   and per-tenant backup and restore.
3. Recommend one for a B2B SaaS with about 50 tenants today that expects
   10x growth in two years, and name the single biggest risk.
4. Write three acceptance tests, in plain language, that would prove
   tenant A can never read tenant B's rows under your recommendation.

Do not write code yet. Give me the decision, the reasoning and the tests.

The fourth step is the verification gate: you review three testable statements, not two pages of reasoning.

Connect MCP servers that load on the first try

MCP servers give Claude Code structured access to GitHub, databases and browsers, so you ask for outcomes instead of pasting context. Most failed setups come from three mistakes: the wrong top-level key, a stdio command where an HTTP URL belongs, and archived reference packages.

Add servers at project scope so the whole team shares them through .mcp.json:

# In the terminal, from the repository root
claude mcp add -s project --transport http github https://api.githubcopilot.com/mcp/ \
  -H 'Authorization: Bearer ${GITHUB_PAT}'
claude mcp add -s project playwright -- npx -y @playwright/mcp@latest
claude mcp add -s project dbhub -- npx -y @bytebase/dbhub@latest \
  --transport stdio --dsn '${DATABASE_URL_READONLY}'

Those three commands write this file (tested on Claude Code 2.1.283). The single quotes keep ${GITHUB_PAT} and ${DATABASE_URL_READONLY} literal, so Claude Code expands them from each developer’s environment and no secret lands in git:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {}
    },
    "dbhub": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub@latest", "--transport", "stdio", "--dsn", "${DATABASE_URL_READONLY}"],
      "env": {}
    }
  }
}

The details that decide whether this works:

• The key is mcpServers. A file with servers fails to parse. Claude Code 2.1.283 reports Missing "mcpServers" — found "servers" instead in claude mcp list, and loads nothing from that file.
• HTTP servers need --transport http. Without it, claude mcp add accepts a URL as a stdio command and the server fails at connect time.
• Project servers wait for approval. Each developer sees a new .mcp.json server as pending until they approve it in a session.
• Skip the archived reference servers. @modelcontextprotocol/server-postgres and @modelcontextprotocol/server-puppeteer are marked “no longer supported” on npm (checked 2026-09-26). Use DBHub (@bytebase/dbhub, 1.3.1) or a vendor server for databases and @playwright/mcp (0.0.82) for browsers. The database MCP guide compares the options, and the GitHub MCP page covers read-only and per-toolset URLs.
• Scope credentials, not prompts. Point DATABASE_URL_READONLY at a database role that can only SELECT, and give the GitHub token only the repositories and permissions the workflow needs. A server with read-only credentials cannot write, whatever the prompt says.

Run claude mcp list after every change. It health-checks each approved server and prints parse errors with a suggested fix, which is the fastest proof that the config is right.

Copy-paste prompt: explore a database safely through DBHub

Using the dbhub MCP server, help me understand this database before I
change anything:

1. List every table with its approximate row count.
2. For the orders table, show columns, indexes and foreign keys.
3. Find any query in src/db/queries.ts that would scan a large table
   sequentially, and show the EXPLAIN output that proves it.
4. Propose the index that fixes it and the EXPLAIN you expect afterwards.

Run read-only queries only. If a statement would write, stop and ask.

Every claim in the answer points at an EXPLAIN result you can compare, so you check the plan output rather than trusting the explanation.

Build a custom MCP tool for your team’s own scripts

Build a server when no published one fits: a deploy script, an internal API, a proprietary CLI. The official TypeScript SDK is @modelcontextprotocol/sdk (1.30.1 on npm, checked 2026-09-26). The same project also publishes a newer split package, @modelcontextprotocol/server (2.1.0); the example below uses the stable v1 API. For the full development guide, see custom MCP development.

1. Install the SDK and zod in the repository:

   npm install @modelcontextprotocol/sdk zod

2. Save the server as tools/deploy-mcp-server.mjs. It validates the branch name before anything runs, calls your existing script without a shell, and reports failures with isError so the agent sees them. The pattern requires a word character first, so a value such as --force cannot reach the script as an option:

   tools/deploy-mcp-server.mjs

   import { execFile } from 'node:child_process';
   import { promisify } from 'node:util';
   import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
   import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
   import { z } from 'zod';
   
   const run = promisify(execFile);
   const server = new McpServer({ name: 'project-tools', version: '1.0.0' });
   
   server.registerTool(
     'deploy_staging',
     {
       description: 'Deploy an existing git branch to staging. Returns the script output.',
       inputSchema: { branch: z.string().regex(/^\w[\w./-]*$/) },
     },
     async ({ branch }) => {
       try {
         const { stdout } = await run('./scripts/deploy-staging.sh', [branch], { timeout: 600_000 });
         return { content: [{ type: 'text', text: stdout }] };
       } catch (err) {
         return { isError: true, content: [{ type: 'text', text: String(err) }] };
       }
     },
   );
   
   await server.connect(new StdioServerTransport());

3. Register it for the whole team:

   claude mcp add -s project project-tools -- node ./tools/deploy-mcp-server.mjs

4. Run claude mcp list and confirm project-tools connects, then ask Claude Code to “deploy the current branch to staging”.

We tested this server with SDK 1.30.1 and zod 4.6.5 on 2026-09-26: the branch feat/x returns the script output, and the inputs x; rm -rf / and --force both come back as isError: true with Input validation error before the script runs. Keep that pattern. The schema is your first guard, execFile without a shell is the second, and the permission prompt for the mcp__project-tools__deploy_staging tool is the third.

Snippets that do not work

Tool handlers must return a content array, not a bare object. server.addTool() and server.start() are not part of the v1 SDK API; use registerTool and server.connect(transport).

Run a Claude review on every pull request

The anthropics/claude-code-action@v1 GitHub Action runs Claude Code in your CI. It needs two workflows: one that reviews every pull request, and one that answers @claude mentions in comments.

1. Run the installer at the Claude Code prompt. It installs the GitHub app, saves the ANTHROPIC_API_KEY secret and creates two workflows: claude.yml for mentions and claude-code-review.yml for automatic reviews:

   /install-github-app

2. Tighten the generated review workflow. The review job needs pull-requests: write and explicit tool permissions, or it finishes without posting anything:

   .github/workflows/claude-code-review.yml

   name: Claude review
   on:
     pull_request:
       types: [opened, synchronize, ready_for_review]
   jobs:
     review:
       runs-on: ubuntu-latest
       permissions:
         contents: read
         pull-requests: write
         id-token: write
       steps:
         - uses: actions/checkout@v7
           with:
             fetch-depth: 1
             persist-credentials: false
         - uses: anthropics/claude-code-action@v1
           with:
             anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
             prompt: |
               REPO: ${{ github.repository }}
               PR NUMBER: ${{ github.event.pull_request.number }}
               Review this PR. Report only defects: security, correctness,
               missing error handling, missing tests for changed behaviour.
               For each finding give file, line, the failing input and a fix.
               Skip style. If you find nothing, say so in one line.
             claude_args: |
               --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

3. Keep the mention workflow, .github/workflows/claude.yml. It triggers on issue_comment, pull_request_review_comment, pull_request_review and issues events, which is what makes a comment like this work:

   @claude check the migration in this PR for backwards compatibility with the v2 API clients

Both workflows run with your API key in the environment

• Keep the action’s default that only users with write access to the repository can trigger it. Do not set allowed_non_write_users on a job that can write, and list trusted bots by name in allowed_bots rather than '*'.
• Never switch the review workflow to pull_request_target and check out the pull request’s head into the workspace: contributor code would then run next to your secrets. The action’s security notes show the safe layout, with the head in a subdirectory passed through --add-dir.
• On pull requests, the action restores .claude/, .mcp.json and CLAUDE.md from the base branch, but package.json, lockfiles and the Makefile stay at the pull request’s head. A base-branch hook that runs npm run … or make … therefore executes code the pull request supplies; call pinned tools directly instead.

The inputs prompt and claude_args are the v1 names; the v0.x direct_prompt input is not in the v1 action.yml (checked 2026-09-26). For review design, cost and noise control, see review automation; for how a team reviews agent pull requests by evidence, see agent PR review.

The Claude review is a second signal, never the merge gate. Your required checks (tests, type check, lint) stay the gate, and a human owns the merge decision.

Run parallel tasks in isolated git worktrees

Give each independent task its own git worktree so parallel sessions never share a working directory. --add-dir does not do this: it adds directories to a single session.

# Terminal 1
claude --worktree feature-notifications
# Terminal 2, with its own tmux session
claude --worktree hotfix-auth-timeout --tmux

Each worktree lands under .claude/worktrees/<name>/ on a new branch named worktree-<name>. Before the first run:

1. Add .claude/worktrees/ to .gitignore.
2. Create .worktreeinclude at the repository root, in .gitignore syntax, listing the gitignored files each fresh checkout needs, such as .env.local (only files that match a pattern and are gitignored are copied).
3. Run plain claude once in the repository so workspace trust is set.

When an interactive worktree session ends, Claude Code removes a clean worktree automatically and asks whether to keep or remove one that holds changes. Headless runs (claude -p --worktree) leave the worktree in place and locked; run git worktree unlock <path> if needed, then git worktree remove <path>. For a specific existing branch, use git directly: git worktree add ../app-hotfix hotfix/auth-timeout, then run claude inside it.

To fan one large change out automatically, the bundled /batch skill splits it into 5 to 30 units, each run by a background subagent in its own worktree. To watch several sessions at once, see agent view or tmux for agent fleets.

Copy-paste prompt: a scoped hotfix in a fresh worktree

This worktree is dedicated to one task: the auth timeout hotfix.

1. Reproduce the timeout with the failing test in tests/auth/ and show
   me the failure output before changing anything.
2. Find the root cause. Do not patch symptoms or raise timeouts.
3. Implement the smallest fix and run the auth tests, then the full suite.
4. Write a conventional commit message that names the root cause.

Do not touch files outside src/auth/ and tests/auth/. If the fix needs
changes elsewhere, stop and tell me why.

The failing-test-first step gives you a red-then-green record to check instead of the diff.

How do you verify the output without reading every line?

Each technique makes the agent faster; this table says what proves the result is right and who signs off.

Technique	Verification gate	Who signs off
Higher effort	Acceptance tests written before code, then run	Developer who owns the change
MCP servers	claude mcp list passes; read-only credentials; tool calls visible in the transcript	Developer; tech lead approves shared .mcp.json
Custom MCP tool	Schema rejects bad input; isError on failure; permission prompt before each call	Tech lead reviews the server once, not each call
CI review	Required checks stay the merge gate; each finding cites file, line and failing input	Human reviewer merges
Worktrees	Each branch passes CI on its own pull request	Developer, for each pull request

Bundle the results into one record per pull request, as described in the evidence bundle. A reviewer then checks the evidence, and reads code only where the evidence is missing or a check failed.

When advanced Claude Code techniques break

Answers stay shallow at every effort level. Run /effort to see the current level; an organization’s maxEffortLevel setting can cap it. If xhigh still falls short, the problem is usually missing context, not depth: add the failing test, logs or schema through MCP, then retry.

CLAUDE_CODE_EFFORT_LEVEL seems ignored. The variable overrides the saved effort for sessions started from that shell only. Run echo $CLAUDE_CODE_EFFORT_LEVEL in the terminal that launched Claude Code, and remember that /effort changes are saved per model.

An MCP server does not load. Run claude mcp list and read the diagnostics. Check the mcpServers key, --transport http on URL servers, and whether the project server is still pending approval. For stdio servers, run the npx command on its own in a terminal; for startup logs, run claude --debug. The MCP connection issues page covers the rest.

The custom tool returns nothing useful. Check that the handler returns { content: [...] } and sets isError on failure; a thrown exception or a bare object leaves the agent guessing. Test the script outside MCP first.

The review job runs but posts nothing. Add pull-requests: write to permissions and the gh pr comment and inline-comment tools to --allowedTools. If @claude mentions get no answer, the mention workflow is missing, the ANTHROPIC_API_KEY secret is not set, or the commenter lacks write access to the repository.

The review job fails on pull requests from forks. GitHub does not pass repository secrets to pull_request runs from forks, so the action has no API key. Leave it that way rather than moving to pull_request_target; a maintainer can ask for a review with an @claude comment after reading the change.

Parallel sessions still collide. They share a directory. Start each with --worktree, not --add-dir, and check with git worktree list. If a worktree lacks .env files, add them to .worktreeinclude.

Where to go next with advanced Claude Code techniques

• Enforce these gates automatically with hooks.
• Hand repeatable roles to custom subagents.
• Run Claude Code headless on a schedule with automation.
• Roll the setup out to a team with team collaboration.
• Compare the same levers in the other tools: advanced Codex techniques and advanced Cursor techniques.