Use AI to organize a research project from Day 1 and to build its replication package before publication. You only need to choose the step that matches your project today.
When: At the beginning of a project—or whenever an existing project needs a clear structure.
Do one thing: Open the project’s common root folder in your AI assistant, click the button below, and paste the copied instruction.
The AI will inspect the folder, preserve existing work, and help establish the recommended project environment.
When: As soon as analyses begin producing results intended for the manuscript. Do not wait for acceptance or the submission deadline.
Do one thing: Open the same project root, click the button below, and paste the copied instruction into your AI assistant.
The AI will inspect the research workflow and help build, document, run, and validate the public replication package.
The AI—not the user—is expected to read and apply the detailed instructions. There is one and only one research-guide AGENTS.md for both steps. Each button copies that same research-specific operational standard with a different short instruction in front: Step 1 activates project-setup mode, and Step 2 activates replication-package mode.
The universal/global instructions and the research-project instructions have different scopes; they are not competing files. Each research project maintains one canonical root AGENTS.md. If the AI Collaboration recording convention is already installed globally or present in the root file, the AI preserves it and merges only missing research-specific requirements without creating duplicate recording sections.
AGENTS.md; never replace, overwrite, truncate, or discard it.analysis/, whether the project uses R, Python, Stata, Julia, MATLAB, multiple languages, or another toolchain.Step 1 creates one durable workspace for the whole research project:
Research-Project/
|-- AGENTS.md # shared instructions
|-- README.md # private project map
|-- manuscript/ # Git repository 1
|-- analysis/ # Git repository 2
|-- project_history/
| `-- Person_Name/
| `-- YYYY-MM-DD by Agent.md
`-- others/ # optional
The AI first identifies existing files, repositories, instructions, data locations, and synchronization arrangements. It does not silently delete, move, or overwrite substantive work.
If AGENTS.md already exists, the AI appends or carefully merges the new instructions. It never replaces, overwrites, truncates, or discards the existing file. The resulting root file governs both repositories and records project-specific boundaries, data restrictions, synchronization rules, and output-promotion procedures.
Researchers should normally place the common project root in Dropbox, Google Drive, iCloud, SharePoint, Box, or another institutionally approved synchronized location. This keeps the root instructions, project map, AI-use history, both repositories, and permitted local files synchronized across the researcher’s computers. The recommendation applies only when consent, license, IRB, data-use agreements, and institutional policy permit the service.
Cloud synchronization and GitHub have different scopes. Git versions approved files inside manuscript/ and analysis/; the synchronized parent is not normally a third Git repository. Data may remain inside the approved synchronized parent without being tracked by Git. Data prohibited from the selected storage service must remain in an authorized secure location documented by the project.
Transparency means documenting provenance, methods, restrictions, and reproducibility limits as fully as permitted. It does not mean exposing protected records, confidential sources, identifying information, security-sensitive details, or material that the project is not legally or ethically allowed to disclose.
The AI follows the current AI Collaboration Guide and maintains one private project_history/ at the common root. It records substantive AI work, exact available model/runtime metadata, files and sources used, changes, verification, limitations, and unresolved questions.
manuscript/ contains compilation-relevant paper and supplement sources and may connect to Overleaf through GitHub.analysis/ contains the software-neutral research workflow: data construction, analysis, validation, generated results, codebooks, and future public-package staging.Generated figures and tables move from analysis/ to manuscript/ through a documented promotion step.
Step 2 begins while the paper is still being developed, once analyses produce results intended for the manuscript.
Before changing the package, the AI reads:
AGENTS.md and README.md;The journal’s current requirements control when they conflict with this general guide, but they do not override law, regulation, consent, ethics/IRB requirements, contracts, licenses, data-use agreements, privacy, security, or institutional policy.
The AI keeps the private research workspace, manuscript repository, public replication package, and journal production/submission files conceptually and physically distinct.
Depending on project complexity, the AI uses a compact package or separates data building from analysis. The public package should have:
README.md;R projects may use master.R and session_info.log; Python, Stata, Julia, MATLAB, mixed-language, and other projects use equivalent entry points and environment records.
The analysis/ repository should track code, documentation, codebooks, validation tools, logs, and appropriate generated results—not automatically upload the project’s data. Its .gitignore should exclude raw, received, restricted, licensed, confidential, secure-local, and working data paths.
Before staging, committing, or pushing Step 2 work, the AI checks Git’s tracked and staged files for datasets and sensitive material. Only data that are deliberately classified as redistributable public replication inputs—and are permitted by consent, license, ethics, institutional policy, and journal rules—may be added to Git. Large public release data should normally be deposited with the replication archive or an appropriate data repository rather than GitHub.
analysis/Use the compact structure for small or medium projects when public data can be included directly, data preparation and analysis are closely connected, and the complete workflow can run end to end:
analysis/
|-- README.md
|-- master.R # or equivalent entry point
|-- data/
|-- documents/
|-- scripts/
|-- functions/
|-- figures/
|-- tables/
|-- output/
`-- logs/
Use the build/analyze structure when data construction is long or conceptually separate, inputs are restricted or licensed, or the public package should begin with analysis-ready data:
analysis/
|-- README.md
|-- master.R # or equivalent entry point
|-- build/
| |-- data/
| |-- documents/
| |-- scripts/
| |-- output/
| | `-- analysis_ready/
| `-- logs/
`-- analyze/
|-- scripts/
|-- functions/
|-- figures/
|-- tables/
|-- output/
`-- logs/
When uncertain, use the compact structure. Choose build/analyze only when the data-building stage creates real complexity, access restrictions, or a meaningful boundary for users.
When manuscript source is available, the AI traces figures, tables, labels, estimates, uncertainty measures, sample sizes, dates, percentages, significance statements, and appendix results back to scripts, logs, and generated outputs.
The AI runs every authorized public path from a clean session, records warnings and limitations, generates MANIFEST-SHA256.txt, creates the release archive, extracts it into a new temporary directory, verifies its checksums, and runs it without relying on files outside the archive.
This guide is an authoring and project-management framework. ReproAI, developed by Yiqing Xu and Leo Yang Yang, is a complementary author-facing diagnostic tool for checking an existing replication package, venue compliance, and common reproducibility problems. After preparing and validating the package with this guide, the researcher should run ReproAI as a final pre-submission check and resolve any additional issues it identifies.
The final readiness report states whether the package is ready, ready with caveats, or not ready—and identifies exactly what still needs the researcher’s attention.