We've spent months refining our Claude Code setup. What started as default configuration has evolved into a comprehensive system of custom agents, MCP integrations, hooks, and automation patterns that multiply our productivity. This article documents the setup in detail. Whether you're just getting started with Claude Code or looking to level up an existing configuration, you'll find patterns you can adopt.

Project structure

Our Claude Code configuration lives in several locations.

project/
├── .claude/
│   ├── agents/              # Project-specific agents
│   │   ├── full-stack-engineer.md
│   │   ├── seo-specialist.md
│   │   └── qa-engineer.md
│   └── settings.json        # Project settings & hooks
├── CLAUDE.md                # Project context (always loaded)
└── .agent/                  # Navigator documentation system
    ├── DEVELOPMENT-README.md
    ├── tasks/
    ├── system/
    └── sops/

The .claude/ directory contains Claude Code-specific configuration. The .agent/ directory holds our Navigator documentation system, a structured approach to managing project knowledge that Claude loads on demand.

The CLAUDE.md file

CLAUDE.md is automatically loaded at the start of every Claude Code session. It's our single source of truth for project context.

# Project: QuantFlow Landing

## Context
High-performance landing page.
Tech: Next.js + React + TypeScript + TailwindCSS v4.

## SSR-First Principles (CRITICAL)
1. DEFAULT TO SERVER COMPONENTS
2. Page components MUST be server
3. 'use client' ONLY for interactivity

## Forbidden Actions
- NEVER 'use client' on page components
- No package.json modifications without approval
- No inline styles (use TailwindCSS)

## Development Workflow
1. Read .agent/DEVELOPMENT-README.md first
2. Check Linear for assigned tickets
3. Use TodoWrite for complex tasks

Key principles for effective CLAUDE.md files:

• –Keep it focused. Token budget matters. Include only what Claude needs for every session.
• –Be explicit about rules. "Never" and "Always" statements prevent common mistakes.
• –Reference other docs. Point to detailed documentation rather than duplicating it.
• –Version it. Track changes to your project context alongside your code.

Custom agents

Agents are specialized AI assistants with their own context windows and instructions. Here's our full-stack engineer agent.

---
name: full-stack-engineer
description: >
  Implementation agent for Next.js features.
  Auto-invoke for coding tasks, refactoring, testing.
model: sonnet
tools: Read, Write, Edit, Bash, Grep, Glob
---

You are a senior full-stack engineer specializing in
Next.js, React, TypeScript, and TailwindCSS v4.

## Core Principles
- SSR-first: Server Components by default
- No inline styles: TailwindCSS only
- TypeScript strict mode: No 'any' without justification

## When Implementing Features
1. Check existing patterns in codebase
2. Follow SSR decision tree
3. Extract client components to separate files
4. Add proper TypeScript types
5. Update tests if applicable

## Forbidden
- Never add 'use client' to page.tsx files
- Never modify package.json without asking
- Never use inline styles

We have agents for different roles: SEO specialist handles metadata and schema markup, QA engineer runs comprehensive testing, Linear PM manages ticket workflows. Each agent has focused instructions that encode our team's standards.

MCP integrations

The Model Context Protocol (MCP) is what makes Claude Code truly powerful. It's the "USB-C for AI": a universal way to connect Claude to external tools and services. Our active MCP servers:

Linear MCP, ticket management directly from Claude Code:

// Read assigned issues
list_issues({ assignee: "me" })

// Get ticket details
get_issue({ id: "QF-123" })

// Update progress
update_issue({ id: "QF-123", state: "In Progress" })

// Add comments
create_comment({ issueId: "QF-123", body: "Implementation complete" })

Slack MCP, team communication without leaving the terminal:

// Post updates to engineering channel
conversations_add_message({
  channel_id: "#quantflow-engineering",
  payload: "QF-123 deployed to staging"
})

Chrome DevTools MCP, browser automation for testing:

// Navigate and screenshot
navigate_page({ url: "http://localhost:3000" })
take_screenshot({ fullPage: true })

// Performance tracing
performance_start_trace({ reload: true, autoStop: true })

Adding a new MCP server is simple:

claude mcp add linear-server --scope user
claude mcp add slack --scope user
claude mcp list  # Verify installation

Hooks system

Hooks are shell commands that execute at specific lifecycle points. They provide deterministic control over Claude's behavior, essential for enforcing team standards. Example: auto-format on file edit.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Available hook events:

• –PreToolUse: before tool calls (can block them)
• –PostToolUse: after tool calls complete
• –UserPromptSubmit: when the user submits a prompt
• –PermissionRequest: when permission dialogs appear
• –Stop: when Claude finishes a task
• –SessionStart / SessionEnd: session lifecycle

We use hooks for automatic formatting, lint fixes, commit message validation, and file protection (preventing edits to production configs).

Context optimization

With a 200K token context window, Claude can hold a lot, but not everything. We've developed strategies to maximize context efficiency.

• –Navigator documentation system. Instead of loading all documentation at session start, we use a lightweight index (DEVELOPMENT-README.md) that tells Claude what docs exist and when to load them. Typical savings: 90%+ reduction in documentation tokens.
• –Agent-based research. For codebase exploration, we spawn Explore subagents rather than loading files directly. The subagent does the searching, summarizes findings, and returns only relevant context.
• –Strategic /compact. After completing isolated tasks, we run /compact to clear conversation history while preserving key context. This resets the token budget for the next task.
• –Context markers. Before compacting, we save state to .agent/.context-markers/. This lets us resume work exactly where we left off in future sessions.

Automation patterns

Beyond interactive use, Claude Code integrates into our broader automation. Headless mode for batch operations:

# Analyze multiple files
find src -name "*.tsx" | xargs -I {} claude -p "Review for SSR violations: {}"

# Generate documentation
claude -p "Generate JSDoc for all exported functions" --output json

Parallel execution with worktrees:

# Create isolated worktree for parallel development
git worktree add ../project-feature-x feature-x

# Run Claude Code in each worktree
# Changes stay isolated until merge

Getting started

If you want to replicate our setup, start here.

• –Install Claude Code: npm install -g @anthropic-ai/claude-code, then claude auth login.
• –Create your CLAUDE.md. Start with project basics: tech stack, coding standards, forbidden actions. Iterate as you learn what context Claude needs.
• –Add your first MCP server: claude mcp add github --scope user.
• –Create a custom agent. Start with the /agents command to manage agents interactively. Create focused agents for your most common workflows.
• –Set up hooks. Add a .claude/settings.json with your first hook; auto-formatting is a good start.

Conclusion

Our Claude Code setup isn't magic. It's the result of iterative refinement. We've tried approaches that didn't work, simplified configurations that were too complex, and gradually built a system that amplifies our productivity. The key insight: Claude Code is most powerful when you invest in configuration. Default settings work, but custom agents, MCP integrations, and thoughtful context management transform it from a useful tool into a force multiplier.

If you're building with Claude Code and want to compare notes, we're always learning, and we'd love to hear about your setup.