Cairn

Cairn is a working method for scientists developing software with AI coding agents. It brings together project rules, written proposals, review, testing, and a record of decisions kept alongside the code.

Research software often outlives the conversation that produced it. Someone still needs to know why an assumption was made, what a change was checked against, and what remains uncertain. Cairn gives that information a home in the repository, so work can continue across sessions, tools, and collaborators.

Try a small example · See a toy example · Read the workflow · Browse the methodology · Project site

What it provides

• Project instructions and templates that agents can read and you can edit.
• A way to discuss substantial changes before committing to their implementation.
• Written reviews that question assumptions and check the work against evidence.
• A plain-language writing standard for how agents report to you: Cairn Plain Language puts the conclusion first, keeps what was measured apart from what was assumed, and says what was not checked.
• Guidance for testing, documentation, security, and scientific-software practice.
• A versioned record of decisions, unfinished work, and context for the next session.
• Installation and update tools for adapting the method to a particular project.

Cairn is a set of files and local tools, not a hosted development service. It works with different agent tools and programming languages. You can use the written guidance on its own or install the templates and supporting tools.

How the work moves

Not every change needs the same process. Before anything is written, a change is sorted into one of three lanes, and only the heaviest one carries a proposal and a plan:

For a substantial change, the deliberate lane:

1. Write a proposal explaining the problem, the proposed change, alternatives, and what would show it wrong.
2. Have it reviewed while the design can still change.
3. The human Maintainer decides whether to proceed. Non-trivial work gets a plan with acceptance criteria.
4. Implement the change and record the checks actually run, including failures and omissions. Review the code before closing the work.
5. Keep the proposal, reviews, responses, and decision in git with the code.

Security-sensitive work has additional requirements. The lifecycle describes how a change is sorted and where those boundaries sit.

Review is by a fresh reviewer who did not write the work. A fresh session of the same AI tool is sufficient. The Maintainer can request another model or a person for a particular review. Each review records who wrote it and the evidence it considered. The review guidance gives the questions to ask at each stage.

The written record is useful in its own right. It lets you revisit a decision, pick up unfinished work, or understand a scientific assumption without needing the original chat. It is also work to maintain: if the process obscures the change or costs more attention than it saves, it needs to be simplified.

A toy example: asking for a new feature

This is an illustration, not a record from a real project. You ask your agent: "Check the model's simulated streamflow against the stream-gauge records, so we can see how well it matches reality." That is a new capability, with a new dataset, so it takes the full path. Here is what happens, and who does it:

Step	Who	What happens
1. Proposal	The agent, before any code	Writes one short file. Why: validation is done by hand in a notebook today, so it is rarely rerun after the model changes. The change: read daily discharge records for each gauge, match each gauge to its model stream reach, and report the fit (Nash–Sutcliffe efficiency and percent bias) for each one. The assumptions, stated: gauges report cubic feet per second and the model cubic metres per second; missing days are skipped, never treated as zero. Rejected: keeping the notebook, because its results cannot be repeated after each change. How a mistake would show up: see step 5.
2. Review	A fresh agent session that did not write it	Asks: "Gauge records flag days as ice-affected or estimated. Are those compared as if they were measured?" The author revises: flagged days are left out of the fit, and the report says how many were left out.
3. Decision	You	Accept, and add one requirement from your own experience: the report also lists the date range each gauge covers, so a short record is never mistaken for a good fit.
4. Plan	The agent, then a fresh reviewer	Splits the work into steps (reader, matching, statistics, report) with how each will be checked. The reviewer confirms the plan delivers what you accepted, including your added requirement.
5. Build	The agent	Writes each piece with its tests and documentation. Before trusting the fit statistics on real gauges, it runs them on made-up series whose scores the formulas fix in advance: a series compared with itself must score an efficiency of exactly 1 and a bias of 0, and a flat line at the observed average must score exactly 0. (No real model scores 1; these inputs test the arithmetic, not the model.) A gauge reading of 35.3147 cubic feet per second must arrive as 1.0 cubic metre per second. Then it skips the unit conversion on purpose and records that the check fails, which shows the check can catch that mistake.
6. Code review	A reviewer who did not build it	Tries to break it with a record that has gaps, a record that starts before the model run, and two gauges on one reach, and records what was tried and what happened.

Afterwards your repository holds the new code and its tests, plus the proposal, the review, your decision and the plan, all in git. Next spring, when a colleague asks "why are ice-affected days left out of the fit?", the answer is in the review: who raised it, and why. It is a file they can open, not a chat that has gone.

A small fix skips most of this: a typo or a one-line bug is just the change and its test, with no code review. For real files from a small change, see the scientific example, where a reviewer confirms which test catches a flipped sign in a water-budget formula.

Engineering practice and scientific judgment

Cairn gives agents a common set of working instructions: test the behavior being changed, check claims against the files and results, keep changes reviewable, and ask for a human decision where one is required.

For scientific software, those instructions also need the project's domain knowledge. A passing test does not establish that a model represents the right physical process. Units, conservation laws, reference data, numerical tolerances, and the limits of an interpretation need explicit checks and explanation.

So a change that touches a scientific assumption, such as a governing equation, a unit or sign convention, a boundary condition or a parameter default, names one check whose expected answer does not come from the code or from a test written from the same understanding. The implementer then makes the feared mistake on purpose and records that the check fails. The proposal template sets out what the check must state.

The scientific example shows the workflow around a mass-balance test. The rationale explains the research and experience behind the method, including its limitations.

Adapt it to your project

A short analysis script and a long-lived simulation model need different amounts of structure. Cairn uses project profiles (solo-greenfield, collaborative-team, high-rigor-legacy) and optional modules to choose what gets installed. Start with the smallest configuration that fits the work.

An install writes ordinary files into your repository:

• AGENTS.md and VENDOR.md — the operational rules your agent reads (VENDOR.md is renamed to the file your tool loads automatically, such as CLAUDE.md or GEMINI.md).
• dev/ — templates for proposals and plans, roadmap boards, and one guide per installed module, plus dev/.cairn/ to store the lockfile and install state.
• tools/ and scripts/ — standard-library Python helpers for session handoffs (tools/session.py), reading the board (tools/board.py), coordinating file edits (tools/intent.py), checking file and line citations (scripts/claim_check.py), checking Markdown links (scripts/link_check.py), and scanning agent-instruction files (scripts/run_portable_security_sweeps.py).

Your project conventions and local instructions remain yours to change. Updates use a three-way merge so local customizations are retained, with conflicts resolved explicitly.

See the on-ramp for choosing a profile, tool usage for the command-line helpers, and the glossary for unfamiliar terms. Useful adaptations can be proposed back to Cairn.

Getting started

What you need: Python 3.13+, Git, and any AI coding agent that can read and write files in a directory. Cairn uses only the Python standard library (zero third-party packages).

Try it on a disposable repository. The quickstart walks through one small change with one human and one agent. The getting-started guide explains the steps in more detail. The guides map everything else to read.

Then choose how much to adopt:

• Read the guidance. Use the doctrine as a handbook without installing anything.

• Install it into a project. Copy a starter profile from bootstrap/profiles/, preview what it will write, and run the installer (full walkthrough in the bootstrap procedure):

  python bootstrap/scaffold.py --config profile.yml --target /path/to/your-repo --summary
  python bootstrap/scaffold.py --config profile.yml --target /path/to/your-repo
  

For an existing scientific codebase, the readiness report helps identify gaps in tests, data handling, reproducibility, and scientific assumptions before choosing a configuration.

Status and limits

Cairn is in active development. The most recent version listed in the changelog is 0.5.0 (2026-10-28).

Cairn was developed by Anthony Kendall through work on modflow_tools and LHM, and this repository uses the method for its own development. These are deployments by the same human maintainer, not independent adoptions.

There is no controlled study showing that Cairn improves development outcomes. An adoption by someone outside its development remains an outstanding test; no outside project has run the install yet. The method draws on established practices, but its benefits and costs need to be judged in use. Related practices describes the overlap with decision records, lab notebooks, pre-registration, and code review.

Safety

AI coding agents can read files, run commands, and send repository content to their model provider. Keep secrets, credentials, private paths, embargoed datasets, and unpublished results out of agent-readable material. Check the permissions and data-handling terms of the agent you use.

Cairn's scanners and integrity checks have limits; a clean result is not proof that a file or operation is safe. Read the security statement before installing third-party instructions or running agents on sensitive work.

Repository guide

Directory	Contents
doctrine/	The methodology: decisions, review, roles, session continuity, and rationale.
templates/	Instructions, document templates, and optional modules installed into a project.
dimensions/	How the configuration varies with the codebase and team.
bootstrap/	Installation, upgrades, integrity checks, and their tests.
docs/	Start here: a map of the guides.
examples/	Small repositories showing the workflow.
case-studies/	Accounts of using Cairn in research-software projects.
dev/	Cairn's own proposals, plans, strategy, and development record.

License and citation

Source code is MIT licensed, wherever it lives. Prose, document templates, and explanatory diagrams are CC BY 4.0. The Cairn brand mark alone is CC BY-ND 4.0.

If you use Cairn, see CITATION.cff for citation details. Cite using the DOI (10.5281/zenodo.23500751) or the version and repository URL.