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 runs the gate suite (./scripts/backtest.sh — 10 checkers) and the quality scorer, 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; machine-specific notes accumulate in Claude Code's native auto memory (~/.claude/projects/<project>/memory/, machine-local, never committed). 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. New interactive sessions on Pro/Max/Team start in auto mode (classifier-gated — most actions run, risky ones prompt); on plans and providers without auto, Normal mode prompts per risky tool call. If you still see too many prompts, 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 ships defaultMode: bypassPermissions with broad catch-all allows (Bash(*), Edit(**), Write(**) — 7 wildcard rules, not a curated list), so out of the box almost nothing prompts. That is a deliberate power-user default: to tighten it, set defaultMode: "default" in .claude/settings.json and approve tools as you go, or remove the override to fall back to the platform's auto mode.

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. One command — ./scripts/backtest.sh — runs ten gates: surface-sync, skill integrity, model currency against the SSoT, link and anchor resolution, Agent Skills spec conformance, staleness (including source-vs-published divergence), repo hygiene, derived counts (enumerable claims re-counted from disk), ledger coverage (the qualification ledger and the checks that actually run must agree in both directions, and every hook declared in settings must exist and be invocable — a one-character path typo no longer disables a hook in silence), and a seeded hook battery (every active guard hook is re-fired against the failure it targets, alongside clean controls, on every run). A version-controlled pre-commit hook (run ./scripts/install-hooks.sh once) runs it plus the quality check (≥80) 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) and refuses a merge, rebase, or pull while the tree is dirty — reading the tree as it is rather than predicting what a chained command might do to it, so git stash && git merge is denied too and you run the two steps separately (ALLOW_DIRTY_MERGE=1 if you mean it); like its sibling it is a textual check over the command line, so an op carried inside an interpreter, an alias, or a script is outside what it can see, and its docstring says which forms those are. Its sibling root-of-trust-guard denies the common shell write paths into the files that define the gates themselves (.claude/settings*.json, .claude/hooks/, .githooks/) — redirection, tee, cp/mv/rm, in-place sed — and, because it already unwraps bash -c and env -S payloads for those rules, it hands the unwrapped payload to the same destructive-git deny list, so bash -c 'git reset --hard' and bash -c 'git clean -fdx' no longer fall between the two hooks. Read that one as a tripwire, not a lock, and read the name as a filename rather than a claim: it is a best-effort textual scan that fails open on its own errors, and the files it watches stay replaceable through channels the template deliberately allows — an Edit/Write/MultiEdit, a branch switch, a clean merge, or a bug in the hook itself. What it buys is a change of channel — a change to a gate arrives as a reviewable diff instead of an invisible overwrite — not a guarantee that the gates cannot be disabled. Nothing here recovers anything either: the transcript and git reflog are an audit trail and a commit-history aid, and neither holds the bytes of an uncommitted edit or an untracked file. The review runtime re-checks any reviewer-introduced "fatal" finding before it counts.
• Every gate is qualified, and the ledger is itself a gate. Each one has been shown a planted defect and confirmed to go red, with recall and false-alarm rate recorded in quality_reports/qualification/LEDGER.md — and that ledger is now load-bearing rather than aspirational: a registered check with no row there fails the build, and a row naming a checker that no longer exists fails too. Checks that have not been qualified are listed there by name as visible debt — because an unqualified check is not weak evidence, it is none. Run /vaccinate to qualify one.
• 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 automation handles recurring chores and notifies only