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

Understanding the Structure

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:

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

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.

Adding Coding Standards

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:

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.

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

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

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:

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

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

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

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.

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