How I use Claude Code and Claude Science

1. The global instruction file

CLAUDE.md is read at the start of every session, in every project. It contains no project knowledge. It holds the standing constraints that do not vary: the languages, the environment discipline, and the operations that are not permitted. A session therefore starts with those constraints in force rather than requiring them to be restated.

# General Behavior
- Always ask clarifying questions before starting a task. Do not make assumptions and proceed.
- When the task involves building an application, create a PRD together with the user before writing any code.

# Programming Language Preferences
- Preferred languages: Python, R, Rust.
- For Python, use Google-style docstrings for all functions and classes.

# Python Environment Rules
- NEVER use `pip install` directly. Always use `uv` for Python dependency management.
- When running Python scripts, prefer `uv run python ...` to ensure the correct virtual environment.
- Never install packages into the system or global Python environment.

# Containers & Environments
- For R projects, always use a container to run the code unless instructed otherwise.
- If a project has a `Dockerfile`, use Podman rather than Docker.

# Code Execution
- Save code in a script before running it. Do not run inline code snippets.

# ML
- Never apply SMOTE or equivalent oversampling without explicit user approval. Raise the tradeoff first.

# Git Commit Rules
- Use Conventional Commits. Commit after each logical unit of work.
- NEVER push hardcoded secrets or API keys. Read credentials from environment variables.

Two of these constraints were load-bearing on this project. Always ask clarifying questions prevents an agent selecting a method where the correct action is to ask which method is wanted. For R, use a container is why the doublet-detection step runs in a pinned Bioconductor image rather than against an ambient R installation, which is a precondition for the step to be reproducible.

2. The session summary

One file per project, at the repository root. It is the working memory: what the method is, what has been learned, and what has already been done. Claude Code reads it at the start of a session and maintains part of it as it works. The whole design is in who is allowed to edit which section.

# SESSION SUMMARY

## How to maintain this file   the contract. Read at the start of a session.
## Rules                        how we work. The HUMAN curates. The LLM may propose, never edit.
## Insights                     lessons learned, not facts. The HUMAN curates.
## Logs                         append-only, LLM-maintained. One dated block per session.
                                Dead ends prefixed DEAD END: so no session pays for them twice.

Session discipline: at the start, read Rules then Insights. During, commit each logical
unit and append its Logs line immediately. At the end, leave the tree clean.

Rules and Insights are curated by me. The assistant may propose a change but is not permitted to add, reword, or delete one, since an agent that can edit the rules it is evaluated against is evaluating itself. Logs are maintained by the assistant, append-only, and written as the work proceeds rather than reconstructed afterwards, so an interrupted session still leaves a record. Dead ends are logged under a separate prefix so that a discarded approach is not attempted twice.

The Rules are the method. They are pinned across sessions and applied by default:

## Rules   (pinned; the human curates)

#1   Scientific accuracy first, above demo appeal. A correct understated result beats a
     compelling overstated one. When a claim is refuted, retract it across every surface.
#2   The human sets strategy and framing; the LLM executes, verifies, and reports faithfully.
#3   Reproducibility is non-negotiable. All code runs in a controlled environment: a uv venv,
     a Podman container, or an nf-core pipeline. Never a system interpreter.
#5   This file is public. Never put secrets in it.
#6   Work like a scientist: literature, implement, critically review, report.
#7   Assert nothing you have not checked against a control that could fail.
#8   Score per patient, then summarize. Never pool cells. Any pooled score is a bug.
#9   Positivity is not `count > 0`. A scRNA zero is not proof of absence.
#10  Scripts write the committed tables; the report only reads and draws them.
#12  Claim discipline. Own the benchmark recovery as a trust signal, not a discovery.
#13  The positive-control gate is sacred. If PSMA-PSCA does not recover, the scoring is
     wrong and no nomination is trustworthy.
#15  Claude Code orchestrates, Claude Science verifies. Log every handoff, including
     disagreements. An empty disagreements column is a weak submission.
#16  Commit during the work, one logical unit per commit. Append one Logs line after each.

Each of these is visible in the artefacts. Rule 8 is why the explorer shows the pooled fraction and the per-patient median side by side, and why they differ. Rule 10 is why every figure regenerates from a committed table rather than being a saved image. Rule 13 is why the benchmark appears before the nomination. Rule 15 is why the tooling log has a disagreements column.

3. The tooling log

docs/claude_tooling_log.md is a dated table, one row per meaningful handoff: what was asked, what came back, and what changed as a result. The last column is the one that matters. A handoff that changed nothing is noise; a handoff that changed the analysis is evidence.

The log records the cases where a tool was wrong and where I overruled it, because a tool that is only ever agreed with has not been tested. Entries on this project include a database rejected as unreliable for a specific set of genes, an environment claim from a research agent contradicted by the dependency resolver, and a metric I corrected myself because it would have passed a marker expressed across all prostate cells, malignant and benign alike. The log is where the work was adjudicated, and by whom.

4. How the Claude Science tasks are organised

Claude Science is a browser workbench with literature access and data connectors. It reaches GTEx, the Human Protein Atlas, and the trials registry, none of which the pipeline touches. I use it for the evidence that is not in a count matrix. The organisation is the part worth copying:

claude_life_science/
  tasks/     cs01 ... cs10   the prompt, committed BEFORE the run
  outputs/   cs03, cs08      the answer, its backing tables, and its DOIs
  scripts/   cs03, cs08      the workbench kernel code, reconstructed

CS01  Methods for AND-gate dual-marker discovery
CS02  Methods for NOT-gate / inhibitory-logic targets
CS03  Approved and clinical dual-target / logic-gated prostate therapies
CS04  Clinically validated single prostate surface antigens and their binders
CS05  Key single-cell prostate cancer datasets
CS06  Key proteomics / surface-proteomics datasets
CS07  Antigen expression shifts in mCRPC and neuroendocrine disease
CS08  Normal-tissue expression liabilities of the candidate antigens
CS09  Statistical best practices for single-cell target ranking
CS10  Adversarial review of the report

Three rules govern it, and they exist to stop a fluent answer becoming a finding.

1. The prompt is committed before the run. The task file enters git before the workbench session. The question is therefore on the record and cannot be revised after the answer is known.
2. The answer ships with its sources. Each committed output carries a literature_refs.csv mapping every claim to a DOI, so a reader can check it without asking me.
3. A workbench answer is a lead, not a result. The directory's own README says it: these are literature syntheses, nothing regenerates them, and they are not inputs to any committed analysis. A claim enters the report only after it has been checked against the cited primary source.

Only the report-usable subset is committed. Two were: the clinical dual-target landscape, which is the evidence behind the report's refusal to claim the target pair as novel, and the normal-tissue liability review, which brought protein-level facts the single-cell data cannot contain, including membrane polarity and antibody-assay false negatives. The rest stayed local by the same policy.

5. What I use each one for

They fail in opposite directions, which is the reason to run both.

The full handoff record, including the rows where a tool was overruled, is in docs/claude_tooling_log.md. The session summary, the rules, and the Claude Science task files are all in the science repository, which is public. The report is where the claims live.