Claude Code: The Complete Guide to AI-Augmented Development
Everything you need to know about Claude Code -- from installation and CLAUDE.md design to agent teams, MCP servers, and cost optimization. Based on 18+ months of daily production use.
By Jose Nobile | Updated 2026-04-23 | 30 min read
Table of Contents
- What Is Claude Code?
- The Agentic Loop
- Installation & Setup
- CLAUDE.md: Your Project Brain
- Memory System
- Custom Skills
- Hooks System
- MCP Servers
- Subagents & Agent Teams
- Plan Mode & Worktrees
- IDE Integrations
- Permissions & Sandboxing
- Session Management
- Keybindings
- Context Window Management
- Checkpoint System
- Scheduled Tasks & /loop
- Non-Interactive Mode
- Code Review
- Plugins & Marketplace
- Claude Code Channels (Telegram & Discord)
- Remote Control
- Models & Extended Thinking
- Enterprise Features
- Cloud Execution
- Third-Party Providers
- Anthropic Academy & Community
- Cost Optimization
- Real-World Example: SaaS Platform
What Is Claude Code?
Claude Code is Anthropic's official CLI tool for AI-augmented software development. Unlike chat-based coding assistants, Claude Code operates as an agentic coding tool that can read your entire codebase, execute terminal commands, edit files, and orchestrate complex multi-step workflows -- all from a single terminal session.
It ships as an npm package and runs inside your terminal, connecting directly to Claude's API. The key differentiator is that it understands your project holistically: it reads your CLAUDE.md configuration, respects your coding standards, and learns from your project's architecture to deliver contextually accurate changes.
Claude Code supports multiple operation modes: interactive chat, headless mode for CI/CD, plan mode for architecture review, and multi-agent orchestration for parallel development tasks. It integrates with VS Code and JetBrains IDEs while keeping the terminal as the primary interface.
Installation & Setup
The recommended installation method since October 2025 is the native installer. Node.js is no longer required:
curl -fsSL https://claude.ai/install.sh | bash
# macOS via Homebrew
brew install --cask claude-code
# Legacy alternative (requires Node.js 18+)
npm install -g @anthropic-ai/claude-code
claude
On first launch, Claude Code authenticates via your Anthropic account or API key. It creates a ~/.claude/ directory for global configuration and memory. For organizations, managed authentication via SSO is available through the Anthropic Console.
System Requirements
Node.js 18+, macOS / Linux / WSL2 on Windows. 4GB RAM minimum, 8GB recommended. Anthropic API key or Claude Max subscription.
Initial Configuration
Run claude config to set preferred model, permission mode, and default behaviors. Create CLAUDE.md at your project root for project-specific instructions.
Authentication Options
Direct API key, Claude Max 5x ($100/mo) or Max 20x ($200/mo), Claude Pro ($20/mo, includes Claude Code access), or enterprise SSO. API usage billed per token; Max and Pro offer predictable monthly costs.
CLAUDE.md: Your Project Brain
CLAUDE.md is the single most important file in any Claude Code project. It serves as the persistent instruction set that shapes how Claude interacts with your codebase. Think of it as a living document that encodes your team's coding standards, architecture decisions, and workflow preferences.
Claude Code reads CLAUDE.md files from multiple levels in a strict hierarchy: organization (~/.claude/org/CLAUDE.md, managed by admins), user (~/.claude/CLAUDE.md), project root, and nested subdirectories. Each subdirectory can have its own CLAUDE.md that adds context for that module. Additionally, a .claude/rules/ directory can contain multiple .md files that are all loaded as supplementary instructions, enabling modular rule organization.
In production projects, a well-crafted CLAUDE.md can be 200-500+ lines. For example, the project AGENTS.md (which functions as CLAUDE.md) contains 512 lines covering 8 custom skills, parallel agent strategies, and detailed architectural context.
A solid CLAUDE.md should include:
- Project overview and architecture summary
- Technology stack and version constraints
- Coding standards (naming conventions, file structure, error handling patterns)
- Testing requirements (TDD expectations, coverage thresholds, test structure)
- Git workflow (branch naming, commit message format, PR template)
- Custom skill definitions and when to use them
- Forbidden patterns (things Claude should never do)
- Environment-specific instructions (dev, staging, production)
Custom Skills
Skills are reusable prompt templates stored as Markdown files in .claude/skills/. When invoked via slash commands (e.g., /skill:deploy), they inject specialized instructions into Claude's context. Skills turn repetitive multi-step workflows into one-command operations.
Each skill is a Markdown file with optional YAML frontmatter for metadata like description, args (typed parameters the user passes when invoking), and allowed-tools. Skills support nested directory structures for organization (e.g., .claude/skills/deploy/staging.md) and can be scoped at three levels: user (~/.claude/skills/), project (.claude/skills/), and organization (managed via enterprise settings).
Claude Code ships with bundled skills you can use immediately: /simplify (reduce code complexity), /batch (apply changes across multiple files), /debug (systematic debugging with hypothesis testing), /loop (run recurring tasks), and /review (structured code review). These serve as both useful tools and templates for building your own skills.
Example: commit
Skill that validates changes, runs tests, formats code, and creates a conventional commit with proper message -- all from a single /commit command.
Example: review-pr
Analyzes a PR diff, checks for security issues, validates test coverage, verifies coding standards compliance, and generates a structured review comment.
Example: create-service
Scaffolds a new microservice with boilerplate, Dockerfile, Helm chart, CI pipeline, and unit tests following your team's architecture patterns.
Jose's project uses 8 custom skills: /testing, /deploying, /debugging, /developing, /mr-review, /jira-docs, /planning, and /cli-tools. Each skill encodes team-specific workflows, saving approximately 30 minutes per invocation and ensuring consistent quality across all developers.
Hooks System
Hooks are shell commands or scripts that run automatically at specific points during Claude Code's operation. They enable automated quality gates without manual intervention. Hooks are configured in .claude/settings.json and execute before or after tool calls.
Claude Code supports 24+ hook event points organized into categories:
- PreToolUse / PostToolUse -- Run before/after any tool call. Use matchers to target specific tools (e.g., only trigger on
EditorBash). Supports wildcards likemcp__*for all MCP tools. - SessionStart -- Runs when a session begins. Ideal for environment validation, dependency checks, or loading project state.
- UserPromptSubmit -- Fires after you submit a prompt but before Claude processes it. Enables input modification, prompt enrichment, or content filtering.
- Stop -- Runs when Claude finishes its turn. Use for final validation, notifications, or summary generation.
- Notification -- Event-based triggers for external integrations (Slack, email, webhooks).
- SubagentStart -- Fires when a subagent is spawned. Use to configure subagent-specific permissions or inject context.
Hooks support four types: shell (run a bash command), HTTP (call a webhook URL), LLM (invoke another model for validation), and agent (spawn a subagent). Exit codes control behavior: 0 = proceed, 1 = block the action, 2 = modify the input and retry. Async hooks run without blocking the main flow, useful for logging and notifications.
Recent additions to the hook event system include: StopFailure (fires when Claude's turn ends due to an error), PostCompact (runs after context compaction), Elicitation / ElicitationResult (triggers around MCP elicitation dialogs), and WorktreeCreate / WorktreeRemove (fires when worktrees are created or removed). HTTP hooks are now a first-class hook type alongside shell hooks.
MCP Servers
The Model Context Protocol (MCP) extends Claude Code's capabilities by connecting to external data sources and tools through standardized server interfaces. MCP servers expose tools, resources, and prompts that Claude can invoke during its operation.
MCP servers connect via three transports: stdio (local process, most common), SSE (server-sent events over HTTP), and streamable HTTP (bidirectional streaming). Configuration lives in .claude/settings.json at project, user, or organization scope. With 50+ community servers available, Claude can access practically any external service. Use the built-in tool search (ToolSearch) to discover available MCP tools at runtime -- Claude loads tool schemas on demand rather than loading all tools upfront.
Database Access
Connect to MySQL, PostgreSQL, MongoDB, or Supabase. Claude can query schemas, analyze data, write migrations, and validate queries against real databases during development.
Project Management & DevOps
Integrate with Atlassian Jira/Confluence (Rovo), GitHub, GitLab, Linear, and Slack. Claude can create issues, update tickets, post messages, and synchronize work across platforms.
Custom MCP Development
Build MCP servers in TypeScript or Python using the official SDK. Expose your internal APIs, documentation, or tooling as Claude-accessible tools with typed schemas.
Payments & Infrastructure
Connect Stripe for billing operations, Firebase for app backends, Puppeteer for browser automation, and cloud providers (AWS, GCP, Azure) for infrastructure management.
Jose runs 9 MCP servers in production: Atlassian Rovo (Jira + Confluence), Firebase, GitHub, GitLab, Slack, Linear, Supabase, Stripe, and Puppeteer. This gives Claude access to the entire development lifecycle -- from ticket creation to deployment verification to billing checks.
MCP Elicitation: MCP servers can now request structured input from the user mid-task via interactive dialogs. Two modes are supported: form fields (text inputs, dropdowns, checkboxes rendered inline) and browser URL (opens a URL for OAuth flows or complex forms). This enables MCP tools to collect credentials, confirm destructive actions, or gather parameters without breaking the agentic loop.
MCP Apps: Interactive UI in Claude Code
MCP Apps, released as GA in January 2026, is the first official MCP extension that enables tools to return interactive UI components directly within the conversation. Instead of receiving only text responses, Claude Code can now render dashboards, charts, forms, 3D visualizations, maps, and document viewers inline -- powered by MCP servers that expose UI resources via the ui:// URI scheme.
When an MCP tool includes a _meta.ui.resourceUri field in its response, Claude Code fetches the referenced UI resource and renders it in a sandboxed iframe. The app and host communicate bidirectionally via JSON-RPC 2.0 over postMessage, enabling the UI to request tool calls, update context, and receive live data. All UI runs in a security sandbox -- no access to the parent window and no arbitrary network requests.
This changes the interaction model significantly: instead of Claude describing data in text, it can show an interactive chart the user manipulates directly. A database query result becomes a sortable table. A deployment status becomes a live dashboard. The AI still orchestrates the workflow, but the user experience gains a visual, interactive dimension.
Data Dashboards
Query a database via MCP, then render results as interactive charts with zoom, hover tooltips, and series toggles -- all inside the Claude Code conversation.
System Monitoring
Real-time CPU, memory, and disk dashboards with live updates. The system-monitor-server example in the ext-apps repo demonstrates this pattern.
Document and Map Viewers
Render PDFs, interactive maps, 3D models (Three.js), and sheet music directly in the conversation. Users interact with content without leaving Claude Code.
Multi-Step Workflows
Forms and wizards that collect structured input from users. The UI sends data back to the MCP server via JSON-RPC, enabling complex approval and configuration flows.
For a deep dive into MCP Apps architecture, the ui:// URI scheme, security model, and code examples, see the MCP Servers guide.
Subagents & Agent Teams
Subagents are independent Claude Code instances spawned by a parent agent to handle specific subtasks. They come in two modes: foreground (blocks the parent until complete, returns results inline) and background (runs independently, notifies on completion). Each subagent operates in an isolated context with its own tool permissions and context window, preventing interference between tasks.
You can define custom agent types as Markdown files in .claude/agents/. Each file defines the agent's persona, allowed tools, and behavioral constraints. Built-in agent types include the Task agent (general purpose), Research agent (read-only exploration), and Review agent (code analysis). Subagents inherit the parent's CLAUDE.md and MCP configuration but can override specific settings.
Agent teams take this further with multi-session coordination: multiple agents share a task list, send peer messages to each other, and can pursue competing hypotheses. For example, two agents might try different approaches to a performance optimization; the parent evaluates both results and picks the winner.
Key patterns for multi-agent workflows:
- Fan-out / Fan-in -- Parent spawns N agents for parallel tasks, collects results, and synthesizes them
- Pipeline -- Agents work sequentially, each building on the previous agent's output
- Specialist teams -- Frontend agent, backend agent, and test agent work in parallel on related changes
- Competing hypotheses -- Multiple agents try different solutions; the best result wins
In the project, parallel agent strategies reduced feature development time by approximately 40%. Three agents work simultaneously: one on API endpoints, one on frontend components, and one on integration tests. The AGENTS.md file defines each agent's scope and coordination protocol.
Plan Mode & Worktrees
Plan mode (Shift+Tab to toggle) switches Claude Code into a read-only analysis mode with extended thinking enabled. Claude cannot edit files or run commands; it can only read, search, and reason. This forces deeper analysis and produces higher-quality implementation plans. You review the plan and explicitly approve before Claude executes any changes.
Worktrees provide git-level isolation for parallel work. Each worktree is a separate checkout of your repository on a different branch, with its own working directory. Claude Code creates per-branch sessions tied to each worktree, so context and history stay isolated. Multiple agents can work on different features simultaneously without merge conflicts during development.
The combination of plan mode and worktrees creates a powerful workflow: use plan mode to decompose a large feature into tasks, then spawn agents in separate worktrees to implement each task in parallel. Merge results back when all agents complete.
Recent worktree enhancements include: the --worktree (-w) CLI flag to launch directly into a worktree, isolation: worktree in agent definitions for automatic worktree creation per agent, and worktree.sparsePaths configuration for large monorepos to check out only the directories each agent needs.
Practical example: Toggle plan mode and ask "How should we refactor the payment service to support multi-currency?" Claude reads the entire payment module, analyzes dependencies, and produces a step-by-step plan with file-level change descriptions. Approve it, and Claude switches to act mode to execute the plan precisely.
IDE Integrations
Claude Code integrates with VS Code, JetBrains IDEs (IntelliJ, WebStorm, PyCharm), the standalone Desktop app, Slack, and Chrome via official extensions. Each integration surface provides context-aware access to Claude Code's full capabilities.
In VS Code, the extension adds a sidebar panel with chat, a terminal integration that automatically provides file context, and inline diff previews for proposed changes. In JetBrains, a similar tool window integrates with the IDE's refactoring and navigation features. The Desktop app provides a standalone interface for users who want Claude Code without opening a terminal or IDE. Slack integration enables team members to interact with Claude Code from channels, triggering builds, reviews, or queries. The Chrome extension connects web browsing context to Claude Code sessions.
Despite IDE support, many power users (including Jose) prefer the pure terminal experience. The terminal provides faster iteration, easier scripting, and better compatibility with headless and CI/CD workflows.
Claude in GitHub Copilot: Since February 26, 2026, Claude is available as a model option inside GitHub Copilot for Business and Pro users. It works on github.com, GitHub Mobile, and VS Code -- giving developers Claude's reasoning directly within Copilot's familiar interface.
Permissions & Sandboxing
Claude Code offers three permission modes that control what operations Claude can perform without explicit approval:
- Default mode -- Prompts for approval on file edits, command execution, and MCP tool calls. Safest for learning.
- Auto-accept edits -- Allows file modifications without prompts but still asks for command execution. Good balance for experienced users.
- YOLO / Dangerously Skip Permissions -- Unrestricted mode. Claude executes everything without prompts. Only recommended in containers or sandboxed environments.
Beyond the three modes, permissions can be configured per-tool using tool-specific rules with wildcard support. For example, allow Bash(git *) to auto-approve all git commands while still prompting for other shell operations. Use mcp__* wildcards to allow all tools from a specific MCP server. Managed permissions let organization admins enforce permission policies across all team members, preventing developers from escalating to YOLO mode on production codebases.
The sandbox adds a second defense layer: filesystem restrictions limit access to project directories, network restrictions block unauthorized outbound calls, and subprocess restrictions prevent dangerous system commands. Together, permissions and sandboxing ensure Claude operates within safe boundaries.
Practical example: Configure permissions to auto-approve Edit, Read, Glob, Grep, and Bash(npm test *), while requiring approval for Bash(git push *) and all MCP tools. This lets Claude develop freely while gating deployment and external actions.
Plugins & Marketplace
Claude Code includes a plugin marketplace with hundreds of community plugins across multiple marketplaces. Install extensions with /plugin install name@marketplace. Browse with /plugin. Marketplace includes: Code Intelligence LSP plugins, pre-configured MCP integrations (GitHub, GitLab, Jira, Slack), and workflow automation plugins. Plugins auto-update and are scoped to three levels: user, project, and local. Manage installed agents and plugins with the claude agents CLI command.
Claude Code Channels (Research Preview)
Claude Code Channels let you control Claude Code sessions through MCP servers connected to messaging platforms -- starting with Telegram and Discord. Claude reads events from the channel and replies through the same channel, turning your favorite messaging app into a development interface.
This is a game-changer for asynchronous workflows. You can keep development moving while you are away from your terminal: review diffs on your phone, approve deployments from a Discord server, or monitor background agent progress through Telegram notifications. Channels bridge the gap between terminal-bound sessions and the mobility of modern messaging.
Channels is currently a Research Preview feature. It works by connecting Claude Code to an MCP server that bridges the messaging platform's API. Messages you send in the channel are routed to the active Claude Code session, and Claude's responses are posted back to the same thread.
Telegram Channel
Connect a Telegram bot to your Claude Code session. Send prompts, review file diffs, and approve changes -- all from the Telegram app on your phone or desktop.
Discord Channel
Run Claude Code from a Discord server. Ideal for team workflows where multiple developers interact with the same session, review outputs, and coordinate through threads.
Asynchronous Development
Start a task in the terminal, then monitor and guide Claude from your messaging app while commuting, in meetings, or away from your desk. No laptop required.
Practical example: Start a background refactoring task in your terminal before leaving for lunch. From your phone's Telegram app, check progress, approve Claude's proposed changes, and get notified when the PR is ready -- all without returning to your desk.
Remote Control
Remote Control (/remote-control or claude rc) bridges Claude Code with claude.ai/code for device continuity. Start a session in your terminal, then seamlessly control it from the web interface or the Claude mobile app on iOS and Android. Pause CLI work, resume in browser or on your phone. File edits sync automatically. Sessions auto-name.
The Claude mobile app (available on iOS and Android) takes remote control to the next level. Review diffs, approve file changes, and monitor agent progress from your phone. Combined with Channels, you can manage your entire development workflow from anywhere -- no laptop required.
Practical example: Start claude rc in your terminal before a meeting. From the Claude mobile app on your phone, check progress, approve changes, and respond to Claude's questions -- all without opening your laptop.
Models & Extended Thinking
Claude Opus 4.6 and Sonnet 4.6 support 1M token context windows with extended thinking. Opus 4.6: 64k output (128k max), ideal for complex architecture. Configure effort via /effort: Low (○), Medium (◐), High (●). Select your model at any time with /model. 1M context enables loading entire codebases simultaneously.
As of April 2026, 1M context with Opus 4.6 is included at no extra usage cost on Max, Team, and Enterprise plans. This means longer sessions, fewer compactions, and significantly more room for codebase context -- all without worrying about additional token charges. This dramatically improves the experience for long-running agent sessions and large-scale refactoring tasks.
Sonnet 4.6 (released February 17, 2026) delivers flagship-level quality at 1/5 the cost of Opus, with adaptive thinking and 1M context. It is the default model for most Claude Code tasks. Haiku 3 was retired on April 19, 2026 -- API requests to claude-3-haiku-20240307 now return errors -- use Haiku 4.5 instead.
Claude Opus 4.7 (released April 16, 2026) is the latest flagship model. It scores 64.3% on SWE-bench Pro (up from 53.4% with Opus 4.6), the highest verified score for any model on that benchmark. Opus 4.7 introduces a new xhigh reasoning effort level between high and max, giving finer control over thinking depth without paying the full cost of max effort. Vision resolution increases to 2,576px max (3x the previous limit), dramatically improving performance on screenshots, diagrams, and architectural whiteboard photos. Pricing remains unchanged at $5/$25 per MTok (input/output). Opus 4.6 remains available via /model for sessions where you prefer its behavior.
Opus 4.7 is available on all deployment channels: the Anthropic API, Amazon Bedrock, Google Cloud Vertex AI, and the newly added Microsoft Foundry. This means organizations using any of these cloud providers can access the latest model through their existing infrastructure and billing. For Claude Code users on Max, Team, and Enterprise plans, Opus 4.7 is accessible immediately via /model with the same 1M context window at no extra usage cost.
API pricing: Prices change frequently. See current pricing at anthropic.com/pricing.
v2.1.110+ (April 22, 2026): Auto mode is now available to Max subscribers using Opus 4.7 without --enable-auto-mode. /effort opens an interactive slider when called without arguments (arrow-key navigation, Enter to confirm). New /tui fullscreen command enables flicker-free TUI rendering within the same conversation. Mobile push notifications deliver alerts when background tasks complete. /resume on large sessions is up to 67% faster (40MB+ sessions). Fixed random character tearing in iTerm2 + tmux, stale pre-edit LSP diagnostics causing unnecessary re-reads, and improved stalled API stream handling with abort-and-retry after 5 minutes of no data. Previous milestones: v2.1.101 (April 10) added /team-onboarding and OS CA certificate trust; v2.1.98 (April 9) introduced Vertex AI setup wizard, Monitor tool, and child process sandbox; v2.1.92 (April 4) added Bedrock setup wizard and /release-notes version selector. Also includes /powerup interactive lessons and 60% faster Write tool diff computation for large files.
Practical example: With 1M context included, you can load an entire monorepo into a single session, ask Claude to analyze cross-service dependencies, and get comprehensive refactoring plans -- all without hitting context limits or incurring extra costs on Max plans.
Enterprise Features
SSO & Managed Auth
SAML/OIDC single sign-on through Anthropic Console. Centralized user management, team provisioning, and role-based access control for Claude Code installations.
Managed Settings
Administrators define organization-wide CLAUDE.md, permission policies, approved MCP servers, and allowed commands. Settings propagate to all team members automatically.
Zero Data Retention (ZDR)
Conversations and code are not stored by Anthropic. ZDR ensures proprietary code never persists on Anthropic's servers, meeting strict compliance requirements.
Audit & Compliance
Detailed audit logs of all Claude Code operations, token usage tracking, and cost attribution per team/project. Integration with existing observability stacks.
Analytics Dashboard
Track developer productivity metrics: tasks completed, tokens consumed, time saved, and acceptance rates. Compare team performance and identify where Claude delivers the most value.
PR Attribution
Pull requests created by Claude Code are tagged with co-author attribution, making AI-assisted contributions visible in Git history. Track what percentage of code is human-written vs. AI-assisted across the organization.
Expanding Enterprise Integrations
Anthropic continues expanding enterprise integrations, connecting Claude to business tools like Google Drive, Gmail, and DocuSign for cross-functional workflows. Organization-specific tooling and plugin ecosystems bridge development and business operations in a single AI platform.
Anthropic Academy & Community
Anthropic launched Anthropic Academy, an official training platform with structured courses for Claude tools. The Claude Code in Action course covers context management, custom commands and skills, MCP server configuration, and GitHub workflow automation. It is the recommended starting point for developers new to Claude Code.
Additionally, the Claude Community Ambassadors program connects a global network of Claude power users who host events, share workflows, and contribute to the ecosystem. Community ambassadors organize local meetups, online workshops, and contribute open-source skills and MCP servers that benefit the broader Claude Code community.
Claude Code in Action Course
Official Anthropic Academy course covering context management, custom commands, MCP servers, and GitHub workflows. Hands-on exercises with real codebases.
Community Ambassadors
Global network of Claude users hosting events, sharing best practices, and building open-source tools. Join to connect with experienced practitioners and stay current on new features.
Cost Optimization
Claude Code costs scale with token usage. Understanding and optimizing token consumption is critical for sustainable adoption. Here are battle-tested strategies:
Write Clear CLAUDE.md
A detailed CLAUDE.md reduces back-and-forth. When Claude understands your architecture upfront, it produces correct code on the first attempt, saving tokens on revisions.
Use Compact Mode
The /compact command compresses conversation history when context grows large. Use it regularly to reduce token overhead on long sessions.
Scope Your Tasks
Give Claude specific, well-defined tasks rather than vague requests. "Add validation to the user registration endpoint" costs less than "improve the auth system."
Leverage Subagents
Subagents use separate context windows. For large projects, spawning focused subagents is cheaper than loading the entire codebase into one massive conversation.
Claude Max Subscription
For heavy users, Claude Max 5x ($100/mo) or Max 20x ($200/mo) offers predictable billing. Claude Pro ($20/mo) also includes Claude Code access. Often cheaper than API usage for teams doing 4+ hours of daily Claude Code work.
Monitor with /cost
Track session costs in real-time with the /cost command. Set daily budget alerts in Anthropic Console to prevent unexpected charges.
Model Selection
Use claude config set model to choose the right model per task. Opus for complex architecture work, Sonnet for routine coding, Haiku for simple queries. Match model capability to task complexity.
Context Reduction
Keep CLAUDE.md focused. Use subagents for isolated tasks instead of loading everything into one session. Start new sessions for unrelated work rather than continuing a bloated conversation.
Real-World Example: SaaS Platform
The platform is a fitness management SaaS platform with 26 microservices, 41 branded Android apps, and multi-country billing. Jose uses Claude Code as the primary development tool for this platform, demonstrating what AI-augmented development looks like at scale.
512-Line AGENTS.md
The project's CLAUDE.md equivalent contains complete architecture documentation, 8 custom skills, agent team configurations, and detailed coding standards that ensure consistency across the entire platform. One of 15 project configs Jose maintains across different repositories.
8 Custom Skills
/testing, /deploying, /debugging, /developing, /mr-review, /jira-docs, /planning, and /cli-tools. Each encodes team-specific workflows for the platform.
9 MCP Servers
Atlassian Rovo (Jira + Confluence), Firebase, GitHub, GitLab, Slack, Linear, Supabase, Stripe, and Puppeteer. Together they give Claude access to the entire development and business operations lifecycle.
Parallel Agent Strategy
Three-agent teams handle feature development: API agent, Frontend agent, and Testing agent work simultaneously in separate worktrees, reducing feature delivery from days to hours.
The Agentic Loop
Every Claude Code interaction follows a three-phase agentic loop: Gather, Act, and Verify. Understanding this loop is key to writing effective prompts and getting consistent results.
In the Gather phase, Claude reads your CLAUDE.md, scans relevant files, searches the codebase with Grep and Glob, and builds a mental model of the task. In the Act phase, it executes changes: editing files, running commands, spawning subagents, or calling MCP tools. In the Verify phase, it confirms changes work: running tests, checking linter output, reviewing diffs, and validating against your stated requirements.
The loop is self-correcting. If verification fails, Claude returns to Act with the error context and retries. This is why well-structured CLAUDE.md files with clear success criteria matter: they give Claude precise verification targets.
Practical example: When you ask "add email validation to the signup form," Claude gathers (reads form component, validation utils, test files), acts (adds regex validation, updates error messages, creates tests), and verifies (runs the test suite, checks linter). If tests fail, it reads the error, fixes the code, and re-runs -- all automatically.
Memory System
Claude Code maintains a persistent memory system through MEMORY.md files. Unlike session-based chat history, memory survives across sessions and conversations. The memory index at ~/.claude/projects/<project>/memory/MEMORY.md serves as the central reference.
Memory is organized into four types:
- User memory -- Your role, preferences, and working style (e.g., "prefers terminal over IDE," "uses vos conjugation in Spanish")
- Feedback memory -- Corrections you have given Claude that persist (e.g., "never leave work incomplete," "manual test before automating")
- Project memory -- Architecture notes, troubleshooting steps, and project-specific patterns learned over time
- Reference memory -- Links, documentation pointers, and external context Claude should remember
Auto-memory triggers when Claude learns something important during a session. It writes a new .md file in the appropriate memory subdirectory and updates the MEMORY.md index. You can also manually add memories with /memory.
Practical example: After you correct Claude once with "never read images larger than 2000px," it stores this in feedback memory. Every future session in every project respects this rule without you repeating it.
Sandboxing
Claude Code runs in a sandboxed environment that restricts filesystem access, network requests, and subprocess execution. This prevents accidental damage to your system and limits the blast radius of any mistakes.
Three sandboxing layers protect your system:
- Filesystem sandbox -- Claude can only access files within the project directory and explicitly allowed paths. It cannot read
/etc/passwd, your SSH keys, or other sensitive system files. - Network sandbox -- Outbound network requests are restricted by default. MCP servers and explicitly allowed domains can bypass this, but Claude cannot make arbitrary HTTP calls.
- Subprocess sandbox -- Commands run in a restricted shell. Dangerous operations like
rm -rf /are blocked. The permission system gates which commands Claude can execute.
For maximum isolation, run Claude Code inside Docker containers or VMs. Enterprise deployments often use ephemeral containers that are destroyed after each session.
Practical example: In CI/CD pipelines, run Claude Code inside a Docker container with --network=none and a read-only filesystem mount. This guarantees Claude can only modify designated output directories.
Scheduled Tasks & /loop
Claude Code can run tasks in the background while you continue working. Background subagents operate independently, and you receive notifications when they complete. This is ideal for long-running operations like test suites, large refactors, or code generation tasks.
The /loop command enables scheduled, recurring tasks. You can set Claude to run periodic checks: lint the codebase every hour, run the test suite after every file change, or monitor log files for errors. Loops run as background processes and report results asynchronously.
As of April 2026, scheduled tasks are available in both the CLI and the Claude Desktop app. In the desktop app, you can configure recurring tasks through a visual interface -- no terminal required. Examples include updating documentation weekly, summarizing open PRs every Monday morning, or running security scans nightly.
Background tasks share the same permission model as foreground operations. They respect your CLAUDE.md, use the same MCP servers, and produce the same audit logs. The only difference is they do not block your terminal.
Practical example: In the Claude Desktop app, schedule a task to summarize all open PRs every Monday at 9 AM and post the summary to your team's Slack channel. Or use /loop in the CLI to refactor 50 API endpoints in the background while you build new features in the foreground.
Non-Interactive Mode
Non-interactive (headless) mode enables Claude Code to run without human input, making it ideal for CI/CD pipelines, automated code reviews, and batch processing. Invoke it with claude --print for single-shot queries or pipe input via stdin.
Common CI/CD patterns include:
- Automated PR reviews -- Trigger Claude Code on every pull request to review diffs, check for security issues, and post comments
- Code generation -- Generate boilerplate, API clients, or documentation as part of build pipelines
- Migration scripts -- Run Claude in headless mode to apply codebase-wide transformations (e.g., upgrade all React class components to hooks)
- Test generation -- Automatically generate unit tests for untested code paths detected by coverage tools
Headless mode respects all permissions and sandboxing. Use --dangerously-skip-permissions only in trusted, isolated environments like ephemeral CI containers.
The --bare flag provides a minimal startup for CI/CD scripts: it skips hooks, LSP initialization, and plugin sync for faster cold starts. Requires ANTHROPIC_API_KEY to be set. Combine with --print for lightweight pipeline integrations.
GitHub Actions Integration: The official claude-code-action action enables automated PR review and issue handling directly in GitHub workflows. Set up quickly via /install-github-app. Supports Anthropic API, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry authentication.
Practical example: In a GitHub Actions workflow, run echo "Review this PR for security issues" | claude --print -p to get an automated security review posted as a PR comment on every push.
Session Management
Claude Code sessions persist your conversation history, tool results, and working context. You can resume previous sessions, branch them (/branch, formerly /fork) into new branches of exploration, and name them for easy retrieval.
Key session operations:
- Resume --
claude --resumecontinues your most recent session with full context intact - /branch (formerly /fork) -- Create a new session branching from any point in an existing session, preserving context up to that point
- Named sessions --
claude --session "feature-auth"creates or resumes a named session for organized, long-running work - Cross-platform sync -- Sessions stored locally can be referenced across terminal, VS Code, and JetBrains integrations
Sessions are stored in ~/.claude/projects/<project>/sessions/. Each session tracks the full conversation, file snapshots, and checkpoint history for rewind support.
The --from-pr flag lets you resume a session linked to a specific pull request. Reference by PR number (claude --from-pr 123) or full URL. Claude loads the PR context -- diff, comments, and review status -- directly into the session.
Practical example: Use named sessions per feature branch -- claude --session "auth-refactor" keeps all your auth work in one thread. Switch to claude --session "billing-fix" for a different task, then resume either one later with full context.
Keybindings
Claude Code provides customizable keybindings for efficient terminal interaction. Key shortcuts accelerate common operations and reduce friction during long coding sessions.
Essential keybindings:
- Shift+Tab -- Toggle between Plan mode and Act mode
- Esc (single) -- Cancel current generation / interrupt Claude
- Esc+Esc (double) -- Rewind to the last checkpoint, undoing all file changes since that point
- Ctrl+C -- Exit current operation gracefully
- Ctrl+L -- Clear the screen while preserving session
Claude Code supports chord-style keybindings (multi-key sequences) and vim mode for users who prefer modal editing in the input area. Customize bindings in ~/.claude/settings.json under the keybindings key.
Additional interactive commands added in recent releases:
- /voice -- Push-to-talk voice mode (hold spacebar to speak). Speech is transcribed in real-time. Available on Pro, Max, Team, and Enterprise plans. Rolled out March 2026.
- /btw -- Quick side-chain question without interrupting your main task. Answer appears in an overlay and does not add to conversation history. Reuses prompt cache. No tool access.
- /fast -- Activates fast mode for up to 2.5x faster output. A lightning bolt icon appears when active. Toggle off by running
/fastagain.
Practical example: When Claude makes an unwanted change, press Esc+Esc to instantly rewind all file modifications to the previous checkpoint. No manual git reset needed -- Claude's checkpoint system handles it.
Context Window Management
Claude Code operates within a finite context window (up to 1M tokens depending on the model). Managing this window is critical for long sessions. When context fills up, Claude loses access to earlier parts of the conversation, leading to repeated mistakes or forgotten instructions.
Context management strategies:
- /compact -- Compresses conversation history by summarizing earlier exchanges, freeing up context space
- /context -- Shows current context usage as a percentage, helping you decide when to compact or start fresh
- Auto-compaction -- Claude automatically compacts when context exceeds a threshold, preserving the most relevant information
- Focused subagents -- Offload specific tasks to subagents with clean context windows instead of loading everything into one conversation
The CLAUDE.md file is always injected at the start of every context window, which is why keeping it concise but comprehensive matters. A 500-line CLAUDE.md consumes context on every interaction.
Practical example: During a long refactoring session, run /context periodically. When it shows 70%+ usage, run /compact to reclaim space. For tasks requiring deep codebase exploration, spawn a subagent so the main session stays lightweight.
Checkpoint System
Claude Code automatically creates file snapshots (checkpoints) before making changes. These checkpoints enable instant rollback to any previous state without relying on Git. Think of them as automatic save points during your coding session.
Checkpoint operations:
- Automatic creation -- A checkpoint is saved before every file edit, command execution, or batch of changes
- Esc+Esc rewind -- Instantly revert all files to the previous checkpoint state
- Selective rollback -- Choose which specific checkpoint to rewind to from the session history
- Diff preview -- Review what changed between checkpoints before deciding whether to keep or revert
Checkpoints are stored in the session directory and persist across session resumes. They are separate from Git commits, giving you a safety net even for uncommitted experimental changes.
Practical example: Ask Claude to try two different approaches to implement caching. After the first approach, checkpoint. Let Claude try the second approach. Compare both, then rewind to whichever worked better -- all without creating throwaway Git branches.
Code Review Feature
Claude Code includes an automated code review system that analyzes diffs, detects issues, and generates structured feedback. Reviews can run on local changes, staged commits, or pull request diffs from GitHub and GitLab.
Reviews use severity levels:
- Critical -- Security vulnerabilities, data loss risks, or breaking changes that must be fixed before merge
- Warning -- Performance issues, code smells, or maintainability concerns that should be addressed
- Info -- Style suggestions, documentation improvements, or optional enhancements
Configure review behavior in a REVIEW.md file at project root. Define what Claude should check for: security patterns, performance antipatterns, accessibility compliance, or framework-specific best practices. Reviews can be triggered automatically via hooks or CI/CD.
Practical example: Configure a PostToolUse hook that triggers a code review after every file edit. Claude reviews its own changes before you see them, catching obvious issues like missing error handling or untested edge cases before they reach your review queue.
Cloud Execution
Anthropic offers cloud-hosted VMs for running Claude Code without local resource constraints. Cloud execution provides dedicated compute, pre-configured environments, and network isolation for enterprise workloads.
Cloud execution features:
- Anthropic VMs -- Managed virtual machines with Claude Code pre-installed, optimized for AI development workflows
- Setup scripts -- Define initialization scripts that run when VMs start, installing dependencies and configuring the environment
- Network policy -- Fine-grained network access controls that allow specific outbound connections (e.g., npm registry, Docker Hub) while blocking everything else
- Ephemeral environments -- VMs are created per-task and destroyed after completion, ensuring clean state and zero data persistence
Cloud execution is particularly useful for parallel agent teams: spin up 5 VMs, each running a specialized agent on a different microservice, and merge results when all complete.
Practical example: For a large-scale migration (e.g., upgrading 50 microservices from Node 18 to Node 22), spin up one cloud VM per service. Each VM runs Claude Code autonomously, applies the upgrade, runs tests, and creates a PR. All 50 PRs land in parallel.
Third-Party Providers
While Claude Code connects to Anthropic's API by default, it also supports third-party model providers for organizations with specific compliance, latency, or cost requirements.
Supported providers:
- Amazon Bedrock -- Run Claude models through AWS infrastructure with VPC isolation, IAM roles, and AWS billing consolidation
- Google Vertex AI -- Access Claude via Google Cloud with integration into GCP's security and monitoring stack
- Microsoft Foundry -- Deploy Claude through Azure with Active Directory integration and Azure compliance certifications. Use
CLAUDE_CODE_USE_FOUNDRY=1andANTHROPIC_FOUNDRY_RESOURCEto configure. - LiteLLM -- Use LiteLLM as a proxy to route requests through any OpenAI-compatible endpoint, enabling custom routing, caching, and fallback strategies
Configure providers with claude config set provider bedrock or via environment variables. Each provider supports the same Claude Code features; only the transport layer and billing differ.
Practical example: An enterprise running AWS can use CLAUDE_CODE_USE_BEDROCK=1 to route all Claude Code traffic through their existing VPC. No data leaves their AWS account, and costs appear on their standard AWS bill alongside other services.