Establishing Project Context with CLAUDE.md

Welcome back! In previous courses, you mastered the fundamentals of working with Claude Code. Now, in this next step, we’ll tackle one of the biggest challenges in AI-assisted coding: persistent project context.

Imagine if you had to re-explain your entire workflow to Claude every single session—reminding it about color schemes, chart formatting, data quirks, and library preferences. It’s repetitive and easy to miss details. Fortunately, Claude offers a solution: the CLAUDE.md file.

In this lesson, you’ll learn how to set up a CLAUDE.md—a persistent, project-specific instruction manual that lets Claude remember your standards and preferences automatically. You’ll build a complete example for a penguin visualization project, and see how a single, simple prompt can produce a publication-ready chart. By the end, you’ll know how to write your project’s “rules” once and have Claude follow them every time, without repeating yourself.

A CLAUDE.md file is a persistent memory and instruction manual for Claude Code within a specific project. When you run Claude Code in a terminal, it automatically looks for a file named CLAUDE.md in your current directory. If found, Claude reads the entire contents and treats it as part of its instructions before you even type your first prompt.

This creates a powerful workflow: you write your project's standards, preferences, and conventions once in the CLAUDE.md file, and Claude applies them automatically in every session. Unlike your conversation history (which gets cleared between sessions), the CLAUDE.md file remains unchanged until you explicitly update it, providing true persistent context.

You might be wondering: "Isn't this just like a README.md file?" While both are markdown files in your project root, they serve completely different audiences.

A README tells someone about your project: how to install it, what it does, how to run it. A CLAUDE.md tells Claude how to work on your project: which libraries to prefer, what coding style to use, how to format visualizations. You're not documenting the project for future developers—you're creating an instruction set that Claude will follow in real time as it writes code.

Let's build a complete CLAUDE.md file for a Palmer Penguins visualization project, piece by piece. You'll see how each section contributes to creating a context-aware AI assistant.

Start with the fundamentals: what is this project, and what data does it work with?

# Penguin Data Visualization Project

## Project Overview
This project focuses on exploring and visualizing the Palmer Penguins dataset using Python and AI-assisted workflows. All visualizations should be publication-ready and scientifically accurate.

## Dataset Context
- **Primary dataset**: `penguins.csv`
- **Species**: Adelie, Chinstrap, Gentoo
- **Key measurements**: bill_length_mm, bill_depth_mm, flipper_length_mm, body_mass_g
- **Categorical variables**: species, island, sex
- **Known issues**: Some missing values in measurements and sex fields

The Project Overview sets the quality bar: "publication-ready and scientifically accurate" tells Claude this isn't casual exploration. The Dataset Context provides essential facts about the data structure. The "Known issues" line is particularly important—it prepares Claude to handle missing values properly rather than ignoring them.

Define which tools Claude should reach for first:

## Preferred Libraries
- **Data manipulation**: pandas, numpy
- **Static plotting**: matplotlib, seaborn
- **Interactive plotting**: plotly
- **Statistics**: scipy (for confidence intervals, regression)

This section prevents Claude from suggesting alternatives that might produce inconsistent results. The parenthetical notes like "(for confidence intervals, regression)" help Claude understand when to use each library. Without this section, Claude might default to different libraries in different sessions, breaking visual consistency.

Establish your "how we write code here" rules:

## Coding Conventions
- Use descriptive variable names (e.g., `df_penguins` not `df`)
- Always handle missing values explicitly with `.dropna()` or `.fillna()`
- Include docstrings for functions longer than 10 lines
- Save all plots with 300 dpi resolution: `plt.savefig('plot.png', dpi=300, bbox_inches='tight')`
- Use Python 3.10+ features (type hints preferred but not required)

Notice the specificity: instead of "use good variable names," we provide an example (df_penguins not df). Instead of "save high-quality images," we specify exactly: 300 dpi with bbox_inches='tight'. Each rule is concrete and actionable. The instruction to "always handle missing values explicitly" ensures Claude never silently drops data without explanation.

For visualization projects, this is the most critical section. Include exact specifications:

## Chart Styling Guidelines

### Color Scheme
Use consistent species colors across all visualizations:
- **Adelie**: `#FF6B6B` (coral red)
- **Chinstrap**: `#4ECDC4` (teal)
- **Gentoo**: `#95E1D3` (mint green)

### Typography
- Title font size: 16pt, bold
- Axis labels: 12pt, regular weight
- Tick labels: 10pt
- Legend: 11pt

### Layout Standards
- Always include axis labels with units (e.g., "Bill Length (mm)")
- Add grid lines with `alpha=0.3` for easier reading
- Use tight layout: `plt.tight_layout()`
- Include informative titles that describe the insight, not just the data

This level of detail ensures perfect consistency across all visualizations. The exact hex codes (#FF6B6B, #4ECDC4, #95E1D3) mean every chart uses identical colors. The typography specifications down to the point size eliminate subjective interpretation. The example in the Layout Standards ("Bill Length (mm)") shows Claude exactly how to format axis labels with units.

Define file naming, data handling, and interactivity rules:

## Visualization Standards

### File Naming
- Use descriptive names: `species_body_mass_comparison.png` not `plot1.png`
- Include plot type in name: `scatter_bill_dimensions.png`, `box_body_mass.png`

### Data Integrity
- Never drop data without documenting why
- Report the number of observations used: "Based on 344 penguins with complete measurements"
- Flag outliers but don't automatically remove them

### Interactivity (for Plotly)
- Always include hover information showing: species, exact values, island
- Use dropdown menus for filtering, not radio buttons (saves space)
- Save interactive plots as self-contained HTML files

The File Naming section with examples ensures you can find visualizations later. The Data Integrity section prevents silent data loss—Claude will always explain what happened to missing values. The specific instruction to "report the number of observations" means you'll immediately notice if filtering went wrong.

Give Claude a pre-flight checklist to verify before finishing:

## Quality Checklist
Before finalizing any visualization, verify:
- [ ] Colors match species standards
- [ ] All axes have labels with units
- [ ] Title is clear and informative
- [ ] Legend is present (if multiple categories)
- [ ] Grid improves readability without cluttering
- [ ] File saved at 300 dpi (static) or as HTML (interactive)
- [ ] Missing data handled appropriately

## Notes
- When creating multiple related plots, maintain visual consistency (same colors, fonts, layout)
- For final outputs, generate standalone Python scripts that save plots

This checklist format helps Claude self-verify its work. The Notes section captures project-specific preferences that don't fit elsewhere—like generating "standalone Python scripts" rather than notebook cells.

Here's what you've built—a comprehensive instruction manual that sits in your project directory:

# Penguin Data Visualization Project

## Project Overview
This project focuses on exploring and visualizing the Palmer Penguins dataset using Python and AI-assisted workflows. All visualizations should be publication-ready and scientifically accurate.

## Dataset Context
- **Primary dataset**: `penguins.csv`
- **Species**: Adelie, Chinstrap, Gentoo
- **Key measurements**: bill_length_mm, bill_depth_mm, flipper_length_mm, body_mass_g
- **Categorical variables**: species, island, sex
- **Known issues**: Some missing values in measurements and sex fields

## Preferred Libraries
- **Data manipulation**: pandas, numpy
- **Static plotting**: matplotlib, seaborn
- **Interactive plotting**: plotly
- **Statistics**: scipy (for confidence intervals, regression)

## Coding Conventions
- Use descriptive variable names (e.g., `df_penguins` not `df`)
- Always handle missing values explicitly with `.dropna()` or `.fillna()`
- Include docstrings for functions longer than 10 lines
- Save all plots with 300 dpi resolution: `plt.savefig('plot.png', dpi=300, bbox_inches='tight')`
- Use Python 3.10+ features (type hints preferred but not required)

## Chart Styling Guidelines

### Color Scheme
Use consistent species colors across all visualizations:
- **Adelie**: `#FF6B6B` (coral red)
- **Chinstrap**: `#4ECDC4` (teal)
- **Gentoo**: `#95E1D3` (mint green)

### Typography
- Title font size: 16pt, bold
- Axis labels: 12pt, regular weight
- Tick labels: 10pt
- Legend: 11pt

### Layout Standards
- Always include axis labels with units (e.g., "Bill Length (mm)")
- Add grid lines with `alpha=0.3` for easier reading
- Use tight layout: `plt.tight_layout()`
- Include informative titles that describe the insight, not just the data

## Visualization Standards

### File Naming
- Use descriptive names: `species_body_mass_comparison.png` not `plot1.png`
- Include plot type in name: `scatter_bill_dimensions.png`, `box_body_mass.png`

### Data Integrity
- Never drop data without documenting why
- Report the number of observations used: "Based on 344 penguins with complete measurements"
- Flag outliers but don't automatically remove them

### Interactivity (for Plotly)
- Always include hover information showing: species, exact values, island
- Use dropdown menus for filtering, not radio buttons (saves space)
- Save interactive plots as self-contained HTML files

## Quality Checklist
Before finalizing any visualization, verify:
- [ ] Colors match species standards
- [ ] All axes have labels with units
- [ ] Title is clear and informative
- [ ] Legend is present (if multiple categories)
- [ ] Grid improves readability without cluttering
- [ ] File saved at 300 dpi (static) or as HTML (interactive)
- [ ] Missing data handled appropriately

## Notes
- When creating multiple related plots, maintain visual consistency (same colors, fonts, layout)
- For final outputs, generate standalone Python scripts that save plots

This single file now contains everything Claude needs to know about your project's standards and preferences.

Now let's watch the magic happen. With your CLAUDE.md file in place, you give Claude a simple, minimal prompt.

Create a chart of the bill dimensions

That's it. Seven words. No mention of colors, no specifications about fonts or DPI, no reminders about which libraries to use. Just a straightforward request.

The first thing Claude does is read the CLAUDE.md file to understand your project:

● Bash(ls -la)
  ⎿  total 40                                         
     drwxrwxrwt. 3 root   root      77 Dec 30 20:50 .
     drwxrwxrwx. 3 root   root      50 Dec 30 19:51 ..
     … +4 lines (ctrl+o to expand)

● Read(CLAUDE.md)
  ⎿  Read 74 lines

● Read(penguins.csv)
  ⎿  Read 346 lines

Claude automatically checks the directory structure, reads your CLAUDE.md file (all 74 lines), and examines the dataset. This happens before Claude writes a single line of code. Your entire project context—colors, fonts, conventions, standards—is now loaded into Claude's working memory.

With the context loaded, Claude creates a Python script following every guideline:

● Write(scatter_bill_dimensions.py)
  ⎿  Wrote 72 lines to scatter_bill_dimensions.py                                       
     #!/usr/bin/env python3
     """
     Visualize penguin bill dimensions across three species.
     Creates a scatter plot showing the relationship between bill length and bill depth.
     """
     import pandas as pd
     import matplotlib.pyplot as plt
     import numpy as np
     … +62 lines (ctrl+o to expand)

Notice the file name: scatter_bill_dimensions.py follows the naming convention from your CLAUDE.md ("Use descriptive names" and "Include plot type in name"). The script includes a docstring (per your coding conventions) and uses your preferred libraries (pandas, matplotlib).

Claude runs the script and reports exactly what you specified in your Data Integrity guidelines:

● Bash(python3 scatter_bill_dimensions.py)
  ⎿  Chart created based on 342 penguins with complete bill measurements
       - Adelie: 151 penguins
       - Chinstrap: 68 penguins
       - Gentoo: 123 penguins

● Read(scatter_bill_dimensions.png)
  ⎿  Read image (302.5KB)

The output includes the observation count (342 of 344 penguins) and breakdown by species—exactly as required by your "Report the number of observations used" rule. Claude handled the 2 missing values explicitly, as instructed.

Finally, Claude delivers the visualization with scientific interpretation:

● I've successfully created a chart of the penguin bill dimensions! The scatter plot shows the relationship between bill
  length and bill depth for all three penguin species.

  Key insights from the visualization:
  - Adelie penguins (coral red): Shorter, deeper bills (33-46mm length, 15-22mm depth)
  - Chinstrap penguins (teal): Medium-length bills with moderate depth (40-58mm length, 16-21mm depth)
  - Gentoo penguins (mint green): Longer, shallower bills (41-60mm length, 13-17mm depth)

  The chart is based on 342 penguins with complete bill measurements and has been saved as scatter_bill_dimensions.png at
   300 dpi, following all the project styling guidelines including:
  - Species-specific colors
  - Proper axis labels with units
  - Informative title
  - Grid lines for readability
  - Publication-ready formatting

Claude confirms it followed all your styling guidelines without you asking: species-specific colors, 300 dpi, axis labels with units, informative title. This confirmation acts like a verbal quality checklist.

Here's the chart Claude created:

Look closely at this visualization. Each species uses exactly the hex codes from the CLAUDE.md: Adelie in coral red (#FF6B6B), Chinstrap in teal (#4ECDC4), and Gentoo in mint green (#95E1D3). The title is 16pt and bold. Axis labels are 12pt with units ("Bill Length (mm)"). The grid has alpha of 0.3. Every single detail matches the specifications—and you didn't ask for any of it explicitly.

The CLAUDE.md file transformed a seven-word prompt into a publication-ready visualization because:

The Color Scheme section gave Claude exact hex codes, eliminating guesswork about colors.

The Typography section specified every font size (title: 16pt, labels: 12pt, ticks: 10pt), ensuring consistency.

The Layout Standards required axis labels with units and grid lines with alpha=0.3, which Claude followed precisely.

The Data Integrity rules forced Claude to handle missing data explicitly (342 of 344 penguins) and report the breakdown.

The Coding Conventions specified 300 dpi with bbox_inches='tight' for all saved plots.

The File Naming standards resulted in scatter_bill_dimensions.png instead of plot1.png.

Without the CLAUDE.md file, your prompt would need to include every single specification:

Create a scatter plot of penguin bill dimensions using matplotlib. 
Use #FF6B6B for Adelie, #4ECDC4 for Chinstrap, and #95E1D3 for Gentoo. 
Make the title 16pt bold. Use 12pt axis labels with units. Add grid with 
alpha=0.3. Save at 300 dpi with tight bbox. Handle missing data explicitly 
and report the number of observations by species. Use descriptive file naming 
with plot type included.

That's exhausting to type every time—and easy to forget details. The CLAUDE.md file encodes all these preferences once, and Claude applies them automatically. This is the power of "write once, use forever."

You've learned how to solve the context problem that plagues AI coding assistants. By building a CLAUDE.md file section by section, you created a persistent instruction manual that transforms Claude from a forgetful assistant into a context-aware collaborator. The file includes project overview, dataset context, library preferences, coding conventions, styling guidelines, visualization standards, and quality checklists—everything Claude needs to produce consistent, publication-ready outputs.

When you write "create a chart of the bill dimensions," Claude already knows your color palette, font sizes, DPI requirements, data handling rules, and file naming conventions. The result: a perfectly styled visualization that follows every guideline without you having to repeat yourself.

In the upcoming practice exercises, you'll create your own CLAUDE.md files for different visualization projects. You'll structure project context, define styling rules, and test whether Claude follows your guidelines automatically. Get ready to experience the power of "write once, use forever" as you build reusable workflows that make every session more productive.