A hands-on Claude Code course for reservoir engineers, production engineers, petroleum engineers, subsurface data scientists, and technical teams who want to use AI-assisted coding without giving up engineering rigor.

This repository teaches Claude Code through reservoir engineering tasks instead of generic toy examples. Every exercise is framed around workflows engineers actually recognize: production data QA, water-cut trends, PVT unit checks, decline curve analysis, material balance discipline, nodal-analysis prompts, black-oil simulation preparation, pyResToolbox usage, and Model Context Protocol (MCP) tools.

The goal is not to make Claude "do engineering" blindly. The goal is to teach engineers how to direct Claude like a disciplined technical assistant: give it context, constrain assumptions, require units, verify results, use tests, and prefer proven libraries or MCP tools over invented formulas.

Reservoir engineering work is full of small but consequential details:

• pressure units: psia vs barsa
• temperature units: degF vs degC
• gas gravity parameter names that change across APIs
• correlations that are only valid in certain ranges
• production forecasts that look smooth but violate simple sanity checks
• material balance calculations that are only as good as their input history
• simulation tables that must be traceable and reproducible

AI tools can accelerate this work, but only when the engineer supplies enough domain context and demands verification. This course shows that workflow in concrete, repeatable exercises.

By the end of the course, you should be able to:

• use Claude Code's explore, plan, code, and verify loop on engineering scripts
• write prompts that identify the file, function, failing behavior, units, and expected engineering relationship
• ask Claude to add tests with known values, monotonicity checks, and physical bounds
• create and use CLAUDE.md project memory for reservoir-specific standards
• package repeatable reservoir workflows as Claude skills
• use a reviewer subagent to catch unit, assumption, and correlation mistakes
• combine Claude with shell commands for production-data QA
• use pyResToolbox and pyrestoolbox-mcp for reservoir calculations rather than hand-rolling correlations
• parallelize independent sensitivity cases and aggregate the results carefully

This course is designed for:

• reservoir engineers learning AI-assisted coding
• production engineers working with CSV exports and decline curves
• petroleum engineering students who know the domain but want better coding workflows
• data scientists supporting subsurface teams
• technical managers evaluating Claude Code for engineering workflows
• open-source contributors building reservoir engineering automation

You do not need to be a software engineer. You should be comfortable reading basic Python and using a terminal.

This project adapts the excellent exercise style of claude-code-for-hydrology to reservoir engineering.

It is built around concepts and tooling from:

• pyResToolbox, a Python reservoir engineering utility library by Mark Burgoyne
• pyrestoolbox-mcp, an MCP server exposing pyResToolbox calculations to AI assistants
• Claude Code workflows: project memory, skills, subagents, testing, MCP, and parallel work

.
├── 01_explore_plan_code/          # Production analysis: explore, plan, implement
├── 02_specific_context/           # PVT conversion bug: precise context beats vague prompts
├── 03_verify_your_work/           # DCA checks: tests and sanity checks
├── 04_init_claude_md/             # Project memory with CLAUDE.md
├── 05_skills/                     # Reservoir engineering Claude skills
├── 06_subagent_review/            # Reservoir reviewer subagent workflow
├── 07_cli_workflow/               # Shell + Python QA for production CSVs
├── 08_mcp_pyrestoolbox/           # Using pyResToolbox through MCP
├── 09_parallel_fanout/            # Parallel sensitivity studies
├── assets/                        # Generated plots and reference result tables
├── scripts/generate_course_figures.py
├── .claude/
│   ├── agents/reservoir-reviewer.md
│   └── skills/
│       ├── reservoir-engineering/SKILL.md
│       └── run-tests/SKILL.md
├── references/pyrestoolbox-workflows.md
├── CLAUDE.md
├── requirements.txt
└── README.md

Install:

• Claude Code
• Python 3.10 or newer
• pip or a Python environment manager
• optional but recommended: pyrestoolbox
• optional for live AI tool calls: pyrestoolbox-mcp

Clone the repository:

git clone https://github.com/gabrielserrao/Claude-for-reservoir-engineering.git
cd Claude-for-reservoir-engineering

Install Python dependencies:

python3 -m pip install -r requirements.txt

If your system uses python instead of python3, adjust the commands accordingly.

Generate the course plots and result tables:

python3 scripts/generate_course_figures.py

The generated outputs live in assets/ and are committed so the course is readable on GitHub without running code first. Re-run the script whenever the sample data or screening assumptions change.

Open Claude Code from the repository root:

claude

Start with Exercise 1:

cd 01_explore_plan_code

Read the exercise README, then try the "before" prompt and the "after" prompt. The contrast is the point of the course: you will see how much better Claude performs when you provide files, units, expected engineering behavior, and verification commands.

Each exercise is self-contained and follows a consistent structure:

1. Read the exercise README.
2. Try the vague prompt first.
3. Clear Claude's context with /clear.
4. Try the improved prompt.
5. Compare the results.
6. Run the tests or checks.
7. Reflect on what changed in the prompt and workflow.

The "before" prompts are intentionally under-specified. They mimic how engineers often start with an AI tool. The "after" prompts show the level of context and constraint that produces dependable technical work.

This course now includes generated figures that make the engineering checks visible. The purpose is not decoration. The plots show what Claude should be asked to produce or verify before an engineer trusts the result.

The sample production data shows two simple but useful signals:

• A-01 has stronger oil volume but water cut still increases from 7.7% to 14.6%.
• B-02 starts wetter and also trends upward, from 21.6% to 27.7%.
• A useful Claude prompt should ask for both the calculation and the interpretation: "is water cut increasing, by how many percentage points, and does the trend respect well/date ordering?"

PVT unit bugs are easier to catch when the expected relationship is visible. Higher API gravity means lighter oil, so specific gravity should decrease as API increases. A fix that passes a round-trip test but violates this monotonic relationship is still suspicious.

The DCA plot makes two checks concrete:

• Higher nominal decline should produce lower future rates for the same initial rate.
• Lower economic limits should increase EUR, but the result is still a screening calculation, not a reserves booking.

The generated tables behind these figures are in assets/generated_results.md.

Claude is most useful when it first understands the codebase. In this exercise, Claude reads a production analysis script, a sample production CSV, and existing tests before adding water-cut trend analysis.

Engineering lesson:

• Water cut must be computed from oil and water volumes.
• The trend must respect well/date ordering.
• A production metric should be tested against known values.
• A plot should reveal whether a calculation is plausible before anyone reads the code line by line.

Claude lesson:

• Plan mode reduces unnecessary edits.
• File-specific prompts produce better implementations.
• Tests define what "done" means.
• Generated figures create a second verification surface: if the table says water cut rises but the plot falls, investigate.

Small PVT conversion bugs are easy to miss and costly to propagate. This exercise shows how to tell Claude exactly which test fails and which petroleum engineering relationship applies.

Engineering relationship:

SG = 141.5 / (API + 131.5)
API = 141.5 / SG - 131.5

Interpretation guardrail:

• API and specific gravity move in opposite directions.
• A 35 API oil has SG near 0.850.
• The conversion is dimensionless; pressure conversion bugs should not be mixed into this function.

Claude lesson:

• "Fix the PVT bug" makes Claude search and guess.
• Naming the failing test and expected formula lets Claude go directly to the fault.
• Asking for monotonic checks catches a broader class of mistakes than one round-trip example.

Decline curve helpers can look plausible while hiding invalid assumptions. This exercise uses known values and sanity checks for exponential decline and EUR calculations.

Good tests include:

• known analytic values
• nonnegative rates
• rejected invalid inputs
• EUR increasing as the economic limit decreases
• sensitivity plots that make method and assumption choices obvious

Claude lesson:

• Ask for verification, not just implementation.
• Give Claude a command to run after edits.
• Make engineering checks explicit.

Reservoir engineering projects have recurring rules: units, method names, assumptions, validation, and output standards. CLAUDE.md keeps that context available across sessions.

This repository's root CLAUDE.md tells Claude to:

• state field vs metric units
• prefer pyResToolbox or MCP tools for standard calculations
• avoid silent correlation changes
• include tests or sanity checks for engineering functions
• watch pyrestoolbox-mcp parameter naming conventions

Claude lesson:

• Persistent project memory prevents repeated explanations.
• Domain-specific instructions improve every later prompt.

Skills package reusable instructions for common work. This repository includes a reservoir engineering skill and a test-running skill.

The reservoir engineering skill covers:

• oil PVT
• gas PVT
• brine and CO2 workflows
• DCA
• material balance
• nodal/IPR/VLP
• relative permeability tables
• simulation table preparation
• parameter naming pitfalls in pyrestoolbox-mcp

Claude lesson:

• Do not paste the same domain rules into every prompt.
• Use skills to keep high-value instructions close to the model.

Engineering code benefits from an independent review pass. The included reservoir-reviewer agent checks for:

• unit consistency
• correlation applicability
• nonphysical outputs
• pyResToolbox or MCP parameter mistakes
• missing tests
• weak assumptions

Claude lesson:

• Use a reviewer for higher-risk work.
• Ask for findings first, not praise or summaries.
• Treat the review as a quality gate.

Before fitting DCA models or running material balance, production data should be checked. This module uses Claude with shell commands and Python checks to inspect CSV data.

Typical QA checks:

• required columns exist
• dates parse correctly
• rates are nonnegative
• well/date rows are not duplicated
• cumulative production is monotonic when expected

Claude lesson:

• Let Claude use the terminal to inspect real files.
• Ask it to summarize evidence, not just assumptions.

Claude should not invent industry correlations when reliable tools are available. This exercise shows how to ask Claude to use pyResToolbox through MCP for live reservoir engineering calculations.

Example prompt:

Use the pyResToolbox MCP tools.
Calculate bubble point pressure for 35 API oil at 180 degF with solution GOR 800 scf/stb and gas gravity 0.75.
Use Valko-McCain if available.
State units, method, inputs, and one sanity check.

Important pyrestoolbox-mcp reminders:

• oil tools usually use sg_g for gas gravity
• gas tools usually use sg
• inflow tools use psd for sandface pressure
• some gas tools use zmethod, not method
• relative permeability table types include SWOF, SGOF, and SGWFN

Claude lesson:

• Use MCP tools when you need live calculations.
• Ask for inputs, units, method, output, and sanity check every time.

Sensitivity cases are often independent. Claude can split them across workers or parallel calls, then aggregate the results.

Example independent cases:

• bubble point methods: STAN, VALMC, VELAR
• gas Z-factor methods: DAK, HY, WYW
• skin cases: -2, 0, 5

Claude lesson:

• Parallelize independent scenarios only.
• Require each worker to return assumptions and units.
• Use a final aggregation step to compare results.

Run all tests:

python3 -m pytest -v

Run one exercise:

python3 -m pytest 01_explore_plan_code/ -v

The tests are intentionally small. They are teaching tools, not a complete engineering validation suite. When adapting the patterns to real work, add more edge cases, known-value comparisons, and domain-specific acceptance criteria.

Install pyResToolbox:

python3 -m pip install pyrestoolbox

Example:

from pyrestoolbox import oil

pbub = oil.oil_pbub(
    api=35,
    degf=180,
    rsb=800,
    sg_g=0.75,
    pbmethod="VALMC",
)

print(pbub)

When using pyResToolbox directly, always capture:

• input values and units
• method/correlation name
• output units
• applicability assumptions
• simple sanity checks

For Claude Desktop or another MCP-capable assistant, use:

https://github.com/gabrielserrao/pyrestoolbox-mcp

That project exposes pyResToolbox calculations as MCP tools so Claude can call reservoir engineering functions directly.

Recommended response format for MCP-backed calculations:

Inputs:
- API gravity: ...
- reservoir temperature: ...
- pressure: ...

Method:
- correlation/tool used: ...

Result:
- value and units: ...

Sanity check:
- physical or engineering check: ...

Assumptions:
- ...

This repository includes Claude configuration examples:

• .claude/skills/reservoir-engineering/SKILL.md
• .claude/skills/run-tests/SKILL.md
• .claude/agents/reservoir-reviewer.md
• .claude/settings.json
• CLAUDE.md

These are meant to be studied and adapted. The most important pattern is not the exact wording. The important pattern is that reservoir engineering constraints are made explicit and reusable.

The course figures are built from scripts/generate_course_figures.py. This script intentionally uses small, transparent calculations:

• water cut and GOR from 01_explore_plan_code/sample_production.csv
• API-to-specific-gravity reference points from the standard petroleum engineering relationship
• exponential decline screening cases with explicit qi, di, and economic-limit assumptions
• a workflow diagram showing the intended Claude Code quality loop

To refresh the figures:

python3 scripts/generate_course_figures.py

Then review assets/generated_results.md and the PNGs before committing. If a figure changes, the narrative should change with it.

For a workshop or internal training session:

1. Spend 10 minutes introducing Claude Code and the repository.
2. Run Exercise 1 as a live demo.
3. Have participants do Exercises 2 and 3 individually.
4. Discuss how each prompt changed Claude's behavior.
5. Show CLAUDE.md, skills, and the reviewer agent.
6. Demonstrate an MCP-backed pyResToolbox calculation.
7. Finish with the parallel fan-out exercise.

Expected workshop duration: 90 to 150 minutes.

Every serious reservoir engineering prompt should include:

• units
• method or correlation
• input ranges
• expected output shape
• validation criteria
• assumptions
• whether field or metric units are being used
• whether the answer is screening-level or decision-grade

Every serious engineering code change should include:

• focused tests
• known-value checks where possible
• nonphysical input handling
• output bounds or monotonicity checks where appropriate
• clear file/function scope

This course is educational. The sample data is fictional and intentionally small. The examples are designed to teach Claude Code workflows, not to certify engineering calculations.

For real reservoir decisions:

• validate against company standards
• check correlation applicability
• peer review material calculations
• document assumptions
• compare against independent tools where appropriate
• do not use AI output as the sole technical basis for field decisions

Contributions are welcome, especially:

• new reservoir engineering exercises
• better tests with known petroleum engineering values
• pyResToolbox or pyrestoolbox-mcp workflow examples
• additional Claude skills or reviewer agents
• teaching notes for classroom or workshop use
• fixes to units, terminology, or engineering assumptions

Suggested contribution pattern:

1. Add a numbered exercise folder.
2. Include a README.md with before/after prompts.
3. Include a small Python file or workflow artifact.
4. Include focused tests or validation instructions.
5. Keep sample data fictional or openly licensed.

This project is intended to be open sourced as a course. See LICENSE for details.

Thanks to the maintainers and contributors of:

• Claude Code and the Claude ecosystem
• pyResToolbox
• pyrestoolbox-mcp
• claude-code-for-hydrology