CLAUDE.md for Python Research Project

Analysis codebase with notebooks for exploration and modules for anything reused.

Python 3.11+pandaspytestuv

How to use this

Save it as CLAUDE.md in your repository root and replace the placeholders in angle brackets. Claude reads it before every task, so keep it short — the Playbooks table at the bottom is how you add detail without paying for it on every unrelated request.

The file

# <project name>

<What this project investigates, and what the output is.>

## Commands

- `uv run python -m src.pipeline` — run the pipeline
- `uv run pytest` — tests
- `uv run ruff check .` — lint

## Project Structure

- `src/` — importable modules; all reusable logic lives here
- `notebooks/` — exploration only
- `data/raw/`, `data/processed/` — raw is read-only
- `outputs/` — figures and tables, all generated

## Conventions

IMPORTANT: if a notebook cell gets reused, move it into `src/` and import it.
YOU MUST: type-hint anything in `src/`.
NEVER: commit data files or credentials.

- Set and record a random seed for anything stochastic.
- Paths come from a config module, never hard-coded.

## Verification

`uv run pytest` passes and the pipeline runs end to end from raw data.

## Working with Claude Code

- Explore the relevant files before proposing a change.
- For anything non-trivial, plan first (Shift+Tab into plan mode) and let me review.
- Run the verification command below before telling me something works.
- Keep commits small and conventional (`feat:`, `fix:`, `docs:`, `chore:`).

## Playbooks

- Running a full experiment sweep → read `.claude/playbooks/experiment.md` first
- Pulling from the upstream data source → read `.claude/playbooks/data-access.md` first

The playbooks it expects

The routing table points at files that don't exist yet. Create them as you need them — each one holds a procedure too long to sit in CLAUDE.md and too rare to justify the context cost.

.claude/playbooks/experiment.mdRunning a full experiment sweep
.claude/playbooks/data-access.mdPulling from the upstream data source

Why CLAUDE.md should stay thin →

Other starting points

Next.js + Supabase

App Router, TypeScript, Tailwind and Supabase with row-level security.

R Data Analysis

Tidyverse analysis project with reproducible figures and a clear data pipeline.

Python REST API

FastAPI service with typed schemas, tests and migrations.

CLI Tool

A command-line tool where the interface is the contract.

Monorepo

Several packages in one repository, where knowing the boundaries matters most.

Need something else? Build one from scratch with the generator.