Chapter 6: Teaching Your AI

A Smart Assistant That Knows Nothing About You

Claude Code is remarkably capable out of the box. It can write Python, debug tracebacks, run shell commands, read files, and reason through complex problems. But the moment you ask it to do something specific to your setup — "launch training on the server" — it freezes. Which server? What's the SSH alias? Where's conda? What GPU is free? It has no idea.

This is the gap between a powerful tool and a useful assistant. A new postdoc who joins your lab is smart, but on day one, they don't know where the data lives, which machines to use, or how your team names experiments. You give them an onboarding document. You walk them through the setup. After a week, they're productive.

Claude Code needs the same onboarding. The difference is: it reads the document once and follows it perfectly, every time, forever. It never forgets. It never drifts. And if you update the document, it adapts immediately.

That document is called CLAUDE.md.

CLAUDE.md: Your AI's Instruction Manual

CLAUDE.md is a Markdown file that Claude Code reads at the start of every conversation. Think of it as a system prompt, but one you write and control. It lives alongside your code, in plain text, versioned in git.

Whatever you put in CLAUDE.md, CC treats as ground truth. If you write "always use tmux for long-running processes," CC will use tmux. If you write "the training data is at /data/imagenet/ on lab-a," CC will look there. If you write "never touch files in /experiments/archived/," CC will stay away.

It's not magic. It's just instructions — read literally, followed precisely.

Where CLAUDE.md Lives

There are two levels, and CC reads both.

Global: ~/.claude/CLAUDE.md

This file applies to every project, every conversation, everywhere on your machine. Put universal truths here: your servers, your preferences, your tools, your conventions. Anything that's true regardless of which project you're working on.

Project: your-project/CLAUDE.md

This file applies only when CC is running inside that directory. Put project-specific context here: dataset locations, current experiment status, training configurations, constraints. When you switch to a different project, CC reads that project's CLAUDE.md instead.

The loading order: CC reads your global CLAUDE.md first, then the project-level one. If they conflict, the project file takes precedence. This means you can set general rules globally and override them per-project when needed.

What to Put in Global CLAUDE.md

Your global file is your universal context. Start with the things you'd tell any new lab member on their first day.

Your Servers

This is the most important section. CC needs to know your machines to do anything useful with them.

# Servers

| Server | SSH | GPUs | VRAM |
|--------|-----|------|------|
| lab-a  | `ssh lab-a` | 4x A100 | 80GB |
| lab-b  | `ssh lab-b` | 8x 4090 | 24GB |
| lab-c  | `ssh lab-c` | 2x H100 | 80GB |

- SSH aliases configured in ~/.ssh/config
- All servers share /data/ for datasets
- Working directory: /home/your-username/research/

With this, CC can SSH into any server by name, knows the GPU topology, and knows where to put files. When you say "check which server has free GPUs," it knows to run ssh lab-a nvidia-smi, ssh lab-b nvidia-smi, and ssh lab-c nvidia-smi, then compare.

Your Preferences

# Preferences

- Communicate in English
- All training runs on remote servers, never locally
- Use tmux for all long-running processes
- Check GPU availability with nvidia-smi before starting any training
- Commit messages in conventional format (feat:, fix:, etc.)

These sound obvious, but without them, CC might try to run python train.py on your laptop. Or launch a training run without checking if GPUs are free. Or write commit messages in a style you don't like. Explicit is better than implicit.

Your Tools

# Tools

- Conda for environment management
- WandB for experiment tracking (always online, never offline mode)
- Git for version control
- rsync for code sync to servers

Your Conventions

# Conventions

- Always sync code before running on server:
  rsync -avz --delete ~/research/project/ lab-a:/home/your-username/research/project/
- Activate conda env before any Python command
- Never install packages globally on servers

A Complete Global Example

Here's what a minimal but functional global CLAUDE.md looks like:

# Servers

| Server | SSH | GPUs | VRAM |
|--------|-----|------|------|
| lab-a  | `ssh lab-a` | 4x A100 | 80GB |
| lab-b  | `ssh lab-b` | 8x 4090 | 24GB |

- Working directory: /home/your-username/research/
- Datasets: /data/ (shared across servers)

# Rules

- All training on remote servers, never locally
- Use tmux for all long-running processes
- Check GPU availability before starting training
- WandB for all experiment tracking (always online mode)
- Sync code with rsync before running on server
- Activate conda env before any Python command

# Preferences

- Communicate in English
- Conventional commit messages

That's 20 lines. It takes five minutes to write. And it transforms CC from "a smart tool that doesn't know your setup" into "an assistant that can autonomously SSH into your servers, check GPUs, activate the right environment, and launch training."

What to Put in Project CLAUDE.md

Your project file is where specificity lives. This is the context that changes between experiments.

Dataset Locations

## Datasets

- Training: /data/imagenet/train/ on lab-a
- Validation: /data/imagenet/val/ on lab-a
- Test (OOD): /data/imagenet-r/ on lab-a

CC now knows exactly where to point the data loaders. No guessing, no asking.

Environment Details

## Environment

- Conda env: `pytorch21` on lab-a
- Activation: `conda activate pytorch21`
- Key packages: torch 2.1, transformers 4.36, wandb

Current Status

This is one of the most powerful sections. It tells CC — and future-you — what's happening right now.

## Current Status

- Baseline ResNet50 trained, val acc = 76.2% (paper reports 76.5%)
- Now working on: LoRA fine-tuning experiment
- Next: Run LoRA on lab-b with learning rates [1e-4, 5e-4, 1e-3]

When you start a new conversation tomorrow morning, CC reads this and immediately knows where you left off. No "what were we doing?" No scrolling through chat history. It picks up exactly where you stopped.

Constraints

## Rules

- Always log to WandB, project name: "image-cls"
- Use batch size 64 for A100, 32 for 4090 (memory constraint)
- Don't modify files in experiments/archived/
- Hyperparameters: lr=1e-4, weight_decay=0.01, warmup_steps=500

Constraints prevent mistakes. Without the batch size rule, CC might use 64 on a 4090 and hit OOM. Without the archival rule, CC might "clean up" old experiment files that you need for the paper.

A Complete Project Example

# Project: Domain Generalization

## Datasets
- Source domains: /data/domainbed/PACS/{art,cartoon,sketch}/ on lab-a
- Target domain: /data/domainbed/PACS/photo/ on lab-a

## Environment
- Conda: `dgenv` on lab-a
- Key deps: torch 2.1, timm 0.9, wilds

## Current Status
stage: training
baseline: ERM on PACS, acc=85.3% (paper: 85.5%)
running: SWAD training on lab-a, GPU 0-3, tmux=pacs-swad
next: Evaluate on remaining datasets (VLCS, OfficeHome)

## Rules
- WandB project: "domain-gen"
- Always train with 3 seeds: [0, 1, 2]
- Use DomainBed's default hyperparameters unless explicitly overriding
- Don't change the data split — use official DomainBed splits only

The Power of Good Instructions

The difference between vague and precise instructions is the difference between an assistant that asks questions and one that acts.

Vague:

I have some servers with GPUs. Use them for training.

CC reads this and knows almost nothing. Which servers? How to connect? How many GPUs? Where are the files? It will have to ask you every time. You'll spend half your conversation answering questions that should have been answered once.

Precise:

| Server | SSH | GPUs | VRAM |
|--------|-----|------|------|
| lab-a  | `ssh lab-a` | 4x A100 | 80GB |

Working directory: /home/your-username/research/
Conda env: pytorch21
Datasets: /data/imagenet/

CC reads this and can independently: SSH into lab-a, check GPU availability, activate pytorch21, find the data, and launch training. No questions asked. You type "train the model" and CC does the rest.

Here's a real interaction that shows the difference. Without good instructions:

You: Train the ResNet on ImageNet.

CC: I'd be happy to help. Which server should I use? What's the SSH command? Where is the ImageNet dataset stored? Which conda environment has the dependencies?

Four questions before anything happens. With good instructions:

You: Train the ResNet on ImageNet.

CC: Let me check GPU availability on lab-a... GPU 0 and 1 are free. I'll SSH in, activate pytorch21, and start training with the data at /data/imagenet/. Using tmux session "resnet-train" and logging to WandB.

Same request. Zero questions. The only difference is twenty lines of Markdown.

The rule of thumb: if CC has to ask you a question, the answer belongs in CLAUDE.md. Every question CC asks is a signal that your instructions are missing something. Treat questions as bugs in your documentation.

Iterating on CLAUDE.md

You don't write the perfect CLAUDE.md on day one. You iterate.

Start simple. Your first version might be just your server table and three rules. That's fine. Use CC for a day.

Watch for repeated questions. Every time CC asks "which conda environment should I use?" or "where is the training data?" — that's a missing instruction. Add it.

Watch for repeated mistakes. If CC keeps trying to run training locally, add a rule: "All training on remote servers." If it keeps using the wrong batch size, add the memory constraints.

Watch for implicit knowledge. Things you take for granted — "obviously we use WandB," "obviously we sync code before running" — are not obvious to CC. Make the implicit explicit.

After a week, your CLAUDE.md will be much richer than the one you started with. After a month, it will be a comprehensive onboarding document that captures how you actually work. This is valuable even beyond CC — it's documentation of your research workflow that a new lab member could read.

Version control it. Your global CLAUDE.md evolves with your infrastructure. Your project CLAUDE.md evolves with the project. Commit both to git. When you look back at your project history, the CLAUDE.md changes tell the story of what happened and why.

When CLAUDE.md Isn't Working

Sometimes you write instructions and CC still does the wrong thing. Common causes:

Ambiguity. You wrote "use the big server" but you have two servers that could be "big." Be specific: use names, paths, numbers.

Contradictions. Your global file says "always use tmux" but your project file says "run training in the foreground for debugging." CC sees both and has to guess which one applies. If you need a project-level exception, state it explicitly: "For this project, run initial training in foreground (overrides global tmux rule) until the first run succeeds, then switch to tmux."

Stale information. Your CLAUDE.md says the baseline is at 76.2% but you've since trained a better model at 78.1%. CC will reference the old number. Keep the status section current — update it when things change, not "sometime later."

Too much information. A CLAUDE.md that's 500 lines long is counterproductive. CC reads it all, but the signal gets diluted by noise. Keep it focused. If a piece of information is only relevant once, put it in the conversation, not the file. CLAUDE.md is for recurring context.

Common Patterns

Here are patterns that researchers find useful:

The "Don't" List. Things CC should never do, no matter what.

## Never
- Never run training on the local machine
- Never delete checkpoint files without asking
- Never push to the main branch directly
- Never install packages with pip outside conda

The Status Dashboard. A section you update at the end of each work session.

## Pipeline Status
stage: training
idea: "Contrastive domain alignment with adaptive mixing"
running: lab-a GPU 0-3, tmux=train01
next: Evaluate on OfficeHome after training completes

The Checklist. Steps CC must follow before launching any experiment.

## Pre-Training Checklist
1. Check GPU availability on target server
2. Sync latest code with rsync
3. Activate correct conda environment
4. Verify dataset paths exist
5. Confirm WandB is set to online mode
6. Run smoke test (1 batch) before full training

The Recovery Context. Information CC needs when continuing from a previous session.

## If Resuming
- Last session ended during hyperparameter sweep
- Results so far: lr=1e-4 acc=82.1%, lr=5e-4 acc=83.7%
- Still need to run: lr=1e-3, lr=5e-3
- All runs on lab-a, tmux sessions: sweep-01 through sweep-04

One File, Compounding Returns

Here's what happens over time.

Week 1: Your CLAUDE.md has servers, conda envs, and basic rules. CC can SSH in and run commands without asking where things are.

Week 2: You've added dataset paths, WandB conventions, and code sync commands. CC can launch training end-to-end with one instruction.

Week 4: You've added project status, pre-flight checklists, and recovery context. CC picks up where you left off across sessions, follows your conventions, and catches its own mistakes before making them.

Month 2: Your CLAUDE.md is a living document that captures your entire research workflow. CC operates autonomously — launching experiments, monitoring training, fixing crashes — because it knows your infrastructure as well as you do. Better, in some ways, because it never forgets a rule.

The compound effect is real. Every line you add to CLAUDE.md saves you from repeating that instruction in every future conversation. Over hundreds of conversations, those saved minutes add up to days.

---

Checkpoint

Write a CLAUDE.md that describes your servers. Include SSH aliases, GPU counts, and VRAM. Put it at ~/.claude/CLAUDE.md. Start a new Claude Code conversation. Ask: "Which server should I use for training right now?"

If CC SSHes into your servers, runs nvidia-smi on each, and gives you a recommendation based on available GPUs — you've successfully taught your AI about your infrastructure. It took twenty lines of Markdown.