M25: Claude Code Mastery

Learning Objectives

• Configure CLAUDE.md files at user, project, and directory levels with correct cascade behavior
• Build custom slash commands and skills with context isolation and tool restrictions
• Choose between plan mode and direct execution based on task complexity and risk
• Use Claude Code's built-in tools (Read, Write, Edit, Bash, Grep, Glob) effectively
• Integrate Claude Code into CI/CD pipelines with session isolation for unbiased review
• Use the Message Batches API for high-volume, cost-efficient processing
• Choose the right permission mode (default, acceptEdits, plan, bypassPermissions) for the risk profile of each session
• Compose long-running and parallel work using /loop, /schedule, worktrees, and the two-Claude review pattern

Claude Code Is an Orchestration Framework, Not a Coding Assistant

Most developers treat Claude Code like a faster Stack Overflow — type a question, get code, copy-paste. That's the wrong mental model. Claude Code is an agent orchestration framework that happens to be excellent at coding. Once you see the layers, you stop fighting the tool and start composing it.

Claude Code vs The Rest of the AI Coding Landscape

The AI coding landscape splits into three tiers based on autonomy. Knowing where Claude Code sits relative to Copilot, Cursor, and SWE-agents like Devin is how you decide which tool fits which task — and why composing Claude Code's six layers gives you something the others structurally can't.

CLAUDE.md Configuration Hierarchy

The Four Anti-Patterns That Kill Compliance

Every team that struggles with "Claude isn't following our CLAUDE.md" is hitting one of these four failure modes. Each one is a budget waste that pushes the file past the dropout threshold or leaves Claude with nowhere to go.

Minimum Viable CLAUDE.md

Before adding rules, start here. This is the under-30-line template that captures everything Claude actually needs and nothing it doesn't. Resist the urge to expand it until you've shipped a feature and noticed Claude getting something wrong.

# Project: [Name]

## Stack
- Node.js 22, TypeScript 5.4, Fastify 4
- PostgreSQL 16 + Drizzle ORM
- Redis 7 for caching
- Jest for testing

See @package.json for all dependencies.
See @docs/architecture.md for system design.

## How to work on this project
- Run tests: `npm test`
- Run single test: `npm test -- --testPathPattern=auth`
- Typecheck: `npm run typecheck`
- Lint: `npm run lint`

## Things Claude tends to get wrong here
- Always use ESM imports (not CommonJS require)
- Redis keys must include version prefix: `v2:user:{id}:...`
- Auth middleware must run BEFORE rate limiting in route registration
- All DB queries go through the service layer, never directly in routes

## Git workflow
- Never commit to main directly
- Branch naming: `feat/`, `fix/`, `chore/`
- Commit messages: conventional commits format

Let's look at what a real-world project-level CLAUDE.md contains. Notice how it is not just formatting preferences — it includes the tech stack, database rules, API patterns, and @import directives that pull in separate rule files for security and testing. This is the kind of context that saves Claude from making wrong assumptions about your project.

# UCC Pipeline Project — Claude Code Configuration

## Project Context
This is a UCC (Uniform Commercial Code) filing data pipeline.
Stack: Python 3.12, FastAPI, PostgreSQL 15, Redis, Docker.
Architecture: Medallion (Bronze → Silver → Gold layers).

## Coding Conventions
- Use type hints on ALL function signatures
- Docstrings: Google style (Args/Returns/Raises)
- Tests: pytest with fixtures, minimum 80% coverage
- Error handling: never catch bare `except:`, always specific exceptions
- Logging: structured JSON via structlog

## Database Rules
- ALL queries must use parameterized statements (no f-strings in SQL)
- Migrations via Alembic — never modify schema directly
- Table names: snake_case, singular (e.g., `ucc_filing`, not `ucc_filings`)

## API Patterns
- Routes: /api/v1/{resource}
- Auth: Bearer token via X-API-Key header
- Responses: always wrap in {data, error, metadata}
- Validation: Pydantic models for all request/response bodies

@import .claude/rules/security.md
@import .claude/rules/testing.md

# Personal Claude Code Preferences

## Editor Preferences
- Indentation: 2 spaces (overridden by project if different)
- Line length: 100 characters max
- Trailing commas: always in multi-line structures

## Workflow Preferences
- Run tests after every code change
- Show git diff before committing
- Prefer small, focused commits over large batches
- Always explain WHY a change was made, not just WHAT

## Communication Style
- Be concise — skip preamble
- When showing code, highlight the changed lines
- If unsure, ask before making assumptions

Custom Slash Commands vs Skills

Here is a skill definition with context isolation and tool restrictions.

---
name: entity-resolution
description: Analyze entity names across UCC filings to find matches and variations. Use when asked to resolve, match, or deduplicate entity names.
context: fork
allowed-tools:
  - Read
  - Grep
  - Glob
---

# Entity Resolution Analysis

You are analyzing UCC filing entity names to find matches.

## Task
Given entity name `$ARGUMENTS`, search the codebase for:
1. Exact matches in filing records
2. Variations (abbreviations, misspellings, legal suffixes)
3. Related entities (parent/subsidiary relationships)

## Process
1. Use Glob to find all filing data files
2. Use Grep to search for the entity name and common variations
3. Read relevant files to extract full entity records
4. Return a structured summary:
   - Exact matches (count, filing numbers)
   - Likely matches (similarity score, reasoning)
   - Recommended canonical name

## Constraints
- Do NOT modify any files
- Do NOT run any shell commands
- Return only the analysis summary to the main session

---
description: Review a UCC filing parser for correctness and edge cases
allowed-tools:
  - Read
  - Grep
  - Glob
argument-hint: filing_type (e.g., UCC-1, UCC-3)
---

# Review Filing Parser

Review the parser implementation for `$ARGUMENTS` filings.

## Checklist
1. Read the parser source file for this filing type
2. Check: Does it handle all required fields?
3. Check: Are edge cases covered? (missing fields, malformed dates, encoding issues)
4. Check: Does it match the expected output schema?
5. Check: Are there tests? Do they cover edge cases?

## Report Format
- **Status**: PASS / FAIL / NEEDS REVIEW
- **Issues found**: list with severity (critical/warning/info)
- **Missing test coverage**: list of untested scenarios
- **Suggested fixes**: code snippets for critical issues

SKILL.md Frontmatter — The Full Spec

The two skills above used four frontmatter fields. The full SKILL.md frontmatter has 15 fields, all optional — only description is recommended. Skills also unify what used to be two separate concepts: custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and use the same frontmatter; the skill format adds optional supporting files, automatic invocation, and subagent execution.

String Substitutions — Inject Args, Session ID, Effort, Skill Path

Skills have six substitution variables that get replaced before the body is sent to Claude. Argument positionals support shell-style quoting ("hello world" = one arg).

Inline Shell Injection — !`cmd` Runs Before Claude Sees Anything

Skills (and slash commands) can run shell commands at render time using backtick-quoted !`command` syntax or fenced ```! blocks. The output replaces the placeholder and the rendered prompt is what reaches Claude — this is preprocessing, not Claude executing the command. Perfect for injecting live data (PR diffs, git status, env versions) without round-tripping through tool calls.

---
name: pr-summary
description: Summarize the current pull request using live GitHub data
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## PR diff
!`gh pr diff`

## Reviewer comments
!`gh pr view --comments`

## Multi-line block (use ```! ... ```)
```!
node --version
npm --version
git status --short
```

Summarize the changes and flag anything that needs reviewer attention.

When the skill runs, the three commands execute first; their stdout is interpolated into the prompt; Claude receives a fully-rendered text body with the actual PR data already inlined. To disable shell injection for non-bundled skills (managed-policy enforcement), set "disableSkillShellExecution": true in settings — each !`cmd` is replaced with [shell command execution disabled by policy].

Bundled Skills — What Ships in Every Session

Claude Code includes prompt-based bundled skills that you invoke like any other slash command. Unlike built-in commands (which execute fixed code), bundled skills hand Claude a detailed playbook and let it orchestrate using its tools. They appear in / autocomplete tagged Skill:

A few built-in commands are also reachable through the Skill tool: /init, /review, /security-review. Others like /compact are not. Block all skills with a Skill deny rule, restrict to specific skills with Skill(name) or Skill(name *) in permissions.allow. To make a skill's body invoke extended thinking, include the literal word "ultrathink" anywhere in the skill content.

Plan Mode vs Direct Execution

Under the hood, plan mode changes how Claude Code processes your request. Normally, Claude reads your prompt and immediately starts calling tools — reading files, making edits, running tests. In plan mode, Claude still reads files and analyzes the codebase, but it stops before making any changes. Instead, it outputs a structured plan: which files it will modify, what changes it will make to each one, and what risks exist. You review the plan, suggest changes, and only when you say "proceed" does Claude execute.

This is more than just "thinking before acting." Plan mode forces Claude to commit to a strategy before it starts editing. Without it, Claude might start refactoring file A, realize halfway through that file B needs to change first, undo its work on A, edit B, then come back to A. Plan mode catches these dependency chains upfront, saving tool calls and avoiding half-finished states.

Here is what plan mode output actually looks like. When you type /plan or ask Claude to "plan first," you get a structured proposal like this before any code is touched:

The Four Permission Modes

settings.json — The Full Configuration Surface

Five-Level Precedence — Who Beats Whom

Claude Code merges settings from up to five sources for every session. Higher-priority levels override lower ones for the same key. Managed settings can also set a few "managed-only" keys (like allowedMcpServers) that lower levels cannot define at all.

The Settings You'll Actually Touch

Settings group into eight functional areas. Here are the high-leverage knobs for each — the rest of the surface is in the upstream reference.

Sandbox Settings — Bash With Filesystem + Network Walls

Set sandbox.enabled: true and Bash runs inside an OS-level jail (Seatbelt on macOS, namespaces on Linux/WSL2). Sandboxed commands skip the permission prompt by default (autoAllowBashIfSandboxed: true) because the OS is enforcing the boundary — making it the safest way to run bypassPermissions-style work without yolo'ing your filesystem.

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "filesystem": {
      "allowWrite": ["./", "~/.cache/claude"],
      "denyWrite": ["./.git", "./.env*"],
      "denyRead":  ["./.env", "~/.ssh", "~/.aws"]
    },
    "network": {
      "allowedDomains": ["api.github.com", "registry.npmjs.org", "*.anthropic.com"],
      "deniedDomains":  ["*"]
    },
    "excludedCommands": ["docker", "kubectl"]
  }
}

Path prefixes: / = absolute, ~/ = home, ./ or no prefix = project-relative. Network domains support wildcards. excludedCommands lets specific binaries bypass the sandbox when they need raw network/filesystem (e.g. docker). Managed admins can also set sandbox.network.allowManagedDomainsOnly to ignore project/user domain lists entirely.

Managed Settings — Org-Wide Policy

For enterprise rollouts, settings can be deployed via OS policy systems — out of reach of users. Three delivery mechanisms:

• macOS: com.anthropic.claudecode plist via Jamf, Kandji, etc.
• Windows admin: HKLM\SOFTWARE\Policies\ClaudeCode via Group Policy or Intune
• File-based: managed-settings.json base file plus managed-settings.d/*.json drop-in fragments (sorted alphabetically — later files override earlier)

Managed-only keys (cannot be set at any other level) include allowedMcpServers, deniedMcpServers, allowManagedMcpServersOnly, allowManagedPermissionRulesOnly, allowManagedHooksOnly, strictKnownMarketplaces, blockedMarketplaces, forceRemoteSettingsRefresh, disableSkillShellExecution, disableBypassPermissions. On Windows, wslInheritsWindowsSettings tells WSL to read the host's policies.

Attribution — Stop the AI From Spamming Co-Author Lines

By default, Claude Code adds a Co-Authored-By: Claude trailer to commits and an attribution line to PR descriptions. The attribution object lets you customize or disable both independently — replaces the deprecated includeCoAuthoredBy bool:

{
  "attribution": {
    "commit": false,
    "pr":     "Generated with Claude Code (internal)"
  },
  "prUrlTemplate": "https://github.acme.internal/{org}/{repo}/pull/{number}"
}

Voice, Status Line, Spinner — The UX Layer

Three settings that meaningfully change the moment-to-moment feel of working with Claude Code:

• voice.enabled: true + voice.mode: "hold" (push-to-talk) or "tap" (toggle), with voice.autoSubmit: true to send when you stop talking. Configure interactively with /voice.
• statusLine.type: "command" + statusLine.command: "./bin/status.sh" — your script's stdout is shown at the bottom of every prompt (great for showing branch / cost / current task).
• spinnerVerbs.mode: "replace" + spinnerVerbs.verbs: ["compiling","analyzing","brewing"] — replaces the rotating "thinking" verbs. Use "append" mode to add custom ones to the defaults.

Built-in Tools: Read, Write, Edit, Bash, Grep, Glob

CI/CD Integration

Let's build a GitHub Actions workflow that puts session isolation into practice. The workflow triggers on every pull request, so every code change gets an independent AI review automatically.

The first half of the workflow — the "Summarize PR Changes" step — is Session A. It reads the git diff and produces a structured summary of what changed. Think of this as the "what happened" step. The second half — "Review PR" — is Session B. It reads the same diff but with a completely different prompt focused on bugs, security issues, and test gaps. Because these are separate claude -p invocations, Session B has zero knowledge of Session A's reasoning. That is the whole point.

One gotcha to watch for: the fetch-depth: 0 on checkout. Without it, GitHub Actions does a shallow clone (only the latest commit), and git diff origin/main...HEAD fails because there is no history to diff against. This is the most common cause of "the review step produced no output" in real CI setups.

# .github/workflows/claude-review.yml
# Automated PR review using Claude Code with session isolation.
# Session A generates a summary; Session B reviews independently.

name: Claude Code PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for diff context

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      # --- Session A: Summarize changes ---
      # This session reads the diff and produces a structured summary.
      - name: Summarize PR Changes
        id: summary
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          claude -p "Summarize these code changes. Focus on: what changed, why it might have changed, and any patterns you notice. Diff: $DIFF" \
            --output-format json > summary.json

      # --- Session B: Independent review ---
      # SEPARATE session — no access to Session A's reasoning.
      - name: Review PR (Independent Session)
        id: review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          claude -p "Review this PR diff for: security vulnerabilities, performance issues, missing error handling, and test coverage gaps. Be specific — cite line numbers. Diff: $DIFF" \
            --output-format json > review.json

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const review = require('./review.json');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## Claude Code Review\n\n${review.result}`
            });

# scripts/review-pr.sh
# Standalone PR review script with session isolation.
# Can be used outside GitHub Actions (e.g., GitLab CI, local review).

#!/usr/bin/env bash
set -euo pipefail

# Ensure ANTHROPIC_API_KEY is set
if [ -z "${ANTHROPIC_API_KEY:-}" ]; then
  echo "Error: ANTHROPIC_API_KEY not set" >&2
  exit 1
fi

DIFF=$(git diff origin/main...HEAD)

if [ -z "$DIFF" ]; then
  echo "No changes to review."
  exit 0
fi

echo "=== Session A: Summarizing changes ==="
SUMMARY=$(claude -p "Summarize these code changes concisely: $DIFF" \
  --output-format json 2>/dev/null)

echo "=== Session B: Independent review ==="
REVIEW=$(claude -p "Review this diff for security issues, bugs, and missing tests. Cite specific line numbers: $DIFF" \
  --output-format json 2>/dev/null)

echo ""
echo "=== Summary ==="
echo "$SUMMARY" | jq -r '.result // .content // .'
echo ""
echo "=== Review ==="
echo "$REVIEW" | jq -r '.result // .content // .'

Batch Processing (Message Batches API)

Under the hood, the Batch API works differently from the standard Messages API. When you call client.messages.create(), Anthropic allocates GPU capacity immediately, processes your request, and streams back the response. Your code blocks until it is done. With batch, you submit a manifest of requests — essentially a list of "here are 10,000 prompts I need answered" — and Anthropic schedules them to run whenever capacity is available. That is why it is cheaper: Anthropic can fill idle GPU slots instead of guaranteeing instant capacity.

If you have used background jobs in web development (Sidekiq, Celery, AWS Lambda queues), the mental model is the same. You submit work, get a job ID, and poll until the job is complete. The difference is the scale: a single batch can hold 10,000 requests, and the polling interval is minutes, not milliseconds.

One important distinction from what you already know: unlike the synchronous API where you handle one response at a time, batch results come back as a collection. Some requests in the batch may succeed while others fail. Your code must handle partial success — iterating through results and checking each one's status individually.

Let's walk through a complete batch processing pipeline step by step. The first function, create_batch_requests, is straightforward — it takes a list of filing text strings and wraps each one into the format the Batch API expects. Each request gets a unique custom_id so you can match results back to the original documents later. Think of it as putting a label on each envelope before dropping them in the mailbox.

The interesting part is run_batch. It submits the batch, then enters a polling loop — checking every 60 seconds whether the batch has finished processing. When the batch status changes to "ended", it iterates through the results. Here is the critical detail: not every request in a batch is guaranteed to succeed. A filing might be too long, or the model might fail to extract valid JSON from a poorly formatted document. So the code checks each result individually and separates successes from errors. Never assume 100% success in batch processing.

# batch_extract.py
# Extract structured data from UCC filing documents using
# the Message Batches API — 50% cheaper than synchronous calls.

import anthropic
import json
import time


def create_batch_requests(filing_texts: list[str]) -> list[dict]:
    """
    Build batch request objects from filing document texts.
    Each request asks Claude to extract structured data.
    """
    requests = []
    for i, text in enumerate(filing_texts):
        requests.append({
            "custom_id": f"filing-{i:04d}",
            "params": {
                "model": "claude-sonnet-4-6",
                "max_tokens": 1024,
                "messages": [
                    {
                        "role": "user",
                        "content": (
                            "Extract structured data from this UCC filing. "
                            "Return JSON with fields: debtor_name, "
                            "secured_party, collateral_description, "
                            "filing_date, lapse_date, filing_number.\n\n"
                            f"Filing text:\n{text}"
                        ),
                    }
                ],
            },
        })
    return requests


def run_batch(filing_texts: list[str]) -> list[dict]:
    """
    Submit a batch of filing extraction requests and wait
    for results. Polls every 60 seconds.
    """
    client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

    requests = create_batch_requests(filing_texts)
    print(f"Submitting batch of {len(requests)} requests...")

    try:
        batch = client.messages.batches.create(requests=requests)
        print(f"Batch created: {batch.id}")

        # Poll for completion
        while True:
            status = client.messages.batches.retrieve(batch.id)
            print(f"Status: {status.processing_status} "
                  f"({status.request_counts.succeeded} done)")

            if status.processing_status == "ended":
                break
            time.sleep(60)  # Check every minute

        # Collect results
        results = []
        for result in client.messages.batches.results(batch.id):
            if result.result.type == "succeeded":
                text = result.result.message.content[0].text
                results.append({
                    "id": result.custom_id,
                    "data": json.loads(text),
                })
            else:
                results.append({
                    "id": result.custom_id,
                    "error": str(result.result),
                })
        return results

    except anthropic.APIError as e:
        print(f"Batch API error: {e}")
        return []


if __name__ == "__main__":
    # Example: process 5 sample filings
    sample_filings = [
        "UCC-1 Filing: Debtor: Acme Corp, 123 Main St...",
        "UCC-1 Filing: Debtor: BuildRight LLC, 456 Oak Ave...",
        "UCC-3 Amendment: Original filing #2024-001234...",
        "UCC-1 Filing: Debtor: Metro Holdings Inc...",
        "UCC-3 Continuation: Original filing #2023-009876...",
    ]
    results = run_batch(sample_filings)
    for r in results:
        print(json.dumps(r, indent=2))

// batch_extract.ts
// Extract structured data from UCC filing documents using
// the Message Batches API — 50% cheaper than synchronous calls.

import Anthropic from "@anthropic-ai/sdk";

interface BatchRequest {
  custom_id: string;
  params: {
    model: string;
    max_tokens: number;
    messages: Anthropic.MessageParam[];
  };
}

function createBatchRequests(filingTexts: string[]): BatchRequest[] {
  return filingTexts.map((text, i) => ({
    custom_id: `filing-${String(i).padStart(4, "0")}`,
    params: {
      model: "claude-sonnet-4-6",
      max_tokens: 1024,
      messages: [
        {
          role: "user" as const,
          content:
            "Extract structured data from this UCC filing. " +
            "Return JSON with fields: debtor_name, " +
            "secured_party, collateral_description, " +
            "filing_date, lapse_date, filing_number.\n\n" +
            `Filing text:\n${text}`,
        },
      ],
    },
  }));
}

async function runBatch(filingTexts: string[]) {
  const client = new Anthropic(); // reads ANTHROPIC_API_KEY

  const requests = createBatchRequests(filingTexts);
  console.log(`Submitting batch of ${requests.length} requests...`);

  try {
    const batch = await client.messages.batches.create({ requests });
    console.log(`Batch created: ${batch.id}`);

    // Poll for completion
    while (true) {
      const status = await client.messages.batches.retrieve(batch.id);
      console.log(
        `Status: ${status.processing_status} ` +
        `(${status.request_counts.succeeded} done)`
      );

      if (status.processing_status === "ended") break;
      await new Promise((r) => setTimeout(r, 60_000)); // 1 min
    }

    // Collect results
    const results: Array<{ id: string; data?: unknown; error?: string }> = [];
    for await (const result of client.messages.batches.results(batch.id)) {
      if (result.result.type === "succeeded") {
        const text = (result.result.message.content[0] as Anthropic.TextBlock).text;
        results.push({ id: result.custom_id, data: JSON.parse(text) });
      } else {
        results.push({ id: result.custom_id, error: String(result.result) });
      }
    }
    return results;

  } catch (error) {
    console.error(`Batch API error: ${error}`);
    return [];
  }
}

// Example usage
const sampleFilings = [
  "UCC-1 Filing: Debtor: Acme Corp, 123 Main St...",
  "UCC-1 Filing: Debtor: BuildRight LLC, 456 Oak Ave...",
  "UCC-3 Amendment: Original filing #2024-001234...",
];
runBatch(sampleFilings).then((results) =>
  results.forEach((r) => console.log(JSON.stringify(r, null, 2)))
);

Background Work & Composition Patterns

Single-session Claude Code is already a force multiplier. But the top-1% workflow is composition: multiple Claude sessions running in parallel, scheduled background agents, and independent reviews of your own work. These aren't experimental features — they ship in Claude Code today and unlock workflows you literally cannot do with any other AI tool.

Worktrees — parallel sessions on the same repo

Git worktrees let you check out multiple branches into separate directories. Claude Code uses this to run truly parallel sessions without stepping on each other's changes. Want one Claude implementing the feature while another reviews the previous PR? Spin up two worktrees, two sessions, two terminals.

# Create a worktree on a new branch, isolated from your main checkout
git worktree add ../proj-feature-auth -b feat/auth

# Open Claude Code there
cd ../proj-feature-auth && claude

# Meanwhile, in your original checkout, run a SECOND Claude session
# reviewing the last commit (the "two-Claude review" pattern)
cd ../proj && claude "review the last commit on main as a staff engineer. Be harsh."

# When done, clean up
git worktree remove ../proj-feature-auth

The Two-Claude Review Pattern

This is the single highest-leverage technique to add to your workflow today. Session A implements a feature with full context of the tradeoffs. Session B starts cold and reviews the diff with no context. The cold reviewer is dramatically harder to fool because it has no rationalization for shortcuts that "made sense at the time."

Background Monitoring with /loop

Some checks shouldn't block your main session — they should run in the background on a timer. Use /loop <interval> <prompt>. The session keeps running, you keep working, and Claude reports back when something changes.

# Watch the CI pipeline on a feature branch
/loop 5m check if the CI pipeline on branch feat/recommendations passed; report back

# Periodically scan for new failing tests on main
/loop 30m check for any new failing tests on main; only ping me on changes

# Self-paced (Claude decides the cadence based on what it's watching)
/loop check the long-running build at task ID build-7842 and tell me when it finishes

Scheduled Routines with /schedule

/schedule creates a cron-style remote agent that runs even when your laptop is closed. Common patterns: a Monday-morning triage agent that processes the weekend's PR queue, or a one-time agent in two weeks that opens a cleanup PR for a feature flag you just shipped.

# Recurring routine: weekly PR triage every Monday at 9am
/schedule "0 9 * * 1" "review all open PRs older than 5 days; comment on staleness"

# One-time routine: clean up a feature flag in 2 weeks
/schedule "in 14 days" "open a PR removing the recommendations_v2 feature flag if it's still rolled out 100%"

Remote Control — Async Workflows from Anywhere

Long-running Claude tasks shouldn't tie you to your laptop. Run claude remote-control on your machine and you can connect to that running session from claude.ai or the iOS app. Kick off a 20-minute refactor, close your laptop, check progress from your phone on the way to a meeting. The session runs on your machine; the browser/app is just a window into it.

Voice — /voice + Push-to-Talk

Some workflows are dramatically faster spoken than typed — especially exploratory thinking-out-loud or describing an architecture. Run /voice to enable push-to-talk. Hold space, describe what you want, release. Claude transcribes and responds. The natural use case: long-form context dumps and brainstorming where typing is the bottleneck.

Plugins — sharing your setup

Once you've curated a great set of skills, slash commands, and hooks for your project, you can package them as a plugin. Plugins are installable via the Claude Code marketplace (or your team's private registry) and are how engineering teams standardize agent infrastructure across projects. The same plugin that gives the SRE team a /incident command and a Slack notification hook can be installed in every repo with one command.

Power User Features & Keyboard Shortcuts

The Anthropic common workflows doc lists the daily features that separate "I use Claude Code" from "I use Claude Code well." This section is the consolidated cheat sheet — every UX detail, keyboard shortcut, and CLI flag the docs recommend.

Plan Mode — The Full UX

You learned plan mode earlier. Here's how the docs say to actually drive it:

@-File & Resource References

The @ prefix has two distinct uses depending on where you type it. Don't confuse them:

• In prompts — @src/utils/auth.js includes the file's full content. @src/components shows a directory listing. @github:repos/owner/repo/issues fetches data from a connected MCP server. Adding @file also pulls the CLAUDE.md from that file's directory and parents into context. Multiple references work in one message: "explain the bug in @app.ts that the tests in @app.test.ts are catching."
• In CLAUDE.md — @README.md imports another file's content into CLAUDE.md at session start. Recursive imports up to 5 hops. Relative paths resolve relative to the file that contains the import. Use @~/.claude/my-prefs.md to share personal instructions across worktrees.

Extended Thinking — The UX

You learned the concept of extended thinking in M22. Here's the daily UX:

Phrases like "think hard" or "think more" are read as regular prompt text, not thinking-budget allocations. Only ultrathink is interpreted as a thinking instruction.

Session Management — Resume, Name, Pick

Sessions persist automatically per project directory. The full vocabulary:

Best practice: name early. /rename auth-refactor when starting a distinct task is much easier to find later than "explain this function." When the session is too old to fully reload, the picker offers a resume from summary path.

Worktree Extras — Built-In Flag, Includes, Subagent Worktrees

You learned worktrees as a parallel-session primitive. Three docs-recommended details:

• Built-in flag: claude --worktree feature-auth creates <repo>/.claude/worktrees/feature-auth/ on a new branch worktree-feature-auth. Omit the name for an auto-generated one. Worktrees branch from origin/HEAD — if your main branch changed, run git remote set-head origin -a to re-sync. Add .claude/worktrees/ to your .gitignore.
• .worktreeinclude: a gitignore-style file at the repo root listing files that should be copied into new worktrees (typically .env.local, config/secrets.json). Only files that match and are gitignored get copied — tracked files are never duplicated.
• Subagent worktrees: add isolation: worktree to a custom subagent's frontmatter, or ask Claude to "use worktrees for your agents." Each subagent gets its own worktree, automatically cleaned up if no changes were made. Orphaned worktrees from interrupted runs sweep at startup based on cleanupPeriodDays.

Scheduling — Pick the Right Tool

The docs list four ways to run Claude on a schedule. Choose by where the task should run:

Scheduled tasks run autonomously — the prompt can't ask clarifying questions. Be explicit about success criteria and what to do with results: "Review open PRs labeled needs-review, comment on issues, post a summary in #eng-reviews Slack."

Unix-Style Utility — Headless & Pipes

Claude Code has a first-class non-interactive mode for shell pipelines and CI:

# Pipe data through Claude
cat build-error.txt | claude -p 'concisely explain the root cause' > output.txt

# Use as a linter in package.json
"lint:claude": "claude -p 'check the diff vs main for typos. report filename and line.'"

# Output formats
claude -p '...' --output-format text        # default plain text
claude -p '...' --output-format json        # full conversation log + cost/duration
claude -p '...' --output-format stream-json # real-time streaming JSON objects

Image Input

Three ways to give Claude an image: (1) drag and drop into the Claude Code window. (2) copy and paste with Ctrl+V (do not use Cmd+V). (3) reference a path: "Analyze this: /path/to/image.png." Useful for debugging error screenshots, generating CSS from design mockups, and reading database-schema diagrams. When Claude references an image like [Image #1], Cmd+Click / Ctrl+Click opens it.

Desktop Notifications via the Notification Hook

Long-running tasks shouldn't keep you tab-switching. The Notification hook fires when Claude needs permission, finishes work, or completes auth. Configure once in ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Claude needs your attention\" with title \"Claude Code\"'"
      }]
    }]
  }
}

Replace the command with notify-send on Linux or a PowerShell MessageBox on Windows. Narrow the matcher to permission_prompt / idle_prompt / auth_success if you only want specific events.

CLAUDE.md Extras the Earlier Section Skipped

Five smaller CLAUDE.md features that didn't fit the main hierarchy diagram but matter at scale:

• /init — generates a starting CLAUDE.md by analyzing your codebase. If a CLAUDE.md exists, it suggests improvements rather than overwriting. Set CLAUDE_CODE_NEW_INIT=1 for an interactive multi-phase flow that also offers to set up skills and hooks.
• AGENTS.md compatibility — Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already has an AGENTS.md for other tools, create a CLAUDE.md that just imports it: @AGENTS.md on line 1, then add Claude-specific instructions below.
• Managed policy CLAUDE.md — org-wide instructions deployed via MDM/Group Policy/Ansible to /Library/Application Support/ClaudeCode/CLAUDE.md (mac), /etc/claude-code/CLAUDE.md (Linux), or C:\Program Files\ClaudeCode\CLAUDE.md (Windows). Cannot be excluded by individual settings.
• claudeMdExcludes — in monorepos, ancestor CLAUDE.md files from other teams may pollute context. Skip them with glob patterns in .claude/settings.local.json: "claudeMdExcludes": ["**/monorepo/CLAUDE.md", "/home/user/monorepo/other-team/.claude/rules/**"].
• --add-dir — gives Claude access to directories outside your working dir. By default their CLAUDE.md isn't loaded; set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 to also load their memory files.

End-to-End: Building a Feature with the Full Stack

You've learned every primitive individually. The payoff is composition. Here's a real workflow for shipping a new API endpoint — from idea to merged PR — using all six layers together. The same task that takes 2–3 hours of manual work compresses to about 25 minutes when the system does the orchestration.

The scenario: add a /api/v2/recommendations endpoint to a Node.js API. Personalized content based on user history. Redis caching, auth middleware, tests.

The Six Steps in Detail

1. Step 0 — CLAUDE.md is already loaded. Because you set this up once, Claude already knows your stack, test framework, git workflow, and the things it gets wrong. Zero setup per session.
2. Step 1 — Interview pattern with AskUserQuestion. Instead of guessing requirements, ask Claude to interview you. "Interview me using AskUserQuestion. Ask about auth, caching strategy, response shape, edge cases, performance constraints. Don't assume anything. When done, write SPEC.md."
3. Step 2 — Implementation in a fresh session. New terminal, new session: "implement the spec in SPEC.md, TDD style". Your PostToolUse hook lints every file as Claude writes it. Your PreToolUse hook blocks dangerous commands. You're not babysitting any of this.
4. Step 3 — Parallel review subagent. While the main session is still running (or right after it commits): "Use the code-reviewer subagent on the last commit." The subagent reads the diff cold and returns a structured MUST FIX / SHOULD FIX / CONSIDER report.
5. Step 4 — Fix and validate. Hand the report back to the main session: "Reviewer found a Redis connection leak and auth middleware in wrong order. Fix both, re-run tests." Tests pass, hooks auto-lint.
6. Step 5 — Security audit subagent. "Use the security-auditor subagent on this feature." Scans for injection vectors, exposed secrets, auth gaps, rate-limit gaps. Returns clean (or more fixes).
7. Step 6 — Automated PR via GitHub MCP. "Create a PR. Include the spec, what changed and why, test coverage summary, known limitations." Claude uses GitHub MCP to create the PR, links Jira via Jira MCP, requests reviewers.

The Production-Grade File Tree

Every primitive in this module corresponds to a file location. This is the consolidated layout for a well-configured Claude Code project — what your .claude/ directory looks like once all six layers are wired up.

your-project/
├── CLAUDE.md                ← project memory (commit this, <150 lines)
├── CLAUDE.local.md          ← personal overrides (gitignore)
├── .claude/
│   ├── settings.json        ← hooks, models, permissions, MCP
│   ├── agents/
│   │   ├── code-reviewer.md
│   │   ├── test-writer.md
│   │   ├── security-auditor.md
│   │   └── pm-spec.md
│   ├── skills/
│   │   ├── deploy.md             ← how we deploy to staging/prod
│   │   ├── database-patterns.md  ← our DB conventions
│   │   └── api-design.md         ← our API design rules
│   ├── commands/
│   │   ├── review-pr.md          ← /review-pr $ARGUMENTS
│   │   ├── ship.md               ← /ship — full pipeline
│   │   └── diagnose.md           ← /diagnose — debugging workflow
│   └── hooks/
│       ├── block_dangerous.py
│       ├── auto_format.sh
│       └── session_summary.py
├── src/
│   ├── api/CLAUDE.md        ← directory-scoped rules (loaded on demand)
│   └── db/CLAUDE.md         ← DB-specific conventions

5-Day Rollout Plan — Where to Start Tomorrow

You don't need to do all of this at once. Start with the smallest change that compounds. Here's the prioritized rollout that the top-1% playbook recommends, in order of return-on-effort.

Hands-On Exercise

What You'll Build

A complete Claude Code project configuration with three-level CLAUDE.md hierarchy, a custom slash command, a skill with context isolation, and a CI/CD review workflow.

Time estimate: 30–45 minutes

Prerequisites: Claude Code installed (npm install -g @anthropic-ai/claude-code), a code project directory to configure, and your ANTHROPIC_API_KEY set.

Files you'll create:

• ~/.claude/CLAUDE.md — Personal preferences (user-level)
• .claude/CLAUDE.md — Team standards (project-level)
• src/api/CLAUDE.md — API-specific rules (directory-level)
• .claude/commands/check-filing.md — Custom slash command
• .claude/skills/entity-resolution/SKILL.md — Skill with context fork
• .github/workflows/claude-review.yml — CI/CD workflow

Environment Setup

# Create project structure
mkdir -p my-ucc-project/src/api
mkdir -p my-ucc-project/.claude/commands
mkdir -p my-ucc-project/.claude/skills/entity-resolution
mkdir -p my-ucc-project/.github/workflows
cd my-ucc-project

# Verify Claude Code is installed
claude --version

# Verify API key is set
echo $ANTHROPIC_API_KEY | head -c 10  # Should print "sk-ant-..." 

Step 1: Create User-Level CLAUDE.md

What & Why: The user-level file holds your personal coding preferences. It applies to every project you open with Claude Code but never gets committed to git, so it does not impose your style on teammates.

Create the file ~/.claude/CLAUDE.md with the following content:

# Personal Claude Code Preferences

## Editor Preferences
- Indentation: 2 spaces
- Line length: 100 characters max
- Trailing commas: always in multi-line structures

## Workflow Preferences
- Run tests after every code change
- Show git diff before committing
- Prefer small, focused commits over large batches

## Communication Style
- Be concise — skip preamble
- If unsure, ask before making assumptions

Run:

Troubleshooting:

• If you see No such file or directory → create the directory first: mkdir -p ~/.claude
• On Windows, the path is %USERPROFILE%\.claude\CLAUDE.md — use type %USERPROFILE%\.claude\CLAUDE.md instead of cat
• If the file exists but is empty → check you saved the content (some editors don't auto-save new files)

Step 2: Create Project-Level CLAUDE.md

What & Why: The project-level file defines team standards. It gets committed to git so every developer shares the same rules. This is where tech stack, database conventions, and API patterns go.

Create the file .claude/CLAUDE.md in your project root:

# UCC Pipeline Project — Claude Code Configuration

## Project Context
This is a UCC (Uniform Commercial Code) filing data pipeline.
Stack: Python 3.12, FastAPI, PostgreSQL 15, Redis, Docker.

## Coding Conventions
- Use type hints on ALL function signatures
- Docstrings: Google style (Args/Returns/Raises)
- Tests: pytest with fixtures, minimum 80% coverage
- Error handling: never catch bare `except:`, always specific exceptions

## Database Rules
- ALL queries must use parameterized statements (no f-strings in SQL)
- Migrations via Alembic — never modify schema directly

## API Patterns
- Routes: /api/v1/{resource}
- Validation: Pydantic models for all request/response bodies

Run:

Troubleshooting:

• If you see No such file or directory → make sure you created the file inside .claude/, not at the project root
• If you accidentally created it at the project root → move it: mv CLAUDE.md .claude/CLAUDE.md
• If the .claude/ directory doesn't exist → run mkdir -p .claude first

Step 3: Create Directory-Level CLAUDE.md

What & Why: Directory-level files override project-level rules for specific code areas. The API directory might require Zod validation, while the database layer requires parameterized queries.

Create src/api/CLAUDE.md:

# API Layer Rules (overrides project-level where applicable)

## Input Validation
- ALL endpoints must validate input with Pydantic models
- Return 422 with field-level error details on validation failure

## Response Format
- Always wrap responses in: { "data": ..., "error": null, "metadata": {} }
- Include request_id in metadata for tracing

## Security
- Bearer token auth via X-API-Key header on all endpoints
- Rate limit: 100 req/min per API key

Run:

Troubleshooting:

• If you see No such file or directory → make sure src/api/ exists: mkdir -p src/api
• If the file shows the project-level content instead → you may have saved to the wrong path. Check with ls -la src/api/

Step 4: Build a Slash Command

What & Why: A slash command creates a reusable workflow you can trigger by typing /check-filing. This one validates a UCC filing parser against known test data.

Create .claude/commands/check-filing.md:

---
description: Validate a UCC filing parser against test data
allowed-tools:
  - Read
  - Grep
  - Glob
argument-hint: filing_type (e.g., UCC-1, UCC-3)
---

# Check Filing Parser

Review the parser for `$ARGUMENTS` filings.

## Checklist
1. Read the parser source for this filing type
2. Check: Does it handle all required fields? (debtor, secured party, collateral, dates)
3. Check: Are edge cases covered? (missing fields, malformed dates)
4. Check: Are there tests with adequate coverage?

## Report Format
- **Status**: PASS / FAIL / NEEDS REVIEW
- **Issues found**: list with severity
- **Missing coverage**: untested scenarios

Run:

Then open Claude Code in your project directory and type / — you should see check-filing in the list of available commands.

Troubleshooting:

• If the command does not appear in / menu → check the file is in .claude/commands/ (not .claude/skills/) and ends with .md
• If you see YAML parse error → check that the frontmatter uses --- delimiters (three dashes) and proper indentation
• If the command appears but fails → verify the allowed-tools list uses correct tool names: Read, Grep, Glob (case-sensitive)

Step 5: Build a Skill with Context Isolation

What & Why: Skills with context: fork run in an isolated context window, so exploring dozens of files does not clutter your main session. This skill does entity resolution — searching for name matches across UCC filings.

Create .claude/skills/entity-resolution/SKILL.md:

---
name: entity-resolution
description: Analyze entity names across UCC filings to find matches and variations. Use when asked to resolve, match, or deduplicate entity names.
context: fork
allowed-tools:
  - Read
  - Grep
  - Glob
---

# Entity Resolution Analysis

Given entity name `$ARGUMENTS`, search for:
1. Exact matches in filing records
2. Variations (abbreviations, misspellings, legal suffixes)
3. Related entities (parent/subsidiary relationships)

Return a structured summary with match counts and a recommended canonical name.
Do NOT modify any files. Return only the analysis summary.

Run:

Then in Claude Code, type "resolve entity Acme Corp" — the skill should trigger automatically based on its description matching your request. You can also invoke it explicitly with /entity-resolution Acme Corp.

Troubleshooting:

• If the skill does not appear → check the file is named exactly SKILL.md (all caps, exact casing) inside .claude/skills/entity-resolution/
• If the skill appears but does not auto-trigger → make sure the description field in the frontmatter contains keywords that match your request (e.g., "resolve", "match", "entity")
• If the skill runs but pollutes your main context → verify context: fork is set in the YAML frontmatter

Step 6: Configure CI/CD Review Workflow

What & Why: This GitHub Actions workflow runs Claude Code on every PR with session isolation — separate sessions for summarizing and reviewing changes. This prevents confirmation bias.

Create .github/workflows/claude-review.yml using the GitHub Actions code from the CI/CD section above. Ensure your repository has ANTHROPIC_API_KEY set in GitHub Secrets.

Run:

Validate the YAML syntax:

Troubleshooting:

• If the workflow does not trigger: ensure on: pull_request is at the top level, not nested under jobs.
• If Claude Code fails in CI: check that ANTHROPIC_API_KEY is set in repository Settings → Secrets → Actions.
• If npm install -g fails in CI: the ubuntu-latest runner includes Node.js by default, but you may need actions/setup-node@v4 first.

Verify Everything Works

Run these checks to confirm your configuration is complete:

# Verify all files exist
echo "=== Checking CLAUDE.md hierarchy ==="
test -f ~/.claude/CLAUDE.md && echo "✓ User-level" || echo "✗ Missing ~/.claude/CLAUDE.md"
test -f .claude/CLAUDE.md && echo "✓ Project-level" || echo "✗ Missing .claude/CLAUDE.md"
test -f src/api/CLAUDE.md && echo "✓ Directory-level" || echo "✗ Missing src/api/CLAUDE.md"

echo "=== Checking commands and skills ==="
test -f .claude/commands/check-filing.md && echo "✓ Command" || echo "✗ Missing command"
test -f .claude/skills/entity-resolution/SKILL.md && echo "✓ Skill" || echo "✗ Missing skill"

echo "=== Checking CI/CD ==="
test -f .github/workflows/claude-review.yml && echo "✓ Workflow" || echo "✗ Missing workflow"

Stretch goal (optional): Add a batch processing script that extracts structured data from 100 UCC filing documents using the Message Batches API from the Batch Processing section above.

Knowledge Check

Module Summary

• CLAUDE.md Hierarchy: User-level (personal) → project-level (team) → directory-level (path-specific). More specific wins. Use @import for shared rules.
• Commands vs Skills: Commands are manual triggers. Skills add context: fork for isolation and automatic invocation. Use skills for complex exploration tasks.
• Plan Mode: Use for complex, risky, or unfamiliar tasks. Skip for simple, well-understood changes. Decision depends on complexity, familiarity, risk, and reversibility.
• Built-in Tools: Glob (find files) → Read (understand) → Edit (change) → Bash (test). Know which tool fits which task.
• CI/CD: Use -p for non-interactive mode, --output-format json for structured output. Always use separate sessions for generation and review.
• Batch API: 50% cost reduction for high-volume, latency-tolerant tasks. 24-hour processing window. Not for real-time user-facing responses.

Next up: M26: Hooks, Sessions & Agent SDK covers event-driven automation, session management, and building custom agents with the Claude Agent SDK.

References & Resources

• Claude Code Documentation — Official guide to configuration and usage
• Message Batches API — Batch processing documentation
• Tool Use Documentation — Built-in and custom tool reference
• Anthropic Cookbook — Production-ready code examples