Claude Code: Setup and Usage Tutorial¶

This work is licensed under a Creative Commons Attribution 4.0 International License.

Claude Code¶

This tutorial will guide you through setting up and using Claude Code, Anthropic's AI-powered development tool.

Claude Code acts as a pair programmer that understands context, writes code, creates documentation, and helps you create software faster.

1. What is Claude Code?¶

Claude Code is an AI-powered development assistant built by Anthropic that integrates directly into your development workflow.

Unlike simple code completion tools, Claude Code is an agentic AI system capable of:

• Understanding entire codebases through contextual analysis
• Writing and editing code across multiple files simultaneously
• Running commands in your terminal to test and verify changes
• Debugging errors by analyzing stack traces and suggesting fixes
• Generating documentation that stays in sync with your code
• Creating tests based on your implementation
• Refactoring code while maintaining functionality

Claude Code represents the evolution of AI-assisted development—moving beyond autocomplete to truly collaborative coding experiences often called "Vibe Coding".

2. Prerequisites & Account Setup¶

2.1 Account Options¶

Option 1: Claude.ai¶

Claude ($20/month), Claude Pro ($100/month), Claude Pro Max ($200/month)

• Access to Claude Code CLI and VS Code Extension
• Extended usage limits (5x more than free tier)
• Priority access during high-traffic periods
• Access to all Claude models (Sonnet, Opus, Haiku)
• Early access to new features

Best for: Individual developers and frequent users

Sign up: claude.ai

Option 2: Anthropic API Key¶

For programmatic access and integration:

• Sign up: console.anthropic.com
• Pricing: Pay-per-use based on tokens (see pricing below)
• API key management: Generate keys in console dashboard
• Usage tracking: Monitor consumption in real-time

Best for: Teams, developers who want fine-grained control, batch processing, or integration with other tools

2.2 System Requirements¶

Operating System¶

• macOS 10.15 (Catalina) or later
• Windows 10/11 (with WSL2 recommended for CLI)
• Linux (Ubuntu 20.04+, Fedora 35+, or equivalent)

Required Software¶

Node.js and npm (for CLI installation):

• Node.js v16.0.0 or later
• npm v7.0.0 or later
• Check versions: node --version && npm --version
• Install from nodejs.org

Git:

• Git v2.20.0 or later
• Check version: git --version
• Install from git-scm.com

VS Code (or clone):

• Visual Studio Code v1.75.0 or later: code.visualstudio.com
• Posit Positron: posit.com
• Google Antigravity: antigravity.google

AI Sandbox Environments (Optional)¶

For isolated, secure, or team-based development environments, Claude Code works in:

Docker Containers

• Run Claude Code in isolated containers
• Useful for reproducible environments
• See Docker Documentation for setup

Virtual Machines

• Full OS isolation for security-sensitive work
• Supports all major VM platforms (VirtualBox, VMware, Hyper-V)
• Good for institutional policies requiring sandboxes

Jupyter Lab

• Integrate Claude Code into notebook workflows
• See our Jupyter AI Guide for details
• Useful for data science and research contexts

Cloud Development Environments

• CyVerse: cyverse.org
• Jetstream-2: jetstream-cloud.org

3. Installation Guide¶

This section covers installing both the Claude Code CLI and the VS Code Extension. You can install one or both depending on your workflow preferences.

3.1 Claude Code CLI¶

Installation on macOS/Linux¶

Open your terminal and run:

curl -fsSL https://claude.ai/install.sh | bash
claude --version

Expected output:

2.1.9 (Claude Code)

Installation on Windows¶

Option 1: Using WSL2 (Recommended)

Windows Subsystem for Linux provides the best experience:

# In WSL2 terminal
curl -fsSL https://claude.ai/install.sh | bash
claude --version

Option 2: PowerShell/Command Prompt

# In PowerShell or CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
claude --version

Authentication Setup¶

After installation, authenticate with your Claude account:

claude

Claude will start with a welcome graphic and ask you to select a color palette

Welcome to Claude Code v2.1.9                                                                   
…………………………………………………………………………………………………………………………………………………………                                      

     *                                       █████▓▓░                                           
                                 *         ███▓░     ░░                                         
            ░░░░░░                        ███▓░                                                 
    ░░░   ░░░░░░░░░░                      ███▓░                                                 
   ░░░░░░░░░░░░░░░░░░░    *                ██▓░░      ▓                                         
                                             ░▓▓███▓▓░                                          
 *                                 ░░░░                                                         
                                 ░░░░░░░░                                                       
                               ░░░░░░░░░░░░░░░░                                                 
       █████████                                        *                                       
      ██▄█████▄██                        *                                                      
       █████████      *                                                                         
…………………█ █   █ █………………………………………………………………………………………………………………                                      

 Let's get started.                                                                             

 Choose the text style that looks best with your terminal                                       
 To change this later, run /theme                                                               

 ❯ 1. Dark mode ✔                                                                               
   2. Light mode                                                                                
   3. Dark mode (colorblind-friendly)                                                           
   4. Light mode (colorblind-friendly)                                                          
   5. Dark mode (ANSI colors only)                                                              
   6. Light mode (ANSI colors only)                                                             

╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 1  function greet() {                                                                          
 2 -  console.log("Hello, World!");                                                             
 2 +  console.log("Hello, Claude!");                                                            
 3  }                                                                                           
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

Next, you will need to authenticate in one of two ways:

Welcome to Claude Code v2.1.9                                                                   
…………………………………………………………………………………………………………………………………………………………                                      

     *                                       █████▓▓░                                           
                                 *         ███▓░     ░░                                         
            ░░░░░░                        ███▓░                                                 
    ░░░   ░░░░░░░░░░                      ███▓░                                                 
   ░░░░░░░░░░░░░░░░░░░    *                ██▓░░      ▓                                         
                                             ░▓▓███▓▓░                                          
 *                                 ░░░░                                                         
                                 ░░░░░░░░                                                       
                               ░░░░░░░░░░░░░░░░                                                 
       █████████                                        *                                       
      ██▄█████▄██                        *                                                      
       █████████      *                                                                         
…………………█ █   █ █………………………………………………………………………………………………………………                                      


 Claude Code can be used with your Claude subscription or billed based on API usage through your
  Console account.                                                                              

 Select login method:                                                                           

 ❯ 1. Claude account with subscription · Pro, Max, Team, or Enterprise                          

   2. Anthropic Console account · API usage billing              

This will:

1. Open your browser to authenticate
2. Ask you to authorize Claude Code
3. Save your credentials securely

For API key users:

# Set API key via environment variable
export ANTHROPIC_API_KEY="your-api-key-here"

export ANTHROPIC_API_KEY="your-api-key-here"

Basic Configurations¶

Configure Claude Code preferences using slash commands

In Claude, type the /model command:

 ▐▛███▜▌   Claude Code v2.1.9                                                                   
▝▜█████▛▘  Sonnet 4.5 (1M context) · Claude Max                                                 
  ▘▘ ▝▝    ~/github/intro-gpt                                                                   

────────────────────────────────────────────────────────────────────────────────────────────────
❯ /model                                                                                        
────────────────────────────────────────────────────────────────────────────────────────────────
  /model                  Set the AI model for Claude Code                                      
  /status                 Show Claude Code status including version, model, account, API conn…  
  /vim                    Toggle between Vim and Normal editing modes                           
  /plan                   Enable plan mode or view the current session plan           

Hit return or enter key on your keyboard to enter the new menu

Select a model from the list:

 ▐▛███▜▌   Claude Code v2.1.9                                                                   
▝▜█████▛▘  Sonnet 4.5 (1M context) · Claude Max                                                 
  ▘▘ ▝▝    ~/github/intro-gpt                                                                   
────────────────────────────────────────────────────────────────────────────────────────────────
 Select model                                                                                   
 Switch between Claude models. Applies to this session and future Claude Code sessions. For     
 other/previous model names, specify with --model.                                              

   1. Default (recommended)  Opus 4.5 · Most capable for complex work                           
   2. Sonnet                 Sonnet 4.5 · Best for everyday tasks                               
 ❯ 3. Sonnet (1M context) ✔  Sonnet 4.5 with 1M context · Uses rate limits faster               
   4. Haiku                  Haiku 4.5 · Fastest for quick answers    

In general, the default Sonnet 4.5 model should be most useful (both efficient and accurate) for coding tasks.

Use the Opus 4.5 model when creating complex plans or for analysing a new codebase

Use Sonnet 4.5 1M for large projects (this is actually the most expensive model)

Use Haiku 4.5 for faster outputs that don't require complexity (Haiku is still excellent for writing code, and is the least expensive model).

3.2 VS Code Extension¶

Installing from Marketplace¶

1. Open VS Code

2. Open Extensions View

3. Click Extensions icon in sidebar (or Ctrl/Cmd + Shift + X)

4. Search for "Claude Code"

5. Type "Claude Code" in search box

6. Look for official Anthropic extension

7. Install

8. Click "Install" button

9. Wait for installation to complete

10. Reload VS Code

11. Click "Reload" if prompted

Alternative: Command Line Installation¶

code --install-extension anthropic.claude

Initial Setup Wizard¶

After installation, the setup wizard will guide you through:

1. Authentication
2. Sign in with your Claude account

3. Or enter API key

4. Model Selection

5. Choose default model (Sonnet recommended)

6. Can change per-conversation

7. Permissions

8. File access permissions
9. Terminal access permissions

10. Confirm security settings

11. Workspace Configuration

12. Optional: configure per-workspace settings
13. Set up .claude directory

Authentication¶

For Claude Pro/Team users:

1. Click "Sign in with Claude" in extension
2. Authorize in browser
3. Return to VS Code

Extension Settings Overview¶

Key settings to configure:

• Default Model: Which Claude model to use
• Auto-save: Whether to save files before running commands
• Context Window: How much code to include in context
• Terminal Integration: Enable/disable terminal access
• MCP Servers: Configure Model Context Protocol connections

Access settings: Preferences > Settings > Extensions > Claude Code

Verification¶

Verify the extension is working:

1. Open Command Palette (Cmd/Ctrl + Shift + P)
2. Type "Claude Code: Chat"
3. Send a test message
4. Confirm Claude responds

3.3 GitHub CLI Setup¶

The GitHub CLI (gh) simplifies repository management and integrates beautifully with Claude Code workflows.

Installing gh Client¶

macOS:

# Using Homebrew
brew install gh

# Verify installation
gh --version

Windows:

# Using winget
winget install --id GitHub.cli

# Or using Chocolatey
choco install gh

# Verify
gh --version

Linux (Ubuntu/Debian):

# Add GitHub CLI repository
type -p curl >/dev/null || sudo apt install curl -y
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
&& sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y

# Verify
gh --version

Linux (Fedora/CentOS/RHEL):

sudo dnf install 'dnf-command(config-manager)'
sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh

# Verify
gh --version

Authentication with GitHub¶

Authenticate the GitHub CLI:

# Start authentication flow
gh auth login

You'll be prompted to:

1. Choose authentication method (browser recommended)
2. Select protocol (HTTPS or SSH)
3. Authenticate in browser
4. Confirm successful authentication

Verify authentication:

gh auth status

Expected output:

✓ Logged in to github.com as your-username
✓ Git operations for github.com configured to use https protocol

Your First Conversational Git Experience¶

Now that you've installed gh CLI and authenticated with GitHub, here's the exciting part: you don't need to memorize Git commands anymore.

Instead of typing manual commands, you can have natural conversations with Claude Code about what you want to accomplish, and Claude handles the Git operations for you.

The Paradigm Shift:

Traditional Git requires remembering specific commands, flags, and syntax.

With Claude Code, you simply describe what you want in plain English, and Claude translates your intent into the appropriate Git operations.

Traditional Git vs. Conversational Git:

Essential Conversational Git Patterns:

Here are realistic dialogues showing how Claude Code handles common Git workflows. Notice how you can ask in natural language, and Claude explains what it's doing:

Example 1: Checking Repository Status

You: What's the current state of my repository?

Claude: Let me check...

[Runs git status]

Your repository is on branch main and it's up to date with origin/main.

You have: - 3 untracked files: src/app.py, requirements.txt, and README.md - No staged or unstaged changes to tracked files

Would you like to add these files and commit them?

Alternative natural phrasings:

• "Check my git status"
• "What files have I changed?"
• "Show me what's in my repo"
• "Did I modify anything?"

Example 2: Adding and Committing Files

You: Add all my files and commit them with a good message

Claude: I'll help you commit these changes. Let me check what we're committing...

[Runs git status]

I see 3 new files: - src/app.py - A Flask application setup - requirements.txt - Python dependencies - README.md - Project documentation

[Runs git add .]

[Runs `git commit -m "feat: initial project setup with Flask app

• Add Flask application skeleton
• Add project dependencies
• Add initial documentation"`]

✓ Changes committed! Would you like to push to the remote repository?

Alternative natural phrasings: - "Commit my changes" - "Save all my work to git" - "Make a commit with a descriptive message" - "Stage and commit everything"

Example 3: Pushing to Remote

You: Push my changes to GitHub

Claude: I'll push your commits to the remote repository.

[Runs git push]

✓ Successfully pushed to origin/main!

Your changes are now on GitHub at: https://github.com/username/repo

Alternative natural phrasings:

• "Push to remote"
• "Upload my commits to GitHub"
• "Send my changes to GitHub"
• "Sync with GitHub"

Example 4: Creating a Pull Request

You: Create a pull request for my changes

Claude: I'll create a PR for you. Let me analyze your changes...

[Runs git diff main]

[Runs `gh pr create --title "feat: Add Flask application" --body "## Summary

• Initial Flask application setup
• Added project dependencies
• Created documentation

Alternative natural phrasings:

• "Make a PR"
• "Open a pull request"
• "Submit for review"
• "Create PR from my branch"

What You Just Experienced:

With Claude Code, Git operations become conversational:

✓ Natural language instead of command memorization ✓ Context awareness - Claude understands your project state ✓ Smart defaults - Claude writes good commit messages and PR descriptions ✓ Safety checks - Claude shows you what it's doing before making changes ✓ Flexibility - Ask in whatever way feels natural to you

Quick Command Reference¶

Common gh and git commands for reference:

# Create a repository
gh repo create my-project --public

# Clone a repository
gh repo clone username/repository

# Create a pull request
gh pr create --title "Feature: Add new component" --body "Description here"

# View repository information
gh repo view

# List your repositories
gh repo list

# Open repository in browser
gh repo view --web

# Check issues
gh issue list

# Create an issue
gh issue create --title "Bug: Something broke" --body "Details"

For more commands: gh --help

Verifying Installation¶

Test all components are working:

# Check versions
echo "Node: $(node --version)"
echo "npm: $(npm --version)"
echo "Git: $(git --version)"
echo "GitHub CLI: $(gh --version)"
echo "Claude Code: $(claude --version)"

All commands should return version numbers without errors.

4. Creating Your First Project¶

Now that you have Claude Code set up and understand conversational Git, let's create your first project using natural conversation. No need to memorize gh commands—just tell Claude what you want to build!

First, create a new folder in the CLI and change directory into it

mkdir review-paper
cd review-paper

4.1 Starting Claude Code¶

Before activating the local folder as a git repository, let's start Claude Code inside the new empty directory.

CLI: Starting a Session¶

Start Claude Code:

# Start Claude Code from any directory
claude

You'll see Claude Code's interactive prompt:

(base) ➜  review-paper claude

────────────────────────────────────────────────────────────────────────────────────────────────
 Do you trust the files in this folder?                                                         

 /Users/tswetnam/review-paper                                                                   

 Claude Code may read, write, or execute files contained in this directory. This can pose       
 security risks, so only use files from trusted sources.                                        

 Learn more                                                                                     

 ❯ 1. Yes, proceed                                                                              
   2. No, exit                                                                                  

 Enter to confirm · Esc to cancel                    

Click 1. Yes, proceed at this point if you are in the correct folder.

4.2 Creating a New Repository (Conversational)¶

Now comes the exciting part: creating your first GitHub repository through conversation with Claude.

No manual commands needed!

Example: Creating a Brand New Project¶

You:

❯ set up this folder as a git repository, include all of the common files for a data            
  science project that uses Python  

Claude:

⏺ I'll help you set up this folder as a git repository with common files for a Python data      
  science project. Let me plan this out.                                                        

⏺ Bash(git init)                                                                                
  ⎿  Running…                                                                                   

  Todos · ctrl+t to hide todos                                                                  
  ☐ Initialize git repository                                                                   
  ☐ Create Python .gitignore file                                                               
  ☐ Create README.md with project template                                                      
  ☐ Create requirements.txt file                                                                
  ☐ Create standard directory structure                                                         
  ☐ Create initial git commit                                                                   

────────────────────────────────────────────────────────────────────────────────────────────────
 Bash command                                                                                   

   git init                                                                                     
   Initialize git repository                                                                    

 Do you want to proceed?                                                                        
 ❯ 1. Yes                                                                                       
   2. Yes, and don't ask again for git init commands in /Users/tswetnam/review-paper            
   3. No                                                                                        

 Esc to cancel · Tab to add additional instructions   

Say Yes

⏺ Bash(git init)                                                                                
  ⎿  Initialized empty Git repository in /Users/tswetnam/review-paper/.git/                     
     hint: Using 'master' as the name for the initial branch. This default branch name          
     hint: is subject to change. To configure the initial branch name to use in all             
     … +8 lines (ctrl+o to expand)                                                              

⏺ Write(.gitignore)                                                                             
  ⎿  Wrote 187 lines to .gitignore                                                              
      1 # Byte-compiled / optimized / DLL files                                                 
      2 __pycache__/                                                                            
      3 *.py[cod]                                                                               
      4 *$py.class                                                                              
      5 # C extensions                                                                          
      6 *.so                                                                                    
      7 # Distribution / packaging                                                              
      8 .Python                                                                                 
     … +177 lines (ctrl+o to expand)                                                            

⏺ Write(README.md)                                                                              

  Todos · ctrl+t to hide todos                                                                  
  ☒ Initialize git repository                                                                   
  ☒ Create Python .gitignore file                                                               
  ☐ Create README.md with project template                                                      
  ☐ Create requirements.txt file                                                                
  ☐ Create standard directory structure                                                         
  ☐ Create initial git commit                                                                   

────────────────────────────────────────────────────────────────────────────────────────────────
 Create file README.md                                                                          
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
   1 # Review Paper                                                                             
   2                                                                                            
   3 ## Project Description                                                                     
   4                                                                                            
   5 A brief description of your review paper project.                                          
   6                                                                                            
   7 ## Project Structure                                                                       
   8                                                                                            
   9 ```                                                                                        
  10 review-paper/                                                                              
  11 ├── data/                                                                                  
  12 │   ├── raw/              # Original, immutable data                                       
  13 │   ├── interim/          # Intermediate transformed data                                  
  14 │   ├── processed/        # Final data sets for modeling                                   
  15 │   └── external/         # Data from third party sources                                  
  16 ├── notebooks/            # Jupyter notebooks for exploration                              
  17 ├── src/                  # Source code for this project                                   
  18 │   ├── __init__.py                                                                        
  19 │   ├── data/            # Scripts to download or generate data                            
  20 │   ├── features/        # Scripts to turn raw data into features                          
  21 │   ├── models/          # Scripts to train models and make predictions                    
  22 │   └── visualization/   # Scripts to create visualizations                                
  23 ├── models/              # Trained and serialized models                                   
  24 ├── reports/             # Generated analysis as HTML, PDF, LaTeX, etc.                    
  25 │   └── figures/         # Generated graphics and figures                                  
  26 ├── tests/               # Unit tests                                                      
  27 ├── requirements.txt     # Python dependencies                                             
  28 ├── .gitignore                                                                             
  29 └── README.md                                                                              
  30 ```                                                                                        
  31                                                                                            
  32 ## Setup                                                                                   
  33                                                                                            
  34 ### Prerequisites                                                                          
  35                                                                                            
  36 - Python 3.8 or higher                                                                     
  37 - pip or conda                                                                             
  38                                                                                            
  39 ### Installation                                                                           
  40                                                                                            
  41 1. Clone this repository                                                                   
  42 ```bash                                                                                    
  43 git clone <repository-url>                                                                 
  44 cd review-paper                                                                            
  45 ```                                                                                        
  46                                                                                            
  47 2. Create a virtual environment                                                            
  48 ```bash                                                                                    
  49 python -m venv venv                                                                        
  50 source venv/bin/activate  # On Windows: venv\Scripts\activate                              
  51 ```                                                                                        
  52                                                                                            
  53 3. Install dependencies                                                                    
  54 ```bash                                                                                    
  55 pip install -r requirements.txt                                                            
  56 ```                                                                                        
  57                                                                                            
  58 ## Usage                                                                                   
  59                                                                                            
  60 Describe how to use your project here.                                                     
  61                                                                                            
  62 ## Data                                                                                    
  63                                                                                            
  64 Describe your data sources and how to obtain them.                                         
  65                                                                                            
  66 ## Results                                                                                 
  67                                                                                            
  68 Summarize key findings and results.                                                        
  69                                                                                            
  70 ## Contributing                                                                            
  71                                                                                            
  72 If this is a collaborative project, describe how others can contribute.                    
  73                                                                                            
  74 ## License                                                                                 
  75                                                                                            
  76 Specify your license here.                                                                 
  77                                                                                            
  78 ## Contact                                                                                 
  79                                                                                            
  80 Your contact information or project maintainer details.                                    
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 Do you want to create README.md?                                                               
 ❯ 1. Yes                                                                                       
   2. Yes, allow all edits during this session (shift+tab)                                      
   3. No                                                                                        

 Esc to cancel · Tab to add additional instructions      

Continue to accept Claude's questions until the tasks are complete.

Claude will continue to execute on the plan until it completes:

⏺ Write(.gitignore)                                                                             
  ⎿  Wrote 187 lines to .gitignore                                                              
      1 # Byte-compiled / optimized / DLL files                                                 
      2 __pycache__/                                                                            
      3 *.py[cod]                                                                               
      4 *$py.class                                                                              
      5 # C extensions                                                                          
      6 *.so                                                                                    
      7 # Distribution / packaging                                                              
      8 .Python                                                                                 
     … +177 lines (ctrl+o to expand)                                                            

⏺ Write(README.md)                                                                              
  ⎿  Wrote 81 lines to README.md                                                                
      1 # Review Paper                                                                          
      2 ## Project Description                                                                  
      3 A brief description of your review paper project.                                       
      4 ## Project Structure                                                                    
      5 ```                                                                                     
      6 review-paper/                                                                           
     … +71 lines (ctrl+o to expand)                                                             

⏺ Write(requirements.txt)                                                                       
  ⎿  Wrote 35 lines to requirements.txt                                                         
      1 # Core data science libraries                                                           
      2 numpy>=1.24.0                                                                           
      3 pandas>=2.0.0                                                                           
      4 scipy>=1.10.0                                                                           
      5 # Visualization                                                                         
      6 matplotlib>=3.7.0                                                                       
      7 seaborn>=0.12.0                                                                         
      8 plotly>=5.14.0                                                                          
     … +25 lines (ctrl+o to expand)                                                             

⏺ Bash(mkdir -p data/raw data/interim data/processed data/external notebooks src/data           
      src/features src/models src/visualization models reports/figures tests && touch d…)       
  ⎿  (No content)                                                                               

⏺ Bash(git add . && git commit -m "Initial commit: Set up Python data science project           
      structure…)                                                                               
  ⎿ [master (root-commit) 0e41ecd] Initial commit: Set up Python data science project struc     
    ture                                                                                        
     14 files changed, 300 insertions(+)                                                        
    … +14 lines (ctrl+o to expand)                                                              


⏺ Done! I've successfully set up your folder as a git repository with a complete Python data    
  science project structure. Here's what was created:                                           

  Core Files:                                                                                   
  - .gitignore - Comprehensive Python and data science exclusions                               
  - README.md - Project template with structure documentation                                   
  - requirements.txt - Common data science libraries (numpy, pandas, scikit-learn, jupyter,     
  matplotlib, etc.)                                                                             

  Directory Structure:                                                                          
  review-paper/                                                                                 
  ├── data/                                                                                     
  │   ├── raw/              # For original data                                                 
  │   ├── interim/          # For intermediate data                                             
  │   ├── processed/        # For final datasets                                                
  │   └── external/         # For third-party data                                              
  ├── notebooks/            # For Jupyter notebooks                                             
  ├── src/                  # Source code modules                                               
  │   ├── data/                                                                                 
  │   ├── features/                                                                             
  │   ├── models/                                                                               
  │   └── visualization/                                                                        
  ├── models/               # For saved models                                                  
  ├── reports/                                                                                  
  │   └── figures/         # For generated visualizations                                       
  └── tests/               # For unit tests                                                     

  All changes have been committed to git. You can start working by:                             
  1. Creating a virtual environment: python -m venv venv                                        
  2. Activating it: source venv/bin/activate                                                    
  3. Installing dependencies: pip install -r requirements.txt                                   

✻ Baked for 1m 32s   

5. Initialization: Two Paths¶

When starting with Claude Code, you'll take one of two paths depending on whether you're working with existing code or starting fresh.

5.1 Path A: Existing Codebase¶

Use this approach when you have an established project with existing code.

When to Use This Path¶

• Joining an existing project
• Working with legacy code
• Analyzing unfamiliar codebases
• Adding features to established apps
• Debugging existing implementations

Running /init Command¶

The /init command tells Claude to comprehensively analyze your codebase:

You: /init

What Claude Analyzes¶

When you run /init, Claude Code:

1. Traverses Directory Structure
2. Maps out folders and files
3. Identifies important directories (src/, tests/, docs/, etc.)

4. Notes configuration files

5. Identifies Technologies

6. Programming languages used
7. Frameworks and libraries (from package files)
8. Build tools and task runners

9. Testing frameworks

10. Analyzes Code Patterns

11. Architecture and design patterns
12. Code organization conventions
13. Naming conventions

14. Common patterns and idioms

15. Reads Key Files

16. README and documentation
17. Package manifests (package.json, requirements.txt, Cargo.toml, etc.)
18. Configuration files (.env.example, config files)

19. Entry points (main.py, index.js, app.py, etc.)

20. Understands Dependencies

21. External libraries and versions
22. Internal module relationships
23. Import/export patterns

Example Output¶

Here's what Claude might report after analyzing a Python web application:

⏺ I'll analyze the codebase and create a CLAUDE.md file with relevant guidance for future       
  instances.                                                                                    

⏺ Bash(find . -type f -name "*.py" -o -name "*.ipynb" -o -name "*.md" -o -name "*.txt" -o -name 
      "*.yml" -o -name "*.yaml" -o -name "*.json" | grep -v ".git" | head -20)                  
  ⎿  ./requirements.txt                                                                         
     ./README.md                                                                                
     ./src/visualization/__init__.py                                                            
     … +4 lines (ctrl+o to expand)                                                              

⏺ Bash(ls -la)                                                                                  
  ⎿  total 24                                                                                   
     drwxr-xr-x@  12 tswetnam  staff   384 Jan 16 15:45 .                                       
     drwxr-xr-x+ 199 tswetnam  staff  6368 Jan 16 15:55 ..                                      
     … +10 lines (ctrl+o to expand)                                                             

⏺ Read(README.md)                                                                               
  ⎿  Read 81 lines                                                                              

⏺ Read(requirements.txt)                                                                        
  ⎿  Read 35 lines                                                                              

⏺ Bash(test -f .cursorrules && cat .cursorrules || test -d .cursor/rules && ls -la .cursor/rules
       || echo "No cursor rules found")                                                         
  ⎿  No cursor rules found                                                                      

⏺ Bash(test -f .github/copilot-instructions.md && cat .github/copilot-instructions.md || echo   
      "No copilot instructions found")                                                          
  ⎿  No copilot instructions found                                                              

⏺ Now I'll create the CLAUDE.md file with relevant guidance for this Python data science        
  project.                                                                                      

⏺ Write(CLAUDE.md)                                                                              
  ⎿  Wrote 103 lines to CLAUDE.md                                                               
      1 # CLAUDE.md                                                                             
      2 This file provides guidance to Claude Code (claude.ai/code) when working with cod       
        e in this repository.                                                                   
      3 ## Project Overview                                                                     
      4 This is a Python data science project for a review paper, following a standard da       
        ta science project structure with separation between raw data, processed data, so       
        urce code, notebooks, and outputs.                                                      
      5 ## Environment Setup                                                                    
     … +93 lines (ctrl+o to expand)                                                             

⏺ I've created a CLAUDE.md file for this repository. The file includes:                         

  1. Environment setup commands - How to create a virtual environment and install dependencies  
  2. Testing commands - How to run all tests, tests with coverage, single test files, and       
  specific tests                                                                                
  3. Code quality commands - How to use Black for formatting and flake8 for linting             
  4. Architecture overview - The Cookiecutter Data Science structure pattern with explanations  
  of each directory's purpose                                                                   
  5. Data flow pattern - The intended workflow from raw data through processing to final outputs
  6. Key dependencies - Categorized list of main libraries used                                 

  The file focuses on the practical commands needed for development and the high-level          
  architectural patterns that aren't immediately obvious from the directory structure alone.    
  Future instances of Claude Code will be able to use this to understand how to work effectively
   in this codebase.                                                                            

✻ Baked for 55s     

Best Practices for Large Projects¶

When working with large codebases:

1. Start with High-Level Overview

You: /init --summary

Get a high-level summary before diving deep.

2. Focus on Specific Areas

You: Can you analyze just the authentication system in src/auth/?

Narrow the scope to avoid overwhelming context.

3. Ask About Specific Patterns

You: How is error handling implemented across the codebase?

Target specific architectural questions.

4. Request Diagrams

You: Can you create a diagram showing how the main modules interact?

Visual representations help with complex systems.

5. Incremental Exploration

Don't try to understand everything at once. Start with:

• Entry points and main flows
• Core business logic
• Critical paths
• Then expand to utilities and helpers

5.2 Path B: Starting from Scratch¶

Use this approach when creating a new project from an empty or minimal repository.

When to Use This Path¶

• Starting a new project
• Building a proof of concept
• Learning a new framework
• Creating a tool or utility
• Prototyping an idea

Planning Session Workflow¶

Instead of /init, start a planning conversation:

You: I want to create a new Python CLI tool that helps developers manage their dotfiles. Can you help me plan the structure?

Claude will engage in a conversation to understand:

1. Project Requirements

2. What problem are you solving?

3. Who are the users?

4. What features are essential?

5. Technical Decisions

6. Programming language and version

7. Frameworks or libraries
8. Architecture approach

9. Testing strategy

10. Project Structure

11. Directory organization

12. File naming conventions
13. Module breakdown
14. Configuration approach

Example Planning Conversation¶

You:

I want to create a task management CLI app in Python that stores tasks in a local SQLite database. It should support adding, listing, completing, and deleting tasks.

Claude:

Great! Let's plan this project. Here's what I'm thinking:

**Project Structure:**

task-manager/
├── .gitignore
├── README.md
├── LICENSE
├── requirements.txt
├── setup.py
├── src/
│   ├── __init__.py
│   ├── cli.py          # CLI interface (Click or argparse)
│   ├── database.py     # SQLite operations
│   ├── models.py       # Task data model
│   └── commands/
│       ├── __init__.py
│       ├── add.py
│       ├── list.py
│       ├── complete.py
│       └── delete.py
└── tests/
    ├── __init__.py
    ├── test_database.py
    ├── test_commands.py
    └── fixtures/

Technology Stack:

• Python 3.9+
• Click for CLI framework (better than argparse for this use case)
• SQLite3 (built-in)
• pytest for testing
• Rich for beautiful terminal output (optional but nice)

Features:

1. task add "Task description" - Add new task
2. task list [--all|--completed|--pending] - List tasks
3. task complete <id> - Mark task as done
4. task delete <id> - Delete task
5. task init - Initialize database

Should I proceed with creating these files? Any changes you'd like?

**You:**

**Claude:**

Ready to create the project structure?

#### Essential Files

Claude will help you create these foundational files:

**1. README.md**

Explains what the project does, how to install, and how to use it:

```bash
You: Create a comprehensive README.md

Claude generates:

# Task Manager CLI

A simple, elegant command-line task manager built with Python.

## Features

- Add tasks with priorities
- List tasks with filtering
- Mark tasks complete
- Beautiful terminal output

## Installation

```bash
pip install -e .

Usage¶

# Add a task
task add "Write documentation" --priority high

# List all tasks
task list

# Complete a task
task complete 1

# Delete a task
task delete 2

Development¶

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest

2. LICENSE

You: Add an MIT license

Claude creates LICENSE with proper MIT license text and your name/year.

3. .gitignore

You: Create a Python .gitignore

Claude generates .gitignore with common Python exclusions:

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
ENV/
*.egg-info/
dist/
build/

# Database
*.db
*.sqlite
*.sqlite3

# IDE
.vscode/
.idea/
*.swp
*.swo

# Testing
.pytest_cache/
.coverage
htmlcov/

# OS
.DS_Store
Thumbs.db

4. requirements.txt

You: Create requirements.txt with our dependencies

click>=8.1.0
rich>=13.0.0
pytest>=7.4.0
pytest-cov>=4.1.0

5. CONTRIBUTING.md (Optional)

For open-source projects:

You: Add a CONTRIBUTING.md guide

Setting Up for Different Languages¶

Claude can help you structure projects in any language:

Python:

You: Create a Python package structure with setuptools

JavaScript/Node:

You: Create a Node.js project with Express and TypeScript

Rust:

You: Initialize a Rust project with Cargo

Go:

You: Create a Go module with a standard project layout

Claude will generate appropriate: - Directory structures - Configuration files (Cargo.toml, package.json, go.mod, etc.) - Build scripts - Testing setup - CI/CD templates

Integration with MCP¶

For advanced projects, integrate Model Context Protocol (MCP) servers:

You: Set up MCP to connect to my PostgreSQL database

Claude will: 1. Create .claude/mcp.json configuration 2. Set up database connection settings 3. Create example queries 4. Configure environment variables

Example MCP configuration:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost/mydb"
      }
    }
  }
}

See our MCP Documentation for comprehensive setup guides.

6. Working with Custom Agents¶

One of Claude Code's most powerful features is the ability to create specialized agents for repeated tasks.

6.1 What are Agents?¶

In Claude Code, an agent is a specialized AI assistant configured for specific tasks with custom instructions, knowledge, and behaviors.

How Agents Differ from Regular Prompts:

Benefits of Specialized Agents:

1. Consistency: Same approach every time
2. Efficiency: No need to repeat instructions
3. Quality: Optimized prompts and workflows
4. Team Alignment: Shared standards across team
5. Expertise: Deep knowledge in specific areas

For deeper understanding of agentic AI concepts, see Agentic AI.

6.2 Built-in Specialized Agents¶

Claude Code includes several built-in specialized agents that handle common development tasks. These agents are always available and can be invoked using the Task tool or through natural conversation.

Available Built-in Agents:

How to Invoke Built-in Agents:

Built-in agents are automatically invoked by Claude when appropriate for your task, but you can also request them explicitly:

# Examples of natural requests that invoke specific agents:
"Explore the authentication system in this codebase"  # → Explore agent
"Plan out how to implement dark mode"                 # → Plan agent
"How do I configure Claude Code hooks?"               # → claude-code-guide agent
"Search for information about Zensical features"      # → webcrawler agent

Thoroughness Levels for Explore Agent:

When using the Explore agent, you can specify how thorough the search should be:

• "quick": Basic searches, fastest response
• "medium": Moderate exploration, balanced approach
• "very thorough": Comprehensive analysis across multiple locations and naming conventions

6.3 Creating a Documentation Writer Agent¶

Let's create a practical example: a documentation writer agent that maintains your project's documentation.

Conceptual Explanation¶

A documentation agent should:

• Understand your documentation style and standards
• Know what type of documentation you need (API docs, tutorials, README updates)
• Follow consistent formatting and tone
• Keep documentation in sync with code changes
• Generate examples and usage instructions

Step-by-Step Creation Using /agents¶

Claude Code provides the /agents slash command to create custom agents interactively. This is the recommended approach as it guides you through the process and generates the configuration file automatically.

Step 1: Run the /agents Command

In Claude Code chat:

/agents

This launches the agent creation wizard that will:

1. Ask you to describe the agent's purpose and responsibilities
2. Help you define the agent's instructions and behavior
3. Set up any domain-specific knowledge
4. Create the agent configuration file in .claude/agents/
5. Automatically register the agent for use

Step 2: Describe Your Agent

When prompted, provide a clear description. For a documentation writer agent:

I need a documentation writer agent that:
- Writes clear, concise technical documentation
- Follows Markdown formatting standards
- Includes code examples for all features
- Creates API docs, README updates, and tutorials
- Uses active voice and present tense
- Keeps documentation in sync with code changes

Step 3: Refine Agent Instructions

The wizard will generate initial instructions and allow you to refine them. You can specify:

• Documentation standards: Formatting, style, structure
• Style guide: Voice, tense, sentence length
• Documentation types: README, API docs, changelogs, etc.
• Code style preferences: Language-specific conventions
• Domain knowledge: Project-specific information

The wizard creates a configuration file like .claude/agents/docs-writer.yaml with content similar to:

name: Documentation Writer
description: Technical documentation specialist for this project
version: 1.0.0

instructions: |
  You are a technical documentation expert specializing in clear, concise, and
  comprehensive documentation for software projects.

  DOCUMENTATION STANDARDS:
  - Write in clear, active voice
  - Use consistent formatting (Markdown)
  - Include code examples for all features
  - Provide usage examples with realistic scenarios
  - Keep README.md up-to-date with project changes
  - Document all public APIs, functions, and classes

  STYLE GUIDE:
  - Use second person ("you") for instructions
  - Use present tense for descriptions
  - Keep sentences concise (< 20 words)
  - Use bullet points for lists
  - Include code blocks with syntax highlighting

# Additional configuration generated by the wizard...

How to Invoke the Agent¶

CLI:

You: @docs-writer Please document the new authentication module in src/auth.py

VS Code:

In chat panel:

@docs-writer Please document the new authentication module in src/auth.py

Or via command palette:

Cmd/Ctrl + Shift + P → "Claude Code: Use Agent" → Select "Documentation Writer"

Example Interaction¶

You:

@docs-writer I just added a new function called calculate_fibonacci(n) in src/math_utils.py.
Please add a comprehensive docstring.

Documentation Writer Agent:

def calculate_fibonacci(n: int) -> int:
    """
    Calculate the nth Fibonacci number using iterative approach.

    The Fibonacci sequence is defined as:
    F(0) = 0, F(1) = 1
    F(n) = F(n-1) + F(n-2) for n > 1

    Args:
        n (int): The position in the Fibonacci sequence (0-indexed).
                 Must be a non-negative integer.

    Returns:
        int: The Fibonacci number at position n.

    Raises:
        ValueError: If n is negative.

    Examples:
        >>> calculate_fibonacci(0)
        0
        >>> calculate_fibonacci(1)
        1
        >>> calculate_fibonacci(10)
        55
        >>> calculate_fibonacci(20)
        6765

    Time Complexity:
        O(n) - Linear time complexity

    Space Complexity:
        O(1) - Constant space complexity

    Note:
        For very large values of n (> 1000), consider using
        memoization or matrix exponentiation for better performance.
    """
    if n < 0:
        raise ValueError("n must be non-negative")

    if n <= 1:
        return n

    prev, curr = 0, 1
    for _ in range(2, n + 1):
        prev, curr = curr, prev + curr

    return curr

When to Use Documentation Agent¶

Invoke the documentation agent when:

• Adding new features or functions
• Refactoring existing code
• Creating release notes
• Writing tutorials or guides
• Updating API documentation
• Generating changelogs
• Writing contribution guidelines

6.4 Other Useful Agent Ideas¶

Here are other specialized agents you might create (conceptual descriptions):

Testing Agent¶

Purpose: Generate comprehensive test suites

Key Instructions: - Write tests for all public functions - Include edge cases and error conditions - Use appropriate testing framework (pytest, Jest, etc.) - Aim for 80%+ code coverage - Write descriptive test names - Use fixtures and mocks appropriately

Invocation: @test-writer Generate tests for the UserService class

Code Review Agent¶

Purpose: Provide thorough code reviews with constructive feedback

Key Instructions: - Check for bugs and edge cases - Identify performance issues - Suggest best practices - Point out security vulnerabilities - Review naming and code style - Suggest refactoring opportunities - Be constructive and specific

Invocation: @code-reviewer Please review the changes in src/api/users.py

Refactoring Agent¶

Purpose: Improve code structure without changing behavior

Key Instructions: - Extract functions for repeated code - Simplify complex conditionals - Apply SOLID principles - Improve naming and clarity - Reduce coupling and increase cohesion - Preserve existing tests and behavior - Make incremental, testable changes

Invocation: @refactor-agent Improve the structure of the DataProcessor class

Security Auditor Agent¶

Purpose: Identify security vulnerabilities

Key Instructions: - Check for SQL injection vulnerabilities - Identify XSS and CSRF risks - Review authentication and authorization - Check for insecure dependencies - Verify proper input validation - Review secrets management - Check for information disclosure

Invocation: @security-auditor Audit the login endpoint for vulnerabilities

Performance Optimizer Agent¶

Purpose: Identify and fix performance bottlenecks

Key Instructions: - Profile code for bottlenecks - Suggest algorithmic improvements - Identify unnecessary computations - Recommend caching strategies - Optimize database queries - Reduce memory allocations - Improve concurrency

Invocation: @performance-optimizer Analyze the data processing pipeline

7. Custom Slash Commands¶

Slash commands provide shortcuts for common workflows, turning multi-step processes into single commands.

7.1 Understanding Slash Commands¶

What are Slash Commands?

Slash commands are custom shortcuts that trigger predefined workflows in Claude Code. They're like macros or aliases that encapsulate common development tasks.

Why They're Useful:

• Efficiency: Execute complex workflows with one command
• Consistency: Same process every time
• Team Alignment: Share common workflows across team
• Automation: Reduce manual, repetitive tasks
• Error Reduction: Less chance of forgetting steps

Built-in Commands:

Claude Code includes several built-in commands:

7.2 Example: Creating /commit Command¶

Let's create a powerful /commit command that automates the git commit workflow.

Purpose and Workflow¶

The /commit command should:

1. Show git status to review changes
2. Stage all changes (or prompt for selective staging)
3. Generate a descriptive commit message based on changes
4. Create the commit
5. Optionally push to remote

Configuration Syntax¶

Create .claude/commands/commit.yaml:

name: commit
description: Intelligent git commit with AI-generated message
version: 1.0.0

# Command behavior
workflow:
  - name: check_git_status
    action: run_command
    command: "git status --short"
    description: "Show current changes"

  - name: confirm_changes
    action: prompt_user
    message: "Proceed with committing these changes?"
    options:
      - value: "all"
        label: "Commit all changes"
      - value: "selective"
        label: "Let me choose files"
      - value: "cancel"
        label: "Cancel"

  - name: stage_changes
    action: conditional
    condition: "confirm_changes != 'cancel'"
    then:
      - action: run_command
        command: "git add -A"
        when: "confirm_changes == 'all'"
      - action: prompt_for_files
        when: "confirm_changes == 'selective'"

  - name: analyze_diff
    action: run_command
    command: "git diff --cached"
    store_output: "diff_content"

  - name: generate_message
    action: ai_task
    prompt: |
      Based on this git diff, generate a commit message following conventional commits format:

      <type>(<scope>): <subject>

      <body>

      <footer>

      Types: feat, fix, docs, style, refactor, test, chore

      Git diff:
      ```
      {{diff_content}}
      ```

      Generate a clear, concise commit message that explains what changed and why.
    store_output: "commit_message"

  - name: show_message
    action: display
    content: |
      Proposed commit message:

      {{commit_message}}

      Approve this message?

  - name: confirm_message
    action: prompt_user
    message: "Use this commit message?"
    options:
      - value: "yes"
        label: "Yes, commit with this message"
      - value: "edit"
        label: "Let me edit it"
      - value: "cancel"
        label: "Cancel"

  - name: edit_message
    action: conditional
    condition: "confirm_message == 'edit'"
    then:
      - action: prompt_for_text
        multiline: true
        default: "{{commit_message}}"
        store_output: "commit_message"

  - name: create_commit
    action: conditional
    condition: "confirm_message != 'cancel'"
    then:
      - action: run_command
        command: "git commit -m '{{commit_message}}'"

  - name: ask_push
    action: prompt_user
    message: "Push to remote?"
    options:
      - value: "yes"
        label: "Yes, push now"
      - value: "no"
        label: "No, I'll push later"

  - name: push_changes
    action: conditional
    condition: "ask_push == 'yes'"
    then:
      - action: run_command
        command: "git push"

# Safety settings
safety:
  confirm_before_execute: true
  allow_destructive_ops: false

# Permissions needed
permissions:
  - git
  - filesystem.read
  - filesystem.write

Simpler Version¶

If the full workflow is too complex, here's a simpler version:

.claude/commands/commit-simple.yaml:

name: commit
description: Quick commit with AI-generated message

workflow:
  - action: run_command
    command: "git add -A"

  - action: ai_task
    prompt: "Analyze the git diff and generate a conventional commit message"
    command: "git diff --cached"

  - action: git_commit
    message: "{{ai_output}}"

permissions:
  - git

Usage Demonstration¶

Basic Usage:

You: /commit

With Options:

You: /commit --no-push
You: /commit --message "fix: resolve login bug"
You: /commit --amend

Example Flow:

You: /commit

Claude Code: Analyzing changes...

Modified files:
  M src/auth.py
  M tests/test_auth.py
  A docs/authentication.md

Proposed commit message:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
feat(auth): add support for OAuth 2.0 authentication

- Implement OAuth2 authentication flow
- Add token validation and refresh logic
- Update authentication tests for new flow
- Add documentation for OAuth setup

Closes #42
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Use this commit message? [Yes/Edit/Cancel]: Yes

Creating commit... Done!
Push to remote? [Yes/No]: Yes
Pushing to origin/main... Done!

✓ Committed and pushed successfully!

7.3 Other Slash Command Ideas¶

Here are more useful custom commands (conceptual descriptions):

/test - Run Test Suite¶

name: test
description: Run tests with coverage and report results

workflow:
  - Run pytest with coverage
  - Generate coverage report
  - Show failed tests with context
  - Suggest fixes for failures

Usage: /test or /test --file tests/test_api.py

/review - Code Review Workflow¶

name: review
description: Request code review before merging

workflow:
  - Show uncommitted changes
  - Run linters and formatters
  - Check for common issues
  - Generate review checklist
  - Create pull request (optional)

Usage: /review or /review --create-pr

/deploy - Deployment Workflow¶

name: deploy
description: Deploy to specified environment

workflow:
  - Verify tests pass
  - Check environment variables
  - Build application
  - Run deployment script
  - Verify deployment
  - Tag release

Usage: /deploy production or /deploy staging --skip-tests

/docs - Documentation Generation¶

name: docs
description: Generate or update documentation

workflow:
  - Scan for undocumented functions
  - Generate missing docstrings
  - Update README if needed
  - Build documentation site
  - Show coverage report

Usage: /docs or /docs --module auth

/refactor - Smart Refactoring¶

name: refactor
description: Refactor code with specific pattern

workflow:
  - Analyze current structure
  - Suggest refactoring approach
  - Apply changes incrementally
  - Run tests after each change
  - Create commit if successful

Usage: /refactor extract-method or /refactor simplify-conditionals

/fix - Automated Bug Fixing¶

name: fix
description: Analyze and fix errors

workflow:
  - Run application/tests
  - Capture error messages
  - Analyze stack traces
  - Suggest fixes
  - Apply fix with approval
  - Verify fix works

Usage: /fix or /fix --error "IndexError on line 42"

8. Development Workflow Best Practices¶

Now that you understand the tools, let's explore effective workflows for daily development with Claude Code.

8.1 Typical Development Session¶

Here's how a productive Claude Code session typically flows:

Starting Your Work¶

1. Navigate to Project:

cd /path/to/your-project

2. Start Claude Code:

# CLI
claude

# VS Code
code . # Opens VS Code, then open Claude panel

3. Review Context:

You: What was I working on last time?

Claude can reference conversation history (if saved) or analyze recent git commits.

4. Set Today's Goal:

You: Today I need to implement user authentication. Let's start by planning the approach.

Iterative Development Flow¶

Development Loop:

flowchart TD
    A[Describe Feature/Fix] --> B[Claude Generates Code]
    B --> C[Review & Discuss]
    C --> D{Satisfactory?}
    D -->|No| E[Request Changes]
    E --> B
    D -->|Yes| F[Apply Changes]
    F --> G[Run Tests]
    G --> H{Tests Pass?}
    H -->|No| I[Debug with Claude]
    I --> B
    H -->|Yes| J[Commit Changes]
    J --> K{More Work?}
    K -->|Yes| A
    K -->|No| L[End Session]

    style F fill:#c8e6c9
    style J fill:#c8e6c9
    style L fill:#e1f5ff

Example Development Flow:

# Step 1: Plan the feature
You: I need to add a password reset feature. What's the best approach?

Claude: [Suggests approach with email tokens, expiration, security considerations]

# Step 2: Implement backend
You: Let's start with the backend. Create the password reset endpoint.

Claude: [Generates Flask/Express/etc. endpoint code]

# Step 3: Review and refine
You: Looks good, but let's add rate limiting to prevent abuse.

Claude: [Updates code with rate limiting]

# Step 4: Write tests
You: @test-writer Create tests for the password reset endpoint

Test Agent: [Generates comprehensive test suite]

# Step 5: Run tests
You: /test

Claude: [Runs tests, reports results]

# Step 6: Update documentation
You: @docs-writer Document the new password reset flow

Docs Agent: [Updates API documentation and README]

# Step 7: Commit
You: /commit

Claude: [Creates commit with descriptive message]

Managing Context¶

Keep Context Relevant:

# Clear context if conversation gets too long
You: /clear

# Focus on specific files
You: Let's focus on just src/auth.py and tests/test_auth.py

# Remove files from context
You: You can forget about the migration files, we don't need those

Loading Additional Context:

# Add files to context
You: Can you also look at config/auth_config.py?

# Load related code
You: Show me other places where we handle authentication

Conversation Organization¶

Use Clear, Specific Requests:

✅ Good:

Refactor the authenticate_user function in src/auth.py to use the Strategy pattern,
making it easier to add new authentication methods.

❌ Unclear:

Make auth better

Break Down Complex Tasks:

Instead of:

Build a complete user authentication system

Do:

1. Let's start with the database models for User and Session
2. Next, create the login endpoint
3. Then, implement JWT token generation
[etc.]

8.2 Git Integration Patterns¶

Claude Code can be a powerful Git assistant.

Commit Message Generation¶

Let Claude analyze your changes:

You: /commit

# Or manually:
You: Generate a commit message for my changes

Claude will: - Analyze the diff - Identify the type of change (feat, fix, refactor, etc.) - Write a clear, conventional commit message - Include relevant details and context

Example Generated Commit:

feat(auth): implement OAuth2 authentication flow

- Add OAuth2 client configuration
- Implement authorization code flow
- Add token refresh mechanism
- Update user model to store OAuth tokens
- Add middleware for OAuth protected routes

This enables users to authenticate using Google, GitHub, and other
OAuth providers instead of just username/password.

Closes #42

Branch Management Strategies¶

Feature Branch Workflow:

# Create feature branch
You: Can you help me create a branch for the password reset feature?

Claude: Sure! Run: git checkout -b feature/password-reset

# Work on feature...

# Before merging
You: /review
You: /test
You: /commit

Reviewing Before Merge:

You: Compare my feature branch with main and identify any conflicts

Claude: [Analyzes differences, identifies conflicts, suggests resolution]

Rebasing:

You: I need to rebase my feature branch on the latest main. Walk me through it safely.

Claude: [Provides step-by-step rebase instructions with safety checks]

Pull Request Descriptions¶

Generate comprehensive PR descriptions:

You: Generate a pull request description for my authentication feature

Claude will generate:

## Pull Request: Add OAuth2 Authentication

### Summary
Implements OAuth2 authentication flow allowing users to sign in with Google, GitHub, and Microsoft accounts.

### Changes
- ✨ Add OAuth2 client configuration (`src/auth/oauth.py`)
- ✨ Implement authorization code flow
- ✨ Add token management and refresh logic
- 🗃️ Update User model to store OAuth provider info
- 🔒 Add middleware for OAuth-protected routes
- ✅ Add comprehensive test coverage (95%)
- 📝 Update API documentation

### Testing
- [x] Unit tests pass
- [x] Integration tests pass
- [x] Manual testing with Google OAuth
- [x] Manual testing with GitHub OAuth
- [x] Security review completed

### Security Considerations
- OAuth tokens stored encrypted in database
- State parameter used to prevent CSRF
- Strict redirect URI validation
- Token refresh handled automatically

### Breaking Changes
None. Existing username/password authentication continues to work.

### Related Issues
Closes #42
Relates to #38, #45

### Screenshots
[Add screenshots of OAuth login flow]

### Deployment Notes
Requires new environment variables:
- `OAUTH_GOOGLE_CLIENT_ID`
- `OAUTH_GOOGLE_CLIENT_SECRET`
- `OAUTH_GITHUB_CLIENT_ID`
- `OAUTH_GITHUB_CLIENT_SECRET`

Code Review with Claude¶

Before submitting PR:

You: @code-reviewer Review my changes and check for issues

Code Reviewer: [Provides detailed feedback on:]
- Potential bugs
- Security concerns
- Performance issues
- Style inconsistencies
- Missing tests
- Documentation gaps

8.3 Security & Privacy¶

Developing securely with AI assistance requires careful attention.

API Key Management¶

Environment Variables:

Never hardcode API keys:

# ❌ BAD - Hardcoded
api_key = "sk-ant-1234567890"

# ✅ GOOD - Environment variable
import os
api_key = os.getenv("ANTHROPIC_API_KEY")

Setting Environment Variables:

# .env file (add to .gitignore!)
ANTHROPIC_API_KEY=your-key-here
DATABASE_URL=postgresql://...
SECRET_KEY=your-secret-key

Load in code:

from dotenv import load_dotenv
load_dotenv()

Claude Can Help:

You: Review my code for hardcoded secrets

Claude: [Identifies hardcoded credentials and suggests fixes]

.gitignore Best Practices¶

Ensure sensitive files are never committed:

You: Create a comprehensive .gitignore for Python/Node/etc.

Claude: [Generates .gitignore including:]

# Environment variables
.env
.env.local
.env.*.local

# Secrets and credentials
*.key
*.pem
*.p12
secrets.yaml
credentials.json

# Database
*.db
*.sqlite
*.sqlite3

# API keys and tokens
.anthropic
.openai
*_key.txt
*_token.txt

# IDE and editors
.vscode/
.idea/
*.swp
*.swo

# OS files
.DS_Store
Thumbs.db

Verify Nothing Sensitive is Tracked:

# Check what's tracked by git
git ls-files

# Check for accidental secrets
You: Scan my repository for potential secrets or API keys

Claude: [Uses regex patterns to identify potential secrets]

Sensitive Data Handling¶

Sanitize Before Sharing with Claude:

# ❌ Don't paste
You: Debug this: DATABASE_URL=postgresql://admin:MyPassword123@prod.example.com/db

# ✅ Do paste
You: Debug this: DATABASE_URL=postgresql://user:password@host/db

Use Placeholders:

You: Here's my config (I've replaced sensitive values with placeholders):

API_KEY=<redacted>
SECRET=<redacted>
DATABASE_URL=postgresql://USER:PASSWORD@HOST/DATABASE

The issue is...

Institutional Compliance¶

Security Checklist¶

Before deploying AI-assisted code:

• No hardcoded credentials
• Environment variables used properly
• .gitignore includes sensitive files
• No secrets in git history
• Input validation on all user input
• SQL injection prevention
• XSS prevention
• CSRF protection implemented
• Authentication tested thoroughly
• Authorization checks in place
• Encryption for sensitive data
• Secure communication (HTTPS)
• Security review completed
• Compliance requirements met

Ask Claude to Help:

You: @security-auditor Review my authentication system for vulnerabilities

Security Auditor: [Comprehensive security analysis]

9. AI Sandbox Environments¶

For certain use cases, you may want to run Claude Code in an isolated sandbox environment.

9.1 Why Use Sandboxes?¶

Isolation Benefits: - Separate development from production environment - Prevent accidental changes to main system - Test destructive operations safely - Maintain clean, reproducible environments

Testing Environments: - Test installations and configurations - Experiment with different setups - Verify cross-platform compatibility - CI/CD integration

Team Collaboration: - Consistent environment across team - Share exact development setup - Onboard new developers quickly - Document infrastructure as code

Security & Compliance: - Meet institutional security requirements - Isolate sensitive data processing - Audit and monitor activity - Enforce security policies

9.2 Options Overview¶

Docker Containers¶

What: Lightweight, isolated containers that package applications with their dependencies.

Pros: - Fast startup - Minimal resource usage - Easy to share (Dockerfile) - Perfect for CI/CD - Version controlled environments

Cons: - Requires Docker knowledge - Linux-only containers (mostly) - Networking can be complex

Learn More: Docker Documentation

Virtual Machines¶

What: Complete OS instances running on your hardware.

Pros: - Complete isolation - Run different OS (Windows on Mac, etc.) - Snapshots and restore - Better for GUI applications

Cons: - Resource-intensive - Slower startup - Large disk usage - More complex setup

Popular Options: - VirtualBox (Free, open-source) - VMware Workstation/Fusion - Parallels (Mac) - Hyper-V (Windows)

Jupyter Lab Integration¶

What: Run Claude Code within Jupyter Lab for notebook-based development.

Pros: - Interactive development - Great for data science - Inline documentation - Shareable notebooks

Cons: - Different workflow than traditional coding - Less suitable for large applications

Learn More: See our Jupyter AI Guide for detailed setup.

Cloud Development Environments¶

GitHub Codespaces - Cloud-based VS Code - Integrated with GitHub repos - Automatic environment setup - Learn more

GitPod - Open-source alternative to Codespaces - Works with GitHub, GitLab, Bitbucket - Free tier available - Learn more

AWS Cloud9 - AWS-integrated IDE - Serverless friendly - Pre-configured for AWS services - Learn more

Replit - Browser-based IDE - Instant setup - Collaborative coding - Learn more

9.3 Quick Docker Setup Example¶

Here's a basic Docker setup for Claude Code development:

Dockerfile:

FROM python:3.11-slim

# Install Node.js for Claude Code CLI
RUN apt-get update && apt-get install -y \
    nodejs \
    npm \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install Claude Code
RUN npm install -g @anthropic-ai/claude

# Install GitHub CLI
RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | \
    dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg && \
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | \
    tee /etc/apt/sources.list.d/github-cli.list > /dev/null && \
    apt-get update && \
    apt-get install gh -y

# Set up workspace
WORKDIR /workspace

# Default command
CMD ["/bin/bash"]

Usage:

# Build the image
docker build -t claude-dev .

# Run container with volume mount
docker run -it \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  claude-dev

# Inside container
claude --version
gh auth login
cd /workspace
claude

For comprehensive Docker guides, see the official Docker documentation.

10. Troubleshooting¶

Common issues and their solutions.

Installation Problems¶

Issue: npm install -g @anthropic-ai/claude fails

Solutions:

1. Check Node/npm versions:

   node --version  # Should be v16+
   npm --version   # Should be v7+
   

2. Update Node:

   # macOS
   brew upgrade node
   
   # Or use nvm
   nvm install --lts
   

3. Try without global:

   npx @anthropic-ai/claude --version
   

4. Permissions issue:

   # Use correct npm permissions (don't use sudo!)
   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
   source ~/.bashrc
   

Issue: VS Code extension not appearing

Solutions:

1. Reload VS Code:

2. Cmd/Ctrl + Shift + P → "Developer: Reload Window"

3. Check VS Code version:

4. Must be v1.75.0 or later

5. Help → About

6. Reinstall extension:

   code --uninstall-extension anthropic.claude
   code --install-extension anthropic.claude
   

Authentication Errors¶

Issue: "Authentication failed" or "Invalid API key"

Solutions:

1. Verify API key:

   echo $ANTHROPIC_API_KEY  # Should output your key
   

2. Re-authenticate:

   # CLI
   claude auth logout
   claude auth login
   
   # Check status
   claude auth status
   

3. Check API key format:

4. Should start with sk-ant-
5. No extra spaces or quotes

6. Not expired or revoked

7. Environment variable:

   # Add to ~/.bashrc or ~/.zshrc
   export ANTHROPIC_API_KEY="your-key-here"
   source ~/.bashrc
   

Issue: "Rate limit exceeded"

Solution: - You've hit usage limits - Wait and try again - Upgrade to Pro plan for higher limits - Check console.anthropic.com for usage

Extension Not Loading¶

Issue: VS Code extension installed but not working

Solutions:

1. Check extension status:
2. View → Extensions
3. Search "Claude Code"

4. Should show "Enabled"

5. Check for conflicts:

6. Disable other AI coding extensions

7. Restart VS Code

8. View logs:

9. Help → Toggle Developer Tools
10. Console tab → filter for "claude"

11. Look for error messages

12. Reinstall clean:

    # Remove extension completely
    rm -rf ~/.vscode/extensions/anthropic.claude-*
    
    # Reinstall
    code --install-extension anthropic.claude
    

Performance Issues¶

Issue: Claude Code is slow or unresponsive

Solutions:

1. Reduce context:

   You: /clear
   You: Let's focus only on the files we need
   

2. Use faster model:

   You: /model claude-4-5-haiku-20260115
   

3. Close unnecessary files (VS Code):

4. Close tabs you're not editing

5. Use .claudeignore to exclude files

6. Check network:

   ping console.anthropic.com
   

7. System resources:

8. Close other applications
9. Check RAM and CPU usage
10. Restart VS Code/terminal

Context Window Limits¶

Issue: "Context window exceeded" error

Solutions:

1. Clear conversation:

   You: /clear
   

2. Focus on specific files:

   You: Let's work only with src/auth.py for now
   

3. Create .claudeignore:

   # .claudeignore (like .gitignore)
   node_modules/
   dist/
   build/
   *.log
   *.min.js
   vendor/
   .git/
   

4. Split large files:

5. Refactor large files into smaller modules

6. Use more focused conversations

7. Use summaries:

   You: Give me a summary of the auth module instead of showing all the code