Overview

This repository is a template for a reproducible modeling or data science project. The default example uses R, Quarto, Git, and GitHub, but the structure is workflow-first so projects can add Python, Julia, shell scripts, or other tools without major reorganization.

This template also includes guidance for AI-supported work. The goal is to make AI tools useful for coding, documentation, review, and troubleshooting while keeping the project transparent, reproducible, and human-reviewed.

Pre-Requisites

The default example uses R, Quarto, GitHub, and a reference manager that can handle BibTeX. Zotero with the Better BibTeX plugin is a good choice.

It is also assumed that you will be working through some sort of IDE. Our currently preferred one is Positron, but others like VS Code, RStudio or another option of your choice also work.

It is also useful to have a word processor installed, such as MS Word or LibreOffice. To produce PDF output, you need a TeX distribution. TinyTeX is a good option; see the Quarto PDF instructions.

The example files use these R packages: broom, dplyr, ggplot2, here, knitr, readxl, rmarkdown, skimr, and tidyr. Install them before running the example workflow:

install.packages(c("broom", "dplyr", "ggplot2", "here", "knitr",
                   "readxl", "rmarkdown", "skimr", "tidyr"))

Getting Started

See new-project-instructions.md for a brief getting started guide.

Template Structure

The template comes with a folder structure and example files to show the kinds of content you would place in each folder. See the folder-specific readme files for more detail.

• ai/: AI workflow notes, an AI-use policy, an AI-use log, and an AI-oriented project summary. See ai/readme-ai.md.
• assets/: static non-code materials such as references, reference style files, PDFs, and manually created figures. See assets/readme-assets.md.
• code/: code organized by workflow stage. See code/readme-code.md.
• data/: everything related to different types of data, such as raw, processed, private, and large data folders. See data/readme-data.md.
• products/: final or near-final deliverables such as reports, manuscripts, presentations, posters, and apps. See products/readme-products.md.
• results/: outputs automatically generated by code, such as simulation/analysis results, figures, tables. See results/readme-results.md.

Important project-level files:

• readme.md: this project overview.
• .here: project-root marker used by the R here package so scripts and Quarto files can find project-relative paths even outside a Git checkout. It can be kept even if R or the here package are not used.
• new-project-instructions.md: instructions for creating a new project from this template.
• usage.md: instructions for running and reproducing the project.
• code-guidelines.md: coding guidelines for scientific and reproducible projects, including documentation, failure behavior, simplicity, packages, and AI-assisted coding expectations.
• agents.md: extra instructions for AI coding assistants.
• license.md: the license for this template, or later for your project.

Naming Conventions

Use descriptive file and folder names. In general:

• use lower-case names;
• separate words with -;
• avoid spaces, underscores, and CamelCase unless a standard file name or file extension requires otherwise.

Readme files are named by folder context, such as readme-code.md or readme-data.md.

Git/GitHub and Sensitive Information

Git and GitHub are useful for tracking changes, backing up work, and sharing a project with other users. While you could use this template without Git/GitHub tracking, in the following it is assumed that you'll be using Git/GitHub.

Before using this template and starting a project, you should familiarize yourself with Git/GitHub at least a little bit, e.g. by going through this brief Git/GitHub introduction.

An important feature of Git/GitHub is the tracking of changes (what Git does) and syncing those changes between local machines and a remote server (what GitHub provides). In Git/GitHub language, you commit project updates, then push/pull between local computer(s) and the remote. Once anything has been committed (e.g., a file has been added) and pushed to GitHub, it can be difficult to fully remove from the history, especially if the repository has been shared.

This might raise questions of confidentiality and the risk of accidentally publicly sharing information that should not be public. Because of this, for many projects, it is wise to start with a private GitHub repository. Later, after checking the data, outputs, license, authorship, and project goals, you can decide whether the repository should remain private or become public.

Do not commit private, sensitive, regulated, identifiable, restricted, or license-protected data unless the project owner has explicitly approved that workflow. A private GitHub repository is not the same as a secure data system or an IRB/DUA-approved storage plan. If the repository stays private because it contains or depends on restricted material, document what can be committed and what must stay local or in an approved storage location.

To keep files out of Git and thus potentially making them public, list them in .gitignore before committing them. For example, this template already ignores the contents of data/private-data/, apart from the readme file, which is included.

If a file has already been committed, adding it to .gitignore is not enough; it must also be removed from Git tracking while leaving the local file in place. See GitHub's documentation on ignoring files for more detail.

In general, any raw or processed data is likely the potentially most sensitive part of your project. Some generated outputs might also contain sensitive information. Check carefully, then decide if what you have can be 1) fully public, 2) private but ok to check into GitHub, 3) so sensitive that you don't want to push it to GitHub, even inside a private repository.

Git/GitHub and large files

Do not try to use Git/GitHub with large files! As a rule of thumb, anything larger than 20MB should not be tracked and synced with Git/GitHub. There are specialized options to work with large files, such as Git LFS. If you think you might have to work with large files, review the relevant information in the brief Git/GitHub introduction course.

This project template is set up to allow for large files, with currently the folders data/large-files/, and results/large-files/ being ignored by Git/GitHub, while keeping small readme or placeholder files in those folders.

Software And Package Management

Document the software and package/library setup your project needs. The default example uses manually installed R packages because that is easiest. It can be suitable for small projects.

In general, you can think of levels of package/software management and use the one that's best for your project. It is possible to switch, but easier to pick the appropriate one early on.

This is a quick overview of the different levels:

• Manual package list: the default for this template. List required packages prominently in user-facing documentation.
• Lockfile or environment manager: use tools such as renv, Conda, Python virtual environments, or Julia project files when exact package versions matter for longer-term work. Commit the lock or project files needed to restore the environment, but do not commit local package libraries or virtual environments.
• Continuous Integration or containers: use GitHub Actions, Docker, or similar tools for advanced long-term, multi-user, multi-language, publication, or regulated workflows that need controlled reruns across machines.

This repository template assumes you will start with a manual approach, and add any more advanced software management pieces yourself, based on needs.

Code should load the needed packages and fail clearly when a package is missing. In general, there should not be any silent install of packages or other environment modification done by code.

As a lightweight reproducibility aid, final products may include optional software/session information, such as sessionInfo() or sessioninfo::session_info(), when that information would help readers or users understand the computing environment.

Code Guidelines

Code should be written for scientific and reproducible workflows. That means it should be transparent, reproducible, simple, heavily documented, and strict about unexpected inputs or missing requirements. See code-guidelines.md for the full coding guidelines that apply to both humans and AI tools.

AI-Supported Workflow

AI tools can help explain code, draft first-pass code, improve documentation, suggest checks, and review for reproducibility problems. They should not be treated as final authority for scientific claims, model choice, data privacy, citation accuracy, or interpretation of results.

When using AI tools:

• Point the tool to readme.md, usage.md, agents.md, code-guidelines.md, data/readme-data.md, and relevant files in ai/. Some AI tools automatically read only files named CLAUDE.md or AGENTS.md. Because this template keeps its agent instructions in agents.md, point the tool at that file explicitly if it does not pick it up on its own.
• AI tools may read and update ai/project-summary.yml as a concise orientation aid. It is a convenience file for AI tools, not human-facing documentation and not the source of truth.
• Do not paste sensitive, private, regulated, or identifiable data into external AI tools unless the project owner has explicitly approved that workflow.
• Ask for small, reviewable changes.
• Rerun affected scripts or rerender affected products after meaningful changes.
• Follow ai/ai-use-policy.md for AI-use expectations.
• AI tools should write concise entries to ai/ai-use-log.md for meaningful project-specific AI-assisted work. Logging is enabled by default once the repository has been renamed for a new project, unless the project owner asks to turn it off. Human users may read the log as needed, but are not expected to write or edit it.

AI-related files and expected readers/writers

The files in ai/ have different expected readers and writers. For example, ai/ai-use-log.md is written by AI tools, while ai/readme-ai.md and ai/ai-use-policy.md are human-facing. See the "File Roles" section of ai/readme-ai.md for the full list.

Project files outside ai/, such as readme.md, usage.md, data/readme-data.md, code/, results/, and products/, are human-facing project materials. Humans should be able to read and understand them. AI tools may help edit or review them, but important scientific, statistical, privacy, and interpretation choices need human review.

GitHub Actions and other automated workflows can be useful for advanced users. They are intentionally not enabled by default in this template because many users will be new to Git and GitHub.

License

This template is licensed under the MIT License. See license.md for the full license text.

The MIT License permits reuse, modification, distribution, and commercial use. That means users may use this template as a starting point for a wide range of projects, including work-related or commercial projects, as long as the license notice is included where required.