A Claude CLI workflow for tasks longer than an hour

The first move in any Claude CLI workflow is a CLAUDE.md at the repo root. Not a manifesto. Keep it under a page and put in the things a new engineer would ask on day one: how to install, how to run tests, which directory is generated and must not be hand-edited, and the two or three conventions your team actually enforces in review.

The test that tells you it is working: ask for a change in an unfamiliar part of the codebase and see whether the first attempt runs your test command correctly without being told. If it guesses npm test when you use a task runner, your file is missing the only line that mattered.

The loop for long work

Plan first, then execute in slices, then review each slice. In practice:

• Describe the task and ask for a plan before any edits. Read it. Correct the approach in one sentence if it is wrong. This is the cheapest correction you will ever make.
• Work in a dedicated worktree so a bad hour is thrown away with git worktree remove rather than untangled.
• Commit every time the tests pass, even halfway through. Checkpoints, not milestones.
• Start a fresh session when the task changes shape. A session carrying an hour of abandoned approaches gets worse, not better.
• Read the diff yourself before the tests convince you. Passing tests on code that solves the wrong problem is the most common bad outcome we see.

Where a Claude CLI workflow goes wrong

Three failures account for most of the pain. The first is one enormous instruction covering four unrelated changes, which produces a diff nobody reviews properly. Split it. The second is running two sessions in the same checkout, where each overwrites the other's edits and you spend the evening in git reflog. The third is treating the session as the record of what happened. When you close the terminal, the reasoning is gone. If a decision matters, it belongs in a commit message or a file in the repo.

A team we trained lost most of a day to the second one. Two engineers, one repo directory, two agents, and a test suite that passed for neither of them. Worktrees fixed it in five minutes and it never happened again.

Automating the boring guardrails

Anything you say twice should stop being a spoken rule. Formatting after an edit, blocking writes to a generated directory, running a linter before a commit: wire these in rather than reminding people. The rule of thumb we give teams is that a convention you have corrected three times is now a hook or a CI check, and correcting it a fourth time is a choice.

What to do next

Write CLAUDE.md today, half a page, build and test commands first. Run your next multi-hour task in a fresh worktree with a plan you actually read. Commit at every green test run. After three tasks, look at which of the three failures above still bites you and fix that one specifically.

If you want help putting this into practice, talk to us.