justin/ai-workflow-course
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(M1-6): apply AI-drives-git reframe, lesson=theory, de-slop, + issue fixes

Browse Source 
Phase 1 of the reframe. M1-3 stay manual-by-hand (browser chat); M4 is the pivot
to the AI agent (Claude Code as example); M5-6 are agent-driven.

- M1: de-slop (em-dashes), relocate the build-note out of the lab. Seam devices kept.
- M2: #78 tell learner how to paste cli.py into chat; #79 commit the delete so the
  tree ends clean. restore/cold-session devices kept.
- M3: #80 define ADR; #81 create-file-before-add; #82 ls before/after merge to prove
  branch isolation; #83 drop "prose"; M3 now owns the branch-basics intro.
- M4: #84 Claude Code as the worked example; #85 AI drives git (arithmetic->calculator);
  #86 /path/to -> ~/ai-workflow-course; #87 agent does the revert+verify.
- M5: #88 ask the agent which config files to commit, then let it stage/commit
  (CLAUDE.md example; repo still uses AGENTS.md).
- M6: #90 stop re-teaching branch basics; rescope to the AI experimenting on a branch;
  the engineered conflict is now AI-resolved, learner-verified.

Closes #78
Closes #79
Closes #80
Closes #81
Closes #82
Closes #84
Closes #85
Closes #87
Closes #88
Closes #90

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TfzV5QvtPDz8LJS3Pu5VLT
This commit is contained in:
Claude (agent)
2026-06-22 21:41:14 -04:00
parent 2467f25901
commit 896c4606c6
8 changed files with 578 additions and 481 deletions
Download Patch File Download Diff File Expand all files Collapse all files
modules/01-the-copy-paste-problem/README.md
+39 -35
View File
@@ -19,7 +19,7 @@ command is shown and explained.
By the end of this module you can:
1. Articulate *why* the chat-to-file copy-paste loop fails — not vaguely, but at the three specific
1. Articulate *why* the chat-to-file copy-paste loop fails: not vaguely, but at the three specific
seams where it breaks.
2. State the course thesis and explain what "the workflow is the durable skill" means for your own
work.
@@ -44,20 +44,20 @@ Here is the workflow almost everyone starts with, and it genuinely works for a w
7. Go to 2.
For a single file you're poking at for an afternoon, this is fine. The friction is low and the
results are real. The problem isn't that this loop is *bad* — it's that it **doesn't scale along the
two axes every real project grows on: more than one file, and more than one day.**
results are real. The problem isn't that this loop is *bad*. It's that the loop **doesn't scale along
the two axes every real project grows on: more than one file, and more than one day.**
### Seam 1 — More than one file
The moment your project is two files instead of one, the chat window loses the thread. You paste in
`cli.py`, ask for a change, and the AI confidently edits it — but the change actually needed to touch
`cli.py`, ask for a change, and the AI confidently edits it. But the change actually needed to touch
`tasks.py` too, which it can't see because you only pasted one file. Or it *can* see it because you
pasted both, but now its reply rewrites both files and you're hand-merging two blobs of text back
into two real files, hoping you didn't drop a function in the shuffle.
You become the integration layer. Every change is a manual diff you perform in your head, between
what's in the chat and what's on disk. That's slow, and worse, it's *error-prone in a way you can't
see* — there's no record of what actually changed.
see*: there's no record of what actually changed.
### Seam 2 — More than one day
@@ -71,33 +71,32 @@ disk, so every session starts cold.
### Seam 3 — No undo, no record, no safety
This is the quiet one, and it's the most dangerous. When the AI confidently makes a mess — deletes a
This is the quiet one, and it's the most dangerous. The AI confidently makes a mess. It deletes a
function you needed, "refactors" something into a subtly broken state, rewrites a file you'd carefully
tuned — what's your recovery plan?
tuned. What's your recovery plan?
Right now it's probably: *Ctrl-Z until it looks right*, or *paste the old version back from the chat
history if I can find it*, or, too often, *retype it from memory*. There is no checkpoint you can
return to and no record of what changed between "working" and "broken." You're doing high-wire work
with no net, and the AI makes it *easier* to do a lot of risky changes fast — which means you fall
more often.
with no net, and the AI makes it *easier* to do a lot of risky changes fast. So you fall more often.
### The reframe
Notice what all three seams have in common: **none of them are about the AI's intelligence.** A
smarter model writes better code, but it doesn't give you a record of changes, a way to undo a mess,
or a memory that survives a closed tab. Those come from the *engineering scaffolding around* the
model — version control, a real editor integration, hosting, review, automation.
model: version control, a real editor integration, hosting, review, automation.
That scaffolding is what this course teaches. And here's why it's worth your time specifically now:
> **The model is the cheap, swappable part. The workflow around it is the skill that lasts.**
Models change every few months. The one you're using today will be replaced — probably by something
cheaper and better — and when that happens, your prompts mostly carry over and your habits fully
Models change every few months. The one you're using today will be replaced, probably by something
cheaper and better, and when that happens your prompts mostly carry over and your habits fully
carry over. The version-control discipline, the review reflex, the CI pipeline, the way you give an
agent a branch instead of your whole repo — *none of that depends on which model you run.* You learn
agent a branch instead of your whole repo: *none of that depends on which model you run.* You learn
it once and it pays out across every model you'll ever use. That's why this course is deliberately
model- and vendor-agnostic: we're teaching the part that doesn't expire.
model- and vendor-agnostic. We're teaching the part that doesn't expire.
---
@@ -107,14 +106,14 @@ A generic "intro to developer tools" course would teach the same git, the same e
CI. What makes this one different is that **AI changes the cost-benefit of every tool in it**, and
usually makes the tool *more* valuable, not less:
- AI makes changes **faster and more confidently** — including the wrong ones. That raises the value
- AI makes changes **faster and more confidently**, including the wrong ones. That raises the value
of an undo you can trust (Module 2) and a review gate (Module 10).
- AI **can't remember** across sessions — but your repo can. Version control becomes durable memory
- AI **can't remember** across sessions, but your repo can. Version control becomes durable memory
the AI reads back (Module 2).
- AI generates code that **looks right** and passes a human skim. That's exactly what automated
testing and CI exist to catch (Modules 13–14).
- AI itself can become a **teammate inside the workflow** — opening PRs, triaging issues, fixing
failing builds — but only safely once the scaffolding is there to catch it (Unit 5).
- AI itself can become a **teammate inside the workflow**, opening PRs, triaging issues, fixing
failing builds, but only safely once the scaffolding is there to catch it (Unit 5).
You don't adopt this toolchain *despite* using AI. You adopt it *because* you're using AI. The pain
you already feel is the curriculum.
@@ -148,7 +147,7 @@ purpose** so you recognize it later.
Everything you'll run in this course lives in one repo. Grab it once, up front — no tools required
beyond a web browser:
1. Open the course's home page — **`https://git.jpaul.io/justin/ai-workflow-course`** — and use its
1. Open the course's home page, **`https://git.jpaul.io/justin/ai-workflow-course`**, and use its
**Download ZIP** (archive) link.
2. Unzip it under your home directory so the course's `modules/` folder lands at
`~/ai-workflow-course/modules/`. (Rename the unzipped folder to `ai-workflow-course` if your download
@@ -157,12 +156,9 @@ beyond a web browser:
You now have every module's files locally, including this one's under
`modules/01-the-copy-paste-problem/`.
> *A cleaner, **updatable** way to get the repo — `git clone` — arrives in **Module 8**, once you've
> *A cleaner, **updatable** way to get the repo, `git clone`, arrives in **Module 8**, once you've
> learned Git (Module 2). A one-time ZIP is all you need today; don't reach for `clone` yet.*
> *Verify-before-publish: confirm this download URL points at the published course host before
> shipping.*
### Part A — Stand up the project
1. Make a working directory and copy in the starter app from this module's `lab/starter/` folder:
@@ -197,16 +193,17 @@ You now have every module's files locally, including this one's under
Now reproduce each failure deliberately. Keep the AI strictly in the **browser chat** — no
editor-integrated tools yet (those arrive in Module 4). This is the "before" picture on purpose.
1. **Seam 1 (multiple files).** First mark a task done so there's something to hide — `python cli.py
done 0`, then `python cli.py list` shows it as `[x]`. Now paste *only* `cli.py` into your chat and
ask: *"Make the `list` command hide tasks that are already done."* Apply whatever it gives you and
run `python cli.py list`. The clean version of this change lives in `tasks.py` — the file you
*didn't* paste: open it and you'll see `render()` already owns the `[x]`/`[ ]` box-and-index
formatting, and a `pending()` helper already returns exactly the not-done tasks. But the chat
never saw that file, so it had to either guess at methods it couldn't see (and `python cli.py
list` errors out) or reach into the raw task list and *re-create* that box-and-index formatting
inside `cli.py` — duplicating logic that already existed one file over. Either way, *you* had to
be the one who knew the change really belonged in the other file.
1. **Seam 1 (multiple files).** First mark a task done so there's something to hide. Run `python
cli.py done 0`, then `python cli.py list` shows it as `[x]`. Now paste *only* `cli.py` into your
chat and ask: *"Make the `list` command hide tasks that are already done."* Apply whatever it
gives you and run `python cli.py list`. The clean version of this change lives in `tasks.py`, the
file you *didn't* paste: open it and you'll see `render()` already owns the `[x]`/`[ ]`
box-and-index formatting, and a `pending()` helper already returns exactly the not-done tasks. But
the chat never saw that file, so it had to do one of two things. Either it guessed at methods it
couldn't see (and `python cli.py list` errors out), or it reached into the raw task list and
*re-created* that box-and-index formatting inside `cli.py`, duplicating logic that already existed
one file over. Either way, *you* had to be the one who knew the change really belonged in the
other file.
2. **Seam 2 (across time).** Close the chat tab. Open a new one. Ask it to *"continue where we left
off."* Watch it have no idea what you were doing. The project's real state is sitting right there
@@ -229,9 +226,9 @@ Be honest about the limits of this module's claims:
- **Copy-paste isn't *wrong*, it's *unscalable*.** For a one-file throwaway script, the loop is
genuinely the fastest path. Don't over-engineer a five-line utility. The toolchain earns its keep
as soon as a project has a second file or a second day — which is most of them, but not all.
as soon as a project has a second file or a second day, which is most of them, but not all.
- **Tools don't fix judgment.** Version control will let you undo a bad AI change instantly; it won't
tell you the change was bad. That skill — reviewing AI output — is its own module (10), and no
tell you the change was bad. That skill, reviewing AI output, is its own module (10), and no
amount of scaffolding replaces it.
- **This module doesn't make you faster yet.** Setup rarely does. The payoff compounds over the next
six modules. If it feels like overhead right now, that's expected.
@@ -251,3 +248,10 @@ Be honest about the limits of this module's claims:
If all three are true, you're ready for Module 2, where we install the safety net that makes the
rest of the course safe to attempt.
---
## Verify-before-publish
- [ ] Confirm the **Download ZIP** URL (`https://git.jpaul.io/justin/ai-workflow-course`) points at
the published course host before shipping.