Welcome to Customizing Claude Code for Your Projects! In this first unit, we'll explore one of Claude Code's most powerful features: project instructions. Every codebase has its own conventions, standards, and workflows. Without clear guidance, Claude would need to ask questions or make assumptions every time we start a new session. By creating a CLAUDE.md file, we establish persistent instructions that Claude automatically follows across all sessions in our project. We'll learn how to use the /init command to create project instructions, understand the difference between team and personal settings, and see how these instructions shape Claude's behavior when building features.

Before diving into code, let's understand the problem we're solving. Imagine working on a data analysis project where we've established specific standards: using pandas for data manipulation, formatting currency as USD, following PEP 8 style guidelines, and saving plots at 300 DPI. Without project instructions, we'd need to remind Claude about these conventions in every session. Even worse, Claude might make inconsistent choices, using different libraries or formatting styles each time.

Project instructions solve this by creating a persistent context that Claude reads at the start of every session. This isn't magical memory; rather, Claude loads the instruction file automatically and applies those guidelines to all its work. The result is consistent, standardized code that matches our project's conventions without repeated explanations.

Let's see how to create project instructions using the /init command. When we type /init in Claude Code, it analyzes our repository structure, examining key files, dependencies, and the codebase organization to generate tailored instructions:

> /init

● I'll analyze the codebase to create a comprehensive CLAUDE.md file. 
  Let me start by exploring the repository structure and key files.

● Bash(find /usercode/FILESYSTEM -maxdepth 2 -type f -name "*.md"...)
  ⎿ /usercode/FILESYSTEM/.codesignal/requirements.txt
    /usercode/FILESYSTEM/.codesignal/README.md

● Read(sales_data.csv)
  ⎿ Read 61 lines

● Read(.codesignal/requirements.txt)
  ⎿ Read 2 lines

● Write(CLAUDE.md)
  ⎿ Wrote 49 lines to CLAUDE.md

● I've created a CLAUDE.md file for this repository...

The /init command actively inspects our project by reading configuration files, examining data structures, and identifying dependencies. This analysis ensures the generated CLAUDE.md reflects our actual project setup rather than using a generic template.

For the rest of this lesson, we'll work with a sales analysis project as our example. This project uses Python and pandas to analyze transaction data from a CSV file. Let's examine what /init created for this sales analysis project:

CLAUDE.md file contents:

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when 
working with code in this repository.

### Project Overview

Sales analysis and reporting project using Python and pandas. 
The project analyzes sales transaction data from `sales_data.csv` 
containing date, product, region, amount, and customer_id fields.

### Dependencies

- Python 3
- pandas >= 2.0.0

Install dependencies:
bash: pip install -r .codesignal/requirements.txt

### Running the Project

Execute the main script:
bash: bash main.sh

### Data Structure

The `sales_data.csv` file contains sales transactions with the 
following schema:
- `date`: Transaction date (YYYY-MM-DD format)
- `product`: Product name (Widget A, Widget B, Widget C)
- `region`: Sales region (North, South, East, West)
- `amount`: Transaction amount (decimal)
- `customer_id`: Customer identifier

The file structure is comprehensive and project-specific. It includes a Project Overview that provides context about the project's purpose and key data sources, a Dependencies section listing required packages with version constraints and installation commands, a Running the Project section documenting how to execute the code, and a Data Structure section detailing the schema and expected data format.

Notice how the instructions are specific to our actual codebase: the data schema lists the exact fields in our CSV, dependencies match our requirements.txt, and commands reference our actual project files. This specificity is what makes CLAUDE.md valuable—it's not generic advice but operational guidance tailored to our project.

While /init creates a solid foundation, we can customize CLAUDE.md to include project-specific coding standards. To ensure Claude provides an interactive menu of options, we need to explicitly request it. When we ask:

> Update CLAUDE.md to add a Standards section. Present options as an interactive menu.

Claude first reads the existing file, then presents an interactive menu where we can select from common standard categories:

● Read(CLAUDE.md)
  ⎿ Read 56 lines

──────────────────────────────────────────────────────────────────────────────
←  ☐ Standards  ✔ Submit  →

What standards would you like me to include in the Standards section?

❯ 1. [ ] Python code style (PEP 8, formatting)
  Standards for Python code formatting, naming conventions, and style guidelines
  2. [ ] pandas usage patterns
  Best practices for working with pandas DataFrames in this project
  3. [ ] Data analysis conventions
  Standards for how to structure and present data analysis results
  4. [ ] Documentation requirements
  Standards for code comments, docstrings, and documentation
  5. [ ] Type something
     Submit
──────────────────────────────────────────────────────────────────────────────

We can select multiple options by checking their boxes. For our sales analysis project, let's select options 2 (pandas usage patterns) and 4 (Documentation requirements), then click Submit:

● User answered Claude's questions:
  ⎿ · What standards would you like me to include in the Standards section? →
      Documentation requirements, pandas usage patterns

Claude then updates the file with detailed, project-specific guidelines:

● Update(CLAUDE.md)
  ⎿ Added 18 lines
    45 +## Standards
    46 +
    47 +### Documentation Requirements
    48 +
    49 +- Add docstrings to all functions describing purpose, parameters, and return values
    50 +- Include inline comments for complex data transformations or business logic
    51 +- Document assumptions about data format and structure
    52 +- Provide clear output descriptions when displaying analysis results
    53 +
    54 +### pandas Usage Patterns
    55 +
    56 +- Read CSV files using `pd.read_csv()` with explicit `parse_dates` parameter
    57 +- Use descriptive variable names for DataFrames (e.g., `sales_df`, `summary_df`)
    58 +- Prefer method chaining for data transformations when it improves readability
    59 +- Use `groupby()` for aggregations by region, product, or time period
    60 +- Handle missing or invalid data explicitly rather than relying on defaults
    61 +- When filtering data, use boolean indexing with clear conditions

Notice how Claude tailors the standards to our project context. The pandas patterns reference our actual data structure (regions, products, time periods), and the documentation requirements align with data analysis workflows. These aren't generic templates—they're actionable guidelines specific to our sales analysis project that Claude will apply automatically in all future sessions.

Now let's see these instructions in action. When we ask Claude to create a function for calculating monthly revenue, watch how it applies the project standards:

> Create a function to calculate monthly revenue

● Based on your project standards, I'll use pandas and proper formatting...

● Write(revenue.py)
  ⎿ Wrote 12 lines to revenue.py

Claude explicitly acknowledges the project standards before writing code. This confirmation shows that it's reading and applying the CLAUDE.md instructions. The resulting code demonstrates this alignment:

import pandas as pd

def calculate_monthly_revenue(df: pd.DataFrame) -> pd.DataFrame:
    """Calculate total revenue grouped by month.
    
    Args:
        df: Sales data with 'date' and 'amount' columns
        
    Returns: 
        DataFrame with month and revenue_usd columns
    """
    df['month'] = pd.to_datetime(df['date']).dt.to_period('M')
    monthly = df.groupby('month')['amount'].sum()
    return monthly.to_frame('revenue_usd').round(2)

Let's break down how Claude followed our standards in the revenue calculation function. First, notice the pandas usage: the function accepts and returns DataFrames, using pandas methods like groupby and to_datetime. This matches our "Use pandas for data manipulation" standard.

The currency formatting appears in the column name revenue_usd and the .round(2) method, ensuring two decimal places as specified. The docstring provides clear documentation, following our "Include docstrings for functions" standard. Even the function signature with explicit type hints (df: pd.DataFrame) reflects PEP 8 style practices.

Without the Standards section in CLAUDE.md, Claude might have used NumPy arrays, omitted type hints, or formatted currency differently. The instructions ensure consistency regardless of when or how we interact with Claude.

Claude Code supports two types of instruction files: CLAUDE.md and CLAUDE.local.md. Understanding the difference is crucial for team collaboration. CLAUDE.md contains team-wide standards that should be committed to version control. Everyone working on the project sees the same conventions: coding style, library choices, and workflow expectations.

CLAUDE.local.md, on the other hand, holds personal preferences and should be added to .gitignore. This might include local development paths, machine-specific Docker commands, or personal formatting preferences that don't affect the team. For example, CLAUDE.md might specify "Run tests before committing," while CLAUDE.local.md could add "On my machine, use the test database at localhost:5433."

When both files exist, Claude loads CLAUDE.md first for shared context, then applies CLAUDE.local.md as a personal overlay. This layering lets us customize our experience without conflicting with team standards.

Effective project instructions share several characteristics. Brevity matters: keep CLAUDE.md focused on operational guidance rather than extensive documentation. A good rule is to include what changes Claude's behavior, not background reading material.

Specificity beats generality: "Use pandas for data manipulation" is better than "Use appropriate libraries." Include actual commands Claude should run: "Run bash main.sh to execute the project" tells Claude exactly how to test changes. Document data schemas explicitly: listing exact column names and formats prevents confusion.

Structure for scanning: use bullet points, clear section headers, and consistent formatting. Claude processes structured instructions more reliably than long paragraphs. Finally, update as needed: CLAUDE.md evolves with the project, so treat it as living documentation that reflects current best practices.

We've explored how project instructions transform Claude Code from a general-purpose tool into a project-aware assistant. By creating CLAUDE.md with /init, we establish persistent context that Claude applies consistently across all sessions. The distinction between team instructions (CLAUDE.md) and personal settings (CLAUDE.local.md) enables both shared standards and individual customization. We've seen how clear, specific guidelines shape Claude's output, ensuring it builds features that match our project's conventions automatically.

Now it's time to put this knowledge into practice and create your own project instructions!