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:

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:

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:

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

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:

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

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:

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:

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!