View source for AI Agents: A Primer

<!-- TODO: set the category (and sort key) to match where this article lives in the wiki -->
[[Category:AI Tools]]

'''Agentic AI''' tools are AI systems that don't just answer questions: they take actions. An agent can search for papers, read your files, write and run code, launch jobs on a cluster, and look at the results, all in a loop, until the task you gave it is done. For statistical research, the most mature agents today are '''AI coding agents''' such as [https://www.claude.com/product/claude-code Claude Code], OpenAI's Codex CLI, and Google's Gemini CLI. They run in your terminal and work directly on your repository.

These tools can save an enormous amount of time, and they can also waste an enormous amount of time (and money). The difference is almost entirely in how they are used. This article explains how agents work, where their costs come from, and a set of concrete practices for getting good results from them in research.

<div style="background-color: #e8f4f8; border-left: 5px solid #17a2b8; padding: 15px; margin-bottom: 20px; margin-top: 15px; overflow: hidden;">
'''Based on a StatBytes talk'''<br>
This article is adapted from the StatBytes talk [https://drive.google.com/drive/folders/1KnyUo9YNr2XL9N5nJgpzW5jWyulSfTIg?usp=drive_link|''Piloting the Suit: Workflow tips for agentic AI in statistical research'']. A small demo repository that goes with it is at [https://github.com/Alex-Shen-CMU/statbytes-agentic-example github.com/Alex-Shen-CMU/statbytes-agentic-example]. Most examples below use Claude Code, but almost everything applies to other coding agents too.
<br><br>
See [https://github.com/Alex-Shen-CMU/stats-agent-setup https://github.com/Alex-Shen-CMU/stats-agent-setup] for a collection of commonly used agent skills and agent instruction files relevant for statistics research.
</div>

== What Is an Agentic AI? ==
An agent has two parts: a '''large language model (LLM)''' that does the thinking, and a '''harness''' that gives the model a way to act on the world.

{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="width: 50%; background-color: #d6eaf3; color: #1d5670; padding: 10px; text-align: left;" | The LLM (the brain)
! style="width: 50%; background-color: #d4edda; color: #155724; padding: 10px; text-align: left;" | The harness (the body)
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px; border-right: 2px solid white;" |
* '''Text in, text out:''' At its core, the model predicts the next token given everything before it.
* '''Reasons and plans:''' It decides what to do next, including ''which tool to call''.
* '''Stateless:''' It knows only what is currently in its context window. It has no memory of yesterday's session unless something puts that information back in front of it.
| style="padding: 15px;" |
* '''Runs the loop:''' It sends the conversation to the model, receives a tool call, executes it, and sends back the result.
* '''Executes tools:''' Web search, reading PDFs, loading data, running code, editing files.
* '''Manages context and memory:''' It decides what goes into the model's context and loads standing instructions.
* '''Enforces permissions:''' It decides what the agent may do without asking, and sandboxes what it runs.
|}

The model and harness talk through '''tool calls''' and '''observations'''. The model emits something like <code>{search: "Conformal Prediction"}</code>. The harness runs the search and returns "10 results: arXiv, ..." as an observation, which becomes part of the conversation for the next step. Around this exchange sit two more parties: '''you''', who supply the goal, the constraints, and the final judgment, and '''the world''', meaning papers, datasets, your files, compute, and the web.

<!-- SCREENSHOT: Slide "What is an agentic AI?" (final overlay), showing the LLM and harness boxes, the tool-call/observation arrows, and the "You" and "The world" boxes. -->
[[File:Agentic-ai-llm-harness.png|thumb|center|700px|An agent is an LLM plus a harness, connected by tool calls and observations.]]

In one sentence: '''an agent is an LLM in a loop, with tools, running until the task is done.'''

=== The agent loop ===
A single request like "What are the extensions of conformal prediction for dependent data?" becomes many turns of the same loop:

# '''Gather context:''' search for papers, read PDFs, load data.
# '''Take action:''' analyze, compute, draft.
# '''Verify:''' cross-check sources and numbers, run the tests.
# Repeat until the model decides no more tool calls are needed, then hand you a summary and sources to review.

One detail matters a great deal for cost: '''every trip around the loop re-sends the entire conversation to the model.''' This is covered in [[#The Cost of Using Agents|The Cost of Using Agents]] below.

<!-- SCREENSHOT: Slide "The agent loop: one task, many turns" (final overlay), with the gather/act/verify cycle around the LLM, the prompt on the left and "Done" on the right. -->
[[File:Agentic-ai-agent-loop.png|thumb|center|650px|The agent loop: gather context, act, verify, repeat.]]

=== What can agents do? ===
Although they are marketed as coding tools, coding agents are general-purpose research assistants that happen to live next to your code.

{| class="wikitable" style="width: 100%;"
|-
! style="background-color: #d6eaf3;" | Software
! style="background-color: #d4edda;" | Computation and data
! style="background-color: #e6dcf0;" | Research writing and reading
|- style="vertical-align: top;"
|
* '''Write code:''' simulations, samplers, neural estimators
* '''Debug:''' read tracebacks, bisect regressions
* '''Refactor:''' turn a script into a package, port R to Python and back
* '''Write tests:''' unit tests, coverage checks, CI
|
* '''Run experiments:''' launch, monitor, collect results
* '''Analyze data:''' EDA, summaries, diagnostic plots
* '''Make figures:''' iterate on a plot, including from a screenshot of a figure you like
* '''Reproduce:''' re-run a paper's code from its repository
|
* '''Literature:''' search, summarize, compare methods
* '''Write LaTeX:''' fix compile errors, build tables from CSVs
* '''Review:''' check a derivation, revise a paper draft
* '''Admin:''' issues, emails, documentation, READMEs
|}

== AI Coding Agents ==

=== The landscape ===
Coding agents fall roughly into two groups. They share the same core loop, and differ in harness, model, and pricing. '''The landscape changes monthly''', so treat any list like this as a snapshot.

{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="width: 50%; background-color: #f5d5db; color: #7a0b1e; padding: 10px; text-align: left;" | Terminal-native
! style="width: 50%; background-color: #d6eaf3; color: #1d5670; padding: 10px; text-align: left;" | IDE and cloud
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px; border-right: 2px solid white;" |
* '''Claude Code''' (Anthropic)
* '''Codex CLI''' (OpenAI)
* '''Gemini CLI''' (Google)
* '''Aider''', '''OpenCode''' (open source)
| style="padding: 15px;" |
* '''Cursor''': an AI-first editor
* '''GitHub Copilot''': agent mode inside VS Code and other editors
* '''Cline''' and similar editor extensions
* '''Cloud agents''' (Devin, Jules, Copilot coding agent): work on a remote copy of your repository and hand back a pull request
|}

Terminal-native agents are a natural fit for statistics research, because so much of our work already happens in a shell: <code>Rscript</code>, <code>python</code>, <code>make</code>, <code>git</code>, <code>ssh</code>, and Slurm.

=== Core features: read, write, execute ===
Every coding agent is built on three capabilities:

* '''Read''' (<code>cat</code>, <code>grep</code>, <code>glob</code>): navigate the repository and find the 3 relevant files out of your 300.
* '''Write''' (edit, create): make targeted diffs rather than rewriting whole files. You can require approval for each edit.
* '''Execute''' (<code>bash</code>): run <code>Rscript</code>, <code>pytest</code>, <code>make</code>, <code>git</code>, and so on, then '''read the output'''.

The output of each command becomes new context, and the agent iterates until the tests pass. This is the key leap over chat assistants: '''the agent runs the code and sees what happens.''' There is no more copy-paste ping-pong between a browser tab and your terminal.

<!-- SCREENSHOT: Slide "Core features: read, write, execute" (final overlay), showing the three boxes and the loop-back arrow. -->
[[File:Coding-agent-read-write-execute.png|thumb|center|650px|Read, write, execute, and feed the output back in.]]

=== Features beyond the basics ===
Modern harnesses add a lot on top of the core loop:

* '''Web search:''' look up documentation, papers, and error messages.
* '''MCP servers:''' the [https://modelcontextprotocol.io Model Context Protocol] connects the agent to outside services such as GitHub, Slack, Notion, or Zotero.
* '''Test writing:''' unit tests, edge cases, and regression tests.
* '''SSH and Slurm:''' with SSH access configured, the agent can run <code>sbatch</code> and <code>squeue</code> on a cluster and pull results back.
* '''Subagents:''' parallel workers that each start with a fresh context and report back only a summary.
* '''Multimodal input:''' screenshots, plots, and PDFs of papers. The agent can also render a plot and ''look at its own output'' to fix overlapping labels before you ever see it.
* '''Memory files:''' <code>CLAUDE.md</code> (or <code>AGENTS.md</code> for some other agents) holds your project conventions and is loaded into every session.
* '''Skills and hooks:''' reusable workflows and automatic actions (see [[#Skills|Skills]] below).

<!-- SCREENSHOT: Slide "A wealth of features beyond the basics" (final overlay), the wheel of eight feature boxes around "Coding agent". -->
[[File:Coding-agent-features.png|thumb|center|650px|Features modern coding agents provide on top of the core loop.]]

== The Cost of Using Agents ==
Agents have two costs: '''tokens''' (money and usage limits) and '''your time'''. They are linked, since a confused agent burns both, but they are not the same thing. A cheap, fast agent can still waste your afternoon.

=== Tokens ===
Recall that every turn of the loop re-sends the whole conversation. If the context grows by a roughly constant amount each turn, then '''the context size grows linearly and the total number of tokens processed grows quadratically''' in the number of turns. Prompt caching lowers the price of re-reading earlier context, but it does nothing about the context window's hard limit.

<!-- SCREENSHOT: Slide "The cost of AI, part 1: tokens" (final overlay), with the linear vs. quadratic pgfplots figure and the token-sink boxes. -->
[[File:Agent-token-cost.png|thumb|center|700px|Context grows linearly, total tokens grow quadratically.]]

The biggest token sinks are:

* '''Long contexts:''' every turn re-reads the whole history.
* '''Dumping big outputs:''' a 50,000-line log, a full CSV, or <code>print(model)</code> on a large object, all of which stay in context for every later turn.
* '''High reasoning effort:''' thinking tokens are billed too.
* '''Open-ended prompts:''' the agent explores the whole repository to guess what you meant.
* '''Lost threads:''' re-explaining everything after the context is compacted, polluted, or gone because you started a new session.

=== Context rot ===
The context window is the agent's entire working memory. In a long session it fills up with a system prompt, memory files, and your task, plus a lot of noise: files it read that turned out to be irrelevant, logs and tracebacks, failed attempts, and old tangents. The useful work is often a small slice at the end.

That noise costs tokens on every turn, and it '''also degrades quality'''. Models get measurably worse as their context fills with irrelevant material (often called "context rot"). They lose instructions given early in the session, repeat fixes that already failed, and contradict earlier decisions. Eventually the agent hits the context limit and has to compact (summarize) its history, which loses detail.

<!-- SCREENSHOT: Slide "Anatomy of a full context window" (final overlay), the colored bar with sys./mem./task/files/logs/tangent/work segments and the "context rot" box. -->
[[File:Agent-context-window.png|thumb|center|700px|A full context window is mostly noise.]]

=== Your time ===
Where does the wall-clock time of a "2-hour" agent session actually go? In an inefficient session, most of it goes to clarifying, waiting, back-and-forth, and fixing things. In an efficient one, you spend a few minutes on a spec and a plan, the agent does the work in the background, and you spend a few minutes reviewing the diff.

<!-- SCREENSHOT: Slide "The cost of AI, part 2: your time" (final overlay), the inefficient vs. efficient timeline bars and the four time-sink boxes. -->
[[File:Agent-time-cost.png|thumb|center|700px|Where the time goes in an inefficient vs. an efficient session.]]

The main time sinks are:

* '''Wrong direction:''' the agent confidently builds the wrong thing, and you notice 30 minutes later.
* '''Opaque code:''' you end up debugging 600 lines you didn't write and don't understand.
* '''Memory loss:''' sessions don't share context, so threads get lost and rebuilt repeatedly.
* '''Ambiguity ping-pong:''' a vague ask produces a vague result, so you ask again.

== The Role of the Researcher ==

=== A common misconception ===
Because agents ''talk'' like humans, it is tempting to assume they ''think'' like humans, and to treat them as a colleague who shares your intuitions and background. This leads to underspecified requests and surprising results.

A more useful mental model: '''we have found a way to write computer programs in natural language.''' Your prompt is source code. Like any program, it does what you ''wrote'', not what you ''meant''. Each step from assembly to C to Python/R to English has made programming higher-level and easier to write, but every step is still programming.

<!-- SCREENSHOT: Slide "Effective usage: a misconception" (final overlay), the misconception/reality boxes and the Assembly → C → Python/R → English ladder. -->
[[File:Agent-misconception.png|thumb|center|650px|Prompts are programs written in English.]]

=== You still need to understand code ===
Using AI for statistics research still requires knowing statistics, or you can't tell a valid result from a confident hallucination. In the same way, using AI for code still requires knowing how code works, or you can't tell a good design from 3,000 lines of spaghetti.

You don't need to write every line yourself, but you do need to know enough to:
* specify the architecture you want,
* read a diff,
* spot a silent bug, and
* say "no, do it this way."

<!-- SCREENSHOT: statbytes_figures/woops.png from the slides ("Don't be that guy"). -->
[[File:Agent-dont-be-that-guy.png|thumb|center|450px|What happens when nobody reviews the agent's work.]]

=== Agentic AI is an Iron Man suit ===
A good way to think about the division of labor is an Iron Man suit:

{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="width: 50%; background-color: #f5d5db; color: #7a0b1e; padding: 10px; text-align: left;" | The pilot (you)
! style="width: 50%; background-color: #d6eaf3; color: #1d5670; padding: 10px; text-align: left;" | The suit (the agent)
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px; border-right: 2px solid white;" |
* Where to go
* What "done" means
* What is ''correct''
* When to abort
* Taste and judgment
| style="padding: 15px;" |
* Speed
* Stamina (it works 24/7)
* Breadth of knowledge
* Boilerplate at scale
* Tireless retries
|}

A great suit makes a skilled pilot '''superhuman'''. It makes an unskilled pilot crash '''faster'''.

== Best Practices ==

=== Saving tokens ===
{| class="wikitable" style="width: 100%;"
|-
! style="width: 22%; background-color: #f8d7da; color: #721c24;" | Problem
! style="background-color: #d4edda; color: #155724;" | Fix
|-
| '''Long contexts'''
| '''One task per session.''' Use <code>/clear</code> between tasks, and <code>/compact</code> with a note on what to keep when you need to continue. A fresh context is cheaper ''and'' smarter.
|-
| '''Big outputs'''
| '''Keep irrelevant data out of the context.''' Use <code>grep</code> or <code>tail</code> on logs, summarize data with <code>head()</code> or <code>str()</code>, and write results to files instead of printing them. Delegate noisy searches to a '''subagent''' that returns only a summary.
|-
| '''Reasoning effort'''
| '''Match effort to the task:''' low for renames and typos, high for design decisions and nasty bugs. Use a smaller, faster model for grunt work.
|-
| '''Needless exploring'''
| '''Say where to look.''' Point at files (<code>@R/sampler.R</code>) and name functions. Don't make the agent search for things you already know.
|-
| '''Going off track'''
| '''Interrupt early''' with <code>Esc</code>. <code>Esc Esc</code> or <code>/rewind</code> rolls back to a checkpoint. Restarting from a good state beats a long correction thread.
|-
| '''Lost threads'''
| '''Persist state outside the chat:''' <code>CLAUDE.md</code> for conventions, a <code>PLAN.md</code> checklist for multi-session work, and GitHub issues or markdown files for the backlog.
|}

=== Saving time ===
{| class="wikitable" style="width: 100%;"
|-
! style="width: 22%; background-color: #f8d7da; color: #721c24;" | Problem
! style="background-color: #d4edda; color: #155724;" | Fix
|-
| '''Unclear goal'''
| '''Say what done looks like:''' the goal, the constraints, and a concrete check ("done when the tests pass and the estimates match <code>lm()</code>"). '''Tell it to ask follow-up questions''' before starting.
|-
| '''Wrong direction'''
| '''Plan first.''' Use plan mode, or say "propose a plan, don't edit yet." Reviewing a 10-line plan beats reviewing a 600-line diff.
|-
| '''Opaque code'''
| '''Take small steps''' and commit each one. Ask for '''tests first''', then the implementation. Ask the agent to explain any change you don't follow.
|-
| '''Repeating yourself'''
| '''Package recurring workflows''' as skills or custom slash commands (e.g. <code>/simstudy</code>; see [[#Skills|Skills]]). Use hooks to run formatters or linters automatically after edits.
|-
| '''Babysitting'''
| '''Use auto mode.''' Allow-list safe commands (<code>pytest</code>, <code>git diff</code>, <code>Rscript</code>). Run in a sandbox or container if you want to give the agent more autonomy.
|-
| '''Waiting'''
| '''Run it in the background''' (e.g. in <code>tmux</code>) and do other work. Run parallel sessions on separate <code>git worktree</code>s for independent tasks.
|}

=== Prompts as specs ===
Since prompts are programs, write them like specifications. Compare:

<div style="background-color: #f8f9fa; border-left: 4px solid #C0392B; padding: 15px; margin-bottom: 10px;">
'''Vague:'''
<pre>
> make the simulation faster
</pre>
The agent reads 40 files, rewrites the random number generator, parallelizes the wrong loop, and breaks reproducibility. An hour later your session usage is gone and the result is unusable.
</div>

<div style="background-color: #f8f9fa; border-left: 4px solid #2E8B57; padding: 15px; margin-bottom: 10px;">
'''Structured:'''
<pre>
> Goal: speed up simulate_paths() in @src/sim.py; it is 90% of runtime.
  Context: profile output in prof.txt. The inner loop over t is pure Python.
  Constraints: keep the seeded RNG stream identical; no new dependencies
  beyond numba.
  Done when: tests/test_sim.py passes and bench.py shows >=5x speedup.
  First: propose a plan and ask me any questions before editing.
</pre>
</div>

A good prompt has five parts: the '''goal''', the relevant '''context''' (and where to find it), the '''constraints''', a checkable '''definition of done''', and an instruction to '''plan and ask questions first'''.

== Skills ==

=== The problem skills solve ===
After a few weeks with an agent, you will notice that you keep typing the same instructions. Every simulation study needs the same seeding conventions, the same output format, and the same summary table. Every figure should use the same theme and fonts. Every Slurm script needs the same partition and module setup. You have two obvious options, and both are bad:

* '''Retype the instructions every time.''' This is tedious, and you will forget something, so results drift from one session to the next.
* '''Put everything in <code>CLAUDE.md</code>.''' The memory file is loaded into ''every'' session, so a long list of procedures costs tokens on every turn of every task, including the ones that have nothing to do with simulation studies. It also adds to the noise that causes context rot.

'''Skills''' are the middle ground: packaged, reusable instructions that are '''available in every session but loaded only when needed'''.

=== How skills work ===
A skill is a folder containing a <code>SKILL.md</code> file, optionally with supporting files such as templates, reference documents, or scripts. In Claude Code, project skills live in <code>.claude/skills/&lt;skill-name&gt;/</code> inside the repository (so they are shared with everyone who clones it), and personal skills live in <code>~/.claude/skills/</code>.

The <code>SKILL.md</code> file starts with a short header giving the skill's name and a description of when to use it:

<pre>
.claude/skills/simstudy/
├── SKILL.md
├── templates/
│   ├── run_sim.R
│   └── simstudy.slurm
└── scripts/
    └── summarize_results.R
</pre>

<pre>
---
name: simstudy
description: Set up, run, and summarize a Monte Carlo simulation study.
  Use when the user asks to design or run a simulation study, compare
  estimators by simulation, or summarize simulation results.
---

# Simulation studies

1. Before writing code, confirm with the user: the data-generating
   process, the estimators being compared, the parameter grid, and the
   number of replications.
2. Copy templates/run_sim.R. Each replication takes (scenario, rep_id)
   and seeds with set.seed(1e5 * scenario + rep_id).
3. Write one .rds file per scenario to results/raw/. Never print raw
   results to the console.
4. Run a 10-replication smoke test locally before submitting anything.
5. Submit with templates/simstudy.slurm as an array job, one task
   per scenario.
6. Summarize with scripts/summarize_results.R: bias, RMSE, coverage,
   and Monte Carlo standard errors for each.
</pre>

The key mechanism is '''progressive disclosure'''. At the start of a session, the agent sees only the name and description of each skill, which costs a few dozen tokens apiece. When a request matches a description, the agent reads the full <code>SKILL.md</code>, and it opens the templates or runs the scripts only when it reaches the step that needs them. You can have dozens of skills installed at almost no standing cost. You can also invoke a skill directly by name, for example by typing <code>/simstudy</code>.

Because skills can bundle scripts, they also let the agent ''run'' a deterministic tool instead of ''regenerating'' its logic each time. A summary script that always computes Monte Carlo standard errors the same way is more reliable than asking the model to rewrite that code in every session, and it saves tokens too.


<div style="background-color: #f8f9fa; border-left: 4px solid #005A9C; padding: 15px; margin-bottom: 10px;">
'''Skills, CLAUDE.md, and hooks:''' Use <code>CLAUDE.md</code> for short facts that are true in every session ("this project uses renv", "never run heavy jobs on the login node"). Use a '''skill''' for a procedure that is needed only for certain tasks. Use a '''hook''' for something that must ''always'' happen after a given action, such as running <code>styler</code> after every edit to an R file. Hooks are enforced by the harness, while skills and memory files are instructions the model may or may not follow perfectly.
</div>

=== Example skills for statistics research ===
{| class="wikitable" style="width: 100%;"
|-
! style="width: 20%;" | Skill
! What it packages
|-
| '''Simulation study'''
| The data-generating process / estimator / replication layout, seeding conventions, file outputs, Slurm array template, and a standard summary of bias, RMSE, coverage, and Monte Carlo error.
|-
| '''Paper figures'''
| Your plotting theme, font sizes matched to the paper's column width, colorblind-safe palette, and export settings (vector PDF, correct dimensions). Can include a script that checks for overlapping labels.
|-
| '''LaTeX tables'''
| Turning a CSV of results into a <code>booktabs</code> table with consistent rounding, bolded best entries, and standard errors in parentheses.
|-
| '''Cluster jobs'''
| The department cluster's partitions, module loads, resource defaults, and etiquette rules, plus how to check on and resubmit failed array tasks.
|-
| '''R package check'''
| Running <code>devtools::document()</code>, <code>devtools::test()</code>, and <code>R CMD check</code>, and fixing NOTEs and WARNINGs in a fixed order.
|-
| '''Reproducibility audit'''
| A checklist for a project before submission or code release: pinned environments (<code>renv</code> / <code>uv</code>), seeds, hard-coded paths, and whether a clean clone reproduces every figure.
|-
| '''Paper reading notes'''
| A fixed template for summarizing a paper: setting, assumptions, main result, proof technique, and how it relates to your work. Useful for building a consistent literature file.
|-
| '''Referee report'''
| Your structure for reviewing a manuscript, from summary through major and minor comments, with a reminder to check derivations and simulation designs.
|}

=== Tips for writing skills ===
* '''The description is what triggers the skill.''' Write it as "what this does, and when to use it", using the words you would actually type in a request. A skill with a vague description will never be picked up.
* '''Keep <code>SKILL.md</code> short.''' Put long reference material in separate files and tell the agent when to open them.
* '''Write the skill after doing the task by hand once.''' Do the workflow with the agent interactively, then ask it to turn the session into a skill and edit the result.
* '''Commit project skills to the repository''' so collaborators (and their agents) follow the same conventions.
* '''Only install skills from sources you trust.''' A skill can contain scripts that the agent will run, so read third-party skills before installing them.
* '''Check your agent's documentation.''' The skill format has been adopted by several coding agents besides Claude Code, but locations and details vary between tools and change over time.

== Running Agents on a Remote Server ==
Agents are most useful when they can run unattended, so it pays to run them somewhere that stays on. A simple setup is to run the agent inside a <code>tmux</code> session on an always-on department server, with your laptop (or phone) serving only as a window into it:

* '''tmux:''' start a session with <code>tmux new -s claude</code>, detach with <code>Ctrl-b d</code>, and reattach from anywhere with <code>tmux attach -t claude</code>. The agent keeps working when you close your laptop.
* '''SSH:''' set up passwordless key-based authentication and put host details in <code>~/.ssh/config</code>, so the agent can reach the cluster without ever seeing a password prompt.
* '''Shared server etiquette:''' the agent edits code and submits jobs; the cluster does the computing. Never let an agent run heavy computations on a shared login or interactive server.
* '''Git is your undo button:''' work on branches, protect <code>main</code>, and review every change before it is merged.

For a complete end-to-end workflow built on this setup, in which tasks are written as GitHub issues and the agent plans, implements, runs experiments on the cluster, and opens a pull request for review, see [[Agentic Workflow via GitHub Issues]].

== What Goes in CLAUDE.md ==
<code>CLAUDE.md</code> sits at the root of the repository and is read at the start of every session. Keep it short, specific, and limited to things that are true for every task. An example:

<pre>
# Project: statbytes-agentic-example

## Cluster
- ssh: user@cluster (keys already set up)
- The cluster runs Slurm. Relevant partitions: ...
- Never run heavy jobs on the department server.
- Do not commit Slurm scripts.

## Conventions
- One branch per task.
- Never force-push; never touch main.
- Don't guess; ask clarifying questions.
</pre>

Things that belong elsewhere: long procedures (make them [[#Skills|skills]]), anything secret such as passwords or tokens (never put these in the repository), and task-specific plans (put them in a <code>PLAN.md</code> or an issue).

== Common Pitfalls ==
{| style="width: 100%; border-collapse: collapse; margin-bottom: 10px;"
|-
! style="background-color: #f8d7da; color: #721c24; padding: 10px; text-align: left;" | Things to Watch Out For
|- style="vertical-align: top; background-color: #f8f9fa;"
| style="padding: 15px;" |
* '''Merging code you haven't read:''' The agent's code is your code once it is in your paper. Review every diff, and ask for explanations of anything you don't follow.
* '''One endless session:''' Long sessions get more expensive per turn ''and'' worse in quality. Start fresh for each task.
* '''Printing everything:''' Large outputs stay in context for the rest of the session. Write to files and summarize.
* '''Vague requests:''' "Make it better" gets you something different, not necessarily better. Give a goal, constraints, and a definition of done.
* '''Letting it run unchecked on shared resources:''' Allow-list commands deliberately, and keep heavy computation on the cluster's compute nodes.
* '''Giving it more access than it needs:''' Scope tokens (e.g. GitHub) to a single repository, keep secrets out of the repository, and protect your <code>main</code> branch.
* '''Bloated memory files:''' Every line of <code>CLAUDE.md</code> is paid for on every turn. Move procedures into skills.
|}

<div style="background-color: #e8f4f8; padding: 15px; text-align: center; margin-top: 20px; font-style: italic;">
'''Note:''' The tools change quickly, but the principles here don't: keep the context small and focused, write prompts like specifications, plan before building, and stay the pilot. For a full worked example, see [[Agentic Workflow via GitHub Issues]] and the [https://github.com/Alex-Shen-CMU/statbytes-agentic-example demo repository]. <!-- TODO: fix this link to match the actual title of the GitHub issue workflow article -->
</div>