Writing research instructions for AutoScholar (the per-paper CLAUDE.md)
A research instruction file is the complete brief for one autonomous research run. It is a product input written for a researcher, not a configuration file: it says what to study, how to study it, what evidence counts, and when the result is acceptable. The platform supplies everything else (sandbox, tools, artifact contract, quality gates, LaTeX class, publication).
What the file is — and is not
- It is loaded verbatim as the project instructions of an isolated Claude Agent SDK workspace on a MacLustr worker. It is frozen and hashed when uploaded; every run references one immutable version.
- It cannot grant permissions, reach credentials, change tools or alter platform rules. Text that targets the platform (sudo, SSH, API keys, "ignore the platform policy", system paths) is rejected at upload.
- Plain Markdown; optional YAML frontmatter with
mode,discipline,title(used to prefill the launch form only).
Required content (12 sections)
- Objective and scope — one precise question; what is in/out; non-goals.
- Domain and mode — discipline; primary mode (
empirical,computational,theoretical,review,experimental,humanities); secondary modes; methodology and why it fits. - Contribution and novelty — expected contribution; closest prior work; novelty in qualified terms.
- Literature/source rules — indexes to search, minimum verified sources, must-read identifiers, claim-to-source mapping.
- Evidence rules — data sources (exact series/tables/licenses), simulations (labelled synthetic), formal objects, corpora.
- Procedure — pre-registered steps; what is confirmatory vs exploratory.
- Baselines, robustness, falsification — what would overturn the claim; which checks are mandatory.
- Reproducibility and artifacts —
code/reproduce.sh, pinned environment, seeds, logs, registered numbers. - Manuscript structure and LaTeX standards — sections, length target (depth over length), figure/table conventions.
- Review, revision, quality — what the independent reviewer should attack.
- Limitations, ethics, legal — constraints the paper must state and respect.
- Acceptance criteria — concrete, checkable conditions for success.
Missing sections are reported as warnings at upload; the run can still start, but vague briefs produce weak papers.
Choosing the mode
| Mode | Use when | Mandatory evidence (publication gates) |
|---|---|---|
| empirical | real data analysis | data manifest with licenses/hashes, executed code with logs, robustness, every reported number traced |
| computational | algorithms/AI/systems | executable benchmark, baselines, seeds, ablations, logs |
| theoretical | proofs/models | formal statements, complete derivations/proofs, counterexample search |
| review | literature synthesis | search strings/dates/counts, screening records, ≥ 10 verified sources |
| experimental | simulations/authorized experiments | protocol, observed-vs-synthetic labelling, uncertainty; human approval required before publication |
| humanities | textual/interpretive | primary-source provenance, quoted evidence with locators |
Medicine, biology, law and psychology always require human approval before publication regardless of mode.
Good practice
- Give exact identifiers (DOIs, arXiv ids, dataset DOIs, API series ids). The literature tool verifies every citation; unverifiable references are never cited.
- Size the study to the budget (default USD 25, 240 minutes) and to a CPU-only node. A small correct study beats an ambitious incomplete one.
- Say explicitly whether synthetic data is allowed. If the only data is simulated, say so and expect the paper to be labelled accordingly.
- State the null-result pathway. Null results are publishable; fabricated positives are not.
- Avoid prescribing agent names, tools or platform internals: describe the science.
Starter templates
research/templates/{general,empirical,theoretical,computational,review}/CLAUDE.md — visible in the admin under Templates ("Use this template" prefills New Research).