Models scored between 90–99% on standalone evaluations for identifying relevant conditions. Real-world users with access to the same models hit 34.5%.

This exposes that this is a fundamentally different task.

The middle ground makes the story richer: models mentioned relevant conditions in 65–73% of the conversations—already a step down from benchmark performance—but users then failed to recognize or retain those conditions in their final answers. So the information was often there (though not 90-99% of the time), just not transferred.

I keep thinking about the methodology. Standalone benchmarks feed models a full clinical vignette and ask for an answer. A back-and-forth dialogue is structurally different—it distributes information across turns, requires active synthesis, and introduces retrieval demands on the human side. We already know LLMs perform better with complete context windows. This paper operationalizes that it matters in practice.

Two questions this raises for me:

Do we need benchmarks that account for the human-in-the-loop performance hit? Frontier capability clearly doesn’t translate automatically to clinical utility, and the gap here is large enough that it should change how we think about deployment readiness.

What does this mean for clinical AI interfaces? If users are missing conditions that models mention, the bottleneck isn’t the model. Is it the interaction design, the information architecture, or what we’re asking users to do with AI-generated output?

Worth reading if you’re thinking about AI in clinical settings.

Paper · Read with Scholia

Skills, plugins, hooks, and MCP servers are the way. This post walks through what I’ve built and what I’ve found useful from the community.

1. Skills: Stop Re-Explaining Yourself

A skill is a SKILL.md file — structured knowledge and workflows Claude can pull in when a situation calls for it. Unlike CLAUDE.md, which loads every session, skills load on demand. The tradeoff is intentional: CLAUDE.md gives Claude its baseline orientation, skills give it deep expertise in specific situations without loading everything at once.

Skills live in ~/.claude/skills/ for global use, or inside a project’s .claude/ directory for project-specific knowledge. The project-level location is where I put most of mine - it lets me titrate Claude’s abilities depending on whether I’m working on Scholia.fyi, the website I built to evaluate primary literature, or research-code, my repo for research tools.

Here’s a sample of what I’ve built recently.

My voice

bjw-voice-modeling is one of the rare global skills (~/.claude/skills/) that isn’t research-specific. Whether a drafted email or a notebook that I use to describe my work, I want it to sound like me. The skill includes four real writing samples across different contexts: an email to a colleague sharing null results, a methodological clarification correspondence, a speech I gave for a former senior resident, and a personal statement. Claude uses these to calibrate before writing anything on my behalf, orienting to my voice.

Anyone can build this, especially when you have Claude to help you. In addition to a bounty of helpful tools, Anthropic has a skill-creator skill that you can use to help compile your skill. For my voice modeling skill, I just provided the four writing samples and iterated with Claude to make this skill that I use almost daily.

Hopefully you’ll see this come up again and again - use Claude to make Claude better.

ICD queries

aou-icd-query builds on something I learned from a colleague. ICD code extraction in All of Us has a pitfall that isn’t obvious — one my labmate Tam Tran first identified when building PheTK: ICD-9 and ICD-10 both have codes beginning with “V,” but they mean entirely different things. Both share the same concept_code in the database, so a text join on condition_source_value returns both rows. (I mentioned this in Part I.)

Tam’s correct query has three stages: extract all ICD events from both condition_occurrence and observation (across both source value and source concept ID columns), then resolve V-code vocabulary ambiguity by tracing through concept_relationship, then union the results. Every time I started a new cohort, I was explaining this from scratch — or hoping Claude would reconstruct it correctly.

Now it’s in a skill, including a note I care about:

The goal is legibility, not abstraction. These scripts help me try to teach as well as analyze in my notebooks.

dsub infrastructure

aou-dsub-infrastructure is institutional memory. Distributed computing on All of Us runs through dsub, which submits jobs to Google Cloud Batch. dsub has a few constraints that are painful to rediscover.

When we migrated to Google Batch last summer, one was particularly painful: c4 machine types didn’t work. c4 requires hyperdisk-balanced boot disks, and dsub couldn’t set boot disk types. I learned this by submitting a job, waiting for it to fail, and debugging the error - exactly the kind of thing that belongs in a skill rather than in someone’s head.

The skill includes a constraint table (machine families, provider requirements, network flags, logging paths), the dsub_script() function pattern I use across SAIGE GWAS and METAL meta-analysis workflows, job monitoring utilities, and a machine type selection guide drawn from actual projects. When I or a trainee opens a new genomics notebook, this doesn’t need to be re-established.

Table schemas

aou-table-schema is an interesting case. In Part I, I described putting All of Us CDR data dictionaries in _reference/all_of_us_tables/ as flat tsv files. Claude could read them when needed — but it had no guidance about when they were relevant or which file to use.

Wrapping those same files in a skill keeps the information out of context when it’s not needed, and adds routing logic: when looking up table columns, load table_schemas.tsv; when estimating query size, load table_row_counts.tsv; when you need to filter by care setting, load visit_concepts.tsv. For the larger files, the skill instructs Claude to grep first, then load. This keeps token usage down, but still makes the data available even when I forget to direct Claude to the reference material.

The shift from “here are files” to “here is a skill with files” is subtle. It turns passive storage into active guidance, but it really draws from why skills are so powerful - Claude has access to all skill metadata every time, so it knows where to look and when.

Plotting conventions

bjw-plotting is the smallest skill but saves real time. I care a lot about making figures that tell a story and look good. This skill carries forward my 11-color colorblind-friendly palette, the same seaborn whitegrid setup, consistent figure sizes by plot type. The All of Us count suppression rule also applies to plots: any annotation showing participant counts between 1 and 19 must display as "< 20". The skill encodes all of this, including the format_count() function, so I don’t establish it at the top of every notebook.

Here’s a taste from my last publication:

2. Plugins: Skills, Agents, Hooks, and More

Plugins are packaged distributions that “extend Claude Code with skills, agents, hooks, and MCP servers.” You install them once and they’re available across projects — no copying files between repos. They live in ~/.claude/plugins/.

The two sources I use:

example-skills

Anthropic ships a set of example skills as a plugin: document creation (docx, pptx, xlsx, pdf), frontend design, web artifacts, and more. These are genuinely useful for the non-code parts of research — formatted reports, slides, analysis dashboards. More importantly, this plugin is the reference implementation for how to write skills. If you want to build your own, reading through these teaches you the structure. The skill-creator skill (included here) guides you through the process.

The Life Sciences Plugin Marketplace

A more exciting set for researchers is the life sciences plugin marketplace. A few plugins worth knowing:

biorender: Integrates BioRender for scientific figure creation.

biorxiv: Access to preprints from bioRxiv and medRxiv. Useful when you want Claude to engage with recent work before it’s indexed in PubMed.

open-targets: This is my recent favorite. Open Targets aggregates SNP data from gnomad, GWAS associations, and QTL credible sets all in one place. For the question “what else is known about this locus?” — which I ask constantly — this replaces a round trip through multiple browser tabs with a structured answer in the same session where I’m already working.

nextflow-development: Guides users through nf-core pipelines with a structured checklist from data acquisition to output verification. I run genomics pipelines through dsub and PLINK2 on All of Us Researcher Workbench, so I haven’t used this one myself, but it targets exactly the bench scientist who has FASTQ files and needs to run a standardized pipeline.

3. Hooks: Guardrails For Your Code

CLAUDE.md instructions are soft constraints. Claude reads them, but in a long session with many steps, they can be forgotten or reasoned around. Hooks are hard constraints. They’re event-driven rules that intercept tool calls before they execute and warn or block based on patterns you define.

Blocking recursive GCS deletion

gsutil rm -r deletes everything at a GCS path, recursively. In an All of Us workspace, that could mean months of GWAS summary statistics, processed genotype files, or model outputs. There’s no recycle bin.

One hook I have intercepts any Bash command matching gsutil (-m )?rm -r and blocks it:

If I genuinely need to delete something, I can disable the rule temporarily, forcing an intentional extra safety step. Ten lines of YAML protecting months of work.

Creating hooks with hookify

I didn’t write that rule file by hand. hookify is a plugin that creates hooks from conversation — I ran /hookify, described what I wanted to prevent, and it generated the file. Rules take effect immediately, and if in practice I find the pattern to be too broad or too narrow, I edit the file directly. It’s worth installing early — once you see what hooks can do, you’ll want more of them.

4. MCP Servers: Real-Time External Connections

CLAUDE.md, skills, and reference files all provide static context — information that was true when you wrote it. (I of course should update my CLAUDE.md files, but this isn’t a strength of mine. Perhaps I need the right hook…) MCP servers connect Claude to external data. Claude can call external tools, get current results, and reason about them in the same context where you’re working.

Two I use somewhat regularly:

PubMed

The PubMed MCP gives Claude access to search_articles, get_full_text_article, find_related_articles, and get_article_metadata. While I do most of my recent literature search or review with Elicit or Scholia.fyi, this is a great resource. Instead of opening yet another tab, I use this to ask Claude to retrieve relevant papers and reason about methodology in the same session where I’m writing code.

context7

context7 retrieves current documentation for software libraries. When I’m working with a library I haven’t used recently — or one that’s changed since Claude’s training (#Polars once upon a time) — I ask Claude to pull the current docs before writing code. Library APIs shift, deprecated functions stick around in training data, and the difference between working code and code-that-looks-like-it-should-work is often one argument that changed between versions. context7 is a small habit that cuts time on avoidable debugging.

Building Your Own

If you want to go further:

Skills: Start with something specific — a query pattern you explain repeatedly, a constraint you keep rediscovering, a set of conventions you want consistent across projects. The skill-creator skill (in example-skills) guides you through the structure. Supporting reference files go in a references/ subdirectory alongside your SKILL.md.

Hooks: Run /hookify and describe what you want to prevent.

MCP servers: MCP servers are external processes that expose tools via a standardized protocol. The mcp-builder skill walks through creating one in Python or TypeScript.

What This Adds Up To

Part I was about giving Claude a map. Part II is about giving it tools. Together: Claude knows my project structure, my domain-specific query patterns, my coding conventions, my voice — and now it won’t delete my results directory, can search the literature without breaking context, and always uses the right palette for my figures.

That’s not replacing judgment. It’s scaffolding that takes the repetitive off my plate so judgment is what’s left. That’s the version of this I find worth using, and most of this can be found at my research-code repo. Hope they help!

In Part III, I’ll show what all of this looks like in practice: building a cohort from scratch in All of Us.

See you then.

1,295 messages across 325 files (+60,192/-13,058 lines of code) over 82 sessions spanning five weeks.

The Summary Felt Spot-On

Claude Code characterized my workflow as “a deeply hands-on, iterative debugger who uses Claude Code as a persistent collaborator.” The key pattern it identified:

You drive complex, multi-file changes through rapid iterative cycles—letting Claude attempt solutions, catching errors and wrong approaches in real time, and steering toward simpler implementations with hands-on corrective feedback.

It felt good to see what feels like growing competency validated, but I also learned a reality of my use: I rarely give exhaustive upfront specifications. Instead, I describe a goal and steer Claude through implementation with real-time feedback—a “try it and fix it” philosophy.

But the Diagnostic Section Hit Harder

What surprised me its surgical precision of the diagnostics. Claude Code didn’t just tell me what I was doing; it told me where things were breaking down and why.

Where Things Broke Down

Incorrect Initial Implementations Requiring Multiple Fix Cycles

Claude’s first-pass code frequently contained bugs—wrong API access patterns, broken migrations, incorrect UI wiring. The report cited specific examples:

Stripe subscription date extraction failed three times (direct attribute access, wrong .get() level, then finally items.data[0]), and credits still weren’t granted afterward—burning an entire session on what should have been a straightforward API integration.

The fix: “Providing more explicit specifications upfront (e.g., expected Stripe object structures, exact DB constraints) or asking Claude to outline its approach before coding could reduce these costly iteration rounds.”

Wrong Solution Architecture Before User Correction

Claude repeatedly proposed overly complex solutions—wrapper abstractions, symlink chains, /tmp hacks—when I already knew a simpler approach existed. Example from my genomics pipeline work:

For GCS file localization, Claude cycled through symlinks, gsutil in-script, and dirname approaches before you steered it to the straightforward FUSE mount solution you wanted from the start.

The insight: State architectural preferences upfront. “Use FUSE mounts, not gsutil” or “no wrapper classes” would have short-circuited wasted iteration.

Aggressive Edits Without Verification

Claude often applied changes too eagerly—editing documents without pausing for review, adding more content than requested, or committing unwanted files. I interrupted tool calls twice during document editing because Claude was applying changes without letting me review intermediate results.

The data quantified this: 20 instances of “wrong approach” friction and 19 instances of “buggy code,” but only 3 rejected actions and 2 user interruptions. I prefer to let Claude attempt things and then correct rather than pre-empt.

The Improvements

Then came the actionable section—not generic advice, but specific refinements drawn from actual sessions:

1. Exact Prompts for CLAUDE.md

The report generated precise additions for my project documentation based on pain points from our sessions:

1
2
3
When working with Stripe API objects, always access nested data through 
`items.data[0]` for subscription details. Never use `.get()` or direct 
attribute access on top-level Stripe objects for period dates.

This wasn’t general strategy. It was extracted from three failed attempts at the same integration pattern.

2. Lifecycle Hooks

The report suggested hooks to auto-run linting or tests after edits, catching buggy first-pass implementations before I see them. Example:

1
2
3
4
5
hooks:
  post-edit:
    # Auto-run linter after Python edits
    - if: "file.endsWith('.py')"
      run: "ruff check {file}"

3. Better Prompt Patterns

Example prompts showing how to add context up front, guide iterative fixes, and spawn parallel agents. One particularly useful pattern for my genomics pipeline work:

1
2
3
4
Context: KIR-mapper pipeline using dsub + Google Batch. Prefer FUSE mounts 
over gsutil. No wrapper abstractions around dsub functions.

Task: Debug why pipeline stalls at sample 199/200...

The Meta-Learning

A tool that accelerates my data processing is also teaching me to use it better. The meta-analysis of my own workflow is as valuable as the code it helped me write.

The report revealed patterns I hadn’t yet noticed:

• My median response time to Claude is 98.6 seconds (average 316.3s)—I’m actively engaged, not fire-and-forget
• 24 of 82 sessions were “Iterative Refinement” type—my most common workflow
• Multi-file changes were Claude’s most helpful capability (20 instances), followed by correct code edits (13)

What I’m Implementing

Based on these diagnostics:

1. Enhanced CLAUDE.md files with tech stack preferences, data processing constraints, and architectural patterns drawn from actual failure modes
2. Pre-commit hooks for automatic linting and basic test runs
3. More upfront context in prompts—especially example data structures for API integrations and explicit architectural constraints for infrastructure work

The report also suggested I’m ready for more ambitious workflows as models improve:

Your most painful sessions—multi-round pipeline debugging and Stripe integration fixes—should become single-prompt workflows where Claude autonomously iterates against your test suite until everything passes.

That’s the future I’m building toward: test coverage comprehensive enough that future Claude can self-correct without intervention.

Try It Yourself

If you’re using Claude Code, type /insights and see what workflow patterns it identifies. The Scott Cunningham method is also worth trying: ask for a slide deck, your place in the taxonomy of how people use Claude Code, and a translation of engineering-speak into concepts you understand.

Still slightly offended it called me an ICU doc though…

If you’d like to follow along, the GitHub repo is research-code. All files referenced here are available for you to use.

Why Context Matters

But Bennett, can’t I just give Claude a snippet of code and ask it to do something? Sometimes that works well, but the key is context.

If LLM context windows are big enough to consider an entire notebook or project, why limit them? Don’t hide how you derived a cohort when that derivation can inform what you’re asking the model to do next.

At the same time, how do you provide information efficiently without bloating the context window? The .ipynb format includes structural metadata that wastes tokens. References to irrelevant methods add noise without value, and you don’t want to hit your usage limit prematurely.

Claude Code already enables users to review an entire codebase and offer bug fixes or deep understanding. Why not do the same for research? Here’s how I approach it.

1. Centralize Reference Information

The models have been trained on what the internet knows about All of Us, which is both good and bad. They have a general sense of what’s available in the biobank, but for rapidly evolving systems, that information may already be outdated.

For my work, I asked Claude what would be helpful to know. Publicly available data dictionaries exist online, but what details matter most? I downloaded the data dictionary and pared it down to essentials: Table Name, Field Name, OMOP CDM Standard or Custom Field, Description, and Field Type. Claude then generated SQL to provide counts for each table in the current CDR. The result: 9 .tsv files of schema structure and data counts, adhering to the <20 censoring required by All of Us (_reference/all_of_us_tables/).

2. Centralize Phecode Lists

Phecodes are manually curated groupings of ICD codes designed to capture clinically meaningful concepts for research. Lisa Bastarache has an excellent review if you want to learn more. Not every phecode is perfect, but if clinicians and researchers have already worked to group billing codes into meaningful categories, why not start there? We all know about the reproducibility crisis in biomedical research, and random unvalidated ICD groupings aren’t going to help.

This is why I include CSV files mapping phecodes to ICD codes (_reference/phecode/).

3. Identify Trusted Queries

I also brought in a trusted ICD query from my labmate, Tam Tran. He’s the force behind PheTK, a fast Python library for Phenome Wide Association Studies (PheWAS) that includes Cox regression for incident analyses, dsub integration for distributed computing, and more.

In developing PheTK, Tam discovered some peculiarities worth noting:

Dual identifiers: ICD codes appear as both concept_id and concept_code (e.g., 1567285 and A40 for Streptococcal sepsis), and not always both present. His query checks for both.

By keeping these queries in _reference/trusted_queries/, I carry forward these lessons in my code.

4. Collect Your Code

Finally, the important part—your actual code. I work in All of Us, a cloud-based environment where researchers cannot download individual data. To export notebooks safely, I created upload_safe.sh, a script that syncs with my GitHub repo, copies selected notebooks, and strips them of output, bucket paths, and secrets. This way, Claude only sees code—not data.

In this public repo, I’ve included a few published projects:

• genomics: Genomic analysis pipelines for All of Us genetic data
• hpv: HPV research cohorts using OMOP CDR data
• nc3: N3C RECOVER Long COVID phenotyping algorithm adapted for All of Us

Orienting Claude Code

Once all files are in place, you’re ready to initialize. Open terminal, navigate to your working folder, and type claude.

Type /init to create a CLAUDE.md file for the repository root.

CLAUDE.md files define coding standards, review criteria, user preferences, and project-specific rules. Each time you start Claude Code, this document loads into context and guides your session. Anthropic recommends keeping it focused and concise, updating as the repository evolves.

Claude does the heavy lifting. It produces a solid first draft:

1
2
3
4
5
6
7
8
9
This repository contains computational methods for research informatics
and genomics research, primarily focused on analyzing data from the NIH's
**_All of Us_ Research Program**. Code examples are shared from
bennettwaxse.com and include analysis tools for:

- **Genomics**: Variant analysis, ancestry inference, PCA workflows using PLINK2 and Hail
- **HPV Research**: Cohort construction and analysis
- **N3C/RECOVER**: Long COVID phenotyping algorithms adapted from PySpark to Python/pandas
- **Reference Materials**: _All of Us_ table schemas, PheCode mappings, and Verily Workbench helpers

It included other useful sections: Platform, Key Environment Variables, Code Structure, Project Organization, Data Handling, Common Libraries, and Workflow Patterns.

Editing CLAUDE.md

The first draft captured the general intent, but I edited line by line. I added a Development Philosophy section describing the importance of:

• Data validation throughout processing: Check frequently that data transforms as expected
• Code clarity over abstraction: These scripts serve a dual purpose—analysis and teaching EHR/genomics informatics. I want trainees to see exactly how processes work.

I also added a section about All of Us rules, including count censoring for all values <20 to minimize problematic reporting.

Some things Claude got wrong. One section referenced code for setting environment variables in the new Verily Workbench. Claude assumed this was required for every project, so I clarified it’s only for new Verily Workbench notebooks, a work-in-progress for All of Us.

As with everything AI-generated, my mantra: review it line by line. Then iterate. Claude refined my verbose writing and kept things focused.

Creating .claudeignore

Next, I asked Claude to create subdirectory CLAUDE.md files. These only load when Claude works in those directories—a good way to reveal specifics only when relevant. Remember, it’s all about efficient context usage.

I created a .claudeignore file to:

• Prevent reading .ipynb files (redundant with .py scripts)
• Block files containing secrets like .env
• Exclude raw data files (.bam, .fastq)—Claude isn’t analyzing actual data
• Skip Python cache, build artifacts, and IDE files

I did keep .csv and .tsv off this list since I share mappings and references with Claude.

Claude also asked clarifying questions. It offered to expand the README and suggested a few other improvements.

The Result

What we have is a meaningfully structured folder with source material that mirrors my typical workflows and resources. CLAUDE.md files orient Claude to the project, and .claudeignore tells it what to avoid.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
research-code/
├── CLAUDE.md              # Root instructions
├── .claudeignore          # Files to skip
├── _reference/
│   ├── CLAUDE.md          # Reference-specific context
│   ├── all_of_us_tables/  # CDR schemas
│   ├── phecode/           # Phecode mappings
│   └── trusted_queries/   # Vetted SQL patterns
├── genomics/
│   ├── CLAUDE.md          # Genomics-specific context
│   └── *.py               # Analysis scripts
├── hpv/
│   └── ...
└── nc3/
    └── ...

What’s Next

If you’re excited to see what Claude can do with this foundation, you’re in the right place. Next time, I’ll introduce skills, plugins, and MCP servers—components that extend what Claude Code can do!

Soon, you’ll see how Claude Code is supercharging my data analysis in All of Us. If you’re already using Claude Code, I’d love to learn how you’re using it too!

Until then, sciencespeed.

At the end of last year, I discovered Claude Code. I was blown away. I built a command-line tool to efficiently evaluate primary literature using LLMs, which eventually became Scholia.fyi—releasing in the next few weeks. When I returned to work in January, it was clear Claude Code would also take my informatics to the next level.

This is the first in a series of posts about using Claude Code for data analysis and scientific work. I found plenty of resources on building apps or websites with Claude Code, but not much on bioinformatics and science. My hope is to create a community of Claude Code-literate scientists who keep humans in the loop and amplify what we can do.

This first example involves scaling a KIR gene mapping pipeline from 40 samples to 200,000+. Beyond optimizing machine types (Claude Code helped me find a 30% cheaper parallelized setup), I consistently hit a wall around 100-200 samples. The tool worked fine at small scale but failed predictably in production. This is a story about debugging something outside my expertise and learning where Claude Code genuinely helps.

The Setup

I’m working with kir-mapper, which aligns KIR genes from whole-genome sequencing. The pipeline orchestrates several tools:

1. GATK PrintReads converts CRAM to BAM, extracting the KIR region
2. kir-mapper map aligns reads to KIR references
3. (Later) ncopy, genotype, haplotype call variants

The strategy was simple: run 5 samples in parallel using GNU parallel, process them in 100-200 sample batches. This should be efficient. Instead, the pipeline stalled reliably at sample 99/100 or 199/200.

The Pattern

The failure was consistent but puzzling:

• 40-sample run: succeeded
• 64-sample run: succeeded
• 100-sample run: stalled at 99/100
• 199-sample run: stalled at 198/199
• 200-sample run: stalled at 199/200

Always at or near the last sample. This suggested something systematic—not random failure, not resource exhaustion, but something about how the parallel queue itself was behaving.

I first analyzed memory and disk usage throughout the runs with Claude Code. We never exhausted resources. That ruled out the obvious culprits. Beyond that, I was stuck. File conflicts in parallel execution was a hypothesis, but debugging GNU parallel internals isn’t my area, and I’d never written low-level code to know where to look.

Where Claude Code Helped

I gave Claude the problem, access to the kir-mapper source code, and access to my base and parallelization scripts. It did something I couldn’t have done efficiently: read through thousands of lines of C++ and identify where temporary files were created.

Here’s what it found in map_dna.cpp (lines 1473-1474):

1
2
string v_sai1 = v_output + "tmp1.sai ";
string v_sai2 = v_output + "tmp2.sai ";

Compare with how SAM files are named (line 1134):

1
string outsamtmp = v_output + v_sample + *i + ".tmp.sam";

The difference is stark: SAM files include the sample name. The temporary BWA index files do not. When five samples run in parallel, they all write to the same tmp1.sai and tmp2.sai files. File locks accumulate. After a certain number of jobs queue up, GNU parallel hits an internal limit and stops accepting new ones.

This explained an interesting observation: GATK worked fine, even though it also runs in parallel. The difference isn’t parallelization strategy—both GATK and kir-mapper use GNU parallel with 5 samples at a time. The difference is how they handle temporary files. GATK apparently names its temp files in a way that avoids collisions (or writes them elsewhere), whereas kir-mapper creates those shared tmp1.sai and tmp2.sai files that all samples contend for. When file locks accumulate on those shared temp files, the GNU parallel queue hits its limit and stops accepting new jobs.

Could I have figured this out alone? Eventually, probably. But it would have taken substantially longer. Could I have abandoned parallelization and forfeited 30% savings, also yes. The key was that Claude could quickly parse unfamiliar C++ and identify the pattern.

Two Fixes

With the diagnosis in hand, I implemented two complementary fixes:

Fix 1: Per-sample output directories. Instead of all samples writing to a shared output directory:

1
2
3
4
5
6
7
8
local sample_output="./kir_output/${person_id}"
mkdir -p "$sample_output"

kir-mapper map \
    -bam "${person_id}_chr19.bam" \
    -sample "${person_id}" \
    -output "$sample_output" \
    -threads $THREADS_PER_SAMPLE 2>&1

Each sample now gets its own subdirectory. The tmp1.sai and tmp2.sai files for sample A don’t collide with those for sample B.

Fix 2: 25-sample sub-batches. Even with per-sample directories, sending 100 jobs through GNU parallel at once keeps you near that queue limit. So instead of:

1
seq 1 100 | parallel -j 5 'run_kirmap {}'

We process in sub-batches:

1
2
3
4
5
6
7
8
9
10
11
BATCH_SIZE=25

while [ $idx -le $NUM_SAMPLES ]; do
    BATCH_END=$((idx + BATCH_SIZE - 1))
    if [ $BATCH_END -gt $NUM_SAMPLES ]; then
        BATCH_END=$NUM_SAMPLES
    fi

    seq $idx $BATCH_END | parallel -j 5 'run_kirmap_with_env {}'
    idx=$((BATCH_END + 1))
done

25 jobs stays well below the queue limit and within the ballpark of successful runs.

Why This Matters

Many of us build bioinformatics pipelines with deep domain expertise but without systems-level knowledge. You understand your science (genomics, epidemiology, medicine) but orchestrating multiple tools, managing parallel job queues, and debugging temporary file handling is a different domain entirely.

Claude Code was useful here specifically because:

1. It could read large codebases quickly and extract relevant sections
2. It could reason about file I/O patterns and concurrency issues
3. It helped me iterate through multiple approaches and find the best

What it didn’t do: it didn’t magically know the answer. I had to provide the logs, frame hypotheses, and verify its analysis myself. The diagnosis made sense conceptually, so I checked the source code to confirm. That verification step is critical, but we’re already used to this in science.

When It’s Actually Useful

If you’re considering Claude Code for bioinformatics, the wins come from:

• Code analysis: Reading unfamiliar source code to find issues
• Prototyping approaches: Testing multiple strategies before committing
• Architecture: Designing cleaner pipeline structure (mine went from 6 stages to 3)
• Getting through the tedium: I’ve also used it to construct new cohorts, an easy but tedious process

The important caveats:

• You still need domain knowledge to evaluate suggestions
• Verify diagnoses yourself, especially for system behavior
• Use it as a thought partner, not a substitute for critical thinking
• If something doesn’t make sense, push back and ask for more detail

The Result

The pipeline now processes all samples in a batch successfully, maintains parallelization efficiency, and scales to multiple ancestries. More importantly, I understand why it failed and what the fixes address. That understanding is what matters for extending the code later, and approaching similar tasks in the future.

If you’re building scientific pipelines and hit problems outside your expertise, try Claude Code. Frame questions clearly, give it access to relevant code, and validate its analysis. The combination of clear problem statements, access to source code, and iterative refinement creates a solid workflow for technical debugging.

I’ll be writing more about how I’m using Claude Code for data analysis work. If you have questions or want to share how you’re using it, I’d be interested to hear.