My Claude Code Setup

Actively maintained. A summary of how I use Claude Code for academic work — slides, papers, data analysis, and more — packaged so you can fork it for your own research. See CHANGELOG.md for the latest changes.

Live site: psantanna.com/claude-code-my-workflow

A ready-to-fork foundation for AI-assisted academic work. You describe what you want — lecture slides, a research paper, a data analysis, a replication package — and Claude plans the approach, runs specialized agents, fixes issues, verifies quality, and presents results. Like a contractor who handles the entire job. Extracted from a production PhD course and extended by a growing community.

Quick Start (5–10 minutes, plus ~30 min for first-time installs)

Before you start: Claude Code + git are the minimum. To run the included HelloWorld demos end-to-end you also need XeLaTeX (Beamer sample) and Quarto (Quarto sample). R and the GitHub CLI are recommended. Python 3 is used by a few internal scripts (check-palette-sync.py, check-tikz-prevention.py) and is pre-installed on macOS/Linux. Full list in Prerequisites below. Fastest path: clone first, then run ./scripts/validate-setup.sh — it reports exactly what's missing with install links.

Only need Python/R/markdown? You don't need XeLaTeX or Quarto. The agents, rules, skills, and orchestration patterns work for any text/code artifact. Skip the HelloWorld demos and head straight to /data-analysis, /review-paper, /lit-review, or /review-r.

Session 2 onwards: MEMORY.md (committed) collects generic [LEARN] entries that help all forkers; .claude/state/personal-memory.md (gitignored) is for machine-specific notes. See .claude/rules/meta-governance.md for the distinction.

1. Fork & Clone

# Fork this repo on GitHub (click "Fork" on the repo page), then:
git clone https://github.com/YOUR_USERNAME/claude-code-my-workflow.git my-project
cd my-project
./scripts/validate-setup.sh        # reports missing tools with install links

Replace YOUR_USERNAME with your GitHub username.

2. Start Claude Code and Paste This Prompt

claude

Using VS Code? Open the Claude Code panel instead. Everything works the same — see the full guide for details.

Avoid prompt fatigue. Out of the box, Claude Code asks permission for every tool invocation. After the first few approvals, toggle Auto-accept edits mode (a keybinding; see the permission modes section of the guide) or run claude --permission-mode acceptEdits. For fully-autonomous runs on a trusted repo, Bypass mode skips prompts entirely. The template's .claude/settings.json pre-approves ~100 common Bash and Edit/Write patterns, so even at default permissions most work is unattended.

Then paste the starter prompt from the guide, filling in your project details:

I am starting to work on [PROJECT NAME] in this repo. [Describe your project in 2–3 sentences.] I've set up the Claude Code academic workflow... Please read the configuration files and adapt them for my project. Enter plan mode and start.

The full guide has the complete starter prompt with all the details.

What this does: Claude reads all the configuration files, fills in your project name, institution, and preferences, then enters contractor mode — planning, implementing, and (within the skill you invoke) running the review + verify loop. You approve the plan, invoke a skill, and the skill handles the rest within its scope.

Heavily adapting CLAUDE.md for a non-academic project? Anthropic's built-in /init command will re-derive a CLAUDE.md from your codebase as a starting point. The pre-shipped CLAUDE.md in this template already covers the academic setup — you only need /init if your fork diverges substantially (e.g., a Python/ML project that doesn't use LaTeX or Quarto).

3. Verify Your Setup

Before building real lectures, confirm your environment works:

./scripts/validate-setup.sh        # Checks XeLaTeX, Quarto, Python, git, etc.

Then inside Claude:

/compile-latex HelloWorld          # Compiles Slides/HelloWorld.tex to PDF
/deploy HelloWorld                 # Renders Quarto/HelloWorld.qmd to HTML

If both succeed, delete Slides/HelloWorld.tex and Quarto/HelloWorld.qmd and start on your real work.

How It Works

Goal-first, gate-enforced (the v2.0 shift)

You don't craft a perfect prompt — you state a goal and let the work loop toward it under gates. Specialist agents do the labor; enforcing gates decide when it's good enough; you adjudicate the disagreements they surface. Three things make that trustworthy:

• Real gates, not reminders. A version-controlled pre-commit hook (run ./scripts/install-hooks.sh once) runs the surface-sync + quality (≥80) checks on every commit — bypassing the skill no longer bypasses the review. A git-guardrails hook blocks destructive git (reset --hard, clean -f, push --force, add -A); the review runtime re-checks any reviewer-introduced "fatal" finding before it counts.
• A real orchestration runtime. Reviews fan out to forked specialist agents, reduce over a shared finding schema, judge with a hallucination gate, and loop until dry — see orchestrator-protocol.md.
• Ground truth as a process. A mismatch isn't always a failure: a defensible, named alternative is recorded as EXPLAINED and carried into your response-to-referees, while genuine errors stay fail-closed.

This is not an autonomous daemon — the loop is always you- or skill-initiated, and you stay the auditor. Scheduled Routines handle recurring chores (nightly reproducibility, weekly lit-delta, inbox triage) and notify only when they find something.

Contractor Mode

You describe a task. For complex or ambiguous requests, Claude first creates a requirements specification with MUST/SHOULD/MAY priorities and clarity status (CLEAR/ASSUMED/BLOCKED). You approve the spec, then Claude plans the approach and invokes the right skill (e.g. /create-lecture, /qa-quarto, /review-paper --adversarial). That skill implements the orchestrator runtime internally — implement, verify, review, fix, re-verify, score — and returns a summary when the work meets quality standards. Say "just do it" and it runs the full loop; commits still require an explicit /commit (which the pre-commit hook then gates).

Specialized Agents

Instead of one general-purpose reviewer, 18 focused agents each check one dimension. A representative sample:

• proofreader — grammar/typos
• slide-auditor — visual layout
• pedagogy-reviewer — teaching quality
• r-reviewer — R code quality
• domain-reviewer — field-specific correctness, slides (template — customize for your field)
• domain-referee / methods-referee / editor — manuscript peer-review pipeline (/review-paper --peer)

Each is better at its narrow task than a generalist would be. The /slide-excellence skill runs the slide-review agents in parallel; /review-paper --peer runs the paper-review pipeline. The same pattern extends to any academic artifact — manuscripts, data pipelines, proposals.

Adversarial QA

Two agents work in opposition: the critic reads both Beamer and Quarto and produces harsh findings. The fixer implements exactly what the critic found. They loop until dry — converging when a round surfaces no new issue (a 5-round cap is the fallback, not the primary stop). This catches errors that single-pass review misses.

Quality Review

Every artifact gets a score (0–100). Scores below threshold halt the workflow and surface the findings — the user decides whether to fix or explicitly override:

• 80 — commit threshold
• 90 — PR threshold
• 95 — excellence (aspirational)

Framing honesty: Thresholds are advisory at the harness level — the /commit skill runs quality checks and halts on failure. And as of v2.0, running ./scripts/install-hooks.sh once installs a real pre-commit hook (.githooks/pre-commit) that runs the surface-sync + quality (≥80) gates on every commit, so bypassing the skill no longer bypasses the review. Opt out per-commit with SKIP_QUALITY_GATE=1 or git commit --no-verify.

Context Survival

Plans, specifications, and session logs survive auto-compression and session boundaries. The PreCompact hook saves a context snapshot before Claude's auto-compression triggers, ensuring critical decisions are never lost. MEMORY.md accumulates learning across sessions, so patterns discovered in one session inform future work.

For forced compression (long pipelines, mid-plan handoffs), /compress-session (v1.9.0) distils the conversation into a structured note — decisions, next actions, and discarded-as-noise — instead of letting auto-compaction truncate. /promote-memory (v1.9.0) periodically harvests generic learnings from gitignored personal-memory.md to committed MEMORY.md via a five-critic council.

Verification Discipline (v1.7.0+)

Multiple complementary verification layers run before submission:

• /verify-claims (v1.7.0) — Chain-of-Verification with a forked verifier that cannot self-confirm because it has never seen the draft. v1.9.0 adds HIGH/MED/LOW-WARN severity tiers; HIGH-WARN (fabricated citation, numerical contradiction) gate-refuses /commit.
• /audit-reproducibility (v1.7.0; Stata coverage v1.9.0) — every numeric claim in the manuscript is cross-checked against the script output that produced it. v1.9.0 adds passport.yaml — a per-paper YAML state file with PASS/FAIL/STALE/UNVERIFIED status per claim.
• /humanize (v1.9.0) — detect AI-voice tells (boilerplate transitions, hedging stacking, sycophancy) before submission. Read-only by design; auto-rewriting degrades quality.
• /review-paper --variance N (v1.9.0) — runs N referees with sampled dispositions and reports a decision distribution, not a point estimate. Motivated by AgentReview (ACL 2024) finding 37% of decisions vary purely from disposition sampling.

The Guide

For a comprehensive walkthrough, read the full guide (or see the source).

It covers:

1. Why This Workflow Exists — the problem and the vision
2. Getting Started — fork, paste one prompt, and Claude sets up the rest
3. The System in Action — specialized agents, adversarial QA, quality scoring
4. The Building Blocks — CLAUDE.md, rules, skills, agents, hooks, memory
5. Workflow Patterns — slides, research, reproducibility, presentation rhetoric, sequential adversarial audits, and more
6. The Ecosystem — extensions by clo-author, claudeblattman, MixtapeTools, autoresearch, ClaudeCodeTools, and a growing community
7. Customizing for Your Domain — creating your own reviewers and knowledge bases

2026 Features

The guide covers Claude Code's latest capabilities:

• Model lineup — Opus 4.8 (claude-opus-4-8) is the newest model and the API default (GA 2026-05-28, $5/$25 per MTok, 1M context, defaults to high effort); Opus 4.7 is the prior generation. Sonnet 4.6 is the workhorse (1M context); Haiku 4.5 the fast tier. Sonnet 4 + original Opus 4 retire 2026-06-15 → migrate to Sonnet 4.6 / Opus 4.8. (Verified against Anthropic docs 2026-05-31.)
• Effort levels — /effort sets cost vs. thoroughness (low / medium / high / xhigh / max). Opus 4.8 defaults to high — its high does roughly what 4.7's xhigh did for fewer tokens, so reserve xhigh for extended exploration and ultracode (xhigh + dynamic workflows) for the largest autonomous runs.
• /goal <verifiable condition> (v1.9.0; Anthropic May 2026) — keep working across turns until a fast model confirms the condition holds. Pairs with /commit quality gates for verified-end-state runs.
• claude agents dashboard (v1.9.0; Anthropic May 2026) — single screen for parallel review work (/review-paper --peer, /slide-excellence).
• Cost-Conscious Composition — prompt-cache TTL (5-min default on API keys; 1-hour automatic on Claude subscriptions), 70/20/10 model routing (Haiku/Sonnet/Opus), /cost + /usage monitoring, Agent SDK credit-pool split (2026-06-15).
• Skill frontmatter — effort, context: fork, agent, hooks, disable-model-invocation (v1.8.0+), and dynamic content ($ARGUMENTS, !command syntax)
• Permission modes — Normal, Auto-accept, Plan, Auto (classifier-gated; on Team / Enterprise / API and rolling out to Max; needs Opus 4.6+ or Sonnet 4.6), Bypass
• Hook handler types — command, prompt, and HTTP handlers with 20+ hook events; hooks see effort.level and $CLAUDE_EFFORT (Apr 2026 Week 19)
• Advanced agent configuration — model, maxTurns, isolation, tool restrictions; model-routing.md rule codifies per-agent tier (v1.9.0)
• Worktree base ref (v1.9.0; Anthropic Apr 2026) — worktree.baseRef setting controls fresh (default; remote default-branch) vs head (local HEAD) for new worktrees
• Built-in skills — /fewer-permission-prompts, /team-onboarding, /autofix-pr, /powerup, Ultraplan, /loop (self-pacing)
• Plugins — /discover-plugins for third-party extensions

Use Cases

Disciplines preloaded: Economics (top-5 journal profiles, R conventions) and Political Science (APSR / AJPS / JOP profiles, formal-theory + survey-experiment paper types, conjoint/cjoint conventions). Forkers extend for psych / sociology / public-health via journal profiles + paper types + discipline cards.

One repo, many project types

This workflow is designed as a single hub for an entire research program — not one paper at a time. The same CLAUDE.md, rules, agents, and quality gates serve courses and lectures, papers and referee reports, data analysis and replication packages, Monte Carlo simulation studies (/simulation-study + sim-reviewer), and the R package release gate (/r-package-check + r-package-reviewer) — all new in v1.10.0. On the roadmap: Stata / Python package checks (SSC / PyPI) and personal-productivity workflows. See .claude/references/v2.0-backlog.md for what's next.

What's Included

Agents (.claude/agents/)

Skills (.claude/skills/)

Research Workflow

Rules (.claude/rules/)

Rules use path-scoped loading: always-on rules load every session (~100 lines total); path-scoped rules load only when Claude works on matching files. Claude follows ~150 instructions reliably, so less is more.

Always-on (no paths: frontmatter — load every session):

Path-scoped (load only when working on matching files):

Templates (templates/)

Prerequisites

Minimum to fork this template: Claude Code + git + Python 3 (Python is already installed on macOS/Linux).

Minimum to run the included HelloWorld demos end-to-end: add XeLaTeX (for /compile-latex HelloWorld) and Quarto (for /deploy HelloWorld).

Your real lectures may need more — R for scripts/R/ analyses, pdf2svg if you use TikZ extraction, gh CLI if you use the PR-based commit workflow. ./scripts/validate-setup.sh reports which of these are installed and what each unlocks.

Adapting for Your Field

1. Fill in the knowledge base (.claude/rules/knowledge-base-template.md) with your notation, applications, and design principles
2. Customize the domain reviewer (.claude/agents/domain-reviewer.md) with review lenses specific to your field
3. Update the color palette — this is a two-surface contract: change the HEX values at the top of both Preambles/header.tex (Beamer/TikZ) and Quarto/theme-template.scss (Quarto slides) so they agree. Then run ./scripts/check-palette-sync.sh to verify. Forgetting one surface silently produces mismatched Beamer vs. Quarto renderings. See Preambles/README.md for the full contract and the TikZ style library.
4. Add field-specific R pitfalls to .claude/rules/r-code-conventions.md
5. Fill in the lecture mapping in .claude/rules/beamer-quarto-sync.md
6. Customize the workflow quick reference (.claude/WORKFLOW_QUICK_REF.md) with your non-negotiables and preferences
7. Set up the exploration folder (explorations/) for experimental work

Additional Resources

• Claude Code Documentation
• Writing a Good CLAUDE.md — official guidance on project memory

Origin

This infrastructure was extracted from Econ 730: Causal Panel Data at Emory University, developed by Pedro Sant'Anna using Claude Code over 6+ sessions. The course produced 6 complete PhD lecture decks with 800+ slides, interactive Quarto versions with plotly charts, and full R replication packages — all managed through this multi-agent workflow. The patterns are domain-agnostic: the same agents, rules, and orchestrator work for any academic project.

Community & Extensions

As of March 2026, 15+ research groups across economics, energy, political science, and engineering have forked and adapted this workflow. The infrastructure (orchestrator, hooks, quality gates) transfers without modification.

Extended workflows:

• clo-author by Hugo Sant'Anna (UAB) — Paper-centric research workflows with 17 specialized agents (6 worker-critic pairs plus referees, data-engineer, verifier), simulated blind peer review, AEA replication compliance, and full research lifecycle management. The /review-paper --peer <journal> pipeline in this template is adapted from clo-author with Hugo's permission (pipeline shape, 6-way disposition taxonomy, journal-calibration schema, paper-type branching). Thanks, Hugo.
• claudeblattman by Chris Blattman (U Chicago) — Comprehensive guide for non-technical academics: executive assistant workflows, proposal writing, agent debates, and self-improving configuration
• MixtapeTools by Scott Cunningham (Baylor) — The Rhetoric of Decks: philosophy and practice of beautiful, rhetorically effective academic presentations
• autoresearch by Andrej Karpathy — Constraint-based autonomous research with program.md as constitutional document
• ClaudeCodeTools — "The Editor" persona: seven-audit sequential paper review protocol

See the guide's ecosystem section for detailed descriptions, design principles, and more resources.

Versioning & Contributing

• What's new: see CHANGELOG.md. We follow loose semver — breaking changes get major bumps so you can decide when to pull updates.
• How to contribute: see .github/CONTRIBUTING.md. PRs welcome for generalizable improvements; fork-specific work stays in your fork.
• Pin to a version: git checkout v2.0.0 (current as of 2026-06-09).

License

MIT License. See LICENSE.