A Claude Code Workflow That Actually Ships

Most people either trust AI coding tools too much or too little. After months of daily use, I landed on a loop that treats the model like a fast, literal-minded pair — brilliant at execution, dangerous without guardrails.

The Problem

Left unattended, agents drift. They refactor files you did not ask about, invent APIs, and confidently break tests. The failure mode is not bad code — it is unscoped code.

Investigation

I logged a week of agent sessions and tagged every intervention. The vast majority of my corrections were about scope, not correctness. The model was capable; it just did not know where the edges were.

An agent is only as good as the boundary you draw around it.

The Solution

I now start every task with an explicit contract: the files in scope, the acceptance check, and what must not change. Then I let the agent plan before it writes a line.

## Task
Add optimistic updates to the comment box.

## In scope
- components/comment-box.tsx
- hooks/use-comments.ts

## Do not touch
- API routes, database schema

## Done when
- New comments appear instantly and reconcile on server response
- Existing tests still pass

The Result

Review time dropped roughly 45%. More importantly, the diffs became boring — small, scoped, and easy to reason about. Boring diffs are shippable diffs.

Lessons Learned

1. Scope is the real prompt. Everything else is detail.
2. Plan first, code second — always review the plan.
3. Keep tasks small enough to hold in your head.
4. The human owns the acceptance criteria, not the model.