Why the first edit is the one that matters most CORE
The temptation, especially on a first directed edit, is to pick something easy: “add a comment,” “rename a variable.” Do not. The first edit should be small enough to finish in one sitting but large enough to actually show you the four moves. A bug fix in a script you can run is the sweet spot.
This lesson gives you exactly that, on a starter repo we have prepared: a small Python CLI (around 200 lines) called tidy that sorts files into subfolders by extension. It has two known bugs — one that is obvious from the output and one you will only notice if you look at the code — and one missing feature you will add later in Lesson 3.5. You will fix both bugs in the Code tab of the Claude desktop app, so by the end of the lesson you'll have directed two real repository edits and have practice running the four-move loop on different shapes of bug. (Optional advanced: an end-of-lesson sidebar shows how to do Bug 2 in the Claude Code CLI instead, for students who set up the CLI in Lesson 2.4.)
If you already have a small codebase of your own you would rather use — a personal script, a homework project — you may substitute it for the starter repo. If you do, pick one that (a) runs, (b) has a small, well-defined bug you can describe in one sentence, and (c) has at least one file you could realistically break if the agent did the wrong thing. That last point is important. A directed edit on a codebase you cannot break is a safe simulation; a directed edit on one you can is the real motion.
The shape of the exercise CORE
Both runs in this lesson follow the same shape:
- State the goal in one sentence, in writing. Not in your head. In the prompt or in a notes file. A goal you cannot write down is a goal you cannot verify against.
- Ask the agent to locate the bug before it writes any code. You are making the locate step explicit. The agent should tell you which file and which function it thinks the bug is in before it proposes a change.
- Ask for a plan before the write. One or two sentences, not an essay. The plan lets you sanity-check the approach before you spend attention on the diff.
- Let the agent write the diff. Watch it. Do not do anything else during the write — no switching tabs, no scrolling the feed. This is not busywork; watching teaches you the rhythm of what “normal” looks like, and that is what lets you notice abnormal later.
- Review the diff before you accept it. Look at the shape — which files changed, how big the change is, did anything get added or deleted that you didn't ask for. Read the agent's own summary of what it did and confirm it matches what you asked for. For any specific change you don't understand, ask the agent to explain it in plain language: “What does this change do, and why did you make it?” You don't need to understand every line of code; you do need to satisfy yourself that what the agent did matches what you asked, and that running it actually does the thing.
- Run the verify step. Re-run the script or the tests. Confirm the behavior changed in the way the goal said it would.
- Commit, or reject and try again. If you merge, write the one-sentence reflection. If you reject, note why it failed — the agent wrote in the wrong place, the plan did not match the diff, the test did not actually pass — and try again with a tighter prompt.
That is the core rhythm of a directed edit for the rest of your career. You will run it thousands of times. Most of them will be faster and less ceremonial than this first one. The scaffolding is heavier here because the shape is what we are installing.
Get the Module 3 starter repo onto your machine RECIPE
| Tool | Git + your terminal |
| Last verified | 2026-04-17 |
| Next review | 2026-07-17 |
| OS | macOS, Linux, Windows |
Prerequisites. Python 3.10+ and git, both installed and verified in Module 2 Lesson 2.2. If you skipped that lesson, the prerequisite callout at the top of this lesson lists the verification commands.
A note on where the starter repo lives. The starter repo is bundled inside this course package under resources/module-03/tidy-starter/. As the course rolls out, the same repo will also be published on GitHub at the URL in the Recipe Book entry cloning-the-module-3-starter-repo. Either source is fine. The git clone path below is the long-term plan; the local-copy path right after it works today and is what most students starting this course will use. Pick one.
Step 0 — Make a “code” folder if you don't have one
You'll keep the starter repo (and any other code projects from this course) in a single parent folder. If you don't already have one, create it now:
- macOS/Linux: mkdir -p ~/code && cd ~/code
- Windows (PowerShell): mkdir $env:USERPROFILE\code -Force ; cd $env:USERPROFILE\code
For the rest of this lesson, “your code folder” means whatever folder you just made (or whatever you already use). Substitute as needed.
Path A — Copy the local starter repo (works right now)
- Open your terminal in your code folder. Confirm with pwd (Mac/Linux) or pwd (Windows).
- Copy the starter repo from the course package into your code folder. Replace <COURSE_PATH> with the path where you have the course files:
- macOS/Linux: cp -r <COURSE_PATH>/resources/module-03/tidy-starter ./tidy-starter && cd tidy-starter
- Windows (PowerShell): Copy-Item -Recurse <COURSE_PATH>\resources\module-03\tidy-starter .\tidy-starter ; cd .\tidy-starter
- Initialize git in the copy (so you can commit your edits): git init && git add . && git commit -m "Initial: starter repo from course". This makes a clean baseline you can revert to.
Path B — Clone from GitHub (when the public repo is live)
- From your code folder: git clone https://github.com/ai-architect-academy/tidy-starter.git && cd tidy-starter
- (If the URL has moved or the repo isn't published yet, fall back to Path A. The current URL is always listed at the top of the Recipe Book entry cloning-the-module-3-starter-repo.)
After either path — verify and warm up
- Confirm the clone/copy succeeded: git status should print On branch main (or On branch master) with either a clean working tree or a fresh “initial commit.” Either is fine.
- Run the script once, before you change anything, so you know what “working” looks like on your machine:
python3 tidy.py --help (Mac/Linux) python tidy.py --help (Windows)You should see a short usage message. If you see a Python error, your install is incomplete — go back to Module 2 Lesson 2.2.
- Install pytest so the test suite can run later:
python3 -m pip install pytest (Mac/Linux) python -m pip install pytest (Windows)Verify: python3 -m pytest --version (or python -m pytest --version on Windows).
- Create a sandbox folder you will let tidy reorganize, without risking real files:
- macOS/Linux: mkdir -p ~/tidy-sandbox && cd ~/tidy-sandbox
- Windows: mkdir $env:USERPROFILE\tidy-sandbox -Force ; cd $env:USERPROFILE\tidy-sandbox
- Drop five or six test files with different extensions into the sandbox — a couple of .txt, a .pdf, a .jpg, and one file named notes.tar.gz. That last file is the one that exposes Bug 1.
Safe default
Never run tidy against a folder of real files until Lesson 3.2 is complete. The sandbox folder is the point. If the agent writes a bad fix, the worst case is that your six test files land in the wrong subfolder, which is a non-event.
Where this fits. You will use this repo and this sandbox folder as your Module 3 workbench through 3.5. Do not delete them at the end of the lesson.
Directed Edit 1 — Fix Bug 1 in the Code tab RECIPE
| Tool | Claude desktop app — Code tab |
| Last verified | 2026-04-17 |
| Next review | 2026-07-17 |
The bug. Run python ~/code/tidy-starter/tidy.py ~/tidy-sandbox. The script sorts the files into subfolders by extension. Check the result: notes.tar.gz has been placed in a subfolder called gz/, not tar.gz/. This is Bug 1. The script is splitting the filename on the first dot instead of handling compound extensions.
Steps.
- Open the Claude desktop app and switch to the Code tab. Click the project / folder picker and connect to ~/code/tidy-starter. Confirm the folder name appears at the top of the Code tab — that's the “is the Code tab live” check from Lesson 3.1's recipe sidebar.
-
In the Code tab, paste this prompt exactly. It is worded to exercise every move of the four-move loop:
I have a Python CLI in this folder called tidy.py that sorts files into subfolders by extension. It is mishandling files with compound extensions like .tar.gz — it puts them in a gz/ folder instead of a tar.gz/ folder.
Please:
- Find the function in tidy.py that determines the destination subfolder for a given filename. Tell me which function it is and which line currently causes the bug, before you propose a fix.
- Propose a one-sentence plan for the fix.
- Wait for me to confirm the plan before you write the change.
- When I confirm, make the change and show me the diff.
- Run the existing tests in tests/test_tidy.py after the change and show me the output.
- Read the Code tab's locate answer. You are checking: did it name a real function in tidy.py, and does the line it pointed to actually match what you see in the file? Open tidy.py in VS Code alongside the Code tab and look (or use the file pane inside the Code tab itself). If the agent named a function that does not exist in the file, stop and say so — that is a hallucination, and you have just caught one, which is the whole point of the locate step.
- Read the one-sentence plan. A reasonable plan looks like: “change the extension extraction to treat everything after the first dot in the filename as the extension, not just the last segment,” or equivalently, “special-case compound extensions like .tar.gz.” Either is defensible; an unreasonable plan would be “rewrite the whole module” for a bug this size.
- Reply “Confirmed, please proceed” — or push back if the plan is wrong. The Code tab will write the change and present a diff inline for you to accept or reject.
- Review the diff. The Code tab shows the diff right in the conversation, file by file, with accept/reject buttons. Look at the shape first — only one file changed, edit roughly the size of the bug fix, nothing added that you didn't ask for. Then read the agent's summary of what it did and check it matches the plan. For any changed line you can't tell about — does this look right? what does that piece do? — ask the Code tab directly: “Explain that line.” The lesson is teaching the review habit, not code-reading.
- Let the Code tab run the tests. Read the test output. The output should show the test suite passing with one new case (the .tar.gz case) passing. If the test output does not appear or the tests error out, do not accept the change — respond with “The tests did not run. Please make sure python -m pytest tests/ actually executes and show me the result.”
- Once the diff reads cleanly and the tests pass, click Accept on each changed file in the Code tab.
-
When the diff reads cleanly
and
tests pass: commit. In your terminal, from inside
~/code/tidy-starter
:
$ git add tidy.py tests/test_tidy.py $ git commit -m "Fix .tar.gz compound-extension bug (directed edit, Code tab)" -
Write one sentence, in a new file at
~/code/tidy-starter/edit-log.md
:
Entry 1. Bug: .tar.gz files were sorted to gz/. Fixed in the Code tab. I reviewed the diff (one file changed, small edit, matched the plan), and the tests passed on my machine. Surprise: [fill in one specific thing that surprised you — could be the agent's locate accuracy, a line you had to ask about, anything honest].
Safe default
If at any point the Code tab asks to run a command that deletes files, moves files around in your home directory, or rewrites your git history (git reset --hard, git push --force), say no and ask for an alternative. None of those are required to fix this bug; if an agent proposes them, the prompt has gone somewhere unexpected and you should bring it back.
Troubleshooting
First move when something doesn't work: ask the Code tab itself. Paste the error message into the Code tab and ask “What does this mean and how should I fix it?” The agent already has context on the folder it's connected to and the file you just edited — it's the fastest diagnostic tool you have. The list below covers a few specific stumbles you're more likely to hit.
- The Code tab says it cannot find tidy.py. Re-check that the Code tab is connected to ~/code/tidy-starter and not some parent folder. Use the folder picker to disconnect and reconnect if needed.
- The diff looks enormous (50+ lines for a small fix). Stop. Ask the Code tab to show you a minimal diff — the smallest change that makes the test pass. Large diffs on small fixes are a red flag for over-eager rewrites.
- Tests do not actually run. Confirm pytest is installed: python -m pip install pytest. Then ask the Code tab to re-run them.
Directed Edit 2 — Fix Bug 2 in the Code tab RECIPE
| Tool | Claude desktop app — Code tab |
| Last verified | 2026-04-17 |
| Next review | 2026-07-17 |
The bug. There is a second bug you will not have noticed from the output — the script does not handle hidden files (files starting with ., like .DS_Store on macOS or .gitkeep in empty folders). It treats the part after the leading dot as the extension, so .DS_Store gets sorted into a folder called DS_Store/. This is Bug 2.
Why a second bug. Bug 1 was obvious from the output. Bug 2 isn't — you'd only notice it if the agent (or a careful reader) called your attention to it. Doing a second directed edit in the same Code tab is not about learning a new tool; it's about practicing the same four-move loop on a different shape of bug, and noticing how the prompt structure stays constant even when the bug changes.
Steps. You're already in the Code tab connected to ~/code/tidy-starter from Bug 1, so most of the setup is already done.
-
In your terminal, add a couple of hidden files to your sandbox so the bug is reproducible:
$ touch ~/tidy-sandbox/.gitkeep ~/tidy-sandbox/.hidden-notes - Run the script once to see the bug: python ~/code/tidy-starter/tidy.py ~/tidy-sandbox. Check the sandbox — you will see a gitkeep/ or hidden-notes/ folder. That is the bug.
-
Switch to the Code tab and paste this prompt. Note the same four-move shape as Bug 1, just pointed at a different bug:
In this repo, tidy.py has a second bug: it does not handle hidden files (files starting with ., like .DS_Store or .gitkeep). Instead of leaving them alone or putting them in a hidden/ folder, it treats the text after the leading dot as the extension.
Please:
- Find the function that builds the destination subfolder name. Tell me the file and line number before proposing a fix.
- Propose a plan in one sentence. The plan must say what the script should do with hidden files — leave in place, put in a hidden/ folder, or something else — and why.
- Wait for me to confirm before writing.
- On confirmation, write the change and show me the diff.
- Run python -m pytest tests/ -v and show me the output.
- Read the Code tab's locate answer. Same hallucination-check as Bug 1: did it name a real function, and does the line it pointed to match what you see when you open the file?
- Read the plan. Pick one of the proposed options or propose your own. For this course, a reasonable default is: hidden files go into a hidden/ subfolder, because it keeps the behavior consistent with every other file class.
- Type “Confirmed” (or equivalent). The Code tab writes the change and shows the diff inline. Review it the same way as Bug 1: the right files, a small change, nothing unexpected, and the agent's summary matches the plan. Ask the Code tab to explain any specific change you can't tell about.
- Let the Code tab run the tests. Read the output. The test suite should pass, including a new case for hidden files. If it does not, do not accept.
-
Commit:
$ git add tidy.py tests/test_tidy.py $ git commit -m "Handle hidden files with leading dot (directed edit, Code tab)" -
Add
Entry 2 (local)
to
~/code/tidy-starter/edit-log.md:
Entry 2 (local practice). Bug: hidden files were sorted by their first-dot name. Fixed in the Code tab. I reviewed the diff (right file, small change, matched the plan); tests passed. What changed in my prompting between Bug 1 and Bug 2: [fill in one specific change you made — could be more specific about the location, asking for tests in a particular way, anything honest].
Note: Entry 2 here stays in the local edit-log.md — it's practice, not capstone material. The capstone log gets only one entry from this lesson (the Bug 1 fix), one from Lesson 3.3 (the deliberately-loose review), and one from Lesson 3.5 (the feature-sized change). The project checkpoint at the end of this lesson will walk through which entries go where.
Safe default
Same as Bug 1 — no destructive git commands, no rewrites, no file deletions outside the sandbox. The Code tab will sometimes ask to run shell commands. Read each command before you approve it. If the command reads files, runs tests, or writes inside the repo, it is almost certainly fine. If it writes outside the repo, deletes things, or touches network, say no and ask what it is trying to accomplish.
Optional advanced — Do Bug 2 in the Claude Code CLI instead. If you set up the Claude Code CLI in Lesson 2.4's optional advanced section, you can do Bug 2 in the CLI for a side-by-side comparison with the Code tab. Click to expand.
Same engine, terminal interface. The prompt is identical; the differences are interface-only (the CLI shows you everything in the terminal pane instead of inline in the desktop app).
- Open your terminal. Change into the repo: cd ~/code/tidy-starter.
- Start the CLI: type claude and press Enter. (If the launch command has changed, the current command is in the Recipe Book.)
- Confirm the agent is live: run /status. You should see the working directory ~/code/tidy-starter and the model. If not, exit (/exit) and restart from the right folder.
- Skip the “add hidden files” and “run the script” steps if you already did them in the Code tab walkthrough above — the bug is already reproducible.
- Paste the same prompt from step 3 above into the CLI. Same four-move shape, same expected behavior.
- Read the locate answer in the terminal. Open the file in VS Code (code tidy.py) to verify the line. Same hallucination check.
- Read the plan. Type “Confirmed”. The CLI writes the change and prints the diff in the terminal. (You can also open VS Code's Source Control panel for a nicer view of the same diff.) Review the same way: right files, small change, nothing unexpected, summary matches the plan.
- Let the CLI run the tests. Read the output. Test suite should pass.
- Commit (only if you didn't already commit the same change in the Code tab walkthrough above — otherwise skip).
- If you did Bug 2 in both the Code tab and the CLI, add a third local entry: “Entry 2-CLI (local practice). Same bug as Entry 2, done in the CLI for comparison. Difference I noticed: [one sentence — could be pacing, output format, anything honest].”
Troubleshooting (CLI). If the CLI cannot find your Python install, check which python (macOS) or where python (Windows) and restart the CLI from the same shell where Python works. If the model loops on the same file, interrupt with Ctrl+C and start a fresh message with the bug and file re-stated.
Try it — Fix a third bug yourself CORE
follows from the two recipes above
You have fixed two bugs in the Code tab using prompts this lesson wrote for you. Now write your own.
Open the starter repo and pick something you want to change. Options, easiest to hardest:
- Add a --dry-run flag that prints what the script would do without actually moving files. (Recommended if you want to keep this small.)
- Add a --verbose flag that prints each move as it happens.
- Make the script skip symlinks instead of following them. (Hardest — requires you to recognize that the current behavior is wrong.)
Write the prompt yourself, following the four-move shape. Use the Code tab (or the CLI if you have it). Make the change, review the diff, run the tests, commit. Add Entry 2.5 (local practice) to edit-log.md with what you tried and what you learned.
This entry does not go in your capstone log — it is practice — but it is how the habit gets legs.
Done with the hands-on?
When both edits are committed and Entry 1 and Entry 2 (local) are in edit-log.md, mark this stage complete to unlock the assessment, reflection, and project checkpoint.
Quick check
Four questions. The emphasis is on the shape of a directed edit, not on tool-specific UI.
Show explanation
Answer: C. The agent jumped from locate to write with no plan in between. You verify the locate claim first (open the file, check line 47 — a hallucination check), then explicitly ask for the plan. A lets the skipped step slide, which is the habit you are trying to prevent. B is half right but skips the hallucination check — you should verify what the agent said before asking for the next move. D is over-rejection; the agent made a recoverable mistake that you can fix by asking for the missing step.
Show explanation
Answer: B. A diff much larger than the fix required is a red flag for scope creep or over-eager refactoring. Asking for a minimal diff is fast, cheap, and almost always produces a smaller, safer change. A is the “read it carefully” trap — correctness of individual lines does not defend against unwanted scope. C violates “you do not merge what you have not understood,” regardless of a follow-up plan. D works but is heavy-handed for a recoverable situation; the minimal-diff ask is the first thing to try.
Show explanation
Answer: B. rm -rf on a directory is destructive, and deleting the tests to “fix” a test failure is a category of fix the course rule explicitly blocks. Ask what the agent is trying to accomplish — usually the answer is “I want to regenerate these tests,” and the right move is to ask it to edit the existing ones instead. A, C, and D all let a destructive command through; the course’s safety rule is “refuse destructive commands, then unblock the underlying goal.”
Show explanation
Answer: B. The verify step is one of the four moves, and the director’s job is to confirm the signal. Re-running the tests is cheap; it takes seconds. A and C both rely on the agent’s self-report, which is exactly what the verify step exists to check. D is too heavy — you can still confirm the verify step after the fact, and if it passes, the commit was fine.
Reflection prompt
Same tab, different bug — what changed in your prompting?
In 6–8 sentences: You ran the four-move loop twice in the Code tab. What changed about your prompting between Bug 1 and Bug 2? What did Bug 2's hidden-files surprise teach you about the locate step that Bug 1's obvious .tar.gz output didn't? At which step of the four-move loop did you find yourself wanting to skip ahead — locate, plan, write, or verify — and what would happen if you actually did? If you also did the optional CLI walkthrough: what did you notice about the CLI's interface vs the Code tab's? Which one felt faster on this size of bug, and why?
Write the answer before Lesson 3.3. The skip-ahead question is the most important one; it names the step where your discipline is currently weakest, and 3.3 will go right at it.
Project checkpoint
Capstone log: Entry 1 only — plus the seed of the directed-edit-log draft.
Your local ~/code/tidy-starter/edit-log.md is your practice notebook for this lesson. The capstone log is a separate, more selective artifact — only one entry from this lesson goes into it (the Bug 1 fix). Entry 2 (the hidden-files Code tab fix) and Entry 2.5 (your Try-it bug) and any optional-CLI entries all stay in the local edit-log; they're practice, not capstone material. Before moving to Lesson 3.3:
- Create /capstone/directed-edit-log-draft.md in your course folder. This is still a draft; it will be frozen at the end of Lesson 3.5 with three canonical entries (Entry 1 from this lesson, Entry 2 from Lesson 3.3, Entry 3 from Lesson 3.5).
-
At the top of the draft, paste the two safety norms from the module README:
Rule 1. You do not merge what you have not reviewed. Every diff, every time. (“Reviewed” means the five-move review from Lesson 3.3, not line-by-line code-reading.)
Rule 2. Never let an agent run a destructive command without confirming the command first.
- Copy only Entry 1 (the Bug 1 fix in the Code tab) from your local edit-log.md into the capstone draft as Entry 1. The hidden-files Bug 2 entry stays local — it's practice, not capstone. (If you also did the optional CLI walkthrough, that entry stays local too.)
- Confirm Entry 1 in the capstone draft includes: the prompt you sent, which tab you used (Code tab), the one-sentence outcome, and the one specific surprise you noted. If anything is missing, go fill it in now — not at the end of the module.
Next in Module 3
Lesson 3.3 — Reviewing what the agent did.
The most important lesson in the module. The four ways an agent's edit can go wrong, the five-move review you run on every change, and the Diff Review Trainer activity where you practice on three real scenarios. Built for directors — no code-reading required.