Chapter 22: Ten Things to Put in Your CLAUDE.md Today

Your CLAUDE.md is the instruction file that Claude reads at the start of every session in a project. It tells Claude your stack, your test command, your rules, and your particular preferences. Think of it as the orientation packet you’d give a new resident on day one — except this resident never forgets it and never sleeps.

It is the single highest-payoff file in any Claude Code project. The ten lines below are the ones that earn their keep at a cancer center.

Apply the litmus test to every line: “Would Claude make a real mistake without this?” If your project doesn’t need it, skip it. For clinical AI work at KHCC, the answer is “yes” more often than not.

1. Your stack, in one sentence

Stack: PySpark on Databricks (Unity Catalog `aidi_catalog`), PydanticAI for
structured extraction, Azure OpenAI `gpt-4.1-mini`, R + tidymodels for analysis,
Django + Postgres for dashboards.

Why it matters in clinical AI work. Without this line, Claude guesses your tools every time you ask for code. With it, every code suggestion lands in the right place on the first try. Databricks is the cloud data platform; Unity Catalog is its permissions system; PydanticAI is the Python library that forces LLM output into a known shape; tidymodels is the modern R framework for statistical modeling. See Chapter 0.5 for the full tour.

2. The test command

Tests: `pytest tests/ -q`. Eval suite: `python aidi/eval/run_deceased_cohort.py`.
Never claim "done" without one of these passing.

Why it matters in clinical AI work. Tests are how Claude can work autonomously without you watching every keystroke. If Claude doesn’t know how to run them, it can’t close the loop on its own work. The eval suite runs against the deceased-patient cohort — see line 3 and line 7 below.

3. The PHI rule

PHI: Never log MRNs or names in plaintext. MRNs are Optimus-encoded,
names are Fernet-encrypted. Outputs to email/dashboards use encoded MRNs only.
Eval cohorts use the frozen deceased-patient set; never include living patients.

Why it matters in clinical AI work. PHI = Protected Health Information — anything that identifies a patient (name, MRN, date of birth, diagnoses linked to an identity). Hospital data-protection rules and most countries’ laws forbid this from leaving controlled systems in readable form. Fernet is a symmetric encryption scheme used at the AI Office to encrypt patient names at rest (encrypted text in, encrypted text out, unreadable in between). Optimus encoding is a reversible scrambling of MRNs into identifiers that look like A8X4-92 — humans cannot read them, but the system can decode them when needed. The deceased-patient eval cohort is a frozen list of ~1,000 patients who have died, with hand-curated ground truth, used to evaluate every prompt change. The patients are deceased so the data never drifts and there is no risk of AI predictions leaking back into a living patient’s care.

This line alone justifies every minute you’ll spend on your CLAUDE.md.

⚠️ Warning. Pair this rule with a PreToolUse hook that blocks any Bash command whose text looks like a raw MRN. Belt and suspenders.

4. The simplicity rule

Simplicity: minimum code that solves the problem. No CLI flags, config files,
or parameterization "in case." If a senior engineer would say it's
overcomplicated, simplify.

Why it matters in clinical AI work. Claude defaults to over-engineering. It will add command-line flags, configuration files, and abstraction layers nobody asked for. Anthropic’s own Data Science team uses the explicit prompt “Why are you doing this? Try something simpler” as their override. Codify it in your CLAUDE.md and you won’t have to say it twice a day.

5. The surgical-changes rule

Surgical changes: touch only what is needed. Don't refactor adjacent code,
comments, or formatting. Don't rename existing columns in extraction tables;
downstream R and dashboard code depend on them. Add new columns; don't reorder.

Why it matters in clinical AI work. Many AI Office pipelines have years of downstream R analyses, Django dashboards, and Power BI reports that depend on specific column names in specific positions. A “helpful” rename ripples into ten silent breakages. This line prevents Claude from “improving” code you didn’t ask it to improve.

6. The fail-loud rule

Fail loud. "Pipeline completed" is wrong if any rows were skipped silently.
"Eval passed" is wrong if any cases were skipped. Always surface skipped rows,
null fields, parse failures, partial successes.

Why it matters in clinical AI work. Silent failures are the most dangerous failure mode in clinical pipelines. A patient missing from the AKI alert run because of an SQL join error is worse than the pipeline crashing — at least a crash gets investigated. A silent skip just produces a slightly wrong list that nobody questions. This rule makes “almost worked” surface as loudly as “didn’t work.”

7. The eval gate

Verification gate: no prompt or extraction logic change ships without an eval
run against the frozen deceased-patient cohort. The eval is the test.

Why it matters in clinical AI work. Prompt regressions are insidious — a one-word change in a system prompt can drop F1 score from 0.91 to 0.83 on a specific field, and you will not notice from spot-checks. The eval against the deceased-patient cohort is the binary gate that says “this change ships” or “this change reverts.” Without this line in CLAUDE.md, Claude will sometimes try to ship a “small prompt improvement” without running the eval.

8. Tool-calling quirks

Tool calls: run `pytest`, not `python -m pytest`. Don't `cd` unnecessarily;
use the full path. Prefer the `gh` CLI over the GitHub MCP server (more
context-efficient). Don't skip pre-commit hooks.

Why it matters in clinical AI work. These look petty in isolation. They are the difference between a smooth session and a chaotic one. Anthropic’s RL Engineering team has the exact pytest rule written in their own CLAUDE.md because the alternative invocation occasionally fails in subtle ways on their setup. Your project will have its own three or four quirks. Write them down here.

9. The token-budget rule

Token budget per task: 4,000. Per session: 30,000. If approaching, summarize
and start fresh; don't push through. Log token usage per call in extraction
loops; fail loud when an outlier note blows the budget.

Why it matters in clinical AI work. A single 50-page discharge summary fed into a pathology extractor can silently consume your daily token quota. PydanticAI extraction loops over thousands of notes need a per-call ceiling and a fail-loud rule when an outlier hits it. Without a budget, the team’s overall API spend creeps up by a factor of three before anyone notices.

10. Read-before-write

Before adding to a file: read the file's exports, the immediate caller, and
shared utilities. Before adding a column to an extraction table, check what
currently consumes it. "Looks orthogonal to me" is the most dangerous phrase
in this codebase.

Why it matters in clinical AI work. Mature pipelines have non-obvious dependencies. The pathology extractor’s output is read by the registry, the chemo-protocol assigner, and three separate research analyses. “Adding a small new column” can break the schema check in one of them. This rule forces Claude to look before it leaps. It prevents 90% of regressions in mature pipelines.

The starter CLAUDE.md, in full

Copy this into any new KHCC project and tune from there:

# CLAUDE.md

## Stack
PySpark + Databricks (`aidi_catalog`), PydanticAI for extraction,
Azure OpenAI `gpt-4.1-mini`, R + tidymodels for analysis,
Django + Postgres for apps.

## Run / test
- Tests: `pytest tests/ -q`
- Eval: `python aidi/eval/run_deceased_cohort.py`
- Lint: `pre-commit run --all-files`

## Behavior rules
1. Think before coding: verify schemas/codes against actual tables; don't guess.
2. Simplicity first: minimum code that solves the problem.
3. Surgical changes: don't touch adjacent code.
4. Goal-driven: define success criteria, loop until verified.
5. LLM only for judgment: KDIGO staging is rules — compute it, don't ask the model.
6. Token budgets: 4k per task, 30k per session.
7. Surface conflicts: don't blend contradictory patterns.
8. Read before write.
9. Tests encode intent: eval cases test clinical meaning, not just data type.
10. Checkpoint after every significant step.
11. Match codebase conventions even if you disagree.
12. Fail loud: surface every skipped row, null, partial success.

## PHI rules
- MRNs: Optimus-encoded only in any output.
- Names: Fernet-encrypted at rest, never in logs.
- Eval cohort: frozen deceased-patient set only.

## Tool quirks
- `pytest`, not `python -m pytest`
- `gh` CLI > GitHub MCP server
- Don't skip pre-commit hooks

Sixty lines. Well under the 150–200-line budget from Chapter 10, past which Claude starts following individual rules less reliably. Every line earns its place.

Try This

Open whichever project you’re working on right now. Copy the starter CLAUDE.md above into the root of the project. Then spend 15 minutes adapting each line to your actual situation — delete what doesn’t apply, and add three project-specific quirks you’ve already noticed Claude getting wrong. (Examples from past sessions: “always pass na.rm = TRUE to summary functions in R,” “tibble dates must be lubridate::ymd-parsed,” “Wilms cohort patients are <21 years old, not <18.”)

Watch Out

CLAUDE.md is a living file, not a one-time artifact. Anthropic’s Data Infrastructure team ends every working session by asking Claude itself to summarize what was learned and suggest improvements to CLAUDE.md. That feedback loop is what turns a starter file into a good file over six months. Do it. The hour you spend tuning CLAUDE.md this quarter saves you twenty hours next quarter.