Academic Research Project Template

A project setup and workflow designed for academic research collaboration, centered around Git and optimized for AI assistance.

Key Features:

• Git repo + Dropbox share, symlinked into one folder
• Git-centric: A must to use AI, because AI messes up things
• Compatible with traditional workflows and no-Git coauthors
• Fine-tuned skills, MCPs, and agents useful for academic research

See ProjectExample/ for structure reference and Setup for automated setup.

Table of Contents

• Academic Research Project Template
  • Table of Contents
  • Project Organization
    • Core Structure
      • In the Git Repo (MyProject)
      • In the Dropbox (MyProject-Share)
  • Automated Setup
  • Git
    • Commit
    • Best Practices
    • What (not) to commit
      • Never commit:
      • Figures and outputs
      • Jupyter notebooks
    • GitHub Pull-Request Workflow
  • AI Instructions
    • Claude Agents
    • Claude Skills
    • MCP Servers
  • Python Environment Management
    • Virtual Environment Location

Project Organization

Projects use a two-folder structure:

• MyProject/ - Git repository containing code, final figures/tables, and LaTeX documents
• MyProject-Share/ - Dropbox-synced folder with data, notes, and intermediate outputs

Folders from MyProject-Share/ are symlinked into MyProject/, so you work in one place with access to everything.

Why two folders? Solves the Git vs. Dropbox dilemma: Dropbox lacks proper version control and handles conflicts poorly, while Git struggles with large files. By linking folders together, you get Git's version control + Dropbox's file sharing while working seamlessly in one place.

Working with non-Git users: you can also clone the repo into the MyProject-Share folder, so they can work just as usual. Because it is shared via Dropbox, you can access all the code and handle Git on their behalf.

Core Structure

In the Git Repo (MyProject)

• Code/ - All analysis scripts and implementation
  • The subfolders are organized around different tasks, e.g., DataCleaning.
• Figures/ - Final presentable charts, plots, and visualizations that we want to track the version with git
• Tables/ - Final presentable result tables and summary statistics that we want to track with git
• Paper/ - The LaTeX folder containing the draft
• Slides/ - The LaTeX folder containing slides

In the Dropbox (MyProject-Share)

• Notes/ - Research notes and documentation
• Data/ - Raw and processed datasets. Typically read-only.
• Output/ - Generated results and intermediate files
  • This folder is organized with subfolders that have the same names as folders under Code.

Automated Setup

1. Clone and create project:

   git clone https://github.com/FuZhiyu/ResearchProjectTemplate.git
   cd ResearchProjectTemplate
   ./create_project.sh YourProjectNameOrPath
   

2. Share with coauthors:

   • Share YourProjectName-Share/ via Dropbox
   • Push to GitHub: cd YourProjectName && git remote add origin <url> && git push -u origin main
   • Coauthors: clone repo and run ./setup_mac.sh

Git

We use Git for version control and GitHub for collaboration. Git helps us track changes, work simultaneously without conflicts, and maintain a complete history of our research progress. Tons of tutorials on Git can be easily found online, so here we briefly explain two key concepts, commit and pull request, and focus more on best practices in academic research.

Why isn't Dropbox/Overleaf version history enough? Version control isn't just "save every copy"—it's about organizing changes meaningfully. Thousands of timestamped versions don't help you understand what changed or easily recover specific states.

Commit

A commit is a snapshot of your project at a specific point in time. Each commit has:

• A message describing what changed
• The author and timestamp
• A complete copy of all files at that moment
• A unique identifier (hash)

When you make changes to files, Git tracks what's different from the last commit. You can then "commit" these changes to create a new snapshot. This allows you to see exactly what changed between different versions.

Best Practices

1. Commit very often - Essential before AI edits. AI can mess things up, but frequent commits let you experiment safely knowing everything can be recovered.

2. Descriptive messages - "Fix typo in

...