Coding with Agents

Coding with Agents (AI-Assisted Development)

What is this?

The lab's policy for using AI coding assistants (Claude Code, Codex, Copilot, Cursor...) on this repository. It is a rule set, not a suggestion.

Why does it matter?

Garbage code makes garbage analyses, and garbage analyses make garbage science. An agent can write a plausible change to a filter or a clock rate in seconds that silently changes every tree.

What do I do?

Follow Rule #1, the review process and the checklist below. Agents themselves read .agents/AGENTS.md.

Rule #1 (non-negotiable)

You must understand what every line of AI-generated code does, and be able to reproduce or explain it without the AI. If you cannot explain a line to the maintainer, it does not get committed.

You, not the agent, are the author of every change you commit.

Required review process

flowchart LR
    A["Agent proposes<br/>a change"] --> B["READ<br/>every line of the diff"]
    B --> C["TEST<br/>dry run, tutorial,<br/>before/after numbers"]
    C --> D["UNDERSTAND<br/>look up anything unclear"]
    D --> E["RE-EXPLAIN<br/>in your own words,<br/>in the PR"]
    E --> F{"Could you have<br/>written it yourself?"}
    F -->|no| B
    F -->|yes| G["Docs updated →<br/>commit → PR review"]

Loading

No step can be skipped, and a "no" sends you back to reading.

1. Read the whole diff (git diff), line by line, including files you did not expect it to touch.
2. Test it: snakemake -n, a Tutorial 1 run, and for Tier 2-3 a before/after comparison of filter logs, tip counts and report tables (Best Practices).
3. Understand it: look up every function, flag and parameter you do not know in the tool's own documentation, not in the agent's explanation.
4. Re-explain it in your own words in the pull request: what changed, why, and what it does to the builds.
5. Tier 2-3 changes still need the maintainer's approval before you start (change tiers), whoever writes the code.

Prompting agents well in this repo

Give it:

• The goal and the scientific reason ("HA builds drop too many 2026 samples; find which filter removes them"), not just "fix it".
• The exact files and rules involved, and the tier.
• Constraints: smallest change, no renames, no reformatting, no new packages, keep thresholds in sync with config/report.yaml.
• What "done" means: the commands to run and the numbers to compare.
• Small tasks. "Add a column to this table", not "improve the pipeline".

Never trust it blindly on:

• Statistical logic: frequencies, season boundaries, QC thresholds, anything producing a number in the report.
• Phylogenetic parameters: clock rates, --clock-filter-iqd, coalescent and date-inference options, references and annotations.
• File paths and wildcards: a wrong path can make Snakemake rebuild everything, read the wrong input, or write into source/.
• Data formats: header formats, ID splitting at _, segment numbering (1 and 2 swap between influenza A and B).
• Claims that tests passed. Run them yourself.

Never give it:

• Raw data. Do not paste sequences, metadata or GISAID records into a chat or let an agent open sequence files: that sends restricted data to a third party (Data Protection).
• A mode that skips approvals on this repository.

What is enforced for you

.claude/settings.json (Claude Code) blocks pushing, uploading to Nextstrain, bypassing or editing the data guard and hooks, force-adding ignored files, and reading sequence files; and asks you first before staging, committing, running Snakemake, changing the environment, or editing pipeline, config, script, .agents/ and documentation files. Personal preferences go in .claude/settings.local.json (ignored); they cannot override the shared blocks. Other agents get the same rules in writing from .agents/AGENTS.md; nothing enforces them, so your review matters more.

Keep the docs in step

Every code change (new feature, bug fix, refactor, parameter change) comes with its documentation in the same pull request. Agents must do this too, and must list which pages they updated and which they checked and left unchanged, with the reason. A change is not complete until the docs match.

If you change...	Update
source_prep/, scripts/prepare_source.py	Step 1, Tutorial 2
fludb/scripts/upload_vaccine.py, vaccine header format	Step 1, Tutorial 3
ingest.smk, flusort, other fludb scripts	Step 3, Snakemake & Scripts Reference, Pipeline Overview
Filters: --query, min_lengths, config/exclude.tsv rules, clock rates, Nextclade datasets	Step 3
Snakefile (rule all, wildcards), profiles/, config/*.yaml run options, snapshot.smk	Step 2, Snakemake & Scripts Reference
segments.smk, genomes.smk (other steps)	Snakemake & Scripts Reference, Pipeline Overview
reports.smk, scripts/report.py, scripts/run_report.py, config/report.yaml	Step 4
Upload scripts, config/description.md, config/*/auspice_config.json	Step 5
scripts/data_guard.sh, .githooks/, .gitignore, folder layout	Data Protection
workflow/envs/environment.yml, scripts/build_env.sh	Getting Started
tutorial/, config/tutorial.yaml, scripts/generate_tutorial_dataset.py	Tutorial 1
Any new or removed script	Snakemake & Scripts Reference
Workflow structure (stages, rule order, new .smk)	Mermaid diagrams on Home, Pipeline Overview, the relevant Step page, the repo README.md; regenerate rulegraph.png
Setup, usage or the top-level DAG	Repo README.md
New terms	Glossary
Agent rules	.agents/AGENTS.md and this page

The wiki is its own git repository: git clone https://github.com/Pekosz-Lab/nextstrain.wiki.git next to your nextstrain clone. Commit wiki changes with the same descriptive messages, referencing the code PR.

Before you commit agent-written code

• I can explain every line without the agent.
• I read the full diff; nothing outside the planned files changed.
• I ran the tests myself and saw them pass (snakemake -n, Tutorial 1, bash scripts/data_guard.sh).
• Tier 2-3: approved by the maintainer beforehand; before/after numbers in the PR.
• No statistical, phylogenetic or path logic accepted on the agent's word alone.
• No raw data was shown to the agent.
• Docs, diagrams and README updated (or checked and unchanged, with the reason).
• The commit message is mine, descriptive, and names the effect on the builds.

Troubleshooting / FAQ

• The agent says it can't push / commit / read a file. That is the policy working. Do those steps yourself, deliberately.
• The agent wants to refactor or reformat a whole file. Say no; ask for the minimal change.
• The agent cites a test result. Rerun it yourself before believing it.
• I don't understand the agent's change. Then it is not ready. Ask the maintainer or a PhD student to walk through it with you.

Next step → Snakemake & Scripts Reference