DEV Community: luiz tanure

Claude Code: Part 11 - Troubleshooting and Recovery

luiz tanure — Mon, 11 Aug 2025 07:12:35 +0000

Claude Code: Part 11 - Troubleshooting and Recovery

The Problem

You're now relying on Claude Code for significant parts of your development workflow. It's become an essential team member. But like any complex system, things occasionally go wrong:

Claude suddenly can't find your CLAUDE.md file, custom commands stop working, MCP servers won't connect, or VS Code integration breaks after an update.

When your AI teammate is having technical difficulties, your entire workflow grinds to a halt. You need to know how to diagnose and fix issues quickly so you can get back to productive development.

The Solution

Most Claude Code issues follow predictable patterns with systematic solutions. Think of this as learning to troubleshoot your AI teammate's technical problems - just like you'd help a human colleague debug their development environment setup.

Common Installation Issues

"Command not found: claude"

Problem: Claude command isn't in your PATH after installation.

Solutions:

# Option 1: Use npx instead
npx @anthropic-ai/claude-code

# Option 2: Add npm global bin to PATH
echo 'export PATH=$PATH:$(npm config get prefix)/bin' >> ~/.bashrc
source ~/.bashrc

# Option 3: Reinstall with proper permissions
sudo npm install -g @anthropic-ai/claude-code

VS Code Extension Not Installing

Problem: Claude doesn't automatically install VS Code extension.

Solutions:

Run Claude from VS Code terminal (not external terminal)
Check VS Code marketplace permissions - allow extension installs
Manual install: Search "Claude Code" in VS Code extensions
Restart VS Code after first Claude run

Permission Errors on macOS/Linux

Problem: Permission denied during installation or file operations.

Solutions:

# Fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Or use a Node version manager (better long-term)
# Install nvm, then:
nvm install node
npm install -g @anthropic-ai/claude-code

CLAUDE.md Not Working

Rules Being Ignored

Problem: Claude doesn't follow your CLAUDE.md rules.

Debug steps:

# Check if Claude can find your CLAUDE.md
ls -la CLAUDE.md

# Verify you're in the right directory
pwd

# Test with simple rule first
echo "- Always say 'CLAUDE.md is working' at the start" > CLAUDE.md

Common causes:

Wrong directory - CLAUDE.md must be in project root
Typos in filename - Must be exactly CLAUDE.md (case-sensitive)
Complex rules - Start simple, add complexity gradually

Rules Conflicting

Problem: Multiple CLAUDE.md files causing confusion.

Check hierarchy:

# See all CLAUDE.md files Claude might read
find . -name "CLAUDE.md" -o -name "CLAUDE.local.md"
ls ~/.claude/CLAUDE.md 2>/dev/null || echo "No user CLAUDE.md"

Rule priority: More specific overrides general

Folder-specific (./src/auth/CLAUDE.md)
Local project (./CLAUDE.local.md)
Project (./CLAUDE.md)
Personal (~/.claude/CLAUDE.md)

Performance Issues

Claude Responses Are Slow

Problem: Long delays between request and response.

Optimization strategies:

# Use faster model for simple tasks
claude --model=haiku

# Clear conversation history
/clear

# Compact long conversations instead of clearing
/compact

# Check your internet connection
curl -I https://api.anthropic.com

Context management:

Keep conversations focused - use /clear for new topics
Avoid huge file dumps - reference specific sections instead
Use subagents for complex analysis to avoid back-and-forth

Token-Saving Pro Tip

Instead of asking Claude to read many files and make changes:

❌ "Look at all components and replace useState with our custom hook"

Ask Claude to create a script that does the work:

✅ "Create a script that finds all useState calls and replaces them with useCustomState, run it, then delete the script"

Why this works:

Claude doesn't need to read all files individually (saves massive input tokens)
Script does bulk operations efficiently (saves output tokens)
Claude runs and cleans up automatically
Much faster for bulk operations across many files

Memory Usage Growing

Problem: Claude Code consuming excessive memory.

Solutions:

# Check Claude processes
ps aux | grep claude

# Restart Claude session
exit
claude

# Clear session data
rm ~/.claude/sessions/*.json

Custom Commands Not Working

Command Not Found

Problem: /my-command returns "command not found."

Debug checklist:

# Check file exists
ls .claude/commands/my-command.md

# Check filename matches exactly (case-sensitive)
ls .claude/commands/

# Restart Claude to reload commands
exit
claude

# Verify with /help
/help

Command File Has Wrong Format

Problem: Command runs but behaves unexpectedly.

Check format:

# ✅ Correct format

Run comprehensive testing:

1. Run pnpm type:check
2. Run pnpm lint
3. Report any issues

# ❌ Wrong format - missing instructions

/test-all

Common mistakes:

Empty files - Must contain instructions
Wrong extension - Must be .md
Command names with spaces - Use hyphens: test-all.md, not test all.md

MCP Server Issues

Server Won't Connect

Problem: MCP servers show as "disconnected" in /mcp.

Troubleshooting:

# Check server installation
npm list -g | grep mcp

# Check configuration syntax
cat ~/.claude/config.json | python -m json.tool

# Test server independently
# (Check server documentation for test commands)

# Restart Claude to reload MCP connections
exit
claude

Authentication Failing

Problem: MCP server requires login but fails.

Steps:

Use /mcp command - Don't try to authenticate manually
Check API tokens - Ensure they're valid and not expired
Verify permissions - Check token scopes/permissions
Check network - Firewalls might block connections

Context Management Issues

"Out of Context" Errors

Problem: Claude says it's out of context or conversation is too long.

Immediate solutions:

# Compact conversation (keeps summary)
/compact

# Start fresh (loses history)
/clear

# Check conversation size
/status

Prevention strategies:

Use focused sessions - One topic per conversation
Break complex tasks into smaller steps
Reference files directly instead of pasting large code blocks
Use subagents for analysis that would require long context

Files Not Loading

Problem: Claude can't read project files.

Check permissions:

# Verify file exists and is readable
ls -la src/components/MyComponent.tsx

# Check file permissions
stat src/components/MyComponent.tsx

# Try with different path format
# Instead of: "Look at ./src/components/MyComponent.tsx"
# Try: "Look at src/components/MyComponent.tsx"

IDE Integration Problems

VS Code Quick Launch Not Working

Problem: Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux) doesn't work.

Solutions:

Run /ide command in Claude first
Check VS Code extension is installed and enabled
Restart VS Code after installing Claude extension
Check keyboard shortcuts - might conflict with other extensions

Context Not Sharing

Problem: Claude doesn't see selected text or current file.

Requirements:

Launch Claude from VS Code terminal (not external terminal)
Run /ide command to establish connection
Select text first, then use quick launch shortcut
Ensure VS Code extension is active

Hook Configuration Issues

Hooks Not Running

Problem: PostToolUse or other hooks don't execute.

Debug steps:

# Check hook syntax
cat .claude/settings.json | python -m json.tool

# Test command manually
pnpm type:check

# Verify file matcher
# Does "Edit:*.ts" match your file? Try "Edit:*" instead

# Check hook permissions
ls -la scripts/my-hook.sh
chmod +x scripts/my-hook.sh

Hook Blocking Claude

Problem: Hook command fails and stops Claude from working.

Quick fix:

# Temporarily disable hooks
claude --no-hooks

# Fix the hook command
# Then re-enable hooks

Common issues:

Non-zero exit codes stop Claude - ensure scripts exit with 0 on success
Missing executables - verify commands exist in PATH
Permission errors - ensure scripts are executable

Productivity Tips

Speed Up Common Tasks

# Use aliases for frequent commands
alias c="claude"
alias cr="claude --resume"
alias cq="claude --quiet"

# Background commands for long operations
# Ctrl+b: npm run build (continue working while building)

# Custom commands for repeated workflows
# Create .claude/commands/daily.md for your daily checklist

Context Management Best Practices

One topic per session - use /clear when switching topics
Reference files instead of pasting code
Use descriptive prompts - "Fix the TypeScript error in UserService.handleLogin" vs "Fix this"
Leverage IDE integration - select code before launching Claude

Efficient File Organization

# Project structure that works well with Claude
project/
├── CLAUDE.md (main rules)
├── CLAUDE.local.md (personal overrides, gitignored)
├── .claude/
│   ├── commands/ (custom commands)
│   └── settings.json (hooks, config)
└── src/
    ├── auth/CLAUDE.md (auth-specific rules)
    └── api/CLAUDE.md (API-specific rules)

Team Collaboration Tips

Share project CLAUDE.md via git
Keep personal rules local (CLAUDE.local.md in .gitignore)
Document custom commands in README
Standardize hook patterns across team projects

When to Get Help

Check These Resources First

Claude Code documentation: https://docs.anthropic.com/en/docs/claude-code
GitHub issues: https://github.com/anthropics/claude-code/issues
Community discussions: Search existing issues before creating new ones

Include This Information When Reporting Issues

# System information
claude --version
node --version
npm --version

# Error details
# Include exact error messages, not paraphrases

# Configuration (remove sensitive data)
cat .claude/settings.json

# Steps to reproduce
# What you did, what you expected, what happened instead

Remember: Most Claude Code issues have simple solutions. Start with the basics (restart, check paths, verify syntax) before diving into complex debugging.

Claude Code Blog Series

Previous: Part 10 - Power User CLI Options and Scripting

Full Series:

Part 1 - Getting Started and Installation
Part 2 - CLAUDE.md Configuration Files
Part 3 - Conversation Management and Context
Part 4 - Slash Commands and Custom Commands
Part 5 - MCP Servers and Tool Integration
Part 6 - Subagents and Task Delegation
Part 7 - IDE Integration with VS Code and JetBrains
Part 8 - Hooks for Automated Quality Checks
Part 9 - Complete Development Workflows
Part 10 - Power User CLI Options and Scripting
Part 11 - Troubleshooting and Recovery (this post)

Series Complete! You now have a comprehensive guide to mastering Claude Code from beginner to expert level. Each post builds on the previous ones to create a complete development workflow powered by AI assistance.

Claude Code: Part 10 - Common Issues and Quick Fixes

luiz tanure — Mon, 11 Aug 2025 07:12:03 +0000

Claude Code: Part 10 - Common Issues and Quick Fixes

The Problem

You've been using Claude Code for weeks. It works great most of the time, but you keep hitting the same frustrating issues: conversations get too long and Claude loses context, your CLAUDE.md rules conflict with each other, tokens run out faster than expected, and custom commands randomly stop working.

These aren't beginner problems - they're the issues experienced users face when pushing Claude Code to its limits.

Context Too Long

Problem: Claude says the conversation is too long or starts forgetting earlier context.

Quick fixes:

# Compress conversation history
/compact

# Start fresh but keep project context
/clear

# Check conversation size
/status

Prevention:

Use /compact regularly instead of letting conversations grow endlessly
Start new conversations for different topics
Reference files instead of pasting large code blocks

Rules Conflicting

Problem: Multiple CLAUDE.md files causing confusion or contradictory behavior.

Debug hierarchy:

Folder-specific (./src/auth/CLAUDE.md) - highest priority
Local project (./CLAUDE.local.md)
Project (./CLAUDE.md)
Personal (~/.claude/CLAUDE.md) - lowest priority

Common conflicts:

# Project CLAUDE.md says:
- Use TypeScript strict mode

# Personal ~/.claude/CLAUDE.md says:
- Skip TypeScript for quick prototypes

Solution: Be more specific about when rules apply:

# In project CLAUDE.md:
- Use TypeScript strict mode for all production code
- Prototypes in /experiments/ can skip strict mode

Token-Saving Pro Tip

Problem: Hitting token limits too quickly, especially with large CLAUDE.md files.

Token wasters:

Verbose CLAUDE.md files (keep under 100 lines each)
Pasting entire files instead of referencing them
Long conversations about multiple topics
Detailed explanations in rules

Token savers:

❌ "When implementing authentication, always ensure you follow security best practices including input validation, proper error handling, secure token storage, and following our established patterns in the auth/ directory..."

✅ "Auth code: validate inputs, handle errors securely, follow auth/ patterns"

Script approach:
Instead of asking Claude to read many files:

❌ "Look at all components and replace useState with our custom hook"

Ask Claude to create a script:

✅ "Create a script to replace useState with useCustomState across all components, run it, then delete the script"

This saves massive input tokens and is much faster.

Custom Commands Not Working

Problem: /my-command returns "command not found" or behaves unexpectedly.

Debug checklist:

Check filename: Must be exactly .claude/commands/my-command.md
Restart Claude: Commands load on startup
File format: Must contain instructions, not just command names

Common mistakes:

❌ Wrong format (just the command name):
/test-all

✅ Correct format (actual instructions):
Run comprehensive testing:
1. Run type checking
2. Run linter
3. Run tests
4. Report issues

File location issues:

Commands must be in .claude/commands/ directory
Use hyphens, not spaces: test-all.md not test all.md
Check case sensitivity on your system

Performance Tips

Slow responses:

Use /clear for new topics instead of continuing long conversations
Reference specific files instead of asking Claude to "look at everything"
Break complex requests into smaller, focused questions

Memory usage:

Restart Claude sessions periodically
Avoid keeping multiple long-running sessions open
Use specific commands instead of general requests

Quick Diagnostics

# Check what's loaded
/help

# See conversation stats
/status

# Restart fresh
/clear

Getting Help

For persistent issues:

Check Claude Code documentation
Search GitHub issues
Include exact error messages and steps to reproduce

Most Claude Code issues have simple solutions - start with the basics before diving into complex debugging.

Claude Code Blog Series

Previous: Part 9 - Complete Development Workflows
Next: Part 11 - Troubleshooting and Recovery

Full Series:

Part 1 - Getting Started and Installation
Part 2 - CLAUDE.md Configuration Files
Part 3 - Conversation Management and Context
Part 4 - Slash Commands and Custom Commands
Part 5 - MCP Servers and Tool Integration
Part 6 - Subagents and Task Delegation
Part 7 - IDE Integration with VS Code and JetBrains
Part 8 - Hooks for Automated Quality Checks
Part 9 - Complete Development Workflows
Part 10 - Common Issues and Quick Fixes (this post)
Part 11 - Troubleshooting and Recovery

Claude Code: Part 9 - Complete Development Workflows

luiz tanure — Mon, 11 Aug 2025 07:11:31 +0000

Claude Code: Part 9 - Complete Development Workflows

The Problem

You've learned all the individual Claude Code features - CLAUDE.md, slash commands, MCP servers, subagents, IDE integration, and hooks. But you're looking at them like separate tools in a toolbox, not sure how they work together.

You know Claude can help with individual tasks, but your real development work isn't isolated tasks. It's complete workflows: planning a feature, implementing it, testing it, reviewing it, and deploying it. Right now, you're using Claude for pieces but not for the whole process.

It's like having a talented team member who's great at individual tasks but hasn't learned how your actual development process works.

The Solution

Real-world workflows combine all Claude Code features into seamless development processes. Think of it as teaching your AI teammate not just individual skills, but how your entire development process flows from idea to production.

Feature Development Workflow

The complete process: From idea to deployed feature using Claude Code.

1. Project Setup

# Start new feature branch
git checkout -b feature/user-notifications

# Launch Claude with context
claude

CLAUDE.md rule: - Run pnpm type:check before marking features complete

2. Planning Phase

Plan the user notifications feature:
1. Database schema for notifications
2. API endpoints needed
3. React components structure
4. Integration points with existing code

Claude analyzes your codebase and creates a structured plan.

3. Implementation with Custom Commands

# Use your custom workflow command
/feature-start notifications

# This runs your .claude/commands/feature-start.md:
# 1. Analyze existing patterns in this codebase
# 2. Create feature folder structure
# 3. Set up basic files following project conventions
# 4. Run type checking to ensure no conflicts

4. Development with MCP Integration

Check GitHub issues labeled "notifications" and implement the API endpoints

With GitHub MCP server connected, Claude:

Reads actual issues from your repository
Understands requirements from issue descriptions
Creates code that addresses specific reported needs

5. Quality Assurance with Hooks

Your PostToolUse hook automatically runs:

{
  "matcher": "Edit:*.ts|Edit:*.tsx",
  "hooks": [
    {
      "type": "command",
      "command": "pnpm type:check && pnpm lint"
    }
  ]
}

Every file Claude edits gets automatically validated.

6. Testing with Subagents

Use an agent to write comprehensive tests for the notifications feature

Subagent autonomously:

Analyzes all notification-related code
Creates unit tests for components
Writes integration tests for API endpoints
Ensures good test coverage

7. Final Review

/feature-complete notifications

# Your custom command:
# 1. Run full test suite
# 2. Check for console.logs and TODOs
# 3. Verify responsive design
# 4. Generate summary of changes
# 5. Suggest improvements before PR

Bug Fixing Workflow

Quick and systematic bug resolution.

1. Bug Analysis

# Open VS Code to the problematic file
# Select the buggy code
# Press Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux)

Claude launches with:

The selected buggy code
Current file context
Any TypeScript/ESLint errors from Problems panel

2. Root Cause Investigation

Analyze this authentication bug. Check related files and explain the issue.

Claude examines:

The specific code causing issues
Related authentication files (following your CLAUDE.md patterns)
Recent git changes that might be related

3. Fix Implementation

Fix this bug following our existing error handling patterns

Your CLAUDE.md ensures:

Consistent error handling approach
Proper logging (no sensitive data)
Following established code patterns

4. Verification

Post-fix hook automatically:

Runs relevant tests
Checks type safety
Validates the fix doesn't break other functionality

Code Review Workflow

Prepare code for review efficiently.

1. Self-Review Preparation

/review-prep

# Your custom command runs:
# 1. Check for TODO comments
# 2. Find hardcoded values
# 3. Verify error handling
# 4. Check TypeScript types
# 5. Suggest readability improvements

2. Documentation Updates

Update the README with the new notifications feature and API endpoints

Claude references:

Your actual implemented code
Existing documentation patterns
API endpoints you just created

3. PR Creation with MCP

Create a GitHub PR for this feature branch with a comprehensive description

With GitHub MCP server:

Analyzes your commits since branch creation
Generates meaningful PR description
Includes testing checklist
References related issues automatically

Legacy Code Modernization

Systematic approach to improving old code.

1. Assessment with Subagents

Use an agent to analyze the legacy auth system and create a modernization plan

Subagent provides:

Complete analysis of existing code
Security concerns identified
Modernization recommendations
Step-by-step migration plan

2. Incremental Updates

Modernize the user authentication to use our current patterns, maintaining backward compatibility

Your folder-specific CLAUDE.md in src/auth/ ensures:

Security-first approach
Consistent with current auth patterns
Proper validation and error handling

3. Testing Strategy

Create comprehensive tests for the modernized auth system to ensure no regressions

Claude creates:

Tests that verify existing functionality
New tests for improved features
Integration tests for compatibility

Daily Development Shortcuts

Speed up common tasks.

Quick File Navigation

# In VS Code terminal
claude

# Then use Claude as your project assistant
"Show me all components that use the UserContext"
"Find files related to payment processing"

Rapid Debugging

# Select error message in VS Code
# Cmd+Esc to launch Claude with context
# Claude sees the error automatically

"Fix this TypeScript error"

Code Quality Maintenance

/health-check

# Custom command that:
# 1. Runs full test suite
# 2. Checks for security issues
# 3. Analyzes bundle size
# 4. Reports technical debt

Team Collaboration Workflows

Consistent team practices.

Onboarding New Developers

Analyze this codebase and create an onboarding guide for new developers

Claude generates:

Architecture overview
Key patterns and conventions
Development setup instructions
Common tasks and workflows

Code Standards Enforcement

Team's shared CLAUDE.md ensures:

Consistent coding patterns across team members
Automated quality checks via hooks
Standardized commit messages and PR formats

Knowledge Sharing

Document the payment integration patterns we use across all features

Claude creates:

Comprehensive documentation
Code examples from actual codebase
Best practices based on your implementations

Combining Features for Maximum Efficiency

The power is in the combination:

CLAUDE.md provides context and standards
Custom commands automate repeated workflows
MCP servers eliminate tool switching
Subagents handle complex analysis
Hooks ensure quality automatically
IDE integration provides seamless context

Result: Claude becomes a true development partner that understands your project, follows your standards, and automates your workflows.

Getting Started with Workflows

Start with one workflow - Pick your most common task
Build incrementally - Add features as you see benefits
Share with team - Successful workflows become team standards
Iterate and improve - Workflows evolve with your needs

The goal is to spend more time on creative problem-solving and less time on repetitive development tasks.

Claude Code Blog Series

Previous: Part 8 - Hooks for Automated Quality Checks
Next: Part 10 - Power User CLI Options and Scripting

Full Series:

Part 1 - Getting Started and Installation
Part 2 - CLAUDE.md Configuration Files
Part 3 - Conversation Management and Context
Part 4 - Slash Commands and Custom Commands
Part 5 - MCP Servers and Tool Integration
Part 6 - Subagents and Task Delegation
Part 7 - IDE Integration with VS Code and JetBrains
Part 8 - Hooks for Automated Quality Checks
Part 9 - Complete Development Workflows (this post)
Part 10 - Power User CLI Options and Scripting
Part 11 - Troubleshooting and Recovery

Claude Code: Part 8 - Hooks for Automated Quality Checks

luiz tanure — Mon, 11 Aug 2025 07:10:59 +0000

Claude Code: Part 8 - Hooks for Automated Quality Checks

The Problem

Every time Claude edits a TypeScript file, you find yourself typing the same commands:

"Now run pnpm type:check to make sure there are no errors"
"Don't forget to run the linter"

"Can you test this change?"

It's like having a talented developer who consistently forgets the basic quality checks. They do great work, but you're constantly reminding them about the fundamentals: compile, lint, test, repeat.

The Solution

Hooks automatically run quality checks at specific points in your workflow. Think of them as training your AI teammate to follow your development standards automatically - like a senior developer who runs tests before every commit without being reminded.

What Are Hooks?

Hooks are shell commands that trigger automatically when certain events happen:

Example: Automatically run pnpm type:check after Claude edits any TypeScript file
Example: Validate security rules before Claude accesses authentication files
Example: Auto-format code after Claude writes new files

Common Hook Events

PostToolUse - After Claude uses a tool

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit:*",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm type:check"
          }
        ]
      }
    ]
  }
}

PreToolUse - Before Claude uses a tool
UserPromptSubmit - When you submit a prompt
SessionStart - When Claude starts

Simple Example: Auto Type-Check

Create this in your Claude settings:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit:*.ts|Edit:*.tsx",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm type:check --noEmit"
          }
        ]
      }
    ]
  }
}

What happens:

Claude edits a TypeScript file
Hook automatically runs type checking
You see results immediately

Practical Hook Patterns

Code Quality Enforcement

{
  "matcher": "Write|Edit",
  "hooks": [
    {
      "type": "command",
      "command": "pnpm lint --fix"
    }
  ]
}

Security Validation

{
  "matcher": "Read:src/auth/*|Edit:src/auth/*",
  "hooks": [
    {
      "type": "command",
      "command": "./scripts/security-check.sh"
    }
  ]
}

Test Runner

{
  "matcher": "Edit:*.test.*",
  "hooks": [
    {
      "type": "command",
      "command": "npm test -- --related"
    }
  ]
}

Communication Improvements

Stop Claude from saying "You are right" repeatedly:

{
  "UserPromptSubmit": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "echo 'Skip acknowledgments - focus on the solution'"
        }
      ]
    }
  ]
}

This hook reminds Claude to be more direct and action-focused in responses.

Hook Configuration Locations

Project-level: .claude/settings.json

{
  "hooks": {
    // Project-specific hooks here
  }
}

Personal: ~/.claude/settings.json

{
  "hooks": {
    // Your personal hooks across all projects
  }
}

Hook Scripts Best Practices

Create focused scripts:

#!/bin/bash
# scripts/validate-auth.sh
echo "Validating authentication code..."
if grep -r "console.log" src/auth/; then
  echo "❌ Found console.log in auth code"
  exit 1
fi
echo "✅ Auth validation passed"

Make them fast:

Use specific file patterns
Avoid running heavy operations on every edit
Cache results when possible

Security Considerations

⚠️ Important: Hooks execute shell commands. Only use hooks you trust.

Best practices:

Review hook commands before adding them
Use absolute paths for scripts
Test hooks in safe environments first
Avoid hooks from untrusted sources

When Hooks Are Useful

Perfect for:

Code quality enforcement (linting, type checking)
Running relevant tests after changes
Security validation for sensitive files
Custom workflow automation

Avoid for:

Complex logic (keep hooks simple)
Slow operations that interrupt workflow
Operations that require user input

Troubleshooting Hooks

Hook not running?

Check JSON syntax in settings
Verify command exists and is executable
Test command manually first

Hook causing problems?

Check exit codes (non-zero stops Claude)
Review hook output for errors
Temporarily disable to isolate issues

Background Command Execution

New in Claude Code 1.0.71: Run bash commands in the background without interrupting your Claude conversation.

Shortcut: Ctrl+b

Example:

Press Ctrl+b
Type: npm run build
Command runs in background
Continue working with Claude while build runs
See results when complete

Perfect for:

Long-running builds or tests
File watching processes
Background monitoring tasks

Getting Started

Start simple - One hook for type checking
Test thoroughly - Run commands manually first
Add gradually - Don't overwhelm your workflow
Monitor impact - Ensure hooks help, don't hinder

Example starter hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit:*.ts|Edit:*.tsx",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'TypeScript file edited'"
          }
        ]
      }
    ]
  }
}

Hooks turn Claude into a more integrated part of your development environment, automatically handling the routine tasks you'd normally do manually.

Claude Code Blog Series

Previous: Part 7 - IDE Integration with VS Code and JetBrains
Next: Part 9 - Complete Development Workflows

Full Series:

Part 1 - Getting Started and Installation
Part 2 - CLAUDE.md Configuration Files
Part 3 - Conversation Management and Context
Part 4 - Slash Commands and Custom Commands
Part 5 - MCP Servers and Tool Integration
Part 6 - Subagents and Task Delegation
Part 7 - IDE Integration with VS Code and JetBrains
Part 8 - Hooks for Automated Quality Checks (this post)
Part 9 - Complete Development Workflows
Part 10 - Power User CLI Options and Scripting
Part 11 - Troubleshooting and Recovery

Claude Code: Part 7 - IDE Integration with VS Code and JetBrains

luiz tanure — Mon, 11 Aug 2025 07:10:28 +0000

Claude Code: Part 7 - IDE Integration with VS Code and JetBrains

The Problem

You're deep in debugging mode in VS Code. You've got the perfect file open, the exact line selected, and error messages staring at you from the Problems panel. But to get Claude's help, you have to:

Open a separate terminal
Launch Claude
Manually describe the file you're in
Copy-paste the error message
Explain the context Claude can't see

By the time Claude understands the situation, you've lost your debugging flow. It's like having a brilliant pair-programming partner who can't see your screen - constantly having to narrate everything breaks your concentration.

The Solution

IDE integration lets Claude see exactly what you're working on without manual context sharing. Think of it as giving your AI teammate a second monitor that mirrors yours - they can see your current file, selected code, and error messages automatically.

VS Code Integration

Quick Setup

Install Claude Code (if not already done)
Open VS Code in your project
Open terminal in VS Code (Ctrl+` or Cmd+`)
Run Claude: claude
Extension auto-installs when first run from VS Code

Quick Launch Shortcut

Mac: Cmd+Esc
Windows/Linux: Ctrl+Esc

Opens Claude with current context:

Selected text (if any)
Current file path
Recent error messages from Problems panel

Simple example:

1. Select a function in VS Code
2. Press Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux)
3. Claude opens with: "Looking at the selected code in src/utils/helpers.js..."

Context Sharing Features

What Claude sees automatically:

Current file you're editing
Text selection
Error messages from VS Code Problems panel
Workspace file structure

What you don't need to do:

Copy-paste code snippets
Explain file locations
Describe error messages manually

JetBrains Integration

Claude Code supports JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, etc.) through terminal integration.

Setup:

Open terminal in your JetBrains IDE
Run claude in the terminal
Context sharing works similar to VS Code

Note: Full plugin integration may vary by IDE - check Claude Code documentation for specific IDE support.

Error Diagnostics Integration

When you have TypeScript errors, ESLint warnings, or other diagnostics:

Errors appear in VS Code Problems panel
Launch Claude with quick shortcut
Claude sees the errors automatically
Ask: "Fix these TypeScript errors"

No need to copy-paste error messages - Claude reads them from your IDE.

Multi-IDE Workflows

Best practices:

One Claude session per project - works across different IDEs
Context switches automatically - based on which IDE you launch from
Use /clear when switching between major tasks

Advanced Integration Features

IDE Command

claude /ide

Connects Claude to IDE for enhanced integration (when available).

File References

Claude understands your IDE's file structure and can reference files directly:

"Update the handleSubmit function in the current file"
"Check the imports in UserList.tsx"

Limitations and Notes

Current limitations:

Full integration varies by IDE
Some features work best with VS Code
Terminal-based integration for most IDEs

For latest IDE support: Check the Claude Code documentation

Getting Started

Start with VS Code (best supported)
Use quick launch shortcuts (Cmd+Esc/Ctrl+Esc)
Test context sharing - select code and launch Claude
Gradually explore other IDE integrations

The goal is seamless development where Claude understands exactly what you're working on without manual context switching.

Claude Code Blog Series

Previous: Part 6 - Subagents and Task Delegation
Next: Part 8 - Hooks for Automated Quality Checks

Full Series:

Part 1 - Getting Started and Installation
Part 2 - CLAUDE.md Configuration Files
Part 3 - Conversation Management and Context
Part 4 - Slash Commands and Custom Commands
Part 5 - MCP Servers and Tool Integration
Part 6 - Subagents and Task Delegation
Part 7 - IDE Integration with VS Code and JetBrains (this post)
Part 8 - Hooks for Automated Quality Checks
Part 9 - Complete Development Workflows
Part 10 - Power User CLI Options and Scripting
Part 11 - Troubleshooting and Recovery

Claude Code: Part 6 - Subagents and Task Delegation

luiz tanure — Mon, 11 Aug 2025 07:09:56 +0000

Claude Code: Part 6 - Subagents and Task Delegation

The Problem

You're facing a complex development challenge that requires deep, systematic analysis:

Refactoring a large legacy system with many interdependencies
Planning a major feature that touches multiple parts of your application
Investigating a performance issue that could have various root causes
Migrating to a new framework while maintaining functionality

These tasks require hours of careful analysis, reading through dozens of files, understanding complex relationships, and maintaining context across multiple steps. It's exhausting to guide Claude through every single step, and you lose focus on the bigger picture while managing the details.

The Solution

Subagents are specialized AI assistants that operate in separate contexts with focused expertise. They handle complex tasks autonomously while you focus on high-level decisions.

Learn more: Subagents Documentation

How Subagents Work

Creation:

/agents  # Interactive interface (recommended)
# Or create files in .claude/agents/ or ~/.claude/agents/

Usage:

Use an agent to analyze the authentication system

What happens: ⏺ indicator shows subagent is working autonomously

Key Features

Separate contexts - Don't consume main conversation tokens
Specialized expertise - Custom system prompts for specific tasks
Tool access control - Limited permissions for security
Automatic selection - Claude picks appropriate agent for task

Agent Types

Code Reviewer: Proactively reviews code quality and security
Debugger: Specializes in root cause analysis

Data Scientist: Focuses on SQL queries and data analysis

When to Use

Complex codebase analysis
Multi-step refactoring plans
Performance investigations
Architecture planning
Systematic code reviews

Best Practices

Single responsibility - One focused purpose per agent
Clear system prompts - Detailed instructions for agent behavior
Limited tool access - Only necessary permissions
Version control - Track project-level agents in git

Example Usage

"Use an agent to analyze the user onboarding flow"
"Use an agent to plan Redux to Zustand migration"  
"Use an agent to review payment processing security"

Working with Results

Review outputs - Subagent results may need refinement
Break down plans - Convert analysis into actionable steps
Chain agents - Use results for follow-up analysis

Task Definition Tips

❌ "Use an agent to look at the code"
✅ "Use an agent to analyze authentication security and create modernization plan"

Be specific:

Define scope and constraints
Set success criteria
Request actionable output

Performance Benefits

Context preservation - Don't consume main conversation tokens
Specialized analysis - Custom expertise for specific tasks
Autonomous work - No need for step-by-step guidance
Chain workflows - Connect multiple agents for complex tasks

When NOT to Use

Simple questions
Interactive debugging
Small changes
Tasks needing frequent input

Getting Started

Use /agents to create specialized agents
Start with analysis tasks
Be specific about scope and goals
Review and iterate on results

Subagents transform Claude into specialized AI analysts handling complex work autonomously.

Claude Code Blog Series

Previous: Part 5 - MCP Servers and Tool Integration
Next: Part 7 - IDE Integration with VS Code and JetBrains

Full Series:

Part 1 - Getting Started and Installation
Part 2 - CLAUDE.md Configuration Files
Part 3 - Conversation Management and Context
Part 4 - Slash Commands and Custom Commands
Part 5 - MCP Servers and Tool Integration
Part 6 - Subagents and Task Delegation (this post)
Part 7 - IDE Integration with VS Code and JetBrains
Part 8 - Hooks for Automated Quality Checks
Part 9 - Complete Development Workflows
Part 10 - Power User CLI Options and Scripting
Part 11 - Troubleshooting and Recovery

Claude Code: Part 5 - MCP Servers and Tool Integration

luiz tanure — Mon, 11 Aug 2025 07:09:24 +0000

Claude Code: Part 5 - MCP Servers and Tool Integration

The Problem

Your development workflow involves constant tool switching:

Claude Code for development assistance
GitHub web interface for issues and PRs
Sentry dashboard for error monitoring
Database tools for query analysis
Slack for team communication
Linear/Jira for project management

Each context switch breaks your flow. You're helping Claude understand an issue, then jumping to Sentry to grab error details, back to Claude to explain the context, then to GitHub to check related issues. By the time you've gathered all the information, you've lost your problem-solving momentum.

The Solution

MCP (Model Context Protocol) servers connect your external tools directly to Claude Code. Think of it as giving Claude direct access to your development toolchain - it can read GitHub issues, analyze Sentry errors, and query databases without you having to switch contexts manually.

What is MCP?

MCP (Model Context Protocol) is an open-source standard that connects Claude Code to external tools and services. Instead of manual copy-pasting, Claude accesses tools directly.

Learn more: MCP Documentation

Example:

You: "Analyze Sentry errors for authentication"
Claude: [Queries Sentry directly, analyzes data, provides insights]

Essential MCP Servers

Installation Methods

# Add local server
claude mcp add server-name /path/to/server

# Add remote SSE server (real-time)
claude mcp add --transport sse name https://server-url/sse

# Add remote HTTP server
claude mcp add --transport http name https://server-url/mcp

GitHub Server

Read issues, PRs, and discussions
Create issues and PRs
Analyze commits and code changes

Sentry Server

Analyze error trends and stack traces
Correlate errors with code changes
Suggest fixes based on context

Other Popular Servers

Linear/Asana - Project management
Notion - Documentation
Stripe - Payment processing
Figma - Design integration
Airtable - Database/spreadsheets
SQLite/PostgreSQL - Database querying

Authentication

OAuth 2.0 support - Secure authentication
Use /mcp to authenticate - Follow prompts
Tokens refresh automatically - No manual renewal

⚠️ Security Note: Use third-party MCP servers at your own risk. Verify trustworthiness before installing.

Managing Connections

Use /mcp to:

View connected servers
Check authentication status
Reconnect or configure servers

Example Workflows

Bug investigation:

"Check Sentry for login errors, correlate with recent GitHub commits"

PR review:

"Review PR #123, check for related Sentry errors and security issues"

Release prep:

"List GitHub issues for v2.1.0, check critical Sentry errors"

Network Security

Firewall considerations - MCP servers make external API calls
Corporate networks - May need proxy configuration
Rate limiting - Respect service API limits

Troubleshooting MCP Issues

Connection Problems

# Check server status
/mcp

# Verify installation
npm list -g | grep mcp

# Test authentication
# Use service-specific test commands

Authentication Failures

Verify tokens are valid and not expired
Check permissions - ensure tokens have necessary scopes
Review network - firewalls might block connections
Restart Claude to reload MCP configurations

Performance Considerations

MCP calls take time - External API requests add latency
Batch requests when possible - ask for related data together
Cache awareness - Some data might be cached by MCP servers

Getting Started with MCP

Start with GitHub - Most immediately useful for developers
Add error monitoring - Sentry integration saves significant context switching
Include security scanning - Socket.dev prevents supply chain issues
Explore gradually - Add servers as you identify workflow gaps

Simple first test:

"Check our GitHub repository for any open issues tagged as 'bug'"

MCP transforms Claude Code from an isolated assistant into a fully connected development partner that can access and analyze data from your entire toolchain.

Claude Code Blog Series

Previous: Part 4 - Slash Commands and Custom Commands
Next: Part 6 - Subagents and Task Delegation

Full Series:

Part 1 - Getting Started and Installation
Part 2 - CLAUDE.md Configuration Files
Part 3 - Conversation Management and Context
Part 4 - Slash Commands and Custom Commands
Part 5 - MCP Servers and Tool Integration (this post)
Part 6 - Subagents and Task Delegation
Part 7 - IDE Integration with VS Code and JetBrains
Part 8 - Hooks for Automated Quality Checks
Part 9 - Complete Development Workflows
Part 10 - Power User CLI Options and Scripting
Part 11 - Troubleshooting and Recovery

Claude Code: Part 4 - Slash Commands and Custom Commands

luiz tanure — Mon, 11 Aug 2025 07:08:53 +0000

Claude Code: Part 4 - Slash Commands and Custom Commands

The Problem

You type the same instructions to Claude every day: "Run tests", "Check TypeScript errors", "Review changes". Repetitive and wasteful.

The Solution

Slash commands turn repeated instructions into shortcuts. /test replaces paragraphs of testing instructions.

Built-in Commands

/clear      # Fresh start
/compact    # Compress history
/help       # Show commands
/mcp        # MCP servers
/ide        # IDE integration
/exit       # End session

Custom Commands

Create .claude/commands/test-all.md:

1. Run pnpm type:check
2. Run pnpm lint
3. Run pnpm test
4. Report issues

Now /test-all runs everything.

Example Commands

.claude/commands/morning.md: Daily setup (git pull, tests, status)
.claude/commands/ready.md: Pre-commit checks
.claude/commands/review.md: PR preparation

Organization

Group commands by phase (planning/, development/, deployment/) or domain (frontend/, backend/, testing/).

Best Practices

Be specific: "Check TypeScript errors in src/" not "Check code"
Include success criteria: "0 test failures, 80% coverage"
Keep commands under 10 steps
Use numbered lists for clarity

Sharing Commands

Team: Commit .claude/commands/ to git
Personal: Use ~/.claude/commands/ globally

Advanced Features

Commands can include:

Parameters: "Ask for feature name, create feature/[name]"
Conditionals: "If production, run security scan"
Context awareness: "Analyze current file"

Getting Started

Identify what you repeat daily
Create .claude/commands/[name].md
Keep instructions under 10 steps
Test and refine

Slash commands eliminate repetitive instructions.

Claude Code Blog Series

Previous: Part 3 - Conversation Management and Context
Next: Part 5 - MCP Servers and Tool Integration

Full Series:

Part 1 - Getting Started and Installation
Part 2 - CLAUDE.md Configuration Files
Part 3 - Conversation Management and Context
Part 4 - Slash Commands and Custom Commands (this post)
Part 5 - MCP Servers and Tool Integration
Part 6 - Subagents and Task Delegation
Part 7 - IDE Integration with VS Code and JetBrains
Part 8 - Hooks for Automated Quality Checks
Part 9 - Complete Development Workflows
Part 10 - Power User CLI Options and Scripting
Part 11 - Troubleshooting and Recovery

Claude Code: Part 3 - Conversation Management and Context

luiz tanure — Mon, 11 Aug 2025 07:08:21 +0000

Claude Code: Part 3 - Conversation Management and Context

The Problem

You've been using Claude Code for a few weeks now. The basic workflow is comfortable - ask questions, get code, make changes. But you're starting to feel limited by treating Claude like a simple question-and-answer tool.

You have bigger ambitions: complex refactoring projects, multi-step feature implementations, and sophisticated analysis tasks. You want to move beyond "Hey Claude, fix this function" to "Claude, help me architect and implement this entire feature from scratch."

The question is: how do you unlock Claude's advanced capabilities for complex, multi-step development work?

The Solution

Advanced Claude Code features let you handle sophisticated development tasks through multi-step workflows, conversation management, and intelligent context handling. Think of it as the difference between using Claude as a coding helper versus a true development partner.

Conversation Management

The `/clear` Command

Start fresh when switching contexts:

/clear

When to use:

Switching between different features
Moving from debugging to new development
When conversation gets too long and unfocused

The `/compact` Command

Summarize long conversations while preserving context:

/compact

What it does:

Compresses conversation history
Keeps key decisions and context
Reduces token usage without losing information

Example:

Before: 50 messages about implementing user authentication
After: Compact summary + recent conversation about email verification

Resume Previous Sessions

Continue where you left off:

claude --resume

Multi-Step Workflows

Planning Complex Features

Instead of diving into code, start with comprehensive planning:

I need to implement a real-time notification system for this React app.
Before writing any code, help me plan:

1. Architecture design considerations
2. Technology choices (WebSocket vs Server-Sent Events vs polling)
3. Database schema requirements
4. Component structure and data flow
5. Testing strategy
6. Performance and scalability considerations

Break this down systematically.

Claude will provide structured analysis before any implementation begins.

Iterative Development Approach

Let's build this notification system step by step:

Phase 1: Create the basic WebSocket connection and message handling
Phase 2: Implement the UI components for displaying notifications
Phase 3: Add persistence and notification history
Phase 4: Implement real-time updates and optimistic UI
Phase 5: Add comprehensive testing

Start with Phase 1. After each phase, I'll review and approve before moving forward.

Complex Refactoring Projects

I need to refactor this legacy authentication system. Here's my approach:

1. First, analyze the current system and identify all dependencies
2. Create a migration plan that maintains backward compatibility
3. Implement the new system alongside the old one
4. Create a feature flag to switch between systems
5. Gradually migrate users and test thoroughly
6. Remove the old system once migration is complete

Start with step 1 - comprehensive analysis of the current system.

Context Management Techniques

Focused Sessions

Keep conversations targeted to specific domains:

# Authentication Session
"I'm working solely on authentication features today.
Only suggest changes related to auth, login, registration, and user management."

# Performance Session
"This session is focused on performance optimization.
Analyze bundle size, loading times, and runtime performance only."

Reference Management

Help Claude understand large codebases:

"The main authentication flow happens in these files:
- src/auth/AuthProvider.tsx (context setup)
- src/auth/hooks/useAuth.ts (auth logic)
- src/pages/login.tsx (login UI)
- api/auth/login.ts (backend logic)

Reference these files when working on auth-related tasks."

Incremental Context Building

"Let me give you context about our e-commerce platform:

1. We use Next.js with TypeScript
2. State management with Zustand
3. UI components with Radix + Tailwind
4. Database with Prisma + PostgreSQL
5. Payment processing with Stripe

I'll be asking you to work on various features within this context."

Advanced Analysis Capabilities

Codebase Architecture Analysis

"Analyze the overall architecture of this React application:

1. Component organization and hierarchy
2. State management patterns used
3. Data flow and communication patterns
4. Third-party integrations and dependencies
5. Testing strategy and coverage
6. Build and deployment setup
7. Potential architectural issues or technical debt

Provide a comprehensive architectural overview."

Performance Analysis

"Conduct a performance analysis of this application:

1. Bundle size analysis and recommendations
2. Runtime performance bottlenecks
3. Database query optimization opportunities
4. API endpoint performance issues
5. Frontend rendering optimizations
6. Caching strategy improvements

Focus on actionable performance improvements."

Security Assessment

"Review this application for security vulnerabilities:

1. Authentication and authorization implementation
2. Input validation and sanitization
3. API endpoint security
4. Database query security (SQL injection prevention)
5. XSS and CSRF protection
6. Sensitive data handling

Identify specific security improvements needed."

Preview Mode

See what Claude will do before making changes:

"Show me exactly what changes you would make to implement user roles,
but don't make any changes yet. I want to review your plan first."

Claude will outline:

Files that need to be modified
New files that need to be created
Specific changes to existing code
Testing requirements
Potential breaking changes

Advanced Problem-Solving Patterns

Root Cause Analysis

"This React component is causing memory leaks. Don't just fix the symptom -
investigate the root cause:

1. Analyze the component lifecycle and cleanup
2. Check for subscription leaks and event listeners
3. Examine state management and data flow
4. Look for circular references or closures
5. Identify the fundamental issue causing the leak

Provide both the analysis and the fix."

System Integration

"Help me integrate Stripe payments into this e-commerce app.
Consider the full integration:

1. Frontend payment component with proper UX
2. Backend webhook handling and security
3. Database schema for orders and payment tracking
4. Error handling and retry logic
5. Testing strategy for payment flows
6. Compliance and security requirements

Design the complete integration, not just the payment form."

Scalability Planning

"This app currently handles 1,000 users. Help me prepare it for 100,000 users:

1. Database optimization and indexing
2. API rate limiting and caching
3. Frontend performance optimization
4. Infrastructure scaling considerations
5. Monitoring and alerting setup

Create a scalability roadmap with specific implementation steps."

Efficient Context Switching

Project Templates

Create reusable project contexts:

"Save this as my 'React + TypeScript Web App' context:
- Next.js 13+ with TypeScript
- Tailwind CSS for styling
- Prisma for database
- NextAuth for authentication
- React Query for API calls
- Jest + React Testing Library for tests

Use this context for all similar projects unless I specify otherwise."

Domain-Specific Sessions

# Database session
claude --session=database
"Focus only on database schema, queries, and data modeling"

# Frontend session
claude --session=frontend
"Work only on React components, styling, and user interface"

# API session
claude --session=api
"Handle only backend logic, API endpoints, and server-side code"

Advanced Debugging Workflows

Systematic Bug Investigation

"This user registration is failing intermittently. Let's debug systematically:

1. Reproduce the issue in development
2. Add comprehensive logging to track the flow
3. Analyze potential race conditions
4. Check database constraints and validation
5. Review error handling and edge cases
6. Create a test that reproduces the bug
7. Fix the root cause
8. Verify the fix prevents regression

Start with step 1 - let's reproduce this issue."

Getting Started with Advanced Features

Plan before coding - Use Claude for architectural planning
Break down complex tasks - Multi-phase implementation approach
Manage conversation context - Use /clear and /compact strategically
Preview changes - Review plans before implementation
Focus sessions - One domain per conversation when possible

Advanced Claude Code usage transforms development from individual task assistance to comprehensive project partnership.

Claude Code Blog Series

Previous: Part 2 - CLAUDE.md Configuration Files
Next: Part 4 - Slash Commands and Custom Commands

Full Series:

Part 1 - Getting Started and Installation
Part 2 - CLAUDE.md Configuration Files
Part 3 - Conversation Management and Context (this post)
Part 4 - Slash Commands and Custom Commands
Part 5 - MCP Servers and Tool Integration
Part 6 - Subagents and Task Delegation
Part 7 - IDE Integration with VS Code and JetBrains
Part 8 - Hooks for Automated Quality Checks
Part 9 - Complete Development Workflows
Part 10 - Power User CLI Options and Scripting
Part 11 - Troubleshooting and Recovery

Claude Code: Part 2 - CLAUDE.md Configuration Files

luiz tanure — Mon, 11 Aug 2025 07:07:49 +0000

Claude Code: Part 2 - CLAUDE.md Configuration Files

The Problem

You've started using Claude Code, and it's incredibly capable. Too capable. It suggests complex architectural changes when you wanted a simple bug fix. It writes elaborate documentation when you needed a quick comment. It refactors your entire component when you asked it to fix one function.

Claude is like an enthusiastic new team member who doesn't yet understand your project's constraints, coding standards, or the difference between "quick fix" and "complete rewrite."

You need a way to teach Claude about your project's specific context, rules, and boundaries.

The Solution

CLAUDE.md files act as a persistent memory system and rule book for your project. Think of it as onboarding documentation that teaches Claude about your project's specific needs, just like you'd brief a new human developer.

How CLAUDE.md Works

Place a CLAUDE.md file in your project root with rules and context:

# Project: E-commerce Platform

## Tech Stack
- Next.js, TypeScript, Tailwind, Prisma

## Rules
- Use TypeScript strict mode
- Follow patterns in src/components/
- Functional components only

Claude now follows your project-specific rules automatically.

Memory Hierarchy

Claude Code respects a hierarchy of configuration files, with more specific files overriding general ones:

Configuration Hierarchy

Personal: ~/.claude/CLAUDE.md - Your preferences across all projects
Project: ./CLAUDE.md - Team rules for this project
Local: ./CLAUDE.local.md - Personal overrides (gitignored)
Folder: ./src/auth/CLAUDE.md - Module-specific rules

More specific files override general ones.

Multi-AI Tool Sharing

Want to use Claude Code alongside other AI tools? The CLAUDE.md approach works for now, but there's an initiative to create a universal standard called AGENT.md. Learn more at ampcode.com/AGENT.md.

For now, you can create a symlink to share the same configuration:

# Create shared memory file
mkdir ~/.ai-tools
touch ~/.ai-tools/shared-memory.md

# Link it as CLAUDE.md
ln -s ~/.ai-tools/shared-memory.md ./CLAUDE.md

# Link for other AI tools
ln -s ~/.ai-tools/shared-memory.md ./AI-CONTEXT.md
ln -s ~/.ai-tools/shared-memory.md ./CURSOR-RULES.md

Benefits:

One source of truth for project context
Consistent behavior across AI tools
Easy maintenance and updates

Writing Effective Rules

Be specific and concise:

❌ "Use good coding practices"
✅ "Functional components, TypeScript, max 200 lines"

Set clear boundaries:

Never modify payment code without review
No new packages without approval
No breaking API changes

Token Consumption Warning

⚠️ Keep CLAUDE.md files under 100 lines! They're included in every interaction.

Write concisely:

❌ "Always ensure components use hooks rather than classes"
✅ "Functional components only"

Best Practices

Start with 5-10 essential rules
Remove outdated rules regularly
Test rules work: "Create a component following our patterns"
Review monthly, prune verbosity

Getting Started

Create CLAUDE.md with 5-10 essential rules
Test it works
Keep it under 100 lines
Update monthly

CLAUDE.md transforms Claude into a project-aware teammate.

Claude Code Blog Series

Previous: Part 1 - Getting Started and Installation
Next: Part 3 - Conversation Management and Context

Full Series:

Part 1 - Getting Started and Installation
Part 2 - CLAUDE.md Configuration Files (this post)
Part 3 - Conversation Management and Context
Part 4 - Slash Commands and Custom Commands
Part 5 - MCP Servers and Tool Integration
Part 6 - Subagents and Task Delegation
Part 7 - IDE Integration with VS Code and JetBrains
Part 8 - Hooks for Automated Quality Checks
Part 9 - Complete Development Workflows
Part 10 - Power User CLI Options and Scripting
Part 11 - Troubleshooting and Recovery

Claude Code: Part 1 - Getting Started and Installation

luiz tanure — Mon, 11 Aug 2025 07:07:17 +0000

Claude Code: Part 1 - Getting Started and Installation

The Problem

You've heard about AI coding assistants, but every one you've tried feels like a disconnected chatbot. They can generate code snippets, but they don't understand your project, follow your patterns, or integrate with your actual development workflow.

You need an AI teammate that works with you, not just for you - one that understands your codebase, follows your coding standards, and becomes a true development partner rather than just another code completion tool.

Meet Your New Teammate

Claude Code is like having a genius junior developer who took too many Red Bulls. Brilliant, capable of incredible work, but needs guidance on your specific project and coding patterns. The difference is that this teammate learns your project inside and out and never gets tired.

What makes Claude Code different:

Full codebase understanding - Reads and comprehends your entire project
Project-aware - Follows your existing patterns and conventions
Tool integration - Works with your development tools and services
Contextual memory - Remembers project-specific rules and preferences

Installation

Prerequisites:

Node.js (version 18 or higher)
npm or yarn package manager

Install globally:

npm install -g @anthropic-ai/claude-code

Verify installation:

claude --version

Start Claude Code:

# In your project directory
cd your-project
claude

First Session Setup

When you first run Claude Code:

Authentication - Follow the prompts to sign in
Project detection - Claude analyzes your current directory
Initial conversation - Start with a simple task to test everything works

Example first interaction:

You: "Analyze this project and tell me what kind of application this is"
Claude: [Examines your files and provides project overview]

Key Features Overview

Codebase Analysis

Claude can read and understand your entire project:

Architecture patterns - Identifies frameworks and structures
Coding conventions - Learns your style preferences
Dependencies - Understands your tech stack
Project context - Knows what your application does

Intelligent Code Generation

Goes beyond simple snippets:

Pattern matching - Follows your existing code patterns
Context-aware - Considers surrounding code and architecture
Integration-focused - Creates code that fits your project

Development Workflow Integration

Works with your existing tools:

Git integration - Understands version control context
File operations - Reads, writes, and modifies files
Build tools - Runs tests, builds, and other project commands
IDE compatibility - Works alongside your favorite editor

Your First Productive Session

Start with exploration:

"Walk me through the main components of this React application"
"Show me how authentication is currently handled"
"What testing patterns are used in this project?"

Move to practical tasks:

"Add error handling to the user registration form"
"Create a new component for displaying user notifications"
"Fix the TypeScript errors in the payment module"

Collaborate on bigger features:

"Help me plan and implement a user dashboard feature"
"Review and refactor the API service layer"
"Add comprehensive logging to the authentication flow"

Best Practices for New Users

Start Small

Begin with simple, isolated tasks
Test Claude's understanding with questions
Gradually increase task complexity

Provide Context

Explain your project's purpose and users
Share relevant business requirements
Mention any constraints or preferences

Review Everything

Always review generated code before using it
Test changes in development environment
Understand what Claude built, don't just copy-paste

Iterate and Improve

Ask follow-up questions for clarification
Request modifications when something isn't quite right
Build on previous work in the same conversation

Common Beginner Questions

Q: How much of my code can Claude see?
A: Claude can read any files in your project directory when needed, but only accesses files relevant to your current task.

Q: Will Claude make changes without asking?
A: Claude asks for permission before modifying files and shows you exactly what changes it will make.

Q: Can Claude learn my project's specific patterns?
A: Yes! Claude learns your coding style, architecture patterns, and project conventions through analysis and your feedback.

Q: Is my code sent to external servers?
A: Claude Code follows Anthropic's privacy policies. Check the latest privacy documentation for specifics about data handling.

Troubleshooting Common Issues

"Command not found" error:

# Try using npx instead
npx @anthropic-ai/claude-code

# Or check your PATH
echo $PATH

Claude seems confused about my project:

Make sure you're in the correct directory
Try asking specific questions about visible files
Provide more context about your project structure

Authentication issues:

Check your internet connection
Try logging out and back in: claude logout then claude login

What's Next?

Now that you have Claude Code running, you're ready to explore deeper features:

Project Configuration - Learn how to customize Claude for your specific project
Advanced Commands - Discover powerful built-in commands
Workflow Integration - Connect Claude with your development tools

The goal is to move from "Claude as a tool" to "Claude as a teammate" - an AI partner that understands your project deeply and helps you build better software faster.

Claude Code Blog Series

This is Part 1 of our comprehensive Claude Code guide series. Each post builds on the previous ones, taking you from beginner to power user.

Next: Part 2 - CLAUDE.md Configuration Files

Full Series:

Part 1 - Getting Started and Installation (this post)
Part 2 - CLAUDE.md Configuration Files
Part 3 - Conversation Management and Context
Part 4 - Slash Commands and Custom Commands
Part 5 - MCP Servers and Tool Integration
Part 6 - Subagents and Task Delegation
Part 7 - IDE Integration with VS Code and JetBrains
Part 8 - Hooks for Automated Quality Checks
Part 9 - Complete Development Workflows
Part 10 - Power User CLI Options and Scripting
Part 11 - Troubleshooting and Recovery

Understand the Acronym Spaghetti: Part 5 - Advanced Principles

luiz tanure — Fri, 18 Jul 2025 20:04:50 +0000

Understand the Acronym Spaghetti: Part 5 - Advanced Principles

TLDR

Law of Demeter: Avoid deep object chaining
Composition over Inheritance: Combine small parts instead of extending classes
Tell Don't Ask: Let objects manage their own state
Convention over Configuration: Smart defaults over explicit setup
Principle of Least Astonishment: Behave as users expect

We've covered The Foundation in Part 1, Code Quality & Safety in Part 2, SOLID Architecture in Part 3, and System Architecture in Part 4.

Advanced Principles are the subtle patterns that separate good developers from great ones. These make code truly elegant and maintainable.

Advanced Principles

These principles help you write code that's not just functional, but intuitive and pleasant to work with.

Law of Demeter (Don't Talk to Strangers)

Definition: A function should only talk to its immediate friends - don't reach through objects to talk to their friends.

Simple explanation: Avoid chaining calls like user.profile.settings.theme.color. Each object should only know about its direct dependencies.

Why it matters: Reduces coupling, makes code less fragile to changes, and prevents the "breaking chain" problem where changes deep in the structure break code far away.

When to use:

Complex object hierarchies
API design where you want to prevent tight coupling
Component props design to avoid props drilling

When NOT to use:

Simple utility functions or data transformations
Well-established patterns like array.map().filter()
Configuration objects where chaining is expected

// ❌ Violates Law of Demeter - too much chaining
const UserProfile = ({ user }: { user: User }) => {
  return (
    <div>
      <h1>{user.profile.name}</h1>
      <p style={{ color: user.settings.theme.color }}>
        Posts: {user.profile.stats.posts}
      </p>
    </div>
  );
};

// ✅ Follows Law of Demeter - service handles deep access
const getUserDisplayData = (user: User) => {
  return {
    name: user.getName(),
    textColor: user.getThemeColor(),
    postCount: user.getPostCount()
  };
};

const UserProfile = ({ user }: { user: User }) => {
  const { name, textColor, postCount } = getUserDisplayData(user);

  return (
    <div>
      <h1>{name}</h1>
      <p style={{ color: textColor }}>
        Posts: {postCount}
      </p>
    </div>
  );
};

Benefits:

Maintainability: Changes to deep objects don't break surface code
Testability: Easier to mock and test components

Common Pitfall: Creating unnecessary wrapper functions for simple property access.

Composition over Inheritance

Definition: Build complex functionality by combining simple components rather than creating complex inheritance hierarchies.

Simple explanation: Instead of creating a "BaseComponent" that others extend, create small, focused components that can be combined in different ways.

Why it matters: More flexible, easier to test, and avoids the "fragile base class" problem where changes to parent classes break child classes.

When to use:

React component design patterns
Building reusable UI components
Creating flexible API interfaces
When you need multiple behaviors that can be mixed and matched

When NOT to use:

Simple cases where inheritance is clearer
Well-established patterns (like extending Error classes)
When you need polymorphism with shared behavior

// ❌ Inheritance-heavy approach
class BaseButton {
  constructor(protected text: string) {}
  render() {
    return `<button>${this.text}</button>`;
  }
}

class PrimaryButton extends BaseButton {
  render() {
    return `<button class="primary">${this.text}</button>`;
  }
}

class LoadingButton extends BaseButton {
  constructor(text: string, private loading: boolean) {
    super(text);
  }
  render() {
    return `<button disabled="${this.loading}">${this.loading ? 'Loading...' : this.text}</button>`;
  }
}

// ❌ What if we need LoadingPrimaryButton? Multiple inheritance problem!

// ✅ Composition approach
interface ButtonProps {
  text: string;
  variant?: 'primary' | 'secondary';
  loading?: boolean;
  onClick?: () => void;
}

const Button = ({ text, variant = 'secondary', loading, onClick }: ButtonProps) => {
  return (
    <button 
      className={`button ${variant}`}
      onClick={onClick}
      disabled={loading}
    >
      {loading ? 'Loading...' : text}
    </button>
  );
};

// ✅ Easy to combine behaviors
const PrimaryButton = (props: Omit<ButtonProps, 'variant'>) => (
  <Button {...props} variant="primary" />
);

const LoadingPrimaryButton = (props: Omit<ButtonProps, 'variant' | 'loading'>) => (
  <Button {...props} variant="primary" loading={true} />
);

Benefits:

Flexibility: Mix and match behaviors as needed
Testability: Easy to test individual behaviors

Common Pitfall: Creating too many small components when a simple solution would work better.

Tell, Don't Ask

Definition: Objects should tell other objects what to do, not ask them for data and make decisions for them.

Simple explanation: Instead of asking an object for its data and then deciding what to do, tell the object what you want done and let it handle the details.

Why it matters: Encapsulates logic where it belongs, reduces coupling, and makes code more maintainable by keeping related logic together.

When to use:

State management where logic belongs with the data
API design where you want to encapsulate business rules
React components that should manage their own state
Reducing prop drilling and state management complexity

When NOT to use:

Simple data structures without behavior
When you genuinely need raw data for multiple purposes
Pure calculation functions that transform data

// ❌ Asking for data and making decisions externally
const ShoppingCart = () => {
  const [cart, setCart] = useState({ items: [], discount: 0 });

  const handleCheckout = () => {
    // Asking for data and calculating externally
    let total = 0;
    cart.items.forEach(item => {
      total += item.price * item.quantity;
    });
    checkout(total);
  };

  return <button onClick={handleCheckout}>Checkout</button>;
};

// ✅ Tell objects what to do
class ShoppingCartModel {
  private items: CartItem[] = [];

  calculateTotal(): number {
    return this.items.reduce((sum, item) => 
      sum + (item.price * item.quantity), 0
    );
  }

  checkout(): CheckoutData {
    return { items: this.items, total: this.calculateTotal() };
  }
}

// ✅ React component tells the cart what to do
const ShoppingCart = () => {
  const [cart] = useState(() => new ShoppingCartModel());

  const handleCheckout = () => {
    const checkoutData = cart.checkout(); // Tell the cart to checkout
    processCheckout(checkoutData);
  };

  return <button onClick={handleCheckout}>Checkout</button>;
};

Benefits:

Encapsulation: Business logic stays with the data
Maintainability: Changes to rules happen in one place

Common Pitfall: Creating overly complex objects when simple data structures would suffice.

Convention over Configuration

Definition: Provide sensible defaults and follow established patterns so developers don't have to configure everything explicitly.

Simple explanation: Make the common case easy by having smart defaults. Only require configuration for the uncommon cases.

Why it matters: Reduces boilerplate, speeds up development, and makes codebases more predictable by following established patterns.

When to use:

Folder structure organization
API endpoint naming
Component file naming and organization
State management patterns
Default configurations

When NOT to use:

When your needs genuinely differ from conventions
When conventions would confuse your team
When explicit configuration improves clarity

// ❌ Everything requires explicit configuration
const routes = {
  users: {
    list: { path: '/api/users', method: 'GET', handler: 'UserController.list' },
    create: { path: '/api/users', method: 'POST', handler: 'UserController.create' },
    get: { path: '/api/users/:id', method: 'GET', handler: 'UserController.get' }
  }
};

// ❌ Manual API client configuration
const apiClient = new ApiClient({
  baseURL: 'https://api.example.com',
  timeout: 5000,
  headers: { 'Content-Type': 'application/json' },
  errorHandler: (error) => 
});

// ✅ Convention-based routing
// File: routes/users.ts - framework maps methods to RESTful routes
export default {
  async index(req, res) ,
  async create(req, res) ,
  async show(req, res) 
};

// ✅ API client with smart defaults
const apiClient = createApiClient(); // Works out of the box

// Only configure what's different
const customApiClient = createApiClient({
  baseURL: process.env.API_URL
});

Benefits:

Productivity: Less boilerplate, faster development
Consistency: Everyone follows the same patterns
Discoverability: Easy to find things in predictable locations
Onboarding: New developers understand the structure quickly

Common Pitfall: Following conventions blindly when they don't fit your use case.

Principle of Least Astonishment

Definition: Software should behave in a way that least surprises users and developers. The behavior should match expectations based on common patterns and naming.

Simple explanation: If most developers would expect something to work a certain way, it should work that way. Don't be clever at the expense of being predictable.

Note: This is similar to "Principle of Least Surprise" from Part 2, but focuses more on API design and system behavior rather than code readability.

Why it matters: Reduces cognitive load, prevents bugs from misunderstood behavior, and makes systems easier to learn and use.

When to use:

API response formats
Error handling patterns
State management behavior
Component lifecycle and side effects
Function naming and behavior

When NOT to use:

When breaking expectations provides significant value
When following patterns would compromise security
When domain requirements genuinely differ from common patterns

// ❌ Astonishing API behavior
app.get('/api/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);

  if (!user) {
    // Surprising: Returns 200 with special format instead of 404
    res.json({ error: 'NOT_FOUND', data: null });
  } else {
    res.json({ error: null, data: user });
  }
});

// ✅ Predictable API behavior
app.get('/api/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);

  if (!user) {
    // Expected: 404 for not found
    res.status(404).json({ error: 'User not found' });
  } else {
    // Expected: 200 with user data
    res.json(user);
  }
});

// ❌ Function with surprising behavior
const saveUserData = async (userData: any) => {
  // Surprising: Function named 'save' also sends emails
  const user = await database.save(userData);
  await emailService.sendWelcome(user);
  return user;
};

// ✅ Function with predictable behavior
const saveUser = async (userData: UserData): Promise<User> => {
  // Function only saves, as the name suggests
  return await database.save(userData);
};

const createUser = async (userData: UserData): Promise<User> => {
  // Separate function for the full creation flow
  const user = await saveUser(userData);
  await emailService.sendWelcome(user);
  return user; // Always returns the same type
};

Benefits:

Reduced Errors: Developers make fewer mistakes when behavior matches expectations
Faster Development: Less time spent understanding quirks

Common Pitfall: Being too clever or trying to "improve" on established patterns without clear benefit.

Summary

These Advanced Principles help you write code that's not just functional, but elegant and maintainable. They're the difference between code that works and code that's a joy to work with.

Advanced principles covered:

Law of Demeter: Don't reach through objects - keep interactions local
Composition over Inheritance: Build complexity from simple, composable parts
Tell, Don't Ask: Let objects manage their own state and behavior
Convention over Configuration: Smart defaults make the common case easy
Principle of Least Astonishment: Behavior should match expectations

Together with the principles from Part 1, Part 2, Part 3, and Part 4, you now have a complete toolkit for writing clean, maintainable code in React and Node.js.

Remember: mastery comes from knowing when to apply these principles and when to break them for the sake of simplicity.