Claude Code Workflows: Explore, Fix, Refactor, Test, Ship

Start broad, then narrow. From the project root:

1give me an overview of this codebase2explain the main architecture patterns used here3what are the key data models?4how is authentication handled?

Then locate the code for a specific feature and follow it end to end:

1find the files that handle user authentication2how do these authentication files work together?3trace the login process from front-end to database

Use the project's own domain words in questions; they match the identifiers Claude searches for. Ask for a glossary of project-specific terms and the coding conventions the code follows. If you already know where to look, reference it directly: @src/auth/session.ts puts the file's contents in the prompt (up to the Read tool's limit, 25,000 tokens by default), and @src/components/ shows a directory listing.

Exploration reads many files, and every file read fills the context window. For a broad question, delegate it: "use a subagent to investigate how our auth system handles token refresh". The subagent reads in its own context and returns only a summary.

Give Claude the symptom, the command that reproduces it, and what "fixed" means. The docs' best-practices page contrasts two prompts:

1# weak2the build is failing3 4# strong5the build fails with this error: [paste error]. fix it and verify the build6succeeds. address the root cause, don't suppress the error

For a behaviour bug, ask for a failing test first:

1users report that login fails after session timeout. check the auth flow in2src/auth/, especially token refresh. write a failing test that reproduces the3issue, then fix it and run the auth tests

The failing test is the important part. It proves Claude understood the bug, it turns "looks fixed" into a pass/fail check Claude can iterate against, and it stays behind as a regression test. Tell Claude whether the error is intermittent or consistent, and paste stack traces rather than describing them.

When Claude says it is done, ask for evidence: the test command it ran and its output, before and after.

Refactoring is where an agent can change the most code with the least visible effect, so it needs the strongest guardrails. The recipe from the docs:

1find deprecated API usage in our codebase2suggest how to refactor utils.js to use modern JavaScript features3refactor utils.js to use ES2024 features while maintaining the same behavior4run tests for the refactored code

Three habits make it safe. Plan first for anything touching several files: switch to plan mode (Shift+Tab until the status bar shows plan mode, or claude --permission-mode plan), have Claude list the files and steps, and edit the plan with Ctrl+G before approving it. Keep behaviour fixed: say "maintain the same behavior" and make sure tests cover the code before you start; if they do not, write characterisation tests first. Go in increments: one module or pattern per step, with tests run after each.

Point Claude at an existing example of the target pattern ("follow how HotDogWidget.php does it") rather than describing the pattern in prose.

Let Claude find the gaps and match your existing style:

1find functions in NotificationsService.swift that are not covered by tests2add tests for the notification service3add test cases for edge conditions in the notification service4run the new tests and fix any failures

Claude reads your existing test files to match the framework, structure, and assertion style. The quality risk is tests that pass because they assert little. Be specific about the behaviour to verify, ask for edge cases (error conditions, boundary values, unexpected input), and say what to avoid, for example "avoid mocks" when you want integration behaviour tested.

One pattern from the best-practices page works well for important code: have one session write the tests and a fresh session write the code that makes them pass. The second session cannot shape the tests around its own implementation.

Documentation follows the same find-generate-review loop:

1find functions without proper JSDoc comments in the auth module2add JSDoc comments to the undocumented functions in auth.js3check if the documentation follows our project standards

Specify the style (JSDoc, docstrings), ask for examples, and focus on public APIs and complex logic rather than documenting every getter.

For pull requests, create a pr for my changes works on its own, or step through it:

1summarize the changes I've made to the authentication module2create a pr3enhance the PR description with more context about the security improvements

Ask Claude to call out risks and anything a reviewer should look at closely. When Claude creates the PR with gh pr create (or glab mr create), Claude Code links the session to it, so claude --from-pr 1234 later opens the session picker filtered to that PR.

Most workflow failures are session failures: the wrong plan, a context full of old attempts, or a mixed bag of unrelated tasks. The tools:

• Plan mode before multi-file changes or unfamiliar code. Skip it when you could describe the diff in one sentence.
• Subagents for research: "use a subagent to review this diff for security issues" or "to investigate X". They work in a separate context and report back.
• Esc stops Claude mid-turn with context kept, so you can redirect. Esc twice or /rewind restores code, conversation, or both to an earlier prompt.
• /clear between unrelated tasks, and after two failed corrections on the same issue.
• claude --continue resumes the latest session in the directory; claude --resume picks from a list. Name sessions with /rename so you can find them.
• Worktrees for parallel work: claude --worktree feature-auth in one terminal and another name in a second.

And for scripts: git log --oneline -20 | claude -p "summarize these recent commits" runs Claude like any Unix tool, which is how these workflows move into CI.

Each of these is a variation of one problem: Claude has the wrong context or no way to check itself. The fixes are cheap. Keep sessions to one task, give every task a check, keep CLAUDE.md short enough that each line earns its place, and move anything that must happen every time, such as formatting or tests before finishing, into hooks, which run deterministically.

The flip side from the docs is worth keeping too: these are defaults, not laws. Sometimes accumulated context on one deep problem is valuable, and sometimes a vague prompt is the right way to see how Claude reads a problem before you constrain it.

Pick a real bug or a small missing behaviour in a repository you know.

1. Start a fresh session. Ask for an overview of the module involved, then "trace the code path for <the behaviour>". 2. Write the bug prompt with the symptom, a reproduction command, and "write a failing test that reproduces it, then fix the root cause". 3. Before accepting, ask: "show me the test output before and after the fix". 4. Ask "use a subagent to review this diff for edge cases and regressions; report only real problems". 5. Run the full test suite, then create a pr and ask Claude to list risks in the description. 6. /clear, and in the fresh session ask whether the PR's description matches the diff.

Pass criterion: the PR contains a test that failed before the fix and passes after it, the review step found or ruled out at least one specific edge case, and you read the evidence for each step rather than Claude's summary.