From setup to your first handler

A path for MARIS team members who will create marisco handlers with the help of an AI agent

These pages take you from a new computer to your first handler. You work with Claude Code, an AI agent that reads the marisco code, proposes changes and runs commands for you. On its own, Claude Code is a general-purpose agent. Most of what makes it useful here comes from aai-coding, Answer.AI’s harness for Claude Code, which you install in stage 1 as part of the aai-ws workspace. aai-coding gives the agent the team’s coding and writing conventions, rules for when to act and when to ask you first, and the tools it uses to read, search and edit notebooks.

The agent can write a handler. It cannot understand the handler for you. A handler is only as good as the team’s understanding of it: which quirks of the source data it deals with, why it converts units or maps species names the way it does, and what would break if the data provider changed their format. That understanding is in people’s heads. The code and its documentation record only part of it. Use the agent to build your understanding faster. Ask it to explain code, to show you the data, to compare options and to tell you what you have not yet checked.

You don’t need to write Python from memory. You do need to be able to explain every change you accept: what it does, why it is done this way and not another way, and what else in marisco it affects. If you cannot explain a change, do not accept it, even if it runs. Ask the agent or a colleague until you can. You also approve or refuse each action the agent takes, and you recover when something goes wrong. Stage 3 shows you how.

This way of working comes from Peter Naur’s essay Programming as Theory Building (1985). Naur argues that a program’s real substance is the understanding its developers carry, and that no document can fully record it. aai-coding gives the agent the same idea, in its guidance on what Naur calls a program’s theory.

The path has four stages. Each stage ends with checks that show you are ready for the next one.

  1. Set up your machine: install the terminal tools, Git, uv, Claude Code and the aai-ws workspace, then add marisco to it.
  2. Find your way: what the terminal, Git, GitHub, uv and nbdev do in marisco, and your first pull request. The cheatsheet lists the commands.
  3. Supervise the agent: what to check before you approve an action, when to stop the agent, how to review and undo its work, and when to move to auto mode.
  4. Write your first handler: a small real dataset, from the first look at the data to a reviewed pull request, following Writing a new handler.