A collection of self-contained exercises for learning Claude Code best practices, built specifically for the hydrological research community. All code examples use real hydrology concepts — streamflow analysis, drought indices, model performance metrics, and USGS gauge data.

Each exercise demonstrates a "before vs. after" prompt pattern — you try a vague prompt, clear context, then try a specific prompt, and compare what Claude produces.

Hydrologists, water scientists, and researchers who want to use AI-assisted coding more effectively. No prior Claude Code experience needed — just Python familiarity and curiosity about LLM-based workflows.

• Claude Code installed (npm install -g @anthropic-ai/claude-code)
• Python 3.10+ with pip
• Basic familiarity with the terminal

# 1. Clone the repo
git clone https://github.com/lorenliu13/claude-code-for-hydrology.git
cd claude-code-for-hydrology

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Open Claude Code
claude

Then pick an exercise below and follow its README.md.

The exercises are ordered from highest-leverage fundamentals to more advanced workflows. Start at the beginning — each exercise builds on the habits established by the previous ones.

Foundations (Exercises 1–4) cover the core prompting practices that improve every interaction with Claude Code. These are the skills you will use in every session.

Workflows (Exercises 5–9) introduce tools and patterns that automate, extend, and scale what you can do — once the foundations are solid.

1. Read the README.md inside the exercise folder — it explains the concept and both prompts.
2. Try the "before" prompt — observe what Claude produces without guidance.
3. Clear context with /clear in Claude Code.
4. Try the "after" prompt — compare the quality of the result.

The difference between the two prompts is the lesson.

Each exercise folder contains a test_*.py file. To run tests for an exercise:

python -m pytest 01_explore_plan_code/ -v

Or run all exercises at once:

python -m pytest -v

Note: Use python3 instead of python on systems where Python 2 is the default.

Concept: Use plan mode (Shift+Tab twice) to separate exploration from implementation. Claude reads existing code before making changes, preventing it from overwriting things it hasn't seen.

Feature to add: compute_exceedance_flows() returning Q90 and Q95 flow thresholds.

Concept: Vague prompts make Claude guess. Naming the file, function, failing test, and symptom lets Claude go directly to the root cause instead of exploring blind.

Bug to fix: swapped mean/std in the Standardized Precipitation Index (SPI) formula.

Concept: The single highest-leverage habit is giving Claude tests with known expected values. Claude becomes its own quality checker and can iterate without your involvement.

Metrics covered: Nash-Sutcliffe Efficiency (NSE) and Kling-Gupta Efficiency (KGE).

Concept: Use /init to generate a CLAUDE.md that gives Claude persistent project context across sessions — so you stop re-explaining your codebase every time you open a new conversation.

Concept: Create reusable skills for domain knowledge (/hydro-context) and repeatable workflows (/flow-report) so you don't re-explain hydrology conventions every session. Skills compose with everything else in this repo.

Concept: Orchestrate a coder subagent and a reviewer subagent in sequence. The parent agent controls context isolation and loops until the review passes — offloading an entire quality gate to Claude.

Concept: Combine Claude with the AWS CLI to discover and download public hydrological datasets (USGS, NOAA, etc.) without leaving the terminal. Claude handles flag lookup and command construction; you supply the science intent.

Concept: Use the MCP fetch server to query the USGS NWIS API in real time, then implement correct response parsing in Python. Demonstrates how MCP tools extend Claude's reach to live external data.

Concept: When the same analysis must run across multiple independent configurations, spawn one subagent per configuration simultaneously — then collect all results with a single reporter subagent. Wall time equals the slowest single subagent, not the sum of all. Applied here to computing SPI drought indices (SPI-1, SPI-3, SPI-6, SPI-12) in parallel and aggregating findings into a unified comparison report.

Contributions are welcome. If you have an idea for a new best-practice exercise:

1. Fork the repo and create a branch.
2. Add a new numbered folder following the existing pattern (a subject Python file, a test file, and a README with before/after prompts).
3. Open a pull request with a short description of the best practice being demonstrated.

MIT — see LICENSE.