Case Study: Shipping a Fix with Claude Code, End to End

Every other subject in this track isolates one mechanism — the agentic loop, permission modes, CLAUDE.md, plan mode, subagents, workflows, sandboxing, scheduled tasks — and teaches it on its own. That's the right way to learn a mechanism, but it hides the thing that actually matters on the job: knowing which mechanism to reach for, in what order, when the stakes are real and the clock is running. This subject does the opposite. It follows one incident from the moment it lands in your queue to the retro two weeks later, in one continuous narrative, using nothing that isn't grounded in how Claude Code actually behaves. Every fork in the road gets a name, a reason, and a pointer to the subject that teaches the mechanism in depth — so you can read this as the "why" that sits on top of everything else you've learned.

The incident: CSV exports intermittently miss rows, and it started about a month ago. The repository is ledger-events, a mid-size TypeScript/Node monorepo — a REST API in apps/api, a background worker in apps/worker that runs scheduled export jobs, a shared packages/export-engine library that paginates a Postgres table and streams the results into CSV, and a packages/schema package holding a Prisma schema plus generated client code. The ticket comes from Customer Success, forwarded from a finance-ops customer who noticed their monthly transaction export was short a handful of rows — not every time, not the same rows, no error in the logs.

You're going to work this ticket the way an experienced Claude Code user works a real incident: not with a single magic prompt, but with a sequence of deliberate choices about mode, delegation, and verification. Read it end to end once, then come back to individual sections when you want the reasoning behind a specific fork.

The codebase, at a glance

Nothing in this incident depends on exotic infrastructure — the point is that the reasoning generalizes, not the stack. The parts that matter:

ledger-events/
├── CLAUDE.md                     # test commands, style rules, the pagination note
├── .claude/
│   ├── settings.json              # project-level allow/deny rules
│   └── hooks/                     # PreToolUse + PostToolUse guards
├── apps/
│   ├── api/                       # REST API, not touched in this incident
│   └── worker/
│       ├── src/jobs/export-transactions.ts
│       └── src/jobs/export-audit-log.ts   # turns out to matter in Phase 5
├── packages/
│   ├── export-engine/
│   │   └── src/
│   │       ├── paginate.ts        # the keyset cursor — where the bug lives
│   │       └── csv-writer.ts
│   └── schema/
│       ├── schema.prisma
│       └── generated/             # off-limits per CLAUDE.md and a hook

export-transactions.ts is the job Customer Success's ticket is actually about. export-audit-log.ts doesn't appear anywhere in the original ticket — it only becomes relevant in Phase 5, once you go looking for siblings.