2  Writing Your CLAUDE.md

A section-by-section guide to configuring Claude Code for research

3 What Is CLAUDE.md and Why Does It Matter?

Claude Code forgets everything between sessions. Every time you open a new terminal and type claude, it starts fresh: no memory of your project, your methods, your file locations, or the decisions you made yesterday. Scott Cunningham calls this the “amnesia problem”:

“Claude has amnesia — it forgets everything between sessions.”

— Cunningham, MixtapeTools workflow.md

The fix is a file called CLAUDE.md that Claude Code reads automatically at the start of every session. It tells Claude who you are, how to behave, where your files live, and what rules to follow. If you skip it, you spend the first five minutes of every session re-explaining context that hasn’t changed.

This tutorial walks through a complete, working CLAUDE.md line by line. The file draws on three sources:

  • Scott Cunningham (MixtapeTools) — research-specific sections like estimation philosophy, variable definitions, and the Referee 2 protocol. (Template on GitHub)
  • Pedro Sant’Anna (claude-code-my-workflow) — the “project constitution” approach: core principles, quality gates, and the ~150 line limit. (Template on GitHub)
  • Chris Blattman (claudeblattman.com) — the general-purpose template: who you are, your tools, skill levels, and preferences. (Guide)

What follows is a CLAUDE.md built for an empirical social science researcher who works primarily in R with Quarto, stores projects in Dropbox, and cares about empirical rigor. Each section is explained: what it does, where the idea came from, and why it belongs in a file you want to keep under ~150 lines.

4 Where to Store It

Claude Code reads CLAUDE.md from three levels:

~/.claude/CLAUDE.md             ← user-level (applies to ALL projects)
project/CLAUDE.md               ← project root (this project only)
project/.claude/CLAUDE.md       ← also project-level (this project only)

The user-level file (~/.claude/CLAUDE.md) is for identity and preferences that apply everywhere: your name, communication style, tool preferences. The project-level file holds project-specific rules like estimation philosophy, folder conventions, and quality gates. If both exist, Claude reads both.

For a single research project, either project-level location works. Cunningham puts it at the project root. Blattman uses the .claude/ subfolder. Pick one and be consistent.

NoteSeeing hidden folders

The .claude/ folder starts with a dot, which makes it hidden by default on macOS and Linux. You won’t see it in Finder or with a plain ls command. To see it:

  • Terminal: use ls -a (the -a flag shows hidden files)
  • macOS Finder: press Cmd + Shift + . to toggle hidden files on and off
  • VS Code: hidden files are shown by default in the Explorer sidebar

If you create a claude/ folder (without the dot), Claude Code will not find your configuration files. The dot matters.

Why hidden? On Unix systems (macOS, Linux), any file or folder starting with . is treated as hidden. This is a convention for configuration and tool metadata — things that are important for the software to function but that you don’t need to see during normal work. You already have many hidden folders in your home directory: .git/ (git internals), .ssh/ (SSH keys), .zshrc (shell config), .Rprofile (R startup). The .claude/ folder follows the same logic: it holds Claude Code’s configuration, not your research files.

Should you keep it hidden? Yes. Resist the temptation to rename it to a visible folder. Hidden folders stay out of your way in Finder and ls, they won’t accidentally get included when you zip a folder to share with a co-author, and tools like .gitignore handle them predictably. More importantly, Claude Code expects the dot — it will not detect configuration or skills in a claude/ folder without it. Learn the Cmd+Shift+. shortcut for Finder and ls -a for the terminal, and you’ll have no trouble accessing it when you need to.

5 The Complete File

Here is the full CLAUDE.md. The rest of this tutorial explains each section.

# CLAUDE.md

## Core Principles

- **Plan first** — enter plan mode before non-trivial tasks
- **Verify after** — run code, render output, confirm results before moving on

---

## Estimation Philosophy

- Do NOT express concern or excitement about point estimates
- Do NOT interpret results as "good" or "bad" until the design is intentional
- Focus entirely on whether the specification is correct — results are meaningless until the design is right
- `/methods-review` NEVER modifies author code — it only reads, runs, and creates replication scripts

---

## Tools and Software

| Tool | Use | Notes |
|------|-----|-------|
| R | Primary analysis, visualization (ggplot2, fixest, sf, dplyr, tidyr) | Always use |
| Python | Cross-language replication (statsmodels, linearmodels, pandas) | For verification |
| Quarto | Slide decks (RevealJS), documents, website, tutorials (.qmd) | NOT Beamer |
| LaTeX | Paper drafts when needed | |

When suggesting code, include comments explaining non-obvious choices.

---

## R Code Style

- Write linear, top-to-bottom scripts — a reader should follow the logic by reading downward
- Use direct column access (`df$var`) over tidy evaluation when it's clearer
- Section headers with `#####` comment blocks, terse step labels (`#Step 3: Run regression`)
- Only create helper functions when the same logic is genuinely reused — not for one-off operations
- Keep comments short — say where you are, not what standard functions do
- No conditional execution paths (`if (!exists(...))`) — scripts should assume they run top to bottom in order
- No lengthy output manifests in script headers — a one-line purpose comment is enough
- Use `setwd()` at the top then relative paths throughout — not `base <- "..." + file.path(base, ...)` everywhere
- When generating ggplot figures, also write the underlying plot data to a CSV in `data/intermediate/` (e.g., `figure_X_data.csv`). This allows accurate interpretation of figures without relying on image parsing.

---

## Folder Structure

project/ ├── code/R/ — R scripts (01_clean.R, 02_analysis.R, …) ├── code/python/ — Replication scripts ├── data/raw/ — Original data (NEVER modify) ├── data/clean/ — Cleaned datasets ├── output/tables/ — Generated tables ├── output/figures/ — Generated figures


- Use relative paths in all code
- Quarto theme: use _extensions/meridian.scss when available
- ggplot2: use theme_bw() when defined in the project (exception: presentation-builder uses theme_meridian())

---

## Quarto Conventions

- Slide decks use RevealJS format with self-contained: true
- Section headers: # Title {background-color="#1e293b"}
- Exercises: {background-color="#b44527"}
- Use :::fragment for progressive disclosure
- Mermaid diagrams: always include %%{init:{...}}%% block with useMaxWidth: true
- Code chunks: echo: false, warning: false, message: false by default
- Maximum 6 bullets per slide, 10 words per bullet
- Slide titles are assertions, not labels ("Trade increased GDP by 12%" not "Results")
- Cognitive load should be roughly equal across all slides
- Lead with the conclusion, then support it (Pyramid Principle)

The file is 113 lines, well under Sant’Anna’s ~150 line recommendation. That limit is not arbitrary: Claude reads the entire file, but following 50 rules simultaneously is harder than following 15. Each additional rule constrains the output space and increases the chance of silent conflicts — where satisfying one rule means subtly violating another. A focused 120-line file where every rule gets followed beats a 400-line file where Claude quietly drops the ones that conflict with others. The sections below explain why each part is there.

6 Section-by-Section Explanation

6.1 Core Principles

## Core Principles

- **Plan first** — enter plan mode before non-trivial tasks
- **Verify after** — run code, render output, confirm results before moving on

Where it comes from: Pedro Sant’Anna’s “project constitution” approach. His CLAUDE.md opens with core principles that govern Claude’s behavior across every session. The idea is that these are non-negotiable rules, not suggestions.

Why it’s here: These two rules address the failure modes I’ve seen most often in AI-assisted research:

  1. Plan first stops Claude from jumping straight into code that goes in the wrong direction. For anything beyond a quick fix, Claude should outline its approach before executing. This is Sant’Anna’s entry gate. Claude Code has a built-in planning mode that you can trigger by asking Claude to “make a plan” before executing — it will outline its approach and ask clarifying questions before writing any code. For larger projects, you can take this further with the research-plan-execute workflow described in the Managing Long Sessions section below.

  2. Verify after means you don’t accept output on faith. After running a regression, rendering a Quarto deck, or generating a figure, Claude should confirm the output is correct before moving on.

Tip

Principles other practitioners promote. Cunningham’s MixtapeTools template adds two behavioral rules worth knowing about: design before results (focus on specification correctness, not point estimates) and cross-replicate (implement key analyses in both R and a second language, since “the mistakes Claude makes in R and Stata are largely independent — they’re orthogonal error vectors”). This tutorial handles both through the Estimation Philosophy section and the Tools table rather than as core principles. Claude Code’s auto-memory feature also functions as an implicit principle: when you correct Claude, it saves a feedback memory that persists across sessions, so corrections compound over time without manual logging.

6.2 Estimation Philosophy

## Estimation Philosophy

- Do NOT express concern or excitement about point estimates
- Do NOT interpret results as "good" or "bad" until the design is intentional
- Focus entirely on whether the specification is correct — results are meaningless until the design is right
- /methods-review NEVER modifies author code — it only reads, runs, and creates replication scripts

Where it comes from: Scott Cunningham’s MixtapeTools template. This section is closely adapted from his approach.

Why it’s here: I think this is the most important section in any research CLAUDE.md. If you leave it out, Claude will cheerfully tell you “Great news, the coefficient is significant!”, express concern about null results, and nudge you toward findings that look “interesting.”

With these lines in place, Claude focuses on whether the specification is correct: the right fixed effects, sample restrictions, standard errors. It treats results as outputs of a design, not as goals. This is where Cunningham’s “design before results” principle lives in practice — not as a one-liner in Core Principles, but as a detailed behavioral constraint that shapes how Claude handles every regression.

6.3 Communication Guidelines

## Tools and Software

```{.markdown}
## Tools and Software

| Tool | Use | Notes |
|------|-----|-------|
| R | Primary analysis, visualization (ggplot2, fixest, sf, dplyr, tidyr) | Always use |
| Python | Cross-language replication (statsmodels, linearmodels, pandas) | For verification |
| Quarto | Slide decks (RevealJS), documents, website, tutorials (.qmd) | NOT Beamer |
| LaTeX | Paper drafts when needed | |

When suggesting code, include comments explaining non-obvious choices.
Note

Communication guidelines. Blattman’s template includes a “How I Prefer to Work” section and Cunningham’s includes “Communication Guidelines” with collaborator names. Claude’s default style is verbose and hedging — it adds caveats like “It’s worth noting that…” which waste time for experienced researchers. You can add communication rules (conciseness, name conventions, no hedging) either as a separate section or, as this file does, as a single line in the Tools section. The choice is yours — what matters is that the instruction exists somewhere.

Where it comes from: Blattman’s template uses a Tools and Software table with columns for Tool, Use, and File Location.

Why it’s here: Claude needs to know which tools to use. If you don’t tell it, it might generate Beamer slides instead of Quarto, or default to matplotlib when you use ggplot2. The “Notes” column does a lot of work here:

  • “Always use” for R means Claude should never default to another language for primary analysis
  • “NOT Beamer” for Quarto prevents Claude from generating LaTeX slide code when you want Quarto RevealJS
  • “For verification” for Python makes clear that Python is a replication tool, not the primary language

Listing specific packages (fixest, sf, dplyr) tells Claude which ecosystem you work in and stops it from suggesting alternatives you don’t use.

6.4 Folder Structure

## Folder Structure

project/ ├── code/R/ — R scripts (01_clean.R, 02_analysis.R, …) ├── code/python/ — Replication scripts ├── data/raw/ — Original data (NEVER modify) ├── data/clean/ — Cleaned datasets ├── output/tables/ — Generated tables ├── output/figures/ — Generated figures


- Use relative paths in all code
- Quarto theme: use _extensions/meridian.scss when available
- ggplot2: use theme_bw() when defined in the project (exception: presentation-builder uses theme_meridian())

Where it comes from: Cunningham’s MixtapeTools includes a /newproject command that generates a standard project scaffold. Sant’Anna’s template includes a full directory tree.

Why it’s here: This keeps Claude from creating files in the wrong places. I’ve seen it save figures to the project root instead of output/figures/, or drop an R script at the top level instead of code/R/.

The rules worth highlighting:

  • data/raw/ — NEVER modify. Raw data doesn’t get touched. All transformations happen in code, producing cleaned versions in data/clean/.
  • Relative paths only prevents the reproducibility failure where code works on your machine but breaks everywhere else because it has /Users/yourname/... hardcoded in it.
  • Numbering convention (01_clean.R, 02_analysis.R) makes execution order obvious.

6.5 Quarto Conventions

## Quarto Conventions

- Slide decks use RevealJS format with self-contained: true
- Section headers: # Title {background-color="#1e293b"}
- Exercises: {background-color="#b44527"}
- Use :::fragment for progressive disclosure
- Mermaid diagrams: always include %%{init:{...}}%% block with useMaxWidth: true
- Code chunks: echo: false, warning: false, message: false by default
- Maximum 6 bullets per slide, 10 words per bullet
- Slide titles are assertions, not labels ("Trade increased GDP by 12%" not "Results")
- Cognitive load should be roughly equal across all slides
- Lead with the conclusion, then support it (Pyramid Principle)

Where it comes from: This section is specific to your workflow. Sant’Anna’s template includes Beamer Custom Environments and Quarto CSS Classes sections, which serve the same purpose for different tools.

Why it’s here: You produce all slide decks in Quarto RevealJS. If Claude doesn’t know your conventions, it will generate slides that don’t match your theme, use wrong background colors for section headers, forget to suppress code output, or produce slides that overflow. The embed-resources: true rule ensures the HTML file bundles all assets (images, fonts) so you can share it as a single file.

The Mermaid diagram rule (%%{init:{...}}%% block) prevents a rendering problem where diagrams come out too small or overflow the slide.

6.6 Project Overview and Status

## Project Overview and Status

See README.md for the current research question, method, data, and status.

Where it comes from: Cunningham’s template has detailed Project Overview, Research Question, Data Sources, Identification Strategy, Current Status, and Key Decisions sections, all inside CLAUDE.md.

Why it’s a pointer, not prose: Research questions evolve. Data sources change. Status updates every session. If you put detailed project descriptions in CLAUDE.md, they go stale fast and bloat the file. The ~150 line budget means you can’t afford to waste space on content that changes weekly.

Instead, this one line tells Claude to read README.md, which it will do when you run the session startup routine:

Read all the markdowns. Read the key programs.
State the goals of this session.

The README.md can be as detailed and frequently updated as you need without affecting CLAUDE.md.

What goes in README.md (not CLAUDE.md):

  • Current research question and method
  • Data sources and time periods
  • Key decisions made (with dates and rationale)
  • Dropped analyses (with reasons)
  • Variable definitions
  • Sample restrictions
  • Current status and next steps

All of these change. CLAUDE.md holds behavioral rules that stay stable across sessions.

A concrete example. Here is what a README.md might look like for a difference-in-differences project studying the effect of a land reform on local public goods provision:

# Land Reform and Public Goods — README

## Research Question
Did the 1996 Colombian land reform increase local public goods provision
(schools, clinics, roads) in treated municipalities?

## Method
Difference-in-differences with staggered treatment adoption.
Primary estimator: Callaway & Sant'Anna (2021) via the `did` R package.
Robustness: Sun & Abraham, Borusyak et al.

## Data
- **Treatment**: Municipality-level reform implementation dates (MinAgricultura).
- **Outcomes**: School and clinic density from DANE census panels, 1990–2010.
- **Controls**: Pre-reform population, elevation, distance to department capital.
- Unit of observation: municipality-year. N ≈ 1,100 municipalities × 21 years.

## Key Decisions
- 2025-03-12: Dropped municipalities with population < 500 (measurement noise).
- 2025-03-18: Switched from TWFE to Callaway–Sant'Anna after heterogeneity diagnostic.

## Current Status
- Cleaning: done (01_clean.R)
- Main estimates: in progress (02_analysis.R)
- Robustness checks: not started
- Draft: outline stage

README holds what changes; CLAUDE.md holds what doesn’t. Claude reads both at session start, but only CLAUDE.md needs to stay short.

Tip

Quality thresholds (from Sant’Anna and Clo-Author). Pedro Sant’Anna’s template includes a Quality Thresholds section with a scoring system: 80 (Commit — good enough to save), 90 (PR-ready — ready for coauthor review), 95 (Excellence — ready for submission). Hugo Sant’Anna’s Clo-Author uses the same thresholds with weighted aggregate scoring. The idea is that quality gates give you a shared vocabulary for “is this done?” — Claude can self-assess against a numeric target instead of the vague “looks good.” This tutorial’s CLAUDE.md does not include quality thresholds, relying instead on the stopping rules and verification skills described in Tutorials 4 and 5. But if you find yourself iterating without a clear endpoint, adding a threshold table to your own file is a concrete way to fix that.

NoteWhat happened to Session Startup and MEMORY.md?

Earlier versions of this template included a Session Startup section (instructing Claude to read README.md and MEMORY.md at session start) and a manual MEMORY.md file with [LEARN:category] tags for recording corrections.

Both are now obsolete. Claude Code reads CLAUDE.md automatically at every session start — no startup instruction needed. And the auto-memory system (built into Claude Code) handles corrections automatically: when you correct Claude, it saves the lesson to ~/.claude/projects/<project>/memory/ without you needing to manage a file. See Tutorial 4 for details.

The methods-review guardrail (“NEVER modifies author code”) was previously in a standalone Referee 2 section. It now lives in the Estimation Philosophy section above, which is where it belongs — it’s loaded every session as part of the core rules.

7 What Was Left Out (and Why)

Several sections from the source templates were left out on purpose:

Variable Definitions, Sample Restrictions, Dropped Analyses (from Cunningham): These all change as your project develops. After 20 key decisions, the decisions table alone would push CLAUDE.md past the 150-line limit. They belong in README.md. If Claude keeps getting a specific variable wrong, correct it and auto-memory will save the lesson.

Key Files (from Cunningham): File paths change as you add scripts. This is README.md territory.

Meeting Schedule (from Cunningham): Does not change Claude’s behavior.

My Skill Level (from Blattman): You know your skill level. Blattman includes this for beginners who need Claude to calibrate explanation depth. If you’re comfortable with R and the terminal, this section wastes lines.

Skills Quick Reference (from Sant’Anna): You don’t have custom skills installed yet. Add this table when you build your first skill.

Beamer Custom Environments (from Sant’Anna): You use Quarto, not Beamer.

Current Project State table (from Sant’Anna): Useful for his 6-lecture course production system, but overkill for a single research project. Status goes in README.md.

Learned Corrections section (from Sant’Anna): The older [LEARN] tag approach has been replaced by Claude Code’s built-in auto-memory system, which handles corrections automatically.

8 Testing Your CLAUDE.md

After creating the file, start Claude Code in your project directory:

cd ~/Library/CloudStorage/Dropbox/my-research-project
claude

Then ask:

What do you know about me and my work?

Claude should reference:

  • Your name and institution
  • Your primary tools (R, Quarto)
  • Your estimation philosophy
  • Your folder structure conventions
  • Your quality thresholds

If it doesn’t, check:

  • The file is at the project root or in .claude/CLAUDE.md
  • The filename is exactly CLAUDE.md (case-sensitive)
  • The file is not empty

You can also ask Claude to help you fill it in. In the terminal, type something like:

“Help me fill out my CLAUDE.md. I’m a [YOUR FIELD] professor who studies [YOUR TOPIC].”

Claude will ask follow-up questions and draft sections for you.

9 Prompting Tips That Compound Over Time

Beyond CLAUDE.md configuration, three prompting patterns consistently improve Claude’s output (Goldsmith-Pinkham, Markus Academy, 2026):

Reference an authority. Instead of describing the style you want, name the source. “Follow the best practices from Kieran Healey’s Data Visualization” produces cleaner ggplot2 figures than “make a nice graph” — Claude knows the book’s principles (direct labeling, minimal chart junk, thoughtful palettes) and applies them. This generalizes: “Write this methods section in the style of an AER paper” or “Structure this lit review like Acemoglu & Robinson” anchors Claude to a concrete standard rather than its generic defaults.

Iterate with praise + correction. “This is great, but I want the age distribution on the x-axis instead” is more effective than “that’s wrong, redo it.” The pattern — acknowledge what worked, then specify the change — keeps Claude on track without starting over.

Ask Claude to self-review. For complex code, add a verification step: “Now review this script and check that the intertemporal budget constraints are satisfied” or “Verify that the merge didn’t drop any observations.” Claude will attempt to audit its own work, catching errors that a single pass misses.

Build a style guide for your writing. The “reference an authority” tip anchors Claude to someone else’s style. A style guide anchors it to yours. Goldsmith-Pinkham describes the workflow (A Causal Affair, 2026): collect 3–5 writing samples you’re happy with — a published paper, a policy memo, a grant narrative — and ask Claude to identify your patterns: sentence length, tone, paragraph structure, how you introduce evidence, how you hedge. Curate the output into a writing_style.md file and reference it in writing prompts. The result is a “laundry list of rules” that constrains Claude’s output toward your voice rather than its generic default. It won’t replicate you perfectly — Goldsmith-Pinkham notes the styled output felt “exaggerated” compared to his actual writing — but it raises the floor. Blattman calls these voice files and recommends them for any recurring writing task (emails, reviews, recommendation letters). Store the file alongside your CLAUDE.md or in your project root.

Tip

Prompt to build a style guide:

“I’m attaching 3 writing samples [paste or @file them]. Analyze my writing style: sentence structure, tone, how I introduce claims, how I use evidence, hedging patterns, word choices I favor or avoid. Produce a writing_style.md I can reference in future prompts.”

10 Session Routines

The CLAUDE.md file works best with consistent session routines, adapted from Cunningham’s workflow.md.

Session startup. Claude Code reads CLAUDE.md automatically at session start. Auto-memory is also loaded automatically. To give Claude additional context, start each session with a prompt like:

Read all the markdowns. Read the key programs.
State the goals of this session.

Session ending. Before closing, preserve context for tomorrow:

Update README.md with decisions made today.
Note unresolved issues for next session.
Commit everything and push to GitHub.

Tutorial 3 covers the git side of this routine, including committing, pushing, and branching.

11 Managing Long Sessions

Claude Code operates within a finite context window. As conversations grow, earlier details get compressed or dropped. Two practices help:

Use /compact proactively. Don’t wait for Claude to slow down. If you’ve been working for 30+ minutes and are about to shift tasks (from data cleaning to estimation, or from coding to writing), run /compact to summarize the conversation so far and free up context space. Think of it as clearing your desk between tasks. You can also guide what /compact preserves by being specific: /compact remember all the things related to the fixed effects specification we just tested. This directs the compaction to prioritize the information you’ll need next.

Chunk work into focused sessions. Rather than doing everything in one marathon conversation — cleaning, estimation, figures, tables, slides — run separate sessions for each stage. A “figures session” where you generate and refine all plots. A “tables session” for regression output. A “writing session” for the manuscript. Each session starts fresh with CLAUDE.md and auto-memory loaded, giving Claude full context for the task at hand rather than a compressed summary of everything you’ve done today. This also creates natural git commit points (Tutorial 3).

Tip

Rule of thumb: if your session involves more than one type of deliverable (code + figures + text), split it into multiple sessions. The context window is a budget — spend it on one thing at a time.

The research → plan → execute pattern. For complex tasks, use a three-phase workflow that keeps each phase focused (Goldsmith-Pinkham, Markus Academy, 2026):

  1. Research — explore the problem with Claude (discuss data sources, read documentation, brainstorm approaches).
  2. Summarize to file — ask Claude to write a plan or summary to a file (e.g., plan.md). This compresses everything useful from the research phase into a permanent artifact. Claude Code also saves plans internally to ~/.claude/plans/ — you can reference these in later sessions, but an explicit file in your project directory is more portable and version-controllable.
  3. Start a new session — close the conversation and open a fresh one. Have Claude read the plan file and execute from it.

Each phase gets a clean context window focused on one job. The plan file acts as a bridge between phases — it carries forward the conclusions without the dead ends, false starts, and debugging noise that accumulated during research. This pattern is especially useful for multi-step data pipelines, literature reviews, or any task where the research phase consumes significant context.

12 The Three Source Templates

If you want to explore the original templates this file draws from:

Source What It Emphasizes Link
Cunningham (MixtapeTools) Estimation philosophy, variable definitions, Referee 2, dropped analyses GitHub
Pedro Sant’Anna Core principles, quality gates, ~150 line limit GitHub
Hugo Sant’Anna (Clo-Author) Worker-critic pairs, research lifecycle, submission pipeline GitHub
Blattman General template, skill levels, preferences, voice files Guide
Goldsmith-Pinkham Prompting tips, reference-an-authority trick, research-plan-execute workflow Markus Academy video series

The progression: start with Blattman’s general template if you’re new to Claude Code, add Cunningham’s research sections when you begin empirical work, adopt Sant’Anna’s governance principles when your workflow involves multi-step tasks or quality gates, and apply Goldsmith-Pinkham’s prompting strategies throughout. This tutorial’s file pulls from all five, tuned for a working researcher.