Three files and the prompts I actually use. Copy them, then change the details to fit your project.
Save it as CLAUDE.md in your project folder (Codex reads AGENTS.md). The agent reads it at the start of every session. A few lines is enough to begin; add one each time something goes wrong.
# [Project name]
Raw data is in [path]. Never modify or delete it.
Write outputs to [path].
Read STATUS.md before starting.
Load software with: [your exact module or conda commands]
A job is finished when its output file has been checked, not when it exits.
Never send an e-mail or message, post, or push to a live site in my name without asking first. "Continue" means more of the same kind of work.
## Things that went wrong before
- [date] A control came back empty and was reported as a pass.Save it as BRIEF.md before any task longer than an hour, and before every overnight run. It is the morning check written in advance, so the result gets compared with what you asked for and not with the agent's summary. Write the "Done when" line first. If you cannot, the task is not ready to hand over.
# Brief: [task] ([date])
Goal: [one sentence]
Inputs (read-only): [paths, with versions]
Done when: [file] exists, has [N] rows, values between [low] and [high]
Decided before seeing results: [filters, thresholds, samples to drop]
If the result were an artifact, it would look like: [your guess, written now]
Before the full run: the check says no to [a known-bad file], and one [sample] is run and checked.
May run without asking: [commands]
Ask first: deleting files, more than [N] jobs, anything outside [path]
If a check fails or an input is missing: stop and write BLOCKED in STATUS.md. Do not change the check.
Known traps: [what went wrong last time]Save it as STATUS.md. Ask the agent to update it after each real step. When a session ends or gets long, the next one starts from here instead of from memory.
# Status ([date])
Goal: [one sentence]
Done when: [which files exist, and what they show]
## Done
- [step]: [output file]
## Open
- [step]: waiting on [what or whom]
## Numbers and where they came from
- [number]: [file], [how it was computed]
## Decisions
- [choice made]: [alternatives tried and dropped], decided [before / after] seeing resultsThe lines I put in a new project's rules file so that the repository stays the record.
## Git
- Commit after every real step, with a message that says what changed and why.
- Quote a commit hash only after the push has succeeded.
- Each session works in its own worktree and branch; never in a checkout another session is using.
- Never commit raw data, large outputs or secrets. Commit a pointer instead: path, size, checksum.
- Anything visual goes in docs/ and is published with GitHub Pages; check the live page, not the local file.Starting a project:
git init my-project && cd my-project
mkdir docs && echo "first rough version" > docs/index.html
git add -A && git commit -m "Start: first rough page"
# create a private repository on github.com, then:
git remote add origin https://github.com/<you>/my-project.git
git push -u origin main
# Settings > Pages > Deploy from a branch > main /docsOne worktree per agent session:
git worktree add ../my-project-fix-figures -b fix-figures
cd ../my-project-fix-figures # start the agent here
git worktree remove ../my-project-fix-figures # when done; the branch staysThe checking procedures I use are packaged as a Claude Code plugin. In Claude Code, run these two lines:
/plugin marketplace add ChenHsieh/agentic-research-toolkit
/plugin install result-checks@agentic-research-toolkitIt adds six skills: check a design for confounds, give a derived statistic a null, try to break a finished result, compare with a second method, trace a data accession to its paper, and the agent playbook. About 1,100 tokens per session until one is used.
Read STATUS.md and the last ten commits. What is done, what is still open, and what is waiting on someone?
Run this check three ways, through the same script the real run uses: on an input built to have the error this check is for (such as shuffled labels), where it should say no; on a copy with only the header line, where it should say no; and on an input with a planted answer, made without the code being checked, where it should say yes. Show me the output each time and the line that calls the check. If it gets any of the three wrong, stop and tell me before changing anything.
What are the three most likely ways this result could be an artifact? Check each one and show me the file for each check.
In an empty folder, rebuild these results using only the Methods text and the raw data. If the text leaves something out, stop and tell me instead of guessing. Finish with a table of each number: expected, what you got, and whether it matched.
Read these papers and tell me which methods they treat as standard. Quote the paper for each claim, with the section. Tell me which papers you could not open.
It is tomorrow morning. This run produced a result that looks convincing but is wrong. List five ways that could have happened. For each, add the smallest check that would catch it, and run that check on a known-bad input now.
Another session worked on this today. Read its commits and output files, not its summary. What was actually done, and what is not supported?
Source ยท text CC BY 4.0