Designing a Course with an AI Co-Designer

How I Used Claude Code to Translate a 16-Week In-Person Course into a 4-Week Intensive Online Format

Author

Davi Moreira

Published

May 11, 2026

Modified

June 16, 2026

NoteA completed account: design and delivery, written after the course ended

The Summer 2026 offering of QM47400 (Predictive Analytics) ran from May 18 to June 12, 2026, with students wrapping up their final activities by June 14. I first drafted this page mid-stream, as a field journal, while I was still building material. I am finalizing it now that the course has fully run, start to finish: every notebook delivered, the midterm and quizzes given, and the term brought to a close. So what follows is no longer a forecast of how I expected the workflow to go. It is an honest account of how it actually went: what worked, what cost me time, and what I would tell a colleague before they start. Working with Claude Code as an AI co-designer changed how I build a course, and the techniques that mattered most by the end are not the ones I would have predicted at the start.

NoteHow this page was written

True to its subject, this page was itself drafted with the help of Claude Code, the same tool I am describing below. I outlined the structure I wanted, dictated the lessons in my own voice, and asked Claude to produce a first pass that I then revised until it sounded like me. So the recommendations and judgments are mine, and the prose you are reading is itself an example of the workflow it describes.

1 Who this page is for

This page is written for faculty colleagues, especially those building or revising a course, who are curious about whether AI coding assistants are useful for teaching material and not just for software engineering. If you have ever maintained a syllabus in plain text, edited slides as code (Beamer, Quarto, R Markdown), or even just kept course files in a Git repository, the workflow below will feel natural. If you have not, this page will give you a sense of what becomes possible if you take the small step of putting your course material under version control.

I am sharing this in the same spirit as Pedro H. C. Sant’Anna’s My Claude Code Setup, which is, frankly, the page that nudged me to write my own. Where Pedro’s guide is the polished playbook of a research economist building an end-to-end agent system, mine is a teaching-oriented field report on what an undergraduate business-analytics course actually looks like when an AI is sitting beside you while you build it.

If you would rather read the story than the reference, I have also published a shorter, narrative companion essay on Substack: How Co-Designing a Course With AI Changed the Way I Work and Use My Computer. This page is the detailed field report; that essay is the same experience told as a narrative.

2 The starting point

I did not begin this project from zero. The 2025 Fall version of QM47400 was already a full-semester course I had designed and created myself (16 weeks, in-person, with quizzes, a Kaggle case competition, and a poster session). Three properties of that existing course mattered enormously when I brought Claude Code into the picture:

  1. The course website was already a Quarto project. index.qmd, syllabus.qmd, and schedule.qmd are plain-text files rendered to HTML. The whole site lives in docs/ and is served by GitHub Pages.
  2. All other artifacts were already plain-text-friendly. Slides were Quarto/RevealJS source, notebooks were .ipynb JSON, and quizzes, exam, and project rubrics were Markdown.
  3. The repository was already on GitHub with a sensible structure (notebooks/, _syllabus/, _quizzes/, _midterm_exam/, _lecture_notes/, lecture_slides/, brightspace/, and so on).

If your course is in a similar shape, meaning files you can read in a text editor and organized in folders, the workflow below is directly transferable. If your course currently lives entirely in PowerPoint decks, Word documents, and the Brightspace or Canvas authoring UI, your first investment should be moving the source-of-truth artifacts into plain text. That is the precondition that makes an AI co-designer useful.

Dimension 2025 Fall (semester, in-person) 2026 Summer (4-week intensive, online)
Duration 16 weeks 4 weeks (20 business days plus a Day 0 launchpad)
Mode In-person, on campus Fully online
Daily student engagement Standard 3-credit class plus outside study About 112.5 minutes per day
Synchronous time Regular class meetings One synchronous Zoom session per week. One synchronous office hour per week.
Primary instruction medium Live lectures and slides Micro-videos (target ≤12 min each) plus Colab notebooks
Pedagogy Lecture, in-class examples, homework Concept, Demo, PAUSE-AND-DO practice, Solution discussion
AI assistance for students Optional, ad hoc Built into the workflow via Gemini in Colab (“vibe coding”: draft, verify, document)
Number of lessons One per class meeting 21 notebooks (one per business day plus a Day 0 launchpad)
Assessment mix Attendance, participation, quizzes, homework, Kaggle case competition, final project and poster Quizzes, Participation through daily PAUSE-AND-DO, Online Midterm Exam, Final Project (project milestones), Course Case Competition (Kaggle)
Capstone Poster at the Undergraduate Research Conference Team final project built across milestones (proposal → baseline model → tuned model and abstract → poster), culminating in a research poster and a reproducible final notebook (conference presentation optional)
Topic coverage Linear regression, classification, resampling, regularization, trees and ensembles, time series, deep learning, unsupervised learning The same predictive arc compressed into 20 days: regression, regularization, classification and thresholding, cross-validation and model selection, trees and ensembles (random forests, gradient boosting), time series forecasting, and a condensed introduction to deep learning. Unsupervised learning is trimmed; in its place the summer leans into an explicit CV-first evaluation spine with a locked test-set protocol, plus dedicated notebooks on data communication (the poster) and an end-to-end competition workflow
Source-of-truth files Slides, syllabus, homework PDFs Notebooks, video guides, Brightspace pages, quizzes, exam, all as plain text
TipYou do not need to be a developer

I am someone comfortable on the command line, with coding in different programming languages, .md files, and with Git, and that lowered my activation cost. But everything I describe below can be done in natural language, which means telling Claude what you want, reviewing what it produced, and asking it to commit the change. You do not need to type a single Git command yourself.

3 The honest tradeoffs

Before the recommendations, the lessons I wish I had taken seriously earlier.

3.1 You will spend more time than you expect

Translating a 16-week course into a 4-week intensive looks, on paper, like compression. In practice it is a redesign. Cognitive load, daily engagement of roughly 112.5 minutes per day, notebook pacing, the order in which concepts appear, the difficulty curve from EDA to gradient boosting in thirteen business days: none of that survives the move unchanged. The CONVERSATION_LOG.md in this repo logs sixteen numbered working sessions during the intensive design phase alone, before delivery even began, and then a run of dated entries through delivery, more than two dozen in all. The AI sped up production, not deliberation. I still had to decide what to teach, in what order, and at what depth. The minute I tried to skip that step and let the assistant just propose a plan, the plan was bland and had to be redone.

3.2 Flexibility is a double-edged sword

Claude Code is extremely flexible. It will adopt almost any convention you ask it to. That is wonderful, because the tool conforms to your course rather than the other way around. But it also means there is no obvious right way to use it, and the time-to-effectiveness is dominated by figuring out your own style. Expect to throw away your first two or three workflows before settling on one that fits.

3.3 Where the AI really shines: structured artifacts at scale

The cautions above are real, but they are not the whole picture. There is a category of work where the assistant is unambiguously better than I am, and it is worth naming because it is the easiest first win for a colleague who has not yet tried this. Generating structured, schema-compliant artifacts at scale is exactly that kind of work, and the example I lean on most is Brightspace-ready quiz CSVs.

Brightspace’s Question Library accepts CSV uploads in a specific column format. Once I showed the assistant the format (one example file in the repo is enough), it can generate dozens of well-structured multiple-choice and short-answer questions from a short topic brief, all in the exact CSV shape Brightspace expects, with distractors that are pedagogically plausible rather than obviously wrong. I review and edit, I do not draft from scratch. What used to be an hour of formatting per quiz is now ten minutes of review. The same pattern works for grading rubrics, casebook scaffolds, peer-review forms, and any other artifact whose value lies in being uniform, complete, and machine-uploadable.

3.4 Think of the AI assistant as a rotating TA/RA team

This is the mental model that finally made the workflow click for me. Claude is the best teaching assistant I have ever had: fast, patient, indefatigable, and well-read. But it is not the same TA in every session. Tone drifts. Default formatting drifts. Last week’s good habit can quietly become next week’s regression. The implication is simple and load-bearing:

If you would tell a new TA something on their first day, write it down where the next TA will see it.

Everything in Recommendations below is a consequence of taking that one sentence seriously.

3.5 Speak to your computer, and run a team of agents

The most unexpected lesson is not about the course at all; it is about how I work. For the first time in my life, I drive my computer mainly by talking to it rather than typing or reaching for the mouse. It began as a small convenience and turned into a genuine change in working style.

Here is how it happened. Midway through the project I noticed I routinely had several terminal windows open at once, each one a separate Claude Code session working on a different corner of the course. Moving between them, it dawned on me that I was no longer operating a single tool: I was directing a small team, each window an agent carrying its own task. Once I saw it that way, typing felt like the wrong interface: you do not type at a team, you talk to it. So I turned on my operating system’s dictation and started speaking to these windows, and my throughput jumped. The evidence points the same way: a Stanford, Baidu, and University of Washington study found speech input about three times faster than typing on a mobile keyboard, at a lower error rate (Ruan et al., 2016). My setup is a laptop, not a phone, but the direction holds: for the long, discursive instructions this work needs, speaking beats typing by a wide margin.

What turned “several terminals” into an actual system was tying each agent to a tracked task. Every window was working one of the issues I had created with the course-tasks skill, a GitHub issue in a private companion repo (see Skills became the backbone, below), and as it worked, it kept that issue updated, refined, and ultimately checked off. The issues were the shared, persistent memory the agents wrote back to, so progress outlived any single session. That is what let one setup both build the course and manage it: the task list, the working memory, and the team of agents were the same thing, and I conducted it by voice.

One honest caveat rides along with dictation. Spoken prompts arrive a little loose: homophones slip through, punctuation goes missing, the occasional clause lands garbled. So the assistant earns its keep by confirming intent when an instruction is ambiguous rather than guessing and barreling ahead. Bake that “check before acting” habit into your CLAUDE.md, and the rough edges of voice stop mattering.

4 Recommendations

4.1 Treat CLAUDE.md as the project’s constitution

CLAUDE.md is the file Claude Code reads at the start of every session. Anything written there is in the assistant’s context by default, like a standing handout you would give every new RA on day one. My CLAUDE.md has grown from a few paragraphs to a structured document with:

  • Project mission (course code, run dates, pedagogy).
  • A small table of “see also” reference files, so the constitution stays slim and detailed material lives elsewhere.
  • Critical rules with a 🚨 prefix that flag the regressions I have actually been bitten by.
  • Style guidelines as a table (random seed 474, train/val/test split 60/20/20, figure size, money in markdown cells, emoji vocabulary).
  • Anti-patterns drawn from real prior mistakes, not from hypotheticals.
  • A session-end checklist.

The most valuable parts are the critical rules and anti-patterns, because they encode lessons the assistant cannot derive from the code. Two real examples from this repository:

NoteExample rule: voice and audience in student-facing content

The student notebook is read by students, not by instructors who then teach it. Every sentence in a student-facing cell, including Gemini prompts and “After running, verify” checklists, must be written to the student, never about the student, and never to the instructor.

This rule exists because in early sessions the assistant drifted into instructor-voice phrasings like “… so students see the per-class breakdown.” The student is the reader, so the phrase is wrong. After the rule went into CLAUDE.md, the regression effectively stopped. I also wrote a small script (scripts/voice_check_guides.py) that grep-audits modified files, so the constitution is enforced and not just declared.

NoteExample rule: CV-first evaluation and test-set lock

From notebook 9 onward, all model-performance claims come from cross-validation. Before notebook 14, the test set is locked and no model evaluation touches it. Notebook 14’s “Opening the Locked Test Set” ceremony is the one and only authorized test-set opening in the entire course.

This is not a style preference. It is the pedagogical spine of the course. If the assistant generates an accuracy_score(y_test, ...) call in notebook 11 because it is the obvious thing to write, notebook 14’s payoff disappears. Encoded as a CLAUDE.md rule plus a runnable audit (scripts/audit_cv_first.py), the rule is durable across sessions.

The pattern is the same in both cases: write the rule down, then encode it as a check the assistant can run on demand.

4.2 Keep a source .md file for every artifact

This is the recommendation I would give first if a colleague asked me for one thing only. Every kind of artifact in the course has a corresponding plain-text “source” file in the repo:

Artifact Source-of-truth file(s)
Notebooks (student-facing) notebooks/nbNN_topic_student.ipynb
Notebooks (instructor, with solutions) notebooks/nbNN_topic_instructor.ipynb (gitignored, local-only)
Video lecture guide (script and timestamps) video_guides/NN_video_lecture_guide.md (gitignored)
Brightspace content pages brightspace/NN_topic.md
Quizzes _quizzes/2026Summer/
Midterm exam _midterm_exam/2026Summer/
Assignment specs and grading rubrics _final_project/2026Summer/milestone_0*.md, _course_case_competition/2026Summer/course_case_competition_instructions.md
Notebook to NotebookLM podcast transcript _notebook_lm/<basename>.md (auto-generated, gitignored)
Course map and rationale _project_docs/MGMT47400_Online4Week_Plan_2026Summer.md
Implementation plan _project_docs/claude_course_plan.md
Conventions and decisions _project_docs/DECISIONS.md
Troubleshooting playbook _project_docs/TROUBLESHOOTING.md
Session-by-session history CONVERSATION_LOG.md

Two benefits compound here. First, the AI can read and edit any of these directly. There is no copy-paste from a web UI, no screenshots, no “look at this PDF.” Second, when a quiz question changes, you can ask the assistant to propagate that change to the matching Brightspace page, to the relevant video-guide section, and to the schedule. Plain-text source files are what make that propagation possible.

The same discipline extends to assignments and their grading rubrics: each milestone and the case competition has a plain-text specification with its rubric, so the criteria students are handed are the criteria they are evaluated against, and the assistant can keep an assignment, its rubric, and the schedule in sync. One firm boundary comes with this: anything that identifies a student, such as rosters, submissions, grades, or filled-in rubrics, must be set up under FERPA from the very start. In this repo that means all of it lives in a gitignored admin tree, with the task tracker in a private companion repo, never in the public-facing repository or its history.

TipWhat goes into a source .md file

Not just the artifact itself, but also the rationale for it. Each Brightspace page in this repo begins with what the student is learning today, why this matters, and how this connects to yesterday and tomorrow. That framing is for me and for the assistant, not only for the student. When the assistant has the rationale, it edits the artifact in ways that preserve intent.

4.3 Adopt an instructor-first notebook workflow

Notebooks are the workhorse of this course (21 of them, roughly one per business day). The convention I settled on after a lot of failed alternatives:

  1. Edit the instructor notebook first. nbNN_topic_instructor.ipynb is the source of truth and contains all solutions inside cells marked with INSTRUCTOR SOLUTION. This file is gitignored and never leaves my machine.
  2. Generate the student notebook from it. Copy the instructor file, strip every cell tagged with INSTRUCTOR SOLUTION, update the Colab badge URL, and commit only the student file.
  3. Update the matching video guide in video_guides/, which is also gitignored. Speaking prompts, cell references, and timestamps live there.
  4. Render the Quarto site and commit docs/ so the website actually reflects the change.

This sequencing matters because it gives the assistant a single, unambiguous answer to the question where do I write the next edit? Without it, the assistant has been known to edit the student file directly, lose the solution version, and force me to reconstruct it from memory. With it, the workflow is mechanical.

One more piece of sequencing surprised me, and I think it generalizes. I can only record the lecture videos after the notebook is genuinely finalized, because the camera captures whatever is on the screen and any later edit forces a re-take. So before I press record, I read the notebook end to end and walk through the matching video-guide narrative one more time. That last pass catches anything that drifted while I was working on adjacent notebooks, and it ensures the notebook, the guide, and the recording all say the same thing. If you skip the pass, the recording will reveal the disagreement and you will lose an hour.

4.4 Encode invariants as runnable scripts

The most reliable rules in this project are the ones I made the assistant enforce on itself before committing. Two examples, both real, both in scripts/:

Notescripts/audit_cv_first.py

Scans every notebooks/*_student.ipynb for model-evaluation uses of X_test and y_test that violate the CV-first rule. The only acceptable hits are the two authorized openings in notebook 14 (the test-set ceremony) and notebook 18 (the Kaggle-submission demo). Anything else is flagged and must be fixed before commit.

Notescripts/voice_check_guides.py

Audits video-guide markdown for instructor-voice violations inside blockquotes only (the read-aloud sections), while leaving wrapper prose untouched. It flags students (as a third-party noun), the instructor, on camera, and speaking prompt, but whitelists Student's t because that one is the statistical test, not a regression.

Why this matters: a rule that lives only in CLAUDE.md depends on the assistant remembering and applying it. A rule that exists as a script gets run every commit, regardless of which “TA” is on shift today. The conversation about voice does not have to happen again. The audit either passes or it does not.

4.5 Automate the boring parts with hooks

Claude Code lets you configure shell commands to run automatically around tool calls and at session boundaries. I use hooks for two things, and both have paid for themselves many times over: the first runs after every relevant edit, the second at the end of every session. The first lives in the repo’s shared .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "f=$(jq -r '.tool_input.file_path // .tool_input.notebook_path // empty'); case \"$f\" in *_instructor.ipynb) bash \"$CLAUDE_PROJECT_DIR/scripts/sync_instructor_md.sh\" \"$f\" >&2 ;; esac"
          }
        ]
      }
    ]
  }
}

Translation: every time the assistant edits an instructor notebook, a shell script regenerates the corresponding _notebook_lm/<basename>.md file so NotebookLM (Google’s research and podcast tool) can ingest the latest version automatically. This is not hypothetical: in this repo the hook keeps a markdown companion in sync for all 21 instructor notebooks, and I have never once had to remember to export one by hand. It is the same idea Pedro Sant’Anna documents extensively in his guide.

4.5.1 The hook that ended “did I remember to push?”

The second hook is the one I would not give up. The single most common project-wide mistake in my first two months was content drift: I would change a notebook, forget to re-render Quarto, and the published website would silently fall behind the source. The render-and-commit ritual (below) fixed that as a discipline. A Stop hook fixed it as tooling, which is strictly better, because tooling does not get tired at 11pm.

The Stop hook fires every time a turn finishes. I wired it to a small script, scripts/session_autocommit.sh, that commits and pushes whatever the turn changed:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/scripts/session_autocommit.sh\"",
            "timeout": 600 }
        ]
      }
    ]
  }
}

The script is deliberately built with guardrails, because an automation that commits on your behalf has to be conservative or it will eventually do something you regret:

  • It is a no-op on ordinary turns. If no tracked file changed, it exits silently, so a conversational turn (asking a question, reading a file) commits nothing.
  • It stages tracked changes only: git add -u, never git add .. Stray untracked artifacts (rendered *.html, *_files/ directories, large CSVs, secrets, the gitignored instructor notebooks) are never swept in. Genuinely new files I still stage by hand, on purpose.
  • It renders before it commits. If the turn touched content (.qmd, .ipynb, _quarto.yml, or an image), the script runs quarto render and stages docs/ first, so the published site can never lag the source.
  • It is tolerant. A failed render or an offline git push logs to stderr and is left for next time; it never aborts the session or loses work.
  • It has escape hatches. touch .claude/.autocommit-off disables it without editing any JSON, and AUTOCOMMIT_DRYRUN=1 makes it print what it would do and change nothing.

Two implementation notes a colleague will care about. First, I chose Stop over the seemingly more natural SessionEnd hook, because SessionEnd does not fire when you quit with /exit, so it cannot reliably push; Stop fires at the end of every turn, and the no-op guardrail keeps it quiet the rest of the time. Second, this hook lives in .claude/settings.local.json, my personal gitignored settings, not in the shared .claude/settings.json that ships with the repo. An auto-push hook is a choice about my own machine and my own push credentials; it would be presumptuous to impose it on anyone who clones the course. The rule of thumb I settled on: shared hooks that benefit everyone (the NotebookLM sync) go in settings.json; personal automation (auto-commit, auto-push) goes in settings.local.json.

4.6 Keep a planning and memory layer, not just a commit log

Git remembers what changed. It does not remember why you changed it, where the course is headed, or what you tried last month that did not work. The biggest single reason this project stayed coherent across more than two dozen sessions and a rotating cast of “TAs” is a small set of plain-text documents that carry exactly that. They split into three jobs: plan forward, decide once, and remember backward.

Plan forward. Two documents hold the design before any notebook exists. _project_docs/MGMT47400_Online4Week_Plan_2026Summer.md is the course map: the delivery constraints, the daily pedagogical pattern, the grading scheme, the notebook-sequence rationale, and a day-by-day plan for all twenty business days. _project_docs/claude_course_plan.md is the implementation plan: how the 16-week in-person course was migrated into the 4-week online format, phase by phase, with a content justification for every notebook in the new sequence. Pointing the assistant at these two files at the start of a session is what lets it act on the whole course rather than the one file in front of it. They are the reason a change to Day 9 does not quietly break the arc that Day 12 depends on.

Decide once. _project_docs/DECISIONS.md is the rationale ledger: eleven short, numbered entries explaining the load-bearing choices, including the 60/20/20 split, RANDOM_SEED = 474, Colab-plus-Gemini over local Jupyter, the instructor-first workflow, CV-first evaluation, the nb08 narrative pattern, and MC option-length parity. Each entry exists because the choice was second-guessed at some point; writing the reasoning down once ends the debate every later time it resurfaces. Most of the critical rules in CLAUDE.md have a matching decision here that explains why the rule is worth enforcing.

Remember backward. CONVERSATION_LOG.md is the project’s memory: a session-by-session journal, appended (never overwritten) at the end of each working session, now more than two dozen entries long. It is the first place I look when I have forgotten what we tried in a prior round, and the first thing I have the assistant read when a session needs to resume with full context. _project_docs/TROUBLESHOOTING.md is the narrower failure playbook: the ten or so problems I have actually hit, each with its fix, from Quarto render glitches and stale GitHub Pages to Colab breaking on an unescaped $ in a money string and a Colab badge pointing at the wrong file. Future-me reads it so future-me does not re-debug what past-me already solved.

None of these five files is glamorous, and together they may be the most important infrastructure in the repository. They are the written form of the rotating-TA lesson from the tradeoffs above: the plan, the rationale, and the memory all live on disk, so the next session, whoever is driving it, starts where the last one left off instead of from scratch.

4.7 Skills became the backbone: running the course from a private companion repo

In the mid-stream draft of this page I wrote that I had not built any skills yet and would “invest there in the next iteration.” That turned out to be the best prediction I made here: skills became the backbone of how I run the course, and I now wish I had built the first one in week one.

Claude Code supports user-defined skills: reusable, invocable workflows (often registered as slash commands) that bundle a prompt, a sequence of steps, and access to specific tools. The one that earned its keep I call course-tasks. It runs both halves of the job off GitHub Issues: course development (write the NB07 quiz, render the schedule, record the Day 9 videos) and live operations (publish the deadline reminder, open the quiz Tuesday and close it Friday, prep the Friday session). I describe a commitment in plain language and it becomes a tracked, labeled (course-task) GitHub issue carrying structured metadata: due date, area, priority, and explicit blocks/blocked-by links. When I ask “show me my tasks,” it reads the open issues and produces a prioritized, deadline-driven report grouped by urgency, escalating anything whose deadline is near or that blocks two or more downstream tasks. The board became my source of truth for what to do next, the same way CLAUDE.md is the source of truth for how to do it.

The design decision I most want a colleague to copy is where those tasks live. They do not live in the public course repository. Each course repo X is paired with a separate, private companion repo named X-tasks (for this course, …MGMT474-tasks) that holds every issue. That separation is deliberate, and I think it is important. A course-operations tracker inevitably accumulates things you must never publish: student names, individual standing, grades. Keeping the tracker in a private companion repo means I can record anything, sensitive or not, in one place, while the public-facing repository stays exactly that. It is the same FERPA-minded instinct that keeps every student-identifying artifact, such as rosters, submissions, or grades, out of the public repo: that material lives in a gitignored admin tree and never touches GitHub Pages or the public history, by construction rather than by my remembering to be careful.

If you are starting a new project, skills are the highest-leverage place to invest early, and a private companion repo for tasks costs nothing on day one while saving you a FERPA headache later. For a domain-specific catalog of how academics are using skills, I recommend the Claude Code Skills for Academics PDF (listed in the references below), which collects concrete patterns by discipline and is the cleanest starting point I have found.

5 Examples from this repository

Concrete is more useful than abstract. Three patterns from this course, named so a colleague can lift them.

5.1 The PAUSE-AND-DO block

Every student notebook is organized around the rhythm Concept, Demo, PAUSE-AND-DO practice, Solution discussion. The PAUSE-AND-DO block has a fixed six-cell anatomy in the instructor notebook (cells 4 through 6 are stripped from the student copy):

1. ## 📝 PAUSE-AND-DO Exercise X       (markdown, prompt)
2. > 💡 Gemini Prompt: ...              (markdown, AI prompt + verify checklist)
3. # YOUR SOLUTION CODE HERE           (code, student writes here)
4. ### INSTRUCTOR SOLUTION             (markdown, removed for student)
5. # INSTRUCTOR SOLUTION               (code, removed for student)
6. <!-- INSTRUCTOR SOLUTION -->        (markdown, "reading the output", removed)

This is encoded in _project_docs/NOTEBOOK_TEMPLATE.md so any session, mine or the assistant’s, can produce a new exercise in the canonical shape without me re-explaining it.

5.2 The narrative polish pattern

Every markdown cell in a student notebook follows five structural elements borrowed from notebooks/nb08_cross_validation_model_comparison_student.ipynb, which I treat as the canonical voice for the course:

  1. A business-case “Why This Matters” cell with a named stakeholder (the HomeValue CFO, the MedScreen chief medical officer, the TechCorp People Analytics lead).
  2. Narrative prose, not bullet lists, in “Reading the output” cells.
  3. Inline Q&A blocks introduced by the grep-findable phrase “A question that often comes up here”.
  4. Explicit section bridges, for example “Section 2 landed the regression estimate with a tight CI. Now apply the identical four steps to the classification problem.”
  5. Warm wrap-ups with a one-paragraph bridge to the next notebook.

Because the pattern is documented and the trigger phrases are grep-findable, the assistant can polish a batch of notebooks consistently, and I can spot-check by running grep "A question that often comes up" across all student notebooks.

5.3 The render-and-commit ritual

The most common project-wide mistake I made in the first two months was pushing a content change without rendering Quarto, so the website would silently go stale. I fixed this by writing the ritual into the constitution, in plain steps the assistant can follow:

# 1. Commit content changes
git add notebooks/nbNN_topic_student.ipynb
git commit -m "feat: Update notebook NN"

# 2. Render the Quarto site
/Applications/RStudio.app/Contents/Resources/app/quarto/bin/quarto render

# 3. Commit rendered docs/
git add docs/
git commit -m "build: Render Quarto site"

# 4. Push everything
git push origin main

Tiny ritual, large payoff. As long as the assistant follows the four-step sequence, the website never drifts from the notebooks.

6 Pitfalls I hit (so you don’t have to)

A short list, in rough chronological order:

  • Trusting “looks done” without rendering. Content pushed, website stale. Fixed by promoting render-and-commit to a critical workflow in CLAUDE.md.
  • Letting solutions leak into the student notebook. Fixed by the instructor-first workflow plus an unambiguous INSTRUCTOR SOLUTION marker convention.
  • Drift in voice between sessions. The student-versus-instructor voice problem. Fixed by the voice_check_guides.py audit plus an explicit rule with examples in CLAUDE.md.
  • Test-set leakage in early-week notebooks. Fixed by the CV-first rule plus the audit_cv_first.py script.
  • Overwriting CONVERSATION_LOG.md instead of appending. Lose the history once, lose it forever. Now an explicit anti-pattern in the constitution.
  • git add . accidentally staging temp files, large CSVs, or local-only video drafts. Always git add <specific files>. Reviewing git status before staging is now part of the routine.

7 Using this course as a template for your own

If you would like to use this repository as a starting point rather than reinventing the workflow, there are two paths. Replicate the design if you teach a course that resembles QM47400 in spirit, meaning a data-skills course delivered online or in a compressed window. Use it as a reference if your domain is different, and lift only the patterns that transfer. And if you would rather build your own from a blank page than clone this one, the closing subsection, starting from scratch, gives the minimal sequence.

The eight steps below are the most direct on-ramp. Each step lists what to do, the prompt you can paste into Claude Code (shown in blockquotes), and the files in this repository to point the assistant at (shown as hyperlinks). Every linked file is public; the only things deliberately kept out of the repo are student-identifying material and answer keys.

7.1 Step 1. Get the repository onto your machine

  1. Clone the repo into a sensible working directory:
git clone https://github.com/davi-moreira/2026Summer_predictive_analytics_purdue_MGMT474.git
cd 2026Summer_predictive_analytics_purdue_MGMT474

  1. Install Claude Code if you have not yet, then launch it from inside the cloned repo so the working directory is set correctly.

  2. (Optional but recommended.) Open the same directory in your preferred editor or IDE so you can read along while the assistant works.

7.2 Step 2. Get oriented before you change anything

  1. Ask the assistant to read the constitution and the course plan, then describe the project back to you:

Read CLAUDE.md and _project_docs/MGMT47400_Online4Week_Plan_2026Summer.md. Describe back to me how this course is structured: the pedagogy, the 21-notebook arc, the source-of-truth files, and the rules that are non-obvious.

  1. Ask for the file map:

List every kind of source file in this repo and what each one is the source of truth for. Group them by artifact type (notebooks, video guides, Brightspace pages, quizzes, exam, and so on).

  1. Spot-check by opening one notebook the assistant cites, for example notebooks/nb08_cross_validation_model_comparison_student.ipynb, so you can see what “canonical voice” actually looks like.

7.3 Step 3. Translate the constitution to your domain

  1. Copy CLAUDE.md into your own repo, then ask the assistant to adapt it:

This is the constitution from another course’s repo. Adapt it for my course, which is [your course code and topic]. Replace QM47400, swap “predictive analytics” for my subject, and go through each critical rule and anti-pattern one by one. For each, tell me whether it transfers cleanly, needs editing, or does not apply.

  1. Keep the structural elements even if every concrete rule changes: project mission, the “see also” reference table, critical rules with a 🚨 prefix, style guidelines as a table, anti-patterns, and a session-end checklist.

  2. Also copy and adapt the companion files: DECISIONS.md, TROUBLESHOOTING.md, and NOTEBOOK_TEMPLATE.md. They start small and grow alongside the project.

7.4 Step 4. Adopt one pattern at a time, not all at once

Start with the two patterns that cost almost nothing and remove the two most common failure modes.

  1. The render-and-commit ritual. Copy the four-step ritual from §5.3 into your own CLAUDE.md as a critical workflow, adjusted to your renderer (Quarto, Jekyll, Hugo, MkDocs).

  2. Per-artifact source .md files. Pick one artifact (a syllabus, one quiz, one Brightspace content page). Convert it to plain-text Markdown. Edit it with the assistant. Notice what the assistant gets right and where it drifts. Capture the corrections in CLAUDE.md.

  3. After those two are stable, add the instructor-first notebook workflow from §4.3 if your course uses notebooks or lab worksheets. This is the highest-leverage addition for any course built around hands-on practice.

7.5 Step 5. Adapt the audit scripts to your invariants

  1. Read both audit scripts in this repo:
  1. Identify two or three invariants in your course that you keep correcting by hand. Then ask the assistant:

Read both audit scripts in scripts/. The invariants in my course are: [list them]. Write the equivalent audit scripts and explain how to wire them into the commit workflow.

  1. A few domain-specific invariants worth automating:
  • Causal inference course: no causal claim on observational data without a stated identifying assumption.
  • Writing-intensive course: passive voice flagged in graded examples and rubrics.
  • Lab course: every method section cites the protocol it follows.
  • Any course with student-facing materials: a voice check like voice_check_guides.py.

7.6 Step 6. Automate the routine, and track the course itself

  1. Move the rituals from discipline into tooling with hooks (§4.5). The single most useful one is a Stop hook that runs your render-and-commit ritual automatically when a session ends. Ask the assistant:

Write a Stop hook for Claude Code, wired in .claude/settings.local.json, that runs a script to commit and push whatever the session changed. Guardrails: no-op when no tracked file changed; stage tracked changes only (git add -u, never git add .); if a .qmd or .ipynb changed, render the site and stage the output first; tolerate a failed render or an offline push without aborting the session.

  1. If you will run the course and not only build it, track it in a private companion repo (§4.7). Create a separate, private <your-repo>-tasks repository and keep announcements, grading windows, and content deadlines there as labeled issues, so nothing student-identifying ever lands in the public course repo.

7.7 Step 7. Reuse the bulk-CSV pattern for Brightspace quizzes

  1. Either export one existing quiz from Brightspace as CSV, or build one by hand in the format Brightspace’s Question Library expects.

  2. Save that file inside a _quizzes/ folder in your own repo. This becomes your schema example. (Mine is intentionally not in the public repo, because quiz banks carry answer keys.)

  3. Generate the next quiz by pointing the assistant at the schema example:

Use _quizzes/<term>/<example-quiz>.csv as the format. Generate a 10-question quiz on [topic], in the same CSV shape, with plausible distractors and one correct answer per question.

  1. Review, edit, upload. The hour you invest in step (a) pays back across the entire semester.

7.8 Step 8. Share what you build (and what failed)

  1. Open an issue on the course repository describing what you adapted, what worked, and what failed.

  2. Or just email me directly. I keep updating this page as I learn, and a sharper version of any of these patterns from a different discipline is genuinely useful to me.

7.9 If you are starting from scratch

Not everyone will want to clone this repo, and you do not have to. If you would rather build your own course workflow from a blank page, the moves are the same; you just bootstrap them yourself:

  1. Create the repo and commit one artifact. Run git init, drop in a single file (even just your syllabus), and commit. That one commit is enough to begin.
  2. Write a one-page CLAUDE.md with your course mission, the three style rules you care most about, and a short “see also” list. Do not over-engineer it; it will grow. Use the structure in §4.1 as the skeleton.
  3. Convert one artifact to a source .md file, a quiz or a content page, edit it with the assistant, and capture every correction back into CLAUDE.md. That single loop will teach you more about the tool than any amount of reading.
  4. Adopt the render-and-commit ritual the moment you have a website, and keep a CONVERSATION_LOG.md from session one, even three sentences per session. Drift is the most common failure and forgotten context is the next; these two habits remove both.

Then iterate. Expect month one to feel like overhead and month three to feel like leverage. That gap is the cost of learning the tool. It is real, it is shorter than you fear, and you only pay it once.

8 References

Feedback welcome. If you are a Daniels School colleague (or anyone else) adopting parts of this workflow for your own course, I would genuinely like to hear what worked and what did not. Email me at dcordeir@purdue.edu. I updated this page across the Summer 2026 offering, from design through delivery, and I will keep refining it as my own practice changes.