AI Tools & Claude

§1 How to think about AI tools

Before AI, working with computers required learning to write in specific formal languages: R, Python, bash. The human had to translate their intent into syntax the machine could execute. AI has changed this interface. You can now describe what you want in plain language, and an AI model will produce, edit, test, and in some cases run the corresponding code. The computation still happens on your hardware; the translation layer has simply become conversational.

This is a meaningful shift. It lowers the barrier to producing complex code and makes certain tasks far faster. It also carries a real risk: if you rely on AI to write all your code, you may stop learning to read and write it yourself. This is a personal choice, and the tradeoffs are yours to navigate. But you should navigate them consciously. There will be moments — debugging a subtle error, evaluating whether an AI-generated function is actually doing what you think it is, reading someone else's code — where the absence of a working mental model of the language will handicap you. Recognize those moments when they arrive, and decide how much de-skilling you are willing to accept.

AI is a tool. Like any tool, its value depends entirely on how clearly you understand what you are trying to do before you pick it up.

§2 What AI is not for

Nobody can outsource thinking.

Reading and writing scientific papers is something this lab reserves for human beings. Reading and writing are forms of thinking. If you outsource them to AI, you will make yourself ignorant — and you will not know it until you have missed many opportunities. Nobody can save you from this choice.

Understanding your own data is not something AI can do for you. If you cannot describe your data structure clearly and specifically, you do not yet understand it. The work of understanding comes before you involve AI in any analysis. A capable AI given a problem it has not been set up to understand will produce confident, fluent, plausible-sounding output that may be entirely wrong. If neither you nor the AI understand the problem, you will spend time and money producing copious output that is not useful.

The thinking comes before the prompt.

§3 Starting a Claude session for lab work

The most effective Claude sessions begin with context, not commands. Before asking Claude to do anything, tell it what it needs to know. For code work in a repository, this means working within a local clone of your personal fork and providing Claude with the following at the start of the session:

• The goals of the project: what the repository is trying to accomplish scientifically
• Open questions: what is unresolved or actively being worked on
• The current task: specifically what you want to accomplish in this session
• Stylistic preferences: professional R code, well-annotated scripts and functions, Roxygen documentation for any functions written, a demo script for every new function showing how to use it

If a CLAUDE.md file exists in the repository root, load it as context at the start of the session. It should contain most of this information already. See §4 for how to write and maintain one.

Claude is currently more capable than other available AI tools at software development tasks, and is the recommended tool for code work in this lab.

§4 CLAUDE.md files

Every Raredon Lab repository should contain a CLAUDE.md file in the root directory. This file is the primary mechanism for giving Claude persistent, project-specific context across sessions and across lab members.

When different lab members each work with Claude from their own personal fork, their Claude sessions will naturally develop slightly different understandings of the project. A shared CLAUDE.md in the origin repository counteracts this: it tells every team member's Claude the same things about the project's structure, goals, conventions, and current state, so that different forks and different users can work with a consistent AI collaborator.

What belongs in a CLAUDE.md

Keep the file focused. Claude can only reliably follow a limited number of instructions at once, and a CLAUDE.md that tries to specify everything will be partially ignored. Prioritize information Claude cannot infer from reading the code itself.

# CLAUDE.md — LungAtlas

## What this repo does
Single-cell and spatial transcriptomics analysis of rat lung
fibrosis models. Primary data: Xenium spatial data (n=12 samples)
and matched scRNAseq. All large objects live on the lab HPC at:
/hpc/raredon/data/lungAtlas/

## Directory structure
functions/   — shared helper functions (Roxygen documented)
scripts/     — numbered analysis scripts
markdowns/   — Rmd vignettes
docs/        — knit HTML outputs (committed to Git)

## Coding conventions
- R throughout; follow Raredon Lab coding standards (Document 04)
- File naming: NN_YYYYMMDD_AB_descriptive-name.ext
- Every function in functions/ must have a demo script in scripts/
- No hardcoded paths; declare all paths at script top

## Current state (update when things change)
- QC and clustering complete for cohort 1 (n=6)
- Cohort 2 preprocessing in progress (AB, branch: dev)
- Spatial niche analysis: not yet started

## Open questions
- Optimal resolution parameter for Leiden clustering
- Whether to merge cohorts before or after cell type annotation

§5 Claude Skills files

Claude Skills are a newer feature that allows you to package a specific workflow, set of instructions, or domain knowledge into a reusable file that Claude can load on demand. Where CLAUDE.md provides project-level context, a Skill encapsulates a repeatable task or methodology that can be applied across many projects.

Skills are defined by a SKILL.md file with a YAML frontmatter header. Claude reads the file when a relevant task is requested and follows its instructions. Skills can be stored in a project's .claude/skills/ directory or at the user level (~/.claude/skills/) to make them available across all sessions.

Skill file structure

---
name: raredon-r-function
description: Write a documented R helper function following Raredon Lab
  standards. Use when writing or refactoring a function for the
  functions/ directory.
---

# Raredon Lab R Function Standard

Write the function with the following structure:
1. Roxygen header (@param, @return, @export, @examples)
2. snake_case function and argument names
3. Sensible defaults for all numeric and string arguments
4. Explicit return() statement
5. A companion demo script named demo_[function_name].R

Style: clear inline comments on non-obvious steps; no hardcoded values.

Sharing skills across the lab

Skills stored in a repository's .claude/skills/ directory are committed to Git and shared with everyone who forks the repo. This is one practical path toward a common AI working standard across lab members: if the origin repository contains a set of agreed-upon Skills, every lab member's Claude — working from their personal fork — has access to the same workflow templates.

Anthropic maintains a public repository of Skills at github.com/anthropics/skills, which can serve as a reference and source of inspiration for building lab-specific ones.

§6 Prompting effectively

Think before prompting

The quality of the output you get from Claude is directly proportional to the clarity of your own thinking going in. If you cannot describe your data structure, your goal, and the specific form you want the output to take, Claude cannot produce something useful. Before you type a prompt, spend time with the problem. If the description comes easily, you are ready. If it does not, you need to think more first.

AI is like a capable colleague who does not know your project. If you do not brief that colleague thoroughly, neither of you will understand the problem, and the resulting work will reflect that.

Write long, specific prompts

Vague prompts produce vague results. A good prompt for a complex task should include: the scientific context, the specific goal, the data structure involved (described in your own words), any constraints or preferences, and the exact form you want the output to take. Longer prompts that specify everything precisely outperform short prompts followed by many rounds of correction.

Describe your data structure — do not upload your data

Never upload raw lab data to a chat-based AI interface. Describe it instead. This practice has three benefits: it protects the lab's intellectual property; it reduces your token usage; and — most importantly — it protects your own learning. If you can describe your data structure clearly and specifically, you understand it. If you cannot, you have more work to do before involving AI. Describe the structure, the column names, the data types, the object class, and the relationships between objects. Send screenshots of outputs if visual reference helps. The AI can then produce tools for you to apply to your data locally.

Iterate deliberately

The best output usually comes from a sustained back-and-forth over time, not a single prompt. Give Claude time to produce something, then read it carefully. Evaluate it against what you actually wanted. Revise your instructions and go again. Save outputs as versioned files as you iterate. Take breaks and return with fresh eyes. Claude will suggest things, produce alternatives, and introduce ideas — some good, some not suited to your specific problem. You are the one who knows the project. Maintain control of the direction.

Do not let the AI take you for a walk. It will try to do whatever you prompt it to do, and it will do so with apparent confidence. Many of its ideas will be poorly suited to your specific situation. A senior lab member is a better guide when you are unsure how to steer a complex AI-assisted workflow.

Requesting literature reviews

When asking Claude to find papers or conduct a literature review, require that every result be reported in a table with: title, authors, year, journal, PMID or DOI, a working URL, and a brief description of relevance. It is your responsibility to verify that every citation exists, that the URL works, and that the paper says what Claude claims it says. Verify before you cite anything.

Tasks AI handles well

AI excels at highly technical, well-defined tasks that can be verified. Identifying tasks in this category and prompting AI to execute them is an effective use of the tool. Good examples include: writing boilerplate code and package infrastructure, implementing complex transformations you can describe but not easily code yourself, writing test suites, building documentation, and reorganizing spreadsheets according to specified rules. Ask AI to do something, then verify the output works as intended.

§7 Knowing AI's limits

Hallucination is by design

AI language models produce fluent, confident output by predicting what text should come next. They do not look things up; they generate. This means they will state false things with complete apparent confidence. You cannot prompt a model to stop hallucinating. The way to work around this is to structure your prompts so that outputs can be independently verified.

Code that runs and produces the right output can be verified. Citations with PMIDs and DOIs can be looked up. Table transformations can be spot-checked against the input. Prioritize tasks where the output is testable. For tasks where it is not — summarizing a paper, explaining a concept — treat the output as a useful starting point to evaluate, not a reliable source to trust.

A practical test

Before relying on any AI output, ask: could this be wrong in a way I would not detect? If yes, build in a verification step. If no — because the output is executable, searchable, or checkable against known data — proceed with appropriate confidence.

§8 Citation integrity

AI systems routinely invent citations. They produce author names, titles, journal names, and year of publication that look entirely plausible and do not correspond to any real paper. This is not a bug to be worked around — it is a fundamental property of how these systems generate text. Treat every AI-generated citation as unverified until you have confirmed it yourself.

On provenance and credit

AI systems learn from an enormous corpus of scientific text and cannot trace the specific sources that inform their outputs. When AI gives you an idea, a method, or a framing, that knowledge originally came from someone. Make a habit of asking Claude to explain how it knows what it knows, and to conduct a literature review with verifiable identifiers so that you can find and credit the original authors. AI is eroding scientific provenance. Active effort to credit original authors where possible is both an ethical obligation and a scientific norm worth protecting.

§9 Attribution standards

When AI tools contribute substantially to work in this lab, that contribution should be documented. The standard for each context:

§10 Yale policies

Yale's Office of the Provost has issued guidelines for the use of generative AI tools that apply to all research and academic work at Yale. The key points relevant to lab members:

• Do not enter confidential or restricted data into AI tools. Yale's data classification policy identifies moderate- and high-risk data categories that must not be shared with external AI systems. When in doubt, treat data as restricted.
• Assume all information shared will become public. Do not share anything with an AI interface that you would not be comfortable making public. Information entered into AI tools may be retained and used in ways outside your control.
• Follow academic integrity guidelines. Unacknowledged AI-generated content constitutes academic dishonesty under Yale policy. Any AI-generated material used in submitted work must be cited or disclosed appropriately.

The full Yale Provost guidelines are available at provost.yale.edu. Individual journals and funding agencies also maintain their own AI disclosure requirements; check these before submitting any manuscript or grant application.

§11 A note on opting out

You do not have to use AI tools to do good work in this lab. If you prefer to work without them, let the PI know. That preference will be respected. What matters is that the work is rigorous, reproducible, and well-documented — the tools used to produce it are secondary.

This document will be updated as the technology and the lab's practices evolve. It is one of the most rapidly changing areas of computational science at the moment, and the guidance here reflects current understanding, not permanent policy.