Mastering Project Instructions

Introduction

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.

Why Projects Need Instructions

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.

Creating Your First CLAUDE.md

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: text > /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... > /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.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

text

> /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...

Markdown

# 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

# 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

text

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

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

text

● 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
──────────────────────────────────────────────────────────────────────────────

● 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
──────────────────────────────────────────────────────────────────────────────

text

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

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

text

● 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

● 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

text

> 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

> 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

Python

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)

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)

Markdown

# 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

text

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

text

● 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
──────────────────────────────────────────────────────────────────────────────

text

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

text

● 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

text

> 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

Python

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)

Introduction

Why Projects Need Instructions

Creating Your First CLAUDE.md

Join the 1M+ learners on CodeSignal

Understanding the Structure

Adding Coding Standards

How Claude Uses Instructions

Building with Standards in Mind

Team vs Personal Instructions

What Makes Good Instructions

Conclusion and Next Steps