6 - Engineer Your AI: The Thinking Engineer's Guide to Advanced Claude Code

Table of Contents

• Introduction
• Part 1: Thinking Engineering
• Part 2: Persistent Context Architecture
• Part 3: AI Development Pipeline with Hooks
• Part 4: Checkpoints - Your Code Time Machine
• Part 5: Multi-Agent Orchestration
• Part 6: Power User Arsenal
• Real-World Workflows
• FAQ
• Conclusion

---

Introduction

Here's a hard truth: Most developers use 10% of Claude Code's power.

They treat it like fancy autocomplete. Type a prompt, get some code, copy-paste, move on. That's like using a Tesla as a golf cart.

The reality? Claude Code is a full AI development system with capabilities that transform how you build software.

What You'll Master Today

| Category | Feature | Impact | |----------|---------|--------| | 🧠 Thinking Modes | 32,000-token deep reasoning | Architecture decisions, security audits | | 💾 Memory System | Persistent context across sessions | No more re-explaining your project | | ⚙️ Automation | 8-hook pipeline framework | Quality gates, auto-formatting, safety | | 🔄 Time Travel | Instant checkpoint rollback | Risk-free experimentation | | 🤖 Multi-Agent | Parallel specialized workers | Security, performance, testing in parallel |

This isn't a features list. This is a systems engineering guide to building your AI development workflow.

By the end, you'll treat Claude Code like what it really is: your AI development team, not your autocomplete.

Let's turn you from a Claude Code user into a Claude Code systems engineer.

---

Part 1: Thinking Engineering

The Hidden Thinking Hierarchy

Most developers don't know this exists. Claude Code has progressive computation budgets triggered by specific words.

The Three Thinking Levels

| Trigger Word | Token Budget | Best For | Example Use Case | |--------------|--------------|----------|------------------| | think | ~4,000 tokens | Basic planning | Architecture decisions, code reviews | | think hard | ~10,000 tokens | Complex analysis | Security audits, refactoring strategy | | ultrathink | ~31,999 tokens | Deep reasoning | System design, zero-downtime migrations |

Key Insight: The word "ultrathink" isn't marketing. It's a programmatic trigger that allocates maximum tokens for reasoning.

# Basic thinking (~4,000 token budget)
> think about the best approach for this refactoring

# Medium thinking (~10,000 token budget)
> think hard about potential security vulnerabilities

# Maximum thinking (~31,999 token budget)
> ultrathink: analyze all edge cases and design the optimal solution

When to Use Each Level

Use "think" when:

• Planning architecture decisions
• Reviewing code for bugs
• Designing API interfaces
• Evaluating trade-offs

Use "think hard" when:

• Complex refactoring with multiple interdependencies
• Security audits
• Performance optimization
• Database schema migrations

Use "ultrathink" when:

• Mission-critical system design
• Large-scale migrations (React → Vue, monolith → microservices)
• Complex algorithm implementation
• Architectural decisions with long-term consequences

Real example:

> ultrathink: We need to migrate our authentication system from sessions
> to JWTs without downtime. Design a zero-downtime migration strategy
> considering: backward compatibility, gradual rollout, rollback plan,
> and security implications.

Claude will spend 32k tokens evaluating alternatives, considering edge cases, and designing a comprehensive strategy. This isn't "think a little harder" - this is deep architectural analysis.

The Thinking Engineering Workflow

Breaking complex tasks into phases prevents cognitive overload and improves output quality.

| Phase | Action | Purpose | Example Command | |-------|--------|---------|-----------------| | 1️⃣ Explore | Read-only analysis | Build context map | > Read @src/auth/ and explain. NO code yet. | | 2️⃣ Think | Strategic planning | Design before implementation | > think hard: Plan refactoring strategy | | 3️⃣ Approve | Human review | Validate approach | Review plan, ask questions | | 4️⃣ Execute | Iterative coding | Implement step-by-step | > Implement step 1: User model changes |

Step 1: Explore (Read-only, no coding)

> Read through the auth system (@src/auth/) and explain the current
> implementation. DO NOT write any code yet.

Step 2: Think (Plan before coding)

> think hard: Based on what you learned, plan a refactoring strategy.
> Show me the plan before implementing anything.

Step 3: Approve (Review the plan)

• Read Claude's plan
• Ask clarifying questions
• Adjust approach if needed

Step 4: Execute (Implement iteratively)

> Let's implement step 1 of your plan. Start with the User model changes.

Why this works: Anthropic's research shows Claude performs significantly better when it plans before coding. The Explore → Think → Approve → Execute pattern is how Anthropic engineers use Claude internally.

Context Engineering: The 3-File Rule

Here's a counterintuitive truth: More context ≠ better results.

LLMs have an "attention budget" - with too much context, performance degrades due to context rot. As token count increases, recall accuracy decreases.

The 3-File Rule: Only include files that directly relate to your current task.

Context Quality Comparison

| Approach | Files Loaded | Signal-to-Noise | Performance | |----------|--------------|-----------------|-------------| | ❌ Bad | @src/ (50+ files) | Low (5-10%) | Context rot, slow | | ✅ Good | 3 specific files | High (90%+) | Fast, accurate |

Bad (context noise):

> Review security: @src/
# Loads 50+ files, most irrelevant

Good (high-signal context):

> Review security: @src/auth/login.js @src/middleware/validate.js @tests/auth.test.js
# 3 directly relevant files

Why it works: LLMs are transformer models with n² pairwise relationships. Every additional file adds computational overhead. Precision > volume.

Just-in-Time Context Loading

Don't pre-load everything. Load dynamically as needed.

| Strategy | Context Delivery | Memory Efficiency | |----------|------------------|-------------------| | ❌ Pre-loading | All at once (2000 lines) | Wastes 80% of context window | | ✅ JIT Loading | Incremental discovery | Uses context only when needed |

Instead of:

claude "Here's my entire database schema (2000 lines)... now help with users table"

Do this:

> First, show me the users table schema only
[Claude shows it]
> Good. Now considering that schema, help me add email verification

Claude can use bash commands (head, tail, grep) to explore files incrementally. Let it discover context rather than drowning it upfront.

The Compaction Strategy

For long sessions (multiple hours of back-and-forth), use compaction:

> /compact

This tells Claude to summarize the conversation, preserving:

• Architectural decisions made
• Unresolved issues
• Implementation details

While discarding:

• Redundant outputs
• Abandoned approaches
• Repetitive discussions

Think of it as "git commit" for your conversation - you save the meaningful parts, discard the noise.

Memory Aid: The PACE Method

Plan → Approve → Code → Execute

This four-step rhythm creates a mental pattern that improves over time. When starting complex tasks, ask yourself: "Which PACE phase am I in?"

---

Part 2: Persistent Context Architecture

The Problem: AI Amnesia

Every time you start Claude Code, it forgets your project. You re-explain the tech stack, architecture, conventions... this is wasteful.

Solution: Memory Bank Pattern

Borrowed from the Cline AI agent community, adapted for Claude Code via CLAUDE.md files.

Create a hierarchy of context files that Claude auto-loads:

project/
├── CLAUDE.md                    # Project-specific context
├── .claude/
│   ├── projectbrief.md          # Core requirements & goals
│   ├── productContext.md        # Why this exists, UX goals
│   ├── activeContext.md         # Current work focus
│   ├── systemPatterns.md        # Architecture & patterns
│   ├── techContext.md           # Stack, versions, tools
│   └── runbooks.md              # Standard procedures

Memory Bank File Types

| File | Purpose | Update Frequency | Example Content | |------|---------|------------------|-----------------| | projectbrief.md | Core requirements | Rarely (quarterly) | Purpose, constraints, non-goals | | systemPatterns.md | Architecture | Monthly | Design patterns, services, critical rules | | activeContext.md | Current focus | Daily/weekly | Sprint goals, recent changes, blockers | | techContext.md | Stack details | As needed | Versions, commands, config paths | | productContext.md | UX & product | Quarterly | User personas, UX goals, workflows | | runbooks.md | Procedures | As needed | Deployment steps, debugging flows |

projectbrief.md - The Foundation

# Project: Zimbra Mail Platform

## Purpose
Enterprise-grade email and collaboration platform serving 10k+ users

## Core Requirements
- 99.9% uptime SLA
- SOC2 compliance
- Multi-tenant architecture
- Real-time collaboration

## Non-Goals
- Consumer email features
- Third-party integrations (phase 2)
- Mobile apps (separate team)

systemPatterns.md - Architecture

# System Architecture

## Core Services
- **Mail Store**: Postfix + Cyrus IMAP
- **Web Client**: Zimbra Web Client (ZWC)
- **LDAP**: OpenLDAP for auth
- **Database**: MariaDB for metadata
- **Cache**: Redis for sessions

## Design Patterns
- Use message queuing for async tasks
- All external API calls must have circuit breakers
- Database writes go through write-ahead log

## IMPORTANT: Never bypass the mail queue directly
## YOU MUST: Use zmprov for all Zimbra admin operations

activeContext.md - Current Focus

# Active Context (Updated: 2025-01-06)

## Current Sprint
Implementing email attachment virus scanning

## Recent Changes
- Added ClamAV integration (2025-01-05)
- Updated mail filtering rules (2025-01-03)

## Known Issues
- Attachment scanning slow for files >10MB
- Need to optimize ClamAV thread pool

## Next Steps
1. Implement async scanning for large files
2. Add progress indicators in UI
3. Write integration tests

techContext.md - Stack Details

# Technology Stack

## Versions
- Zimbra OSE 10.0.x
- Ubuntu 22.04 LTS
- Java 11 (Zimbra requirement)
- MariaDB 10.6
- Redis 7.0
- Node.js 20.x (admin tools)

## Development Commands
- Start dev: `zmcontrol start`
- Run tests: `./test-runner.sh`
- Build: `ant build`
- Deploy: `./deploy-staging.sh`

## Configuration Files
- `/opt/zimbra/conf/` - Zimbra configs
- `/etc/systemd/system/zimbra.service` - Systemd unit

CLAUDE.md Hierarchy

Claude loads CLAUDE.md files in this order:

| Priority | Location | Scope | Use Case | |----------|----------|-------|----------| | 1️⃣ Home | ~/.claude/CLAUDE.md | Global | Personal preferences, coding style | | 2️⃣ Parent | Monorepo root | Workspace | Shared team conventions | | 3️⃣ Root | Project root | Project | Project-specific rules | | 4️⃣ Child | Subdirectories | Module | Feature-specific context |

Pro tip from Anthropic: "Your CLAUDE.md files ARE prompts. Optimize them like prompts."

Prompt Optimization Keywords

| Keyword | Purpose | Example | |---------|---------|---------| | IMPORTANT: | Critical information | IMPORTANT: This project uses React 18 | | YOU MUST: | Required behaviors | YOU MUST: Use functional components with hooks | | NEVER: | Forbidden actions | NEVER: Use any/unknown types | | ALWAYS: | Expected patterns | ALWAYS: Include error handling in API calls |

Example optimization:

# BEFORE (weak)
We use React for frontend.

# AFTER (strong)
IMPORTANT: This project uses React 18 with TypeScript.
YOU MUST: Use functional components with hooks, never class components.
NEVER: Use any/unknown types - always provide explicit type annotations.

The thinking hierarchy pyramid: from regular mode to ultrathink with 32k token budget

Mermaid Diagrams in CLAUDE.md

Here's a power move: Include Mermaid diagrams in your CLAUDE.md.

Why? Mermaid is unambiguous. Each state and transition is clearly defined, unlike prose descriptions.

# Mail Flow Architecture

```mermaid
flowchart LR
    Client[Email Client] --> MTA[Postfix MTA]
    MTA --> Filter[Amavis Filter]
    Filter --> Virus[ClamAV Scan]
    Filter --> Spam[SpamAssassin]
    Virus --> Store[Mail Store]
    Spam --> Store
    Store --> IMAP[Cyrus IMAP]
    IMAP --> Client

When Claude sees this, it understands exactly how mail flows. No ambiguity, no guessing.

Persistent context architecture: hierarchical files loaded just-in-time for optimal performance

Memory Aid: The Memory Bank Pyramid

Think of context files as layers of a pyramid:

• Base (rarely changes): projectbrief, systemPatterns
• Middle (periodic updates): techContext, productContext
• Top (frequent updates): activeContext

Update frequency increases as you move up. This prevents unnecessary file churn.

---

Part 3: AI Development Pipeline with Hooks

The 8 Hooks That Change Everything

Most developers don't know Claude Code has a complete automation framework.

Eight hook types trigger at specific points in the workflow lifecycle.

Complete Hooks Reference

| Hook | Trigger Point | Common Use Cases | Environment Variables | |------|---------------|------------------|----------------------| | SessionStart | Session begins | Load project status, check dependencies | CLAUDE_PROJECT_DIR | | UserPromptSubmit | After user submits prompt | Log prompts, analytics | CLAUDE_USER_PROMPT | | PreToolUse | Before tool execution | Safety gates, confirmations | CLAUDE_TOOL_NAME, CLAUDE_TOOL_INPUT | | PostToolUse | After tool execution | Auto-format, quality checks | CLAUDE_FILE_PATHS | | Notification | Claude needs approval | Desktop alerts, notifications | CLAUDE_NOTIFICATION_MESSAGE | | PreCompact | Before conversation cleanup | Backup conversation history | Session context | | SubagentStop | Subagent completes | Track subagent results | CLAUDE_SUBAGENT_NAME | | Stop | Session ends | Generate reports, metrics | CLAUDE_TOTAL_TOKENS |

1. UserPromptSubmit - Log Every Prompt

# .claude/hooks/user-prompt-submit.sh
#!/bin/bash
echo "[$(date)] $CLAUDE_USER_PROMPT" >> ~/.claude/prompt-history.log

Now you have a searchable log of every prompt you've ever run.

2. PreToolUse - Safety Gates

# .claude/hooks/pre-tool-use.sh
#!/bin/bash

# Block dangerous Zimbra commands
if echo "$CLAUDE_TOOL_INPUT" | grep -q "zmcontrol stop"; then
  echo "ERROR: Stopping Zimbra in production requires approval ticket"
  exit 1
fi

# Require confirmation for database operations
if echo "$CLAUDE_TOOL_NAME" | grep -q "Bash.*mysql"; then
  read -p "Confirm database operation (y/n): " confirm
  [[ $confirm == "y" ]] || exit 1
fi

This hook prevents disasters. Claude can't accidentally stop your production mail server.

3. PostToolUse - Auto-Formatting

# .claude/hooks/post-tool-use.sh
#!/bin/bash

# Auto-format any modified files
for file in $CLAUDE_FILE_PATHS; do
  if [[ $file == *.js ]]; then
    prettier --write "$file"
  elif [[ $file == *.py ]]; then
    black "$file"
  fi
done

Every file Claude touches gets automatically formatted. Zero manual formatting.

4. Notification - Desktop Alerts

# .claude/hooks/notification.sh
#!/bin/bash

# macOS notification when Claude needs approval
osascript -e "display notification \"$CLAUDE_NOTIFICATION_MESSAGE\" with title \"Claude Code\""

Working in another window? Get notified when Claude needs you.

5. Stop - Completion Summary

# .claude/hooks/stop.sh
#!/bin/bash

# Generate completion summary
echo "Session complete: $CLAUDE_TOTAL_TOKENS tokens used"
echo "Files modified: $(echo $CLAUDE_FILE_PATHS | wc -w)"

Track your token usage and productivity metrics automatically.

6. SubagentStop - Track Subagent Work

# .claude/hooks/subagent-stop.sh
#!/bin/bash

echo "Subagent completed: $CLAUDE_SUBAGENT_NAME"
echo "Result: $CLAUDE_SUBAGENT_RESULT"

Monitor what your subagents accomplished.

7. PreCompact - Backup Before Memory Cleanup

# .claude/hooks/pre-compact.sh
#!/bin/bash

# Backup conversation before compaction
claude export-session > ~/claude-backups/session-$(date +%Y%m%d-%H%M%S).json

Never lose important conversation history.

8. SessionStart - Auto-Load Context

# .claude/hooks/session-start.sh
#!/bin/bash

# Auto-check Zimbra status on session start
if [[ "$CLAUDE_PROJECT_DIR" == *"zimbra"* ]]; then
  echo "Loading Zimbra system status..."
  zmcontrol status > /tmp/zimbra-status.txt
  echo "Status loaded. Reference with @/tmp/zimbra-status.txt"
fi

Context loaded before you even ask.

Creating Your Hook Pipeline

Step 1: Enable hooks (in .claude/settings.json):

{
  "hooks": {
    "userPromptSubmit": ".claude/hooks/user-prompt-submit.sh",
    "preToolUse": ".claude/hooks/pre-tool-use.sh",
    "postToolUse": ".claude/hooks/post-tool-use.sh",
    "notification": ".claude/hooks/notification.sh",
    "stop": ".claude/hooks/stop.sh",
    "subagentStop": ".claude/hooks/subagent-stop.sh",
    "preCompact": ".claude/hooks/pre-compact.sh",
    "sessionStart": ".claude/hooks/session-start.sh"
  }
}

Step 2: Create hook scripts:

mkdir -p .claude/hooks
chmod +x .claude/hooks/*.sh

Step 3: Test your pipeline:

claude "test hook pipeline"

You should see your hooks fire at each stage.

Real Pipeline Example: Zimbra Quality Gates

| Stage | Hook | Purpose | Exit on Error? | |-------|------|---------|----------------| | Before Action | PreToolUse | Validate operations | ✅ Yes | | After Action | PostToolUse | Quality checks | ✅ Yes | | Session End | Stop | Documentation | ❌ No |

# .claude/hooks/pre-tool-use.sh (Safety)
#!/bin/bash

# Block direct Zimbra config edits
if [[ "$CLAUDE_TOOL_INPUT" == *"/opt/zimbra/conf"* ]]; then
  echo "ERROR: Use zmprov for config changes, not direct edits"
  exit 1
fi

# .claude/hooks/post-tool-use.sh (Quality)
#!/bin/bash

# Auto-test after Zimbra config changes
if echo "$CLAUDE_FILE_PATHS" | grep -q "zimbra"; then
  echo "Running Zimbra config validation..."
  zmcontrol -v || {
    echo "ERROR: Config validation failed!"
    exit 1
  }
fi

# .claude/hooks/stop.sh (Documentation)
#!/bin/bash

# Auto-update changelog
if [[ -n "$CLAUDE_FILE_PATHS" ]]; then
  echo "$(date): Modified $(echo $CLAUDE_FILE_PATHS | tr ' ' ',') - $CLAUDE_USER_PROMPT" >> CHANGELOG.md
fi

Now you have:

• Safety gates preventing dangerous operations
• Automatic validation after changes
• Auto-generated changelog

All without manual intervention.

The 8-hook automation pipeline: from session start to completion with safety gates at every step

Memory Aid: Hook Lifecycle Stages

Think of hooks in three stages:

1. Pre-Flight (SessionStart, UserPromptSubmit): Setup and validation
2. In-Flight (PreToolUse, PostToolUse, Notification): Active work
3. Post-Flight (PreCompact, SubagentStop, Stop): Cleanup and reporting

This mental model helps you choose the right hook for each automation need.

---

Part 4: Checkpoints - Your Code Time Machine

What Are Checkpoints?

Checkpoints automatically save your code state before each change. Think "git stash" but automatic.

The magic: Press Escape twice to instantly rewind to any previous checkpoint.

Checkpoint Operations

| Operation | Command | Use Case | Persistence | |-----------|---------|----------|-------------| | Auto-save | Automatic (every change) | Safety net | Session-only | | Quick rewind | [Escape] [Escape] | Undo last change | Immediate | | Named save | /checkpoint save-name | Before risky work | Until restore | | Restore | /checkpoint restore save-name | Return to known state | Permanent | | Compare | @checkpoint:name | A/B testing | Analysis-only |

Basic Checkpoint Usage

# Claude makes changes
> Refactor auth.js to use async/await

# See the changes, don't like them?
[Escape] [Escape]

# Back to original! Try different approach:
> Refactor auth.js to use promises with better error handling

Advanced: Named Checkpoints

# Create explicit checkpoint
> /checkpoint save-before-risky-refactor

# Try experimental approach
> Completely rewrite the auth system using passport.js

# Hate it? Rewind to specific checkpoint:
> /checkpoint restore save-before-risky-refactor

Checkpoints for A/B Testing

Scenario: Which state management approach is better?

| Phase | Action | Checkpoint Name | Outcome | |-------|--------|----------------|---------| | Baseline | Save starting point | before-state-management | Clean slate | | Approach A | Implement Redux | redux-implementation | Option 1 | | Rewind | Restore baseline | (restore checkpoint) | Reset | | Approach B | Implement Zustand | zustand-implementation | Option 2 | | Compare | Analyze both | (compare mode) | Decision |

Approach A (Redux):

> /checkpoint before-state-management
> Implement global state with Redux Toolkit
[Claude implements]
> /checkpoint redux-implementation

Approach B (Zustand):

> /checkpoint restore before-state-management
> Implement global state with Zustand
[Claude implements]
> /checkpoint zustand-implementation

Compare:

> Compare the two implementations:
> - @checkpoint:redux-implementation
> - @checkpoint:zustand-implementation
> Analyze code complexity, bundle size, and developer experience

Claude can compare checkpoint states and recommend the better approach.

Checkpoint + Git Worktree = Experimental Heaven

Combine checkpoints with git worktrees for parallel alternative exploration:

Terminal 1 (worktree feature-a):

git worktree add ../project-feature-a feature-a
cd ../project-feature-a
claude "Implement feature A with approach 1"

Terminal 2 (worktree feature-a-alt):

git worktree add ../project-feature-a-alt feature-a
cd ../project-feature-a-alt
claude "Implement feature A with approach 2"

Now you're exploring alternatives in parallel with separate Claude instances, shared git history, and checkpoint safety nets.

When done:

# Compare results
git diff ../project-feature-a ../project-feature-a-alt

# Choose winner, merge
cd project-feature-a
git merge --squash feature-a
git worktree remove ../project-feature-a
git worktree remove ../project-feature-a-alt

Checkpoint vs Git: Decision Matrix

| Feature | Checkpoints | Git Commits | |---------|-------------|-------------| | Speed | Instant (< 1 second) | Seconds to minutes | | Scope | Session-local | Project-global | | Sharing | Not shareable | Team-wide | | Purpose | Experimentation | Version control | | Persistence | Until session ends | Permanent | | Rewind | [Escape] [Escape] | git reset/revert |

Use both: Checkpoints for exploration, git commits for finalized work.

---

Part 5: Multi-Agent Orchestration

The Subagent Pattern

Subagents are specialized AI workers that handle focused tasks while the main agent orchestrates.

Why Use Subagents?

| Benefit | Explanation | Real-World Example | |---------|-------------|-------------------| | 🎯 Isolated context | Each subagent has clean context window | Security audit doesn't see UI code | | ⚡ Parallel execution | Multiple subagents work simultaneously | Test + security + perf checks together | | 🔧 Specialization | Each agent optimized for specific task | DB expert for queries, security for audits | | 🔒 Context isolation | No "spillover" between unrelated tasks | Backend work doesn't confuse frontend |

Creating Custom Subagents

Create .claude/agents/ directory:

mkdir -p .claude/agents

Subagent Template Structure

| Section | Purpose | Example | |---------|---------|---------| | Frontmatter | Name, description | name: security-audit | | Expertise | Domain focus | OWASP Top 10, penetration testing | | Analysis criteria | What to check | SQL injection, XSS, CSRF | | Output format | Expected result | Line numbers, severity, fixes |

Security Auditor Agent (.claude/agents/security-audit.md):

---
name: security-audit
description: Security vulnerability scanner
---

You are a security auditing specialist. Analyze code for:

## OWASP Top 10
- SQL injection
- XSS vulnerabilities
- CSRF attacks
- Insecure authentication
- Security misconfiguration

## Best Practices
- Input validation
- Output encoding
- Proper error handling
- Secure session management

For each issue found:
1. Show exact line number
2. Explain the vulnerability
3. Provide secure alternative
4. Rate severity (Critical/High/Medium/Low)

Database Optimizer Agent (.claude/agents/db-optimize.md):

---
name: db-optimize
description: Database query optimization specialist
---

You are a database performance specialist. Analyze:

## Query Optimization
- Missing indexes
- N+1 query problems
- Inefficient joins
- Full table scans

## Schema Design
- Normalization issues
- Index strategy
- Partitioning opportunities

Provide:
- Current query EXPLAIN plan
- Optimized query
- Expected performance improvement
- Index recommendations

Using Subagents

Invoke with @mention:

> @security-audit review @src/auth/login.js

The security-audit subagent analyzes in isolation, returns findings.

Parallel subagent workflow:

# Main agent
> Implement user profile feature @src/profile/

# Concurrently, launch subagents:
> @security-audit review profile feature as it's being built
> @db-optimize analyze profile queries
> @test-generator create test suite for profile endpoints

Three subagents working in parallel!

Test-Driven Development with Subagents

The gold standard workflow:

| Phase | Actor | Action | Verification | |-------|-------|--------|--------------| | Red | Test subagent | Generate failing tests | All tests fail | | Green | Main agent | Implement features | Tests pass | | Refactor | Main agent | Improve code quality | Tests still pass | | Verify | Test subagent | Re-run full suite | Confirm success |

Step 1: Write tests (you or test-generator subagent)

> @test-generator create comprehensive tests for password reset flow
> Include: valid email, invalid email, expired token, used token

Step 2: Confirm tests fail

> Run the test suite - they should all fail (not implemented yet)

Step 3: Commit tests only

git add tests/password-reset.test.js
git commit -m "Add password reset tests (red phase)"

Step 4: Main agent implements

> Implement password reset functionality to make these tests pass:
> @tests/password-reset.test.js

Step 5: Verification subagent

> @test-verifier run tests and confirm all pass
> Report any failures with specific fixes needed

Step 6: Commit implementation

git add src/auth/password-reset.js
git commit -m "Implement password reset (green phase)"

Why this works: Anthropic's research shows "Claude performs best when it has a clear target to iterate against." Tests provide that target.

Multi-Claude Orchestration

For complex projects, run multiple Claude instances in parallel.

Parallel Development Patterns

| Pattern | Use Case | Coordination Method | Merge Strategy | |---------|----------|---------------------|----------------| | Git Worktrees | Feature development | Shared git history | Merge branches | | Main + Verification | Quality assurance | Separate contexts | Review approval | | Domain Specialists | Microservices | API contracts | Integration tests |

Pattern 1: Git Worktrees

# Main development (main agent)
claude

# Backend API (separate instance)
git worktree add ../project-backend feature/api
cd ../project-backend && claude

# Frontend UI (separate instance)
git worktree add ../project-frontend feature/ui
cd ../project-frontend && claude

# Tests (separate instance)
git worktree add ../project-tests feature/tests
cd ../project-tests && claude

Four Claude instances, shared git history, isolated workspaces.

Pattern 2: Main + Verification

• Main instance: Implements features
• Verification instance: Reviews and tests

# Terminal 1 - Implementation
claude "Implement OAuth integration"

# Terminal 2 - Verification
claude "Review the OAuth implementation for security issues"

Separate contexts often yield better reviews than single-instance self-review.

Zimbra Multi-Agent Example

Main agent (orchestrator):

> Analyze recent mail delivery issues
> Delegate tasks to specialized agents

Subagent 1 (queue-analyzer):

> @queue-analyzer check mail queue for stuck messages
> Analyze: postqueue -p

Subagent 2 (log-analyzer):

> @log-analyzer scan mailbox.log for errors in last hour
> Focus on: SMTP timeouts, connection refused, DNS failures

Subagent 3 (health-checker):

> @health-checker verify all Zimbra services running
> Check: zmcontrol status

Main agent synthesizes:

Results from agents:
- Queue: 47 stuck messages to gmail.com
- Logs: DNS resolution failures for gmail.com MX
- Health: All services running normally

Root cause: DNS server issue
Recommendation: Check /etc/resolv.conf and restart DNS cache

Three specialists, one orchestrator, comprehensive diagnosis.

Multi-agent architecture: main orchestrator delegates to specialized subagents for comprehensive analysis

Memory Aid: Agent Specialization Matrix

When creating subagents, ask:

1. What's the domain? (security, performance, testing)
2. What's the input? (code files, logs, metrics)
3. What's the output? (report, recommendations, fixes)

This 3-question framework ensures your subagents are focused and effective.

---

Part 6: Power User Arsenal

Extended Thinking: Advanced Usage

Combine thinking levels with specific guidance:

Advanced Thinking Template

| Component | Purpose | Example | |-----------|---------|---------| | Trigger word | Allocate thinking budget | ultrathink: | | Requirements | Define constraints | Zero downtime, data integrity | | Considerations | Guide analysis | Dual-write, shadow mode, monitoring | | Deliverables | Expected output | Strategy, rollback plan, metrics |

> ultrathink: Design a database migration strategy
>
> Requirements:
> - Zero downtime (24/7 service)
> - Data integrity guarantees
> - Rollback capability
> - Gradual migration (not big bang)
>
> Consider:
> - Dual-write period
> - Shadow mode validation
> - Traffic switching
> - Monitoring & alerting

With 32k token budget, Claude will:

1. Analyze each requirement deeply
2. Consider edge cases
3. Design comprehensive strategy
4. Include rollback procedures
5. Provide monitoring recommendations

Safe YOLO Mode

Want --dangerously-skip-permissions but safely?

Run Claude in isolated container:

# Dockerfile
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y \
    curl \
    git \
    nodejs \
    npm

# Install Claude CLI
RUN npm install -g @anthropic/claude-cli

# No internet access to production
# No access to sensitive directories
# Sandboxed execution

WORKDIR /workspace
CMD ["claude", "--dangerously-skip-permissions"]

Usage:

docker build -t claude-sandbox .
docker run -it -v $(pwd):/workspace claude-sandbox

Now Claude can work autonomously without risk to production systems.

MCP Server Advanced Patterns

MCP (Model Context Protocol) servers extend Claude Code with external tool access.

MCP Transport Types

| Transport | Use Case | Configuration | Best For | |-----------|----------|---------------|----------| | command | Local tools | Direct executable | Git, filesystem, local DBs | | http | Remote services | URL + headers | APIs, cloud services, enterprise tools | | stdio | npm packages | npx command | Node.js MCP servers |

HTTP MCP servers (recommended for remote services):

{
  "mcpServers": {
    "github-enterprise": {
      "transport": "http",
      "url": "https://mcp.company.com/github",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "jira-api": {
      "transport": "http",
      "url": "https://mcp.company.com/jira"
    }
  }
}

Now Claude can:

• Create GitHub issues from bugs found in code
• Update Jira tickets with progress
• Query production databases (read-only)
• Fetch Figma designs for implementation

All without you manually switching contexts.

The 4 core context engineering strategies: write, select, compress, isolate for optimal output quality

Advanced CLI Flags

| Flag | Purpose | Example Use Case | |------|---------|------------------| | --allowedTools | Restrict tool access | Security: only allow read operations | | MAX_MCP_OUTPUT_TOKENS | Increase MCP limits | Large dataset analysis | | --config-dir | Custom config location | Team shared settings | | --model | Specific model version | Test new model features | | --mcp-debug | Debug MCP issues | Troubleshoot connection problems |

# Specific tools only (security)
claude --allowedTools "Bash(git:*),Bash(npm:*),Read,Edit,Write"

# Increase MCP output limits
MAX_MCP_OUTPUT_TOKENS=100000 claude

# Custom config directory (team settings)
claude --config-dir /team/shared/claude-config

# Specific model version
claude --model claude-sonnet-4.5-20250101

# Debugging MCP issues
claude --mcp-debug

The Visual Iteration Workflow

For UI work, combine screenshots with iteration:

Setup (Puppeteer MCP):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Workflow:

# Step 1: Show design mock
> Here's the design mock: [drag-drop image]
> Implement this landing page

# Step 2: See initial implementation
> Take a screenshot of localhost:3000

# Step 3: Iterate
> The hero section is too cramped. Add 60px vertical padding
> The CTA button should be more prominent - increase size 20%

# Step 4: Verify
> Take another screenshot

# Step 5: Iterate again
> Looking good! Now make it responsive for mobile

Anthropic data: Quality improves significantly after 2-3 iterations with visual feedback.

Git Superpowers

Many Anthropic engineers use Claude for 90%+ of git operations.

Git Operations via Claude

| Operation | Complexity | Claude Advantage | Example | |-----------|------------|------------------|---------| | Simple commit | Low | Conventional commit format | Semantic versioning | | Rebase conflicts | High | Context-aware resolution | API refactor conflicts | | Cherry-pick | Medium | Adapt to different context | Backport feature | | History search | Medium | Natural language queries | "When was rate limiting added?" |

Complex rebase:

> I need to rebase feature-branch onto main, but there will be conflicts
> in auth.js and config.js. Help me resolve them intelligently.

Cherry-pick with grafting:

> Cherry-pick commit abc123 from main to feature-branch,
> but adapt it to our feature's context (different API structure)

Commit archaeology:

> Search git history to find when the "rate limiting" feature
> was introduced and who made the decision

Conventional commits:

> Generate conventional commit message for these changes:
> @git:staged

Claude outputs:

feat(auth): add OAuth2 support for third-party login

- Implement OAuth2 authorization code flow
- Add Google and GitHub providers
- Include PKCE for mobile security
- Add tests for token exchange

BREAKING CHANGE: Auth endpoint moved from /login to /auth/login

---

Real-World Workflows

Workflow 1: Zero-Downtime Database Migration

Goal: Migrate user database from MongoDB to PostgreSQL without downtime.

Migration Phases

| Phase | Duration | Risk Level | Rollback Time | |-------|----------|------------|---------------| | Dual-write setup | 2 days | Low | Instant | | Shadow mode | 1 week | Medium | < 1 minute | | Traffic shift (1%) | 1 day | Medium | < 1 minute | | Traffic shift (50%) | 2 days | High | < 5 minutes | | Full migration | 1 day | Low | Planned only |

Context files:

# .claude/activeContext.md
Current task: MongoDB → PostgreSQL migration
Constraint: Zero downtime (24/7 SaaS)
Timeline: 2-week gradual migration

Step 1: Ultra-think planning

> ultrathink: Design zero-downtime MongoDB → PostgreSQL migration
>
> System: 50k active users, 10M records, 24/7 availability required
> Constraints: <5ms query latency, data integrity guarantees

Claude's 32k-token thinking phase produces:

1. Dual-write architecture (write to both DBs)
2. Shadow mode (validate Postgres results against Mongo)
3. Gradual traffic shifting (1% → 10% → 50% → 100%)
4. Rollback procedure (instant switch back)
5. Monitoring dashboards

Step 2: Implement with subagents

Main agent:

> Implement dual-write layer
> @src/db/

Security subagent (parallel):

> @security-audit review migration code for SQL injection risks

Performance subagent (parallel):

> @db-optimize analyze Postgres query performance
> Compare to MongoDB baseline

Step 3: Automated testing via hooks

.claude/hooks/post-tool-use.sh:

#!/bin/bash
if [[ "$CLAUDE_FILE_PATHS" == *"src/db"* ]]; then
  echo "Running migration test suite..."
  npm run test:migration || exit 1
fi

Step 4: Checkpoint protection

> /checkpoint before-production-rollout

Step 5: Monitor with session hook

.claude/hooks/session-start.sh:

#!/bin/bash
echo "Fetching latest migration metrics..."
psql -c "SELECT COUNT(*) FROM users" > /tmp/pg-count.txt
mongo --eval "db.users.count()" > /tmp/mongo-count.txt
echo "Postgres: $(cat /tmp/pg-count.txt)"
echo "MongoDB: $(cat /tmp/mongo-count.txt)"

Result: Claude manages entire migration with automated safety, parallel verification, and instant rollback capability.

Workflow 2: Zimbra Multi-Tenant Security Audit

Goal: Audit Zimbra configuration for security issues across 50 domains.

Security Audit Checklist

| Domain | Check | Severity | Auto-Fixable? | |--------|-------|----------|---------------| | Isolation | Cross-tenant access | Critical | No (manual review) | | Encryption | TLS enforcement | High | Yes (config update) | | Auth | Password strength | Medium | Yes (policy change) | | Logging | Audit trail | High | Yes (enable logging) |

Setup: Memory Bank for Zimbra

# .claude/zimbraContext.md

## Architecture
- 50 domains (tenant isolation critical)
- Shared infrastructure (separate mailboxes)
- LDAP for auth (per-domain trees)

## Security Requirements
- Domain isolation (no cross-tenant access)
- Encrypted connections (TLS required)
- Strong passwords (12+ chars, complexity)
- Audit logging (all admin actions)

IMPORTANT: Any cross-tenant data access is CRITICAL security bug
YOU MUST: Flag any shared resources between domains

Workflow with hooks and subagents:

Main agent (orchestrator):

> Audit Zimbra security for all 50 domains
> Delegate to specialized agents

Security subagent:

> @security-audit check domain isolation
> Command: zmprov getAllDomains
> Verify: Each domain has separate LDAP tree

Compliance subagent:

> @compliance-audit verify TLS enforcement
> Check: zimbraReverseProxyMailMode is both
> Requirement: All connections must use TLS

Permission subagent:

> @permission-audit check admin privileges
> Find: Any users with global admin rights
> Requirement: Admins should be domain-scoped only

Hook automation (.claude/hooks/post-tool-use.sh):

#!/bin/bash

# Auto-export audit results
if [[ "$CLAUDE_USER_PROMPT" == *"audit"* ]]; then
  echo "Generating audit report..."
  {
    echo "# Zimbra Security Audit - $(date)"
    echo ""
    echo "## Findings"
    cat $CLAUDE_OUTPUT
  } > audit-report-$(date +%Y%m%d).md

  echo "Report saved: audit-report-$(date +%Y%m%d).md"
fi

Result: Comprehensive security audit with:

• Automated report generation
• Parallel agent analysis
• Compliance verification
• Exportable findings

Workflow 3: Test-Driven Zimbra Automation

Goal: Create automated Zimbra backup system with tests.

Step 1: Write tests first

> @test-generator create test suite for Zimbra backup automation
>
> Requirements:
> - Test: Verify backup includes all mailboxes
> - Test: Verify backup compression works
> - Test: Verify backup integrity (checksum validation)
> - Test: Verify old backups are pruned (7-day retention)
> - Test: Verify backup completes within 2 hours

Step 2: Confirm tests fail (red phase)

> Run test suite - confirm all tests fail (not implemented)
$ pytest tests/backup_test.py
# All tests fail ✓

Step 3: Commit tests

git add tests/backup_test.py
git commit -m "test: Add Zimbra backup test suite (red)"

Step 4: Implement with TDD discipline

> Implement backup system to make tests pass
> DO NOT implement any features not covered by tests
> @tests/backup_test.py

Step 5: Hook validates (.claude/hooks/pre-compact.sh):

#!/bin/bash
echo "Running tests before session end..."
pytest tests/backup_test.py || {
  echo "ERROR: Tests failing - session not complete"
  exit 1
}

Step 6: Verification subagent

> @test-verifier run tests, confirm all pass, analyze coverage

Subagent reports:

✓ All 5 tests passing
✓ Code coverage: 94%
⚠ Missing: Error handling for disk full scenario

Step 7: Address gaps

> Add test and implementation for disk-full error handling

Result: Production-ready backup system with:

• 100% test coverage
• TDD discipline maintained
• Automated verification
• No untested code paths

---

FAQ

How does "ultrathink" actually work?

It's a programmatic trigger in Claude Code that allocates a specific token budget (31,999 tokens) for extended thinking. When Claude sees "ultrathink" in your prompt, it enters a deeper reasoning mode, evaluating more alternatives and considering more edge cases.

Not marketing, actual feature.

Important limitation: Ultrathink only works in Claude Code's terminal interface, not in the web chat or API. Claude Code has a preprocessing layer that intercepts these keywords before sending prompts to the model.

Is the Memory Bank pattern officially supported?

No, it's a community pattern from the Cline AI agent. However, it works perfectly with Claude Code via CLAUDE.md files, which ARE officially supported. Think of it as a "design pattern" rather than a built-in feature.

Can hooks access environment variables?

Yes! Hooks receive several environment variables:

| Variable | Content | Example Value | |----------|---------|---------------| | CLAUDE_PROJECT_DIR | Current project directory | /home/user/myproject | | CLAUDE_FILE_PATHS | Files being modified | src/auth.js src/db.js | | CLAUDE_USER_PROMPT | Your original prompt | Implement OAuth login | | CLAUDE_TOOL_NAME | Tool being executed | Bash, Edit, Write | | CLAUDE_TOOL_INPUT | Tool input parameters | Command arguments, file paths |

Use these to build sophisticated automation.

How do I share subagents with my team?

Store subagent definitions in .claude/agents/ directory and commit to git:

git add .claude/agents/
git commit -m "Add team subagents: security-audit, db-optimize"
git push

Now everyone on your team can use @security-audit and @db-optimize.

What's the difference between checkpoints and git commits?

| Feature | Checkpoints | Git Commits | |---------|-------------|-------------| | Creation | Automatic (every change) | Manual (you control) | | Speed | Instant (< 1 second) | Seconds to minutes | | Persistence | Session-local (not on disk) | Permanent history | | Sharing | Personal only | Shared with team | | Purpose | Experimentation | Version control | | Rewind | [Escape] [Escape] | git reset/revert |

Use both: Checkpoints for exploration, git commits for finalized work.

Can I run Claude Code in CI/CD pipelines?

Absolutely! Use headless mode:

# .github/workflows/code-review.yml
name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Claude Review
        run: |
          claude -p "Review PR changes for security issues:
          $(git diff main...HEAD)" \
          --output-format json > review.json
      - name: Comment PR
        uses: actions/github-script@v6
        with:
          script: |
            const review = require('./review.json')
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              body: review.output
            })

How do I optimize CLAUDE.md files?

Treat them as prompts and optimize accordingly:

| Technique | Before | After | |-----------|--------|-------| | Use emphasis | "We use React" | "IMPORTANT: Use React 18 with TypeScript" | | Be specific | "Use hooks" | "YOU MUST: Use functional components with hooks" | | Add examples | (none) | Show code patterns with comments | | Visual diagrams | Text descriptions | Mermaid flowcharts | | Focus | Kitchen sink | Only relevant context |

Run this:

> Analyze my CLAUDE.md and suggest improvements
> Make it more effective at guiding AI behavior
> @CLAUDE.md

What's the 3-File Rule exactly?

Only include files that DIRECTLY relate to your current task.

More context ≠ better results. LLMs have finite "attention budget" - too much context causes performance degradation.

Test: Ask Claude to summarize your codebase with 3 files vs 30 files. Notice the quality difference.

---

Conclusion

You've just learned Claude Code's deep architecture:

✅ Thinking Engineering: Extended thinking modes (think → think hard → ultrathink) ✅ Persistent Context: Memory Bank pattern via CLAUDE.md hierarchy ✅ AI Pipeline: 8-hook automation framework ✅ Code Time Machine: Checkpoints for risk-free experimentation ✅ Multi-Agent System: Subagents + parallel Claude instances ✅ Power Arsenal: Advanced CLI flags, MCP patterns, git superpowers

But here's the real insight: These aren't just "features to try."

They're building blocks for your AI development system.

The Challenge

Build your complete AI engineering stack:

Week 1: Foundations

| Task | Estimated Time | Priority | |------|----------------|----------| | Create Memory Bank files (projectbrief, systemPatterns, techContext) | 2 hours | High | | Optimize CLAUDE.md with emphasis keywords | 1 hour | High | | Set up 3-File Rule habit | Ongoing | High |

Week 2: Automation

| Task | Estimated Time | Priority | |------|----------------|----------| | Implement 3 critical hooks (PreToolUse, PostToolUse, SessionStart) | 3 hours | High | | Create safety gates for dangerous operations | 1 hour | Critical | | Add auto-formatting hook | 30 mins | Medium |

Week 3: Agents

| Task | Estimated Time | Priority | |------|----------------|----------| | Create 3 custom subagents for your domain | 2 hours | High | | Test subagent parallel workflows | 1 hour | Medium | | Implement TDD with test-verifier subagent | 2 hours | High |

Week 4: Advanced

| Task | Estimated Time | Priority | |------|----------------|----------| | Set up git worktrees for parallel development | 1 hour | Medium | | Use checkpoints for A/B testing implementations | Ongoing | Medium | | Integrate Claude into CI/CD pipeline | 3 hours | High |

Your Mission: After 4 weeks, you should have a complete AI development system that feels like having a whole development team.

Then come back and tell us: How much faster are you?

Quick Reference Card

Print this for your desk:

| Task | Command/Pattern | |------|-----------------| | Deep thinking | ultrathink: [your complex problem] | | Load context | @file1.js @file2.js @file3.js (max 3) | | Quick rewind | [Escape] [Escape] | | Named checkpoint | /checkpoint save-name | | Invoke subagent | @subagent-name [task] | | Compact memory | /compact | | Safety gate | Hook: PreToolUse with validation | | Auto-format | Hook: PostToolUse with formatter |

---

👈 Previous: VS Code Integration Guide 👉 Next: Troubleshooting Guide

---

P.S. If you're still not using "ultrathink" for complex decisions, you're leaving 28,000 tokens of thinking budget on the table. Just saying.