Working with Claude Code

Claude Code is a colleague you brief, not a tool you press Tab on. The brief is the work. Five things to start with this week. We will add more as the cohort matures.

Read time: 7 minutes. Audience: you, in a terminal with claude open, about to type your first instruction.

1 Brief it like a new colleague who walked in five minutes ago

"Refactor this" is not a brief. It is a wish. Claude will refactor SOMETHING and you will spend an hour figuring out whether the something was the right something.

A real brief has four parts: what the code is, what you want changed, the constraints that must hold, and how you will know it worked.

Bad:
  refactor OrderController

Better:
  This is the order-submission controller for our checkout API.
  It mixes business logic with EF data access in one 380-line POST
  handler. Refactor into Controller / Service / Repository layers
  using DI. Constraints: do not change the JSON shape of any
  response, keep the existing controller test passing, keep the
  same error codes. Success: the tests still pass and Program.cs
  has the new service registered.

Briefs this size feel like overkill for ten seconds. They save thirty minutes of unwinding the wrong refactor.

2 Ask it to read before it writes

Most of the value of Claude is in the reading and explaining step, not the code-writing step. Before any change, ask it to read the file, summarize what it sees, and propose an approach. Read the summary. Push back. Iterate on the approach. THEN say "implement that."

Do"Read OrderController.cs. Tell me what it is doing and what would surprise a senior reviewer about it. Do not change anything yet."

Don't"Refactor OrderController.cs and tell me what you changed."

The second form gets you a diff you cannot fully judge because you never built your own mental model first.

3 Push back when it sounds confident

Claude hedges accurately when it is uncertain ("this might work, but check X"). When it is confidently asserting that X is the right pattern, that is the moment to challenge.

"Why is that the right approach? What other patterns did you consider? What breaks if I do it differently?"

The argument that follows usually surfaces tradeoffs Claude initially glossed over. Sometimes you discover Claude was right and you learn why. Sometimes you discover the suggestion was load-bearing on assumptions Claude did not state.

4 Reverse the test-then-code flow

The standard rhythm with an AI assistant is: AI writes code, you write a test. That catches your bugs but it does not catch the AI's bugs (the test was written against the new behavior).

Reverse it. You describe the desired change. Claude writes a characterization test that captures the CURRENT behavior. You run that test against the unchanged code to confirm it passes (proves the test is honest). Then you let Claude make the change. The test either passes (the change preserved behavior) or fails (the change broke something you care about).

This is the only sustainable way to refactor legacy code with an AI in the loop. Without the characterization test, every refactor is a leap of faith.

5 Write the commit message before you look at the diff again

After Claude finishes a change, close your terminal pane that shows the diff. In your editor, write the commit message in your own words. Describe what changed and why, three sentences.

Then open the diff. Compare your description to what is actually there.

Three things can happen:

Description and diff agree. Ship it.
Diff has more in it than your description. You missed something. Read it again. If you still think it should ship, expand the description. If it should not be there, ask Claude to remove it.
Description claims things the diff does not have. Claude did not do what you thought. Ask why, then either accept the actual diff or push it to actually do the thing.

This habit catches more bugs than any number of code review tools. It also makes you a better engineer because writing in your own words is the only test of whether you understood the change.

One promise to yourself this week. Every PR description you write covers what changed, why it changed, and what could break. If Claude did the writing, you still own the description. If you cannot defend a line, delete the line. The cohort principle holds with or without an AI in the loop. You don't ship what you cannot explain.