Agentic coding for scientific research

This repository contains short scientific projects for a hands-on session on agentic coding. Choose one project and stay with it as new requirements are revealed.

Level 1 is a small calculation with a clear starting point. Level 2 adds interacting requirements that make a short specification, tests, and independent checks useful. Level 3 is an open research loop in which each result helps determine the next calculation.

Use Claude Code, Codex, Cursor, or another coding agent. The exercises do not depend on a particular tool.

Agent setup

Install Claude Code (instructions):

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

In the terminal you will work in, point it at DeepSeek (DeepSeek instructions):

# macOS / Linux / WSLexport ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<your DeepSeek API key>export ANTHROPIC_MODEL='deepseek-v4-pro[1m]'export ANTHROPIC_DEFAULT_OPUS_MODEL='deepseek-v4-pro[1m]'export ANTHROPIC_DEFAULT_SONNET_MODEL='deepseek-v4-pro[1m]'export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-flash
export CLAUDE_CODE_EFFORT_LEVEL=max

# Windows PowerShell$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"$env:ANTHROPIC_AUTH_TOKEN="<your DeepSeek API key>"$env:ANTHROPIC_MODEL="deepseek-v4-pro[1m]"$env:ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"$env:ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"$env:CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"$env:CLAUDE_CODE_EFFORT_LEVEL="max"

Run claude from your project directory. These variables persist only in the current shell session. They disappear when that terminal or PowerShell session closes, so existing Claude Code logins and other projects are unaffected.

Choose a project

The project table lists each track and its Level 1 question. Start with the README.md in your chosen project.

Level 1

The default branch, main, contains only Level 1 material. Clone it with:

git clone --single-branch --branch main https://github.com/ntveem/agent-coding-tutorial.git
cd agent-coding-tutorial

Enter one project, for example:

cd projects/non-normal

Start your coding agent from that directory so its project context stays local to the exercise.

Try to complete Level 1 without writing or editing a line of code yourself. Interact only through instructions, specifications, and checks.

Have the agent generate its project-level instruction file when you begin. When it keeps rediscovering the same scientific conventions, commands, or validation rules, tell it to record them there. Common examples are:

• Claude Code: CLAUDE.md, generated with /init
• Codex: AGENTS.md, generated with /init
• Cursor: project rules

Commit your work when Level 1 is in a useful state:

git checkout -b my-work
git add -A
git commit -m "level 1"

You can create my-work earlier if you prefer.

Level 2

When you are done with Level 1, merge the Level 2 reveal into your branch:

git fetch origin reveal/level-2:refs/remotes/origin/reveal/level-2
git merge origin/reveal/level-2

Then read LEVEL2.md in your project.

Your code, tests, notes, project instructions, and Git history remain in place. Level 2 adds several requirements that have to hold at the same time, and its calculations reuse the same components many times. When a piece of machinery appears twice, have the agent turn it into a module that later questions call instead of a fresh chat request. This is also a good stage to have the agent write a short spec and add independent checks; point to both from the instruction file so later sessions find them.

Level 3

When you are done with Level 2:

git fetch origin reveal/level-3:refs/remotes/origin/reveal/level-3
git merge origin/reveal/level-3

Then read LEVEL3.md in your project.

Level 3 has no fixed sequence of calculations. Keep a compact machine-readable record of the current hypotheses, results, failures, open questions, and next tasks. Use that record to decide what to do next. The reveal includes a STATE.md template for this record.

The agent can drive much of this loop itself; review the record rather than the full transcript.

Branch layout

main
Level 1
|
+-- reveal/level-2
adds LEVEL2.md files
|
+-- reveal/level-3
adds LEVEL3.md files

Your working branch evolves separately:

main ---- your Level 1 work ---- merge reveal/level-2 ---- your Level 2 work ---- merge reveal/level-3

Future prompts are absent from the initial checkout. The --single-branch clone also leaves the reveal refs unfetched until you request them.

Working conventions

1. Check scientific results that matter. An agent can write correct-looking code that implements the wrong calculation.
2. External libraries and web searches are allowed.
3. Use tests appropriate to the science: exact limits, conservation laws, symmetries, independent numerical routes, brute-force checks on small cases, or ordinary unit tests.
4. Commit useful states in Git.
5. Add project machinery when it starts saving effort. Level 1 should remain lightweight.
6. Later levels are open enough that useful progress is a reasonable workshop outcome.

Python environment

All exercises are small enough for a laptop and ordinary Python scientific computing. One possible environment is:

python -m venv .venv
source .venv/bin/activate
pip install numpy scipy matplotlib pandas networkx sympy

Most projects use only a subset of these packages.

API cost

A few dollars of API credit covers one project if the conversation stays lean.

1. Keep data out of the chat. Results go to files; the agent reads summaries, not raw arrays.
2. Start a fresh session at each level. The instruction file and your notes carry the context forward.
3. If the agent is stuck repeating a failing step, stop it and change the plan instead of letting it retry.