Bioinformatics CLAUDE.md Patterns

A CLAUDE.md file at ~/.claude/CLAUDE.md applies to every project. A CLAUDE.md at the project root applies to that project. The same content patterns work for AGENTS.md (Codex, OpenCode) and GEMINI.md (Gemini CLI), so this page is a useful starting point regardless of which agent you use.

This page shows a complete CLAUDE.md aimed at bioinformatics and data science work, with a short explanation of why each rule is there. The intent is for you to adapt it, not paste it verbatim.

A complete starter file

# Prose Writing Preferences

When writing prose:
- Avoid using hyphens.
- Avoid using em dashes.
- Prefer writing short sentences.
- Avoid parenthetical asides.

# 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 (Product Requirements Document) 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 (compatible with Sphinx/Napoleon).

# Python Environment Rules

- NEVER use `pip install`, `pip3 install`, or `python -m pip install` directly.
- Always use `uv` for Python dependency management.
- When adding dependencies, use `uv add <package>` (updates `pyproject.toml` automatically).
- When running Python scripts, prefer `uv run python ...` to ensure the correct virtual environment.
- Never install packages into the system or global Python environment.
- If a project lacks a `pyproject.toml`, create one with `uv init` before adding dependencies.

# Containers and Environments

- For R projects, always use a container to run the code unless instructed otherwise.
- If a project has a `Dockerfile` or `docker-compose.yml`, use Podman rather than Docker
  (e.g. `podman build`, `podman run`, `podman-compose`).

# Code Execution

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

# ML

- Never apply SMOTE or equivalent oversampling strategies without explicit user approval.
  Raise the tradeoff discussion first. SMOTE has not been shown to be optimal in real-world settings.

# Bioinformatics workflow defaults

- Reference assembly: GRCh38, GENCODE annotation. Confirm version before starting.
- Single-cell: follow the single-cell-best-practices.org workflow rather than bare scanpy.
- Pipelines: prefer nf-core when an nf-core pipeline exists for the task.
- RNA-seq: STAR or HISAT2 for alignment, salmon or kallisto for quantification, DESeq2 for DE.
- Variant calling: GATK best practices for short-variant discovery.
- Survival analysis: lifelines (Python) or survival + ggsurvfit (R).
- For figures: ggplot2 in R, matplotlib or seaborn in Python. Never base R plotting.

# Sudo Rules

- NEVER run `sudo` commands directly. They will fail.
- Always prefer non-sudo alternatives first (user-level installs, `uv`, Podman rootless).
- Only when there is truly no non-sudo alternative, print the `sudo` command for the user to run manually.

# Git Commit Rules

- NEVER mention Claude in commit messages.
- Use Conventional Commits style for all commit messages
  (e.g. `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`).
- Commit changes regularly after each logical unit of work.
- NEVER push hardcoded secrets or API keys. Always read credentials from environment variables.

# Output and File Conventions

- Use snake_case for all output file names.
- Append a timestamp to output file names where relevant
  (e.g. `report_2026_05_04.csv`).

# Session Rules

At the start of each session, ask the user where to save `SESSION_SUMMARY.md`.
Update it regularly throughout the session so that work can be resumed if the session stops.

Why each block is there

The order matters less than the content, but grouping by topic helps you scan it later.

Prose writing preferences

Coding agents tend to write Wikipedia-style prose: long sentences, em dashes for parenthetical thoughts, “moreover” and “furthermore” connectives. This is harder to read in technical documentation than short declarative sentences. Stating the preference once in CLAUDE.md removes a recurring edit.

General behavior

The “ask clarifying questions” rule is the single most useful rule in this file. Without it, agents make assumptions, write code, and present results that drift from what you actually wanted. With it, you get a small Q&A at the start of each task that catches misunderstandings early.

The PRD rule is for non-trivial application work. It forces an explicit alignment step. For a simple bug fix, the agent skips it.

Python environment rules

pip install is the most common way agents pollute a Python environment. The rule prevents this category of mistake at the source. The agent reaches for uv add, which updates pyproject.toml and keeps the environment reproducible.

The “save code in a script” rule prevents the agent from running large analyses with python -c "...", which leaves no record. Every analysis lives in a file you can re-run, version, and review.

Containers and environments

R projects benefit enormously from containers. Bioconductor packages have heavy native dependencies that conflict with system R. A Bioconductor container removes the entire installation problem. The Podman over Docker preference is a Linux user choice; rootless Podman avoids the daemon and the docker group.

ML

This is the rule the user has found most valuable in practice. SMOTE is in every “imbalanced classification” tutorial on the web, so agents reach for it instinctively. The literature shows SMOTE rarely improves real-world classifier calibration, and often makes it worse. Stratified sampling, class weights, threshold tuning, or a different metric are usually better choices. Without an explicit rule, you will re-have this argument every time you work on a classification problem.

Bioinformatics workflow defaults

Three rules in this block punch above their weight:

1. GRCh38 over GRCh37: agents trained on older bioinformatics literature still suggest GRCh37. State the choice explicitly so coordinates and annotations stay consistent across the project.

2. Single-cell-best-practices over bare scanpy: the single-cell-best-practices book by the Theis and Heumos labs is the current consensus reference for scRNA-seq. Bare scanpy tutorials skip QC steps, doublet detection, and ambient RNA correction that the best-practices workflow includes by default.

3. nf-core when available: nf-core pipelines are community-maintained Nextflow pipelines with version pins, container support, and proper test data. Asking the agent to write a custom Nextflow workflow when nf-core/rnaseq exists is wasted effort.

The other defaults (STAR, salmon, GATK, lifelines) are conventional choices that match what the rest of this site recommends.

Git commit rules

Conventional Commits make changelog generation and release tooling much easier. The “never mention Claude in commit messages” rule keeps the project history from being a noisy advertisement.

Output and file conventions

snake_case plus a timestamp produces filenames that sort chronologically and are unambiguous about what they contain. report_2026_05_04.csv is more useful than report.csv six months later.

Session rules

SESSION_SUMMARY.md is a project journal. The agent appends to it as work progresses. When you start a new session a week later, the agent reads the file and picks up where you left off.

Project-level overrides

The global ~/.claude/CLAUDE.md covers your defaults. A project-level CLAUDE.md adds the specifics:

# Project: airway RNA-seq tutorial

## Build and test

- Install: `uv sync`
- Run: `uv run python scripts/run_deseq.py`
- Tests: `uv run pytest`

## Project-specific rules

- Use the airway dataset from the Bioconductor `airway` package.
- DESeq2 LFC shrinkage method: apeglm.
- Significance threshold: padj < 0.05 and |log2FC| > 1.
- All figures saved as PNG, 1600px minimum width, white background.

## Open questions

- Should we include sex covariate? Currently no, all donors are female.
- Stripping ribosomal reads upstream of count matrix? Currently not done.

The project-level file documents decisions you made for this analysis. Six months later, when you or the agent reopen the repo, the rationale is right there.

What to leave out

A few things do not belong in CLAUDE.md:

• Secrets. API keys, tokens, passwords. Use environment variables and a .env file you do not commit.
• Personal email or names. The file is committed; treat it like documentation, not a notebook.
• Long reference material. Move it to a separate file and import with @docs/style-guide.md.
• Information already in code. The agent reads the code; do not duplicate function signatures or module structure.
• Stale rules. Audit CLAUDE.md every few months. Remove rules that no longer apply.

Saving the same config for every agent

The body of the file is portable. Only the filename and location change. The simplest workflow is to keep one canonical copy and symlink the rest, so editing one file updates all four agents at once.

Step 1: save the canonical file

Save your version of the starter file shown above as ~/.claude/CLAUDE.md. Create the directory if it does not exist:

mkdir -p ~/.claude
$EDITOR ~/.claude/CLAUDE.md

Paste the starter content, edit to taste, save.

Step 2: link it from each agent’s expected location

Each agent reads a different filename in a different directory. Symlinks are the cleanest way to share one source of truth:

# Codex CLI reads ~/.codex/AGENTS.md
mkdir -p ~/.codex
ln -sf ~/.claude/CLAUDE.md ~/.codex/AGENTS.md

# OpenCode reads ~/.config/opencode/AGENTS.md
mkdir -p ~/.config/opencode
ln -sf ~/.claude/CLAUDE.md ~/.config/opencode/AGENTS.md

# Gemini CLI reads ~/.gemini/GEMINI.md
mkdir -p ~/.gemini
ln -sf ~/.claude/CLAUDE.md ~/.gemini/GEMINI.md

After this, editing ~/.claude/CLAUDE.md updates the rules for all four agents. Verify the links:

ls -l ~/.codex/AGENTS.md ~/.config/opencode/AGENTS.md ~/.gemini/GEMINI.md

Each line should end with -> /home/<you>/.claude/CLAUDE.md.

Alternative: separate files per agent

If you want different rules per agent, copy instead of symlink:

cp ~/.claude/CLAUDE.md ~/.codex/AGENTS.md
cp ~/.claude/CLAUDE.md ~/.config/opencode/AGENTS.md
cp ~/.claude/CLAUDE.md ~/.gemini/GEMINI.md

Then edit each file to add agent-specific rules. For example, only Gemini benefits from the rule “fall back to Flash when Pro is rate-limited”, because that is Gemini-specific behaviour.

Step 3: tell agents that already accept multiple filenames

OpenCode and Gemini CLI can be configured to read more than one project memory filename. This is useful when a project has a CLAUDE.md already and you want OpenCode or Gemini to pick it up without renaming.

OpenCode falls back to CLAUDE.md when no AGENTS.md exists, no extra config required.

Gemini CLI needs an explicit context.fileName array in ~/.gemini/settings.json:

{
  "context": { "fileName": ["GEMINI.md", "AGENTS.md", "CLAUDE.md"] }
}

Listed in priority order, first found wins per directory.

Project-level overrides

The same pattern works for project-level files. From inside a project directory:

# Author the project file once
$EDITOR CLAUDE.md

# Mirror it to the other agents (project-level paths)
ln -sf CLAUDE.md AGENTS.md      # Codex and OpenCode both read this
ln -sf CLAUDE.md GEMINI.md      # Gemini CLI reads this

Commit CLAUDE.md to git. The other entries are symlinks to it, so a single source-controlled file feeds every agent that runs against the repo.

Summary of paths

Agent	Global path	Project path
Claude Code	~/.claude/CLAUDE.md	<repo>/CLAUDE.md
Codex CLI	~/.codex/AGENTS.md	<repo>/AGENTS.md
OpenCode	~/.config/opencode/AGENTS.md	<repo>/AGENTS.md (falls back to CLAUDE.md)
Gemini CLI	~/.gemini/GEMINI.md	<repo>/GEMINI.md

Each agent loads its file at the start of every session. The cost is one prompt-token expansion per session and the benefit is one less round of “actually we use uv, not pip” per task.

The next page is Common LLM Pitfalls in Data Science, which lists the specific mistakes these rules are designed to prevent.