Appendix A. Project scaffolds and starter files
Appendix A. Project scaffolds and starter files
This appendix provides scaffolds that describe project folder layouts and templates with starting text for project context files and global user instructions. Give the agent a suitable scaffold or template and describe your project. Ask it to create or adapt the files to your needs, preserving any existing organization that works well. If you are unsure where the folders or files belong, ask the agent to suggest suitable locations.
Research paper projects can benefit from all five project context files below. Other projects may need a different set. Ask the agent to adapt these files or create additional ones to suit your workflow. The templates are generic; Chapter 10: The example research project provides a completed paper project with populated files. Chapter 6: Organize your research projects explains the layouts, and Chapter 9: Use skills for recurring tasks explains reusable setup.
| Resource | Purpose or location | Download |
|---|---|---|
| Project scaffolds | ||
| Research paper | Data, analysis, results, and manuscript. | Get file |
| Dataset | Collection, processing, checks, and releases. | Get file |
| Website | Editable pages, assets, and generated site. | Get file |
| Project context files | ||
| CLAUDE.md | Instructions and file locations, inside the project. | Template |
| STATUS.md | Current state, inside the project. | Template |
| TASKS.md | Work remaining and completed, inside the project. | Template |
| SPECIFICATION.md | Current scientific requirements, inside the project. | Template |
| METHODOLOGY.md | Dated scientific decisions and reasons, inside the project. | Template |
| Global user instructions | ||
| CLAUDE.md | Defaults across projects, in ~/.claude/CLAUDE.md. |
Template |
| Version control | ||
| Git exclusions | Files excluded from version control, in the project’s .gitignore. |
Template |
The tilde (~) means your home folder. The project CLAUDE.md belongs in the project’s main folder; global user instructions belong in ~/.claude/CLAUDE.md. Ask the agent to check whether these files already exist. If they do, have it use them as the starting point and adapt the templates to your needs, preserving your existing instructions. Access controls are configured separately, as explained in Chapter 4: Control what the agent can do.
These instruction templates also work with other agents. Codex, for example, uses AGENTS.md instead of CLAUDE.md. Ask your agent to adapt the template and save it with the filename and location it expects. The filename depends on the agent software, including when it uses a locally running LLM.
A.1 Project scaffolds
Research paper
Download the research paper scaffold
Read the paper layout and setup instructions
This layout keeps original inputs, reusable analysis code, exploratory work, and manuscript results distinct. Have the agent retain only the folders the study needs and use the project’s analysis language.
paper-project/
README.md
CLAUDE.md
STATUS.md
TASKS.md
SPECIFICATION.md
METHODOLOGY.md
data/
raw/
processed/
code/
_startup/
_data-acquisition/
_experiments/
_final/
outputs/
figures/
working/
final/
models/
results/
tables/
manuscript/
docs/
references/
notes/
Keep original inputs in data/raw/; save transformations in data/processed/. Reusable setup and functions belong in code/_startup/, while independently runnable analysis scripts sit directly in code/. The other code folders separate acquisition, exploratory work, and assembly of manuscript figures. Save results under outputs/ and manuscript drafts under manuscript/.
Give this layout to the agent with the research question, intended outputs, analysis language, and the folder where the project should be created. Ask it to adapt the layout, describe the project in README.md, and write navigation and maintenance instructions in CLAUDE.md. It should populate STATUS.md and TASKS.md from the current work, SPECIFICATION.md from your approved scientific requirements, and METHODOLOGY.md with dated decisions and reasons, newest first. Unresolved methods should remain questions. After an approved scientific change, the agent should update both scientific files. Have it preserve existing work and check that the paths it records point to the right locations.
Dataset
Read the dataset layout and setup instructions
This layout suits a dataset collected, processed, and released for reuse by several studies, with a separate location for each release.
dataset-project/
README.md
CLAUDE.md
STATUS.md
TASKS.md
scripts/
data/
sources/
processed/
checkpoints/
validation/
outputs/
releases/
reports/
docs/
source-records/
data-dictionary.md
notes/
Preserve downloads unchanged in data/sources/. Acquisition, processing, and checking scripts belong in scripts/; save intermediate datasets in data/processed/. Collection checkpoints let interrupted acquisition resume. data/validation/ holds comparison material used to check the data. Document each source and its acquisition in docs/source-records/.
Save each release in a named subfolder of outputs/releases/, with its data dictionary, source versions, and checks. A paper using that dataset should record which release it used. Access and release arrangements must match the data’s permitted uses.
Give this layout to the agent with the data sources, intended users, access restrictions, and the folder where the project should be created. Ask it to adapt the structure to the collection and release process and create the folders and project context files. It should preserve existing files, record unresolved decisions, and check that the instructions identify the right inputs, scripts, and release locations.
Website
Read the website layout and setup instructions
This layout separates editable material from the generated website. Have the agent adapt the folder names to the chosen website software.
website-project/
README.md
CLAUDE.md
STATUS.md
TASKS.md
DESIGN.md
source/
assets/
images/
styles/
output/
docs/
notes/
The agent writes pages in source/ and keeps images and styles in assets/. The build produces the viewable site in output/; lasting edits belong in the sources so they survive the next build. Have the agent record preview and build commands in README.md, along with where the site will be published.
Give this layout to the agent with the site’s purpose, audience, software if already chosen, and the folder where the project should be created. Ask it to create the structure and project context files and check that the preview uses the intended pages and assets. Publishing the site is a separate task.
A.2 CLAUDE.md: Project instructions
Ask the agent to adapt this template and save it as CLAUDE.md in the project’s main folder. It should describe the actual work, identify the important paths, and include only files the project uses. Chapter 7: Give the agent context for your project explains how to use a maintained AGENTS.md instead.
Download the project CLAUDE.md template
Read the CLAUDE.md template
# [Project name]
[Describe the research question, purpose, and intended outputs.]
[Adapt the paths and file list below to the project. Keep unresolved choices
explicit; do not invent research decisions to complete this template.]
## Read first
- STATUS.md: current state and next decision.
- TASKS.md: work remaining and dated completions.
- SPECIFICATION.md: current scientific requirements; follow it when implementing
or checking the analysis.
- METHODOLOGY.md: dated scientific decisions and their reasons; consult it when
the rationale or history matters.
## Files
- data/raw/: approved original inputs; preserve unchanged.
- code/: saved analysis and validation steps.
- outputs/: saved results, figures, and checks.
- manuscript/: text linked to the saved outputs.
- README.md: actual commands and environment restoration instructions.
## Working rules
- Follow the written specification. Report missing inputs or ambiguities.
- Do not invent observations, alter the estimand, or weaken a failed check.
- Save full-precision results; apply rounding only for presentation.
- Keep exploratory work, simulations, and manuscript results distinguishable.
- Record the exact input and software versions used.
- Inspect changed outputs and record verification before reporting completion.
## Maintain project context files
- Read STATUS.md and TASKS.md before starting; check relevant project files.
- Update the task list as work starts, finishes, or becomes blocked.
- Keep STATUS.md a short account of the current state, not a running history.
- When the researcher approves a scientific change, rewrite SPECIFICATION.md
to reflect the current requirements and add a dated entry at the top of
METHODOLOGY.md explaining the decision, reason, and specification change.
- Preserve older decisions and frozen specifications used for completed runs.
- Keep unfinished work, failed checks, and unresolved questions explicit.
## Access
[Identify approved inputs, storage, and services, and any restrictions on use.]
Ask before adding external services or publishing. These instructions do not
enforce file or network permissions; configure access controls separately.
A.3 STATUS.md: Current state
Have the agent create STATUS.md and rewrite it as the work changes, keeping a short snapshot of what exists, what has been checked, and what comes next. Task history belongs in TASKS.md; scientific reasoning belongs in METHODOLOGY.md.
Read the status template
# STATUS
Last updated: [date]
## Current state
[What exists and what the evidence establishes. Keep this a short snapshot.]
## Next decision or action
[The next substantive step and any required input.]
## Blocked or unverified
[Missing inputs, unresolved decisions, or claims not yet checked.]
## Standing facts
[A few facts needed to resume. Keep decisions and their reasons in METHODOLOGY.md.]
A.4 TASKS.md: Work to do and completed
Have the agent create TASKS.md, move tasks as their status changes, and date completed entries. Keep enough detail to resume unfinished work without turning the file into a transcript of every action.
Read the task-list template
# TASKS
Move tasks between these sections as their status changes. Add a date when a
task finishes. An in-progress entry states what remains to be done.
## To Do
- [Describe an agreed task and the result needed to complete it.]
## In Progress
## Done
A.5 SPECIFICATION.md: Current requirements
Have the agent create SPECIFICATION.md from your research decisions, adapting the fields to the study and leaving unresolved choices explicit for your review. After an approved scientific change, have it rewrite the affected requirements and add the decision and reason at the top of METHODOLOGY.md. Chapter 10: The example research project explains the completed heat-and-birthweight specification.
Read the specification template
# Scientific specification
Project: [name]
Version and date: [identifier]
Researcher approval: [pending / approved, with date]
## Research question and estimands
- Question and intended interpretation:
- Target population and analysis sample:
- Quantities to estimate, comparisons, units, and time periods:
- Assumptions needed for that interpretation:
## Inputs and sample rules
- Approved inputs, versions, dictionary, and access location:
- Inclusion, exclusion, and missing-data rules:
- Required variables, derivations, units, and supported ranges:
## Estimator and reported outputs
- Estimation procedure, statistical model, and relevant settings:
- How fitted results become the requested estimands, including any averaging or standardization:
- Uncertainty calculation and any decision rule:
- Required tables, figures, and saved full-precision results:
## Checks
- Input and execution checks:
- Known-truth scenarios and performance measures, where applicable:
- Independent comparisons and numerical tolerances, where applicable:
## Unresolved decisions
[List questions for the researcher. Do not silently supply missing choices.]
Have the agent maintain the current approved specification here, rewriting it
when decisions change. Record each approved scientific change and its reason
in METHODOLOGY.md, newest entry first. Preserve earlier specification versions
in version control and retain frozen protocols used for particular runs.
A.6 METHODOLOGY.md: Scientific decisions
Have the agent create METHODOLOGY.md and add a dated entry at the top for each approved scientific decision, preserving earlier entries. Each entry should explain what changed, why, and which requirements in SPECIFICATION.md were affected. Routine coding and formatting progress belongs in TASKS.md. Link to the current specification rather than repeating it. Chapter 7: Give the agent context for your project explains how the two files support research decisions.
Read the scientific-decisions template
# METHODOLOGY
Current scientific requirements: [SPECIFICATION.md](SPECIFICATION.md).
Add dated decisions at the top; preserve earlier entries. Keep routine work
progress in STATUS.md and TASKS.md. Link detailed evidence rather than copying it.
## YYYY-MM-DD — Decision title
- Question or discrepancy:
- Evidence considered:
- Decision and reason:
- Change to SPECIFICATION.md, or why none is needed:
- Affected code, outputs, and manuscript passages:
- Verification and remaining limitations:
A.7 Global user instructions
Use this template for defaults that apply across your projects. Have the agent adapt it at ~/.claude/CLAUDE.md, preserving existing guidance. Short conventions can stay in that file. For longer guidance, have the agent add paths to maintained specialist files and instructions on when to read them; Chapter 8: Apply your conventions across projects gives examples.
Download global user instructions
Read the global user instructions template
# Global user instructions
[Describe your research role and the software you normally use.]
## Before a task
- Read the relevant project context files. Preserve accepted work.
- Identify the requested result, constraints, and evidence needed to accept it.
- Ask about consequential ambiguity; do not silently substitute another analysis.
## Conventions
These conventions are defaults across projects. Follow explicit project-specific
exceptions and record their reasons. Ask when instructions conflict and no
exception has been agreed.
[Keep short defaults here. Add paths or links only to files you maintain,
with their locations and when to read them. Possible topics include project
structure, coding, statistical modeling, writing, software, and project locations.]
Read the referenced guidance relevant to the task. If a listed file is missing,
report it; do not create a replacement or invent its instructions.
## Research work
- Preserve original data. Derive new files with saved code.
- Use independently runnable steps with declared inputs and outputs.
- For paper projects, keep current requirements in SPECIFICATION.md and dated
scientific decisions and reasons in METHODOLOGY.md.
- Verify observed outputs before reporting success. Keep failed checks visible.
## Limits
- Use only inputs and services approved for the project.
- Ask before publishing, sending messages, expanding access, or adding a service.
- Do not delete recovery copies or rewrite shared history without approval.
## Finishing
- Update TASKS.md and STATUS.md from the work and checks actually completed.
- Report what changed, how it was checked, and what remains unresolved.
A.8 Git exclusions
If the project uses Git, have the agent adapt these exclusions in its .gitignore. The template excludes data folders by default; permitted public or synthetic inputs may belong in the repository. An ignore rule affects which files Git tracks. It does not restrict agent access or remove files already tracked.
Have the agent preserve the inputs needed for reproduction, including saved fits or LLM responses. Large or protected files can remain in approved storage, with their versions and locations documented in the project. For setup, see Chapter 4: Recover earlier work: git and gh in the companion guide Extending Your Agent’s Toolkit.
Read the Git-exclusion example
# Exclude research inputs by default; share permitted files deliberately.
# Keep shareable input manifests outside these excluded folders.
data/raw/
data/processed/
# Rebuildable environments and caches
.venv/
renv/library/
renv/staging/
cache/
.cache/
.Rproj.user/
.Rhistory
.DS_Store
# Personal settings and secrets
.claude/settings.local.json
.env
.env.*
!.env.example
# Preserve fitted objects, raw LLM responses, and research records required by
# the reproduction route. Store large or protected files in approved storage
# and document their versions and locations rather than silently omitting them.