Reference · /learn/
ISSUE 06Two issues of tools, keys, and plumbing. Nothing actually cooked yet. This is where that changes.
Basecamp and The Trail Markers were entirely about getting ready — git, GitHub, two machines able to reach the same project. Necessary, but none of it was the project. This is the first ticket ever handed to Claude Code, the first thing that actually got built, and a mistake that got caught one command before it went out to the table. The real start.
Where this is going
Four courses: what it means to hand a task to an AI coding tool instead of typing every command yourself, what actually got built, the near-miss — something that almost got served that should have stayed in the kitchen — and the standing order that means this kitchen doesn’t forget the recipe between shifts.
THE PROJECT BEGINS
01brunch
Typing every command yourself and describing what you want are two different jobs. This is where they split.
Everything up to this point was typed by hand, one command at a time. Claude Code works differently — you describe what you want, in plain language, and it proposes the actual commands, shows them before running them, and waits for the go-ahead on anything that changes something real. Less ‘typing the recipe,’ more ‘telling the kitchen what you want and reading the ticket back before it’s cooked.’
First move, before any actual task: get from the laptop into the kitchen. The project lives on the server, not the MacBook — so the first step of every session is arriving in the right place before ordering anything.
$ ssh alice $ cd ~/projects/currency-portfolio-tool $ claude
Then, at the prompt, the first real order — plain English, not a command:
The order, as typed
Set up a Python virtual environment called venv, activate it, and install yfinance, pandas, and requests. Save the installed packages to
requirements.txt. Then write a small script that pulls one day of live data from both APIs and prints it, to confirm both actually work.
Not a recipe. A description of what the finished plate should look like.
02brunch
A closed kitchen — one where nobody outside it can see what’s cooking, and nothing goes out on its own.
Three things came back from that one ticket:
venv/ — an isolated Python environment, Python 3.12, with yfinance, pandas, and requests installed inside it and nowhere else. Isolated on purpose — a kitchen that doesn’t share pans with any other project on the server, so nothing gets cross-contaminated between them.requirements.txt — the actual recipe. Not the finished dish, the list that rebuilds it: run pip install -r requirements.txt against a fresh, empty environment anywhere, and it comes back identical.test_connection.py — proof the kitchen can actually reach its suppliers. Live output: Adidas opened at €152.40 on the day, and 1 USD bought €0.85477. Both real, both fetched live, nothing faked to make the test pass.Recipe, not the dish
A venv folder itself never goes anywhere — it’s not portable, it’s full of paths specific to this one server. requirements.txt is the part that travels. This distinction matters again two sections from now.
03brunch
The difference between a mistake made and a mistake caught is entirely about when someone notices.
Committing the new files meant the usual two-step order: git add ., then git commit. Except this time, before running either, Claude Code stopped and flagged something first:
Flagged before running
git add . would stage 6,876 files — the whole venv/ directory. Flagging before I commit, because pushing that to GitHub is annoying to undo.
6,876 files. One instruction — git add ., meaning ‘everything’ — was about to sweep up not just the two files actually meant to be kept, but the entire isolated kitchen built in the last section: every installed package, every dependency, all of it, headed for GitHub.
git add . 6,876 files staged
“everything” meant everything — the whole venv with it.
# Virtual environment — recreate with: # python3 -m venv venv && ./venv/bin/pip install -r requirements.txt venv/ # Python bytecode __pycache__/ *.py[cod] # Secrets .env
git add . → 3 files the same command. Not sixty-eight hundred.
The reasoning for why that’s wrong, in full: a venv is roughly 100MB of downloaded binaries, some with this exact server’s file path baked directly into them. On a different machine, or even a fresh clone of the same project, half of it wouldn’t work anyway. And it didn’t need to travel — requirements.txt was already sitting right there, the actual portable recipe from the last section.
The fix is a file called .gitignore — a standing instruction that tells git ‘never pick these up, not even when told to grab everything’. After that, the same two-step order again — git add ., git commit — picked up exactly three files this time. Not sixty-eight hundred.
From the pass
Nobody typed ‘please don’t send the whole kitchen to GitHub.’ The catch came from understanding why a venv doesn’t belong in version control, not from a rule written down in advance. That’s the actual value of handing a task to something that can reason about it, rather than just execute instructions literally.
— noted at the pass
The same shape turns up again one issue later, in a different kitchen: what belongs in a cache filename, in Issue 07 — a cache filename that would have quietly served the wrong data, spotted before it had run even once. Neither of them was a bug fixed. Both were a bug that never happened.
.gitignore — a permanent “never pick this up” instruction to git.04brunch
A kitchen that remembers the order between shifts, instead of being told the whole thing again every morning.
One gap, noticed while starting a second Claude Code session for a different task: it could read every file in the project folder — nothing hidden there — but it had no memory of why any of it existed. Why George Russell. Why these five tickers. Why the hedging logic was staying deliberately non-AI. That reasoning lived in conversation, not in the code itself.
Claude Code has a fix built in for exactly this: a file called CLAUDE.md, sitting in the project’s root, read automatically at the start of every single session — no re-explaining required. Not a recipe for one dish. A standing order pinned at the pass, read before any shift starts, so the kitchen never has to be told the same context twice.
$ git add CLAUDE.md $ git commit -m "Add project context for Claude Code" $ git push
One file, read automatically, every time, from here on.
CLAUDE.md — persistent context, read automatically each session.End of the first build dispatch
The kitchen’s stocked, the near-miss is behind it, and the standing order is pinned at the pass. Next time: actually pulling in the ingredients — real FX rates and real share prices, and the first real disagreement about how much of it to keep.