01 - Where Claude Code Fits

🎁 Two engineers use Claude Code on the same task. One finishes in ten minutes, the other fights it for an hour and gives up. Same tool. What did the first one know?

Claude Code isn't magic and it isn't autocomplete. It's an agent that works best on a specific shape of problem. Learn that shape and you'll reach for it at the right moments instead of forcing it everywhere.

What Claude Code Is

Claude Code is an AI agent that runs in your terminal and works inside your actual repo. It reads files, edits them, runs commands, runs your tests, and reads the output to decide what to do next. You talk to it in plain English.

claude
> Add a --json flag to the export command and update its help text.
# It greps for the command, reads the file, makes the edit,
# runs the CLI to confirm the flag works, and reports back.

The difference from a chat window is that it acts. It doesn't hand you a snippet to paste, it makes the change and checks it.

The Sweet Spot: Verifiable Work

Claude Code shines when the work has a clear right answer you can check. A failing test that should pass. A diff that should compile. A bug with a reliable repro. When there's a signal, the agent can loop: try, run, read the result, fix.

Good task: "This test fails with 'nil pointer'. Find why and fix it.
            Run `go test ./cart` until it passes."

The tighter the feedback loop, the better it does. Give it a way to know when it's done and it will grind until it's done.

High-Value Workflows

These are the jobs where it consistently pays off. Notice they all have a verifiable outcome or a bounded scope.

- Onboarding:     "Explain how auth flows from login to session."
- Bug fixing:     paste the stack trace + repro steps.
- Refactors:      "Rename `Client` to `APIClient` across the repo."
- Migrations:     "Upgrade this service from v3 to v4 of the SDK."
- Tests:          "Add tests for the edge cases in parseDate()."
- Code review:    "Review my staged diff for bugs before I push."
- Scaffolding:    "Create a new handler following the pattern in users.go."
- Docs & memory:  "Write a CLAUDE.md describing this repo's structure."
- Incident triage:"Here's the error spike. What changed recently?"

Onboarding and refactors are the fastest wins. Exploring an unfamiliar codebase by hand takes hours; asking where something lives takes seconds. Tedious mechanical changes across dozens of files are exactly what an agent beats a human at.

Where It Struggles

The flip side of "needs a signal" is that it flounders without one. Vague, taste-heavy, or unverifiable work is where you'll waste time.

Weak task: "Make the dashboard feel more modern."
           No target, no test, no way to know when it's right.

Novel architecture decisions are the other trap. "Should we split this into microservices?" is a judgment call with tradeoffs only you can weigh. The agent will produce a confident answer, but confidence isn't correctness. Use it to gather options, not to decide.

Driving vs One-Shotting

The engineer who wins isn't the one with the perfect prompt. It's the one who drives. You read what it proposes, correct course, and keep it pointed at the goal, the same way you'd guide a fast junior dev.

One-shotting:  fire a prompt, walk away, merge whatever comes back. ❌
Driving:       give context, review the plan, catch a wrong turn early,
               verify the result before you trust it. ✅

One-shotting is how you end up with the plausible-looking bug that passes review and breaks in production. Driving is slower per prompt and far faster to a correct result.

Key Takeaways

• Claude Code is a terminal agent that reads, edits, and runs code, not a snippet generator
• It shines on verifiable work: a failing test, a repro, a diff that must compile
• Highest-value workflows: onboarding, bug fixes with a repro, refactors, migrations, tests, review, scaffolding, docs, incident triage
• It struggles on vague or taste-heavy tasks and novel architecture calls, use it to gather options there, not to decide
• Drive it, don't one-shot it: give context, review the plan, catch mistakes early, verify before you trust

🎁 Claude just guessed your project uses npm when you're on pnpm, and picked the wrong test command. What if it knew your conventions before you said a word?