Codebase first-run experience

Day 19: Your codebase is a product, and new hires and agents are its newest users

Every new engineer and every coding agent you point at your repo gets a first-run experience. Maybe you designed it, maybe you didn't. They get one either way. If nobody measures it, you pay for it every week in wrong guesses, broken local environments and Slack threads that start with "quick question".

The hook: the staging seed script

A new engineer joined us. On day two they paired with Claude Code to get a local environment running against staging data. The agent read the README, found the setup section and ran every step in order, including the staging seed script. That script wiped a shared staging dataset another team was using for a demo.

The new hire did nothing wrong, and neither did the agent. They followed the README exactly. Ten minutes into the incident thread, a senior engineer wrote: "oh, nobody does that step anymore."

That one sentence is today's lesson. The README described a process the team had quietly stopped using. Anyone who'd been around a while knew to skip that step. The only two who still trusted it were the newcomers, one human and one model.

The reframe: your codebase has users, and they're new

Earlier in this series you learned to watch real users hit friction rather than ask them what they want. You sat in on sessions, read support tickets and noticed where people hesitated. Today the user is internal. Your codebase is a product. Its UI is the README, the folder structure, the scripts, the error messages and the CLAUDE.md or AGENTS.md file. Its users are the people and agents who have to change it.

It has a first-run experience, the same as any product. And, as with any product, your power users are the worst people to judge it. They've learned every workaround. New humans and new agents haven't learned what to skip yet, which makes them your least-biased testers.

Why the agent is the better usability tester

Each kind of user handles bad docs differently. Only one of them leaves evidence behind.

• ▹Veterans route around the problem. They ask in Slack, remember a conversation from last year, or just know. They never feel the friction, so to them it doesn't exist.
• ▹New hires are polite and blame themselves. They assume they got it wrong, quietly ask a buddy, and never report that the docs are wrong. They feel the friction, but nobody writes it down.
• ▹The agent does neither. No Slack, no buddy, no embarrassment. It acts confidently on whatever the repo says, and when it guesses wrong it shows you exactly where the written system and the real one have drifted apart.

I call these confident wrong guesses, and they're not random hallucinations. The agent reads a stale README, an old migration pattern still sitting in the code, or a helper nobody touches anymore, and treats it as truth. Every wrong guess points at tribal knowledge that your docs pretend isn't there.

If you use coding agents and keep wondering why they get your codebase wrong, this is usually why. The agent isn't misreading your repo. It's reading it accurately. The repo is what's wrong.

The exercise, step by step

Step 1: Give the new hire a real first-week goal, not a reading list. Pick a small change that will actually ship: a real bug, a small feature behind a flag, a missing metric. It has to cross setup, local run, tests and deploy, because that path is where the friction lives. A reading list only tells you whether someone can read. A real goal tells you whether the system is usable.

Step 2: They drive a coding agent toward that goal, using Claude Code, Cursor, Copilot agent mode or whatever your team runs. Their job isn't to rescue the agent when it goes off track. It's to notice when that happens and ask a human what's actually true.

Step 3: Every confident wrong guess goes into a friction log. The log has four columns:

• ▹What the agent assumed: the specific action or belief, e.g. "Ran `make seed-staging` as step 4 of setup."
• ▹What's actually true, meaning how the team really works: "Nobody runs that. Use the snapshot restore script instead."
• ▹Where the truth lives. A person, a Slack thread, a commit message, an old PR description, someone's head. This is the column that matters most.
• ▹What it cost in time lost, rework or blast radius. Rough is fine: "20 min", "half a day", "broke shared staging".

Step 4: At the end of the week, hold a 30-minute review with the new hire, their buddy and one senior engineer or tech lead. Walk through the log together. You're there to understand each entry, not to defend against it. Every entry leaves the room with an owner and a fix type, or it gets explicitly dropped.

What our log actually showed

When we ran this, the entries landed in four buckets:

• ▹Stale setup steps. README instructions that were right once and now range from useless to harmful. The seed script lived here.
• ▹Unwritten conventions: where new services go, which logging helper to use, how feature flags get named. Everyone knew, and nothing in the repo said so.
• ▹"Ask Minh" dependencies, where the knowledge lived with exactly one person. The agent couldn't ask Minh, so it guessed.
• ▹Deprecated paths still in the code, like old API clients, a legacy auth middleware or a v1 folder. The agent found working examples of the wrong pattern and copied them. If a pattern exists in your code, it looks like a pattern you endorse.

Here's the uncomfortable part. About half the entries surprised senior engineers too, so these weren't just "things juniors don't know". Seniors had routed around them so automatically that they'd forgotten the trap was there. Or they'd never hit it because they came into the system by a different path. The log took every engineer's private workarounds and put them where the whole team could see them.

Triage it like a product backlog

A friction log is a usability report, so treat it like one you'd get for a customer-facing product. Score each entry on frequency × cost:

• ▹Frequency: how often will a new human or agent hit this? On every setup, on every PR in that module, or once a year?
• ▹Cost: is it a few minutes of confusion, hours of rework, or broken shared state?

Then decide where the fix goes. In order of preference:

• ▹Code: delete the trap. Remove the dead seed step. Delete the v1 client. Make the deprecated helper throw with a message that names its replacement. If the wrong path is gone, nobody can take it, human or agent.
• ▹Tooling: make the right path the easy one. A `make dev` that does the real setup, a lint rule that blocks the old import, a pre-commit check that catches the convention.
• ▹CLAUDE.md or the README: write the norm down. Save this for conventions that are real decisions but can't be enforced mechanically, such as why something is structured the way it is, or what to avoid and why.

The rule is to remove friction before you document it. A doc that says "don't run step 4" is a warning sign next to a pothole. Fill the pothole. Docs drift, and drift is exactly what caused the incident. Code and checks enforce themselves.

Score = frequency (1-3) x cost (1-3)

7-9  -> fix this sprint. Prefer code/tooling.
4-6  -> fix this month. Tooling or a precise CLAUDE.md/README line.
1-3  -> write one line in the right doc, or explicitly drop it.

Tie-breaker: anything that can break shared state (staging, data, prod creds)
jumps to the top regardless of score.

The double win

Run the exercise once and three things get better:

• ▹Agent context. Every fix makes the next agent session more accurate for everyone on the team, not just new people.
• ▹Human docs. The README and onboarding path get rewritten from evidence instead of memory.
• ▹Team awareness. Seniors learn which parts of the system only work because they're around. That's a risk you want to know about.

On top of that, the new hire ships something real in week one, which is a far better use of their newness than the classic starter ticket. In 2026 an agent clears a typical "fix this typo, rename this variable" ticket in minutes, so the new hire learns almost nothing about how the system really works. Fresh eyes expire within a few weeks. Spend them finding friction, not on busywork.

Common failure modes and how to fix them

• ▹The log turns into a blame list. Entries like "Minh's script is broken" put people on the defensive, and the next hire stops logging honestly. Fix: the log describes gaps in the system, not people. "Minh" can appear in the "where truth lives" column as a location, never as a fault. Seniors go first in the review and say "I didn't know that either" out loud.
• ▹Nobody triages the entries. The log sits in a doc, the hire moves on, and the next hire walks into the same traps. Fix: the 30-minute review is a calendar invite, not a suggestion. Every entry leaves with an owner or an explicit "won't fix", and high scorers go into the normal backlog, not a side doc.
• ▹CLAUDE.md becomes a dumping ground. Each entry becomes one more line until the file is hundreds of lines of "don't do X" and the agent's attention is spread thin across noise. Fix: before you add a line, ask whether the problem could be deleted from the code or caught by a check instead. Keep CLAUDE.md short and about decisions and conventions, and prune it every time you run the exercise.

Copy-paste friction log template

# First-week friction log

New hire: ______   Buddy: ______   Agent/tool: ______
Week of: ______
First-week goal (must ship): ______________________________

| # | What the agent assumed | What's actually true | Where the truth lives | Cost | Freq (1-3) | Cost (1-3) | Score | Fix type (code / tooling / docs / drop) | Owner |
|---|------------------------|----------------------|-----------------------|------|-----------|-----------|-------|------------------------------------------|-------|
| 1 | Ran `make seed-staging` as setup step 4 | Step is obsolete; use `scripts/restore-snapshot.sh` | Senior engineer's memory | Broke shared staging | 3 | 3 | 9 | code: delete target | |
| 2 |  |  |  |  |  |  |  |  |  |

## End-of-week review (30 min)
- Entries that surprised seniors: __
- Top 3 by score + owners:
- CLAUDE.md lines added: __   lines removed: __

## Metric
Confident wrong guesses this first week: __  (previous hire: __)

Track one number across hires: confident wrong guesses per first week. It should go down over time. Goals and people vary, so read it as a rough trend line, not a precise KPI. If it stays flat, you're logging friction without fixing it. If it drops sharply, your first-run experience is improving for everyone, including the agents your seniors use every day.

The principle for Day 19

The people who use a system the most are the worst judges of how usable it is. That's true of your customers' power users, and it's true of your senior engineers. Product people go looking for fresh eyes on purpose. Engineers with a product mindset do the same with their own codebase. Agents read the repo literally, which means you get a fresh pair of eyes every time someone opens a new session.

Tomorrow, Day 20, we shift from people onboarding into your code to people integrating with your APIs. Developer experience is a product surface too, and your API's first five minutes matter as much as your app's.

Extend your knowledge

• ▹Run the exercise once this month. It works even with an existing teammate who's new to a module. Copy the template above, set a real goal, and hold the 30-minute review.
• ▹Audit your CLAUDE.md or AGENTS.md line by line and ask whether each one could be replaced by deleting code or adding a check. Anthropic's Claude Code docs on memory and CLAUDE.md best practices are a good reference for what belongs there.
• ▹Read Steve Krug's 'Don't Make Me Think' and 'Rocket Surgery Made Easy' with your codebase in mind. Small, cheap usability tests work on repos just as well as on websites.
• ▹Dig into developer experience (DevEx) research, starting with the DevEx framework paper by Noda, Storey, Forsgren and Greiler. It's good background for Day 20 and for putting numbers on onboarding friction.