Common Claude Code workflows

Who this is for and what you will get out of it

This guide is for readers who already have Claude Code installed and want to know how to phrase everyday development tasks. After working through it you should be able to get Claude to learn an unfamiliar project, track down and fix an error, add tests to a change, and open a pull request ^[1].

Get oriented in an unfamiliar project

Run claude from the project root and start with a broad request such as "give me an overview of this codebase." Follow up with narrower questions such as "explain the main architecture patterns used here" or "how is authentication handled?" ^[1]. The docs advise starting broad and narrowing down, asking about the project's conventions, and requesting a glossary of project-specific terms ^[1].

To find the code behind a feature, ask Claude to find the files that handle it, then ask how those files work together. A prompt such as "trace the login process from front-end to database" asks it to follow the flow end to end ^[1].

Fix a bug

Paste the error into the conversation and ask for a few possible fixes before choosing one. The docs recommend telling Claude which command reproduces the problem, what steps trigger it, and whether the error is intermittent or consistent ^[1].

Refactor and add tests

For a refactor, find deprecated API usage first, ask for suggestions, apply the change while keeping behavior the same, and run the tests. The docs recommend small, testable steps ^[1].

When you ask for tests, Claude looks at the existing test files and follows their style, frameworks and assertion patterns. Be specific about the behavior you want verified, and ask it to look for edge cases that are easy to miss ^[1].

Create a pull request

You can ask Claude to create a PR directly, or summarize your changes first and then generate the PR. Review the generated PR before you submit it, and ask Claude to point out possible risks ^[1].

When Claude creates a PR with gh pr create or glab mr create, it links the session to that PR. Running claude --from-pr 1234 then opens the session picker filtered to sessions linked to that PR number ^[1].

Reference files in a prompt

Typing @ followed by a path, such as "Explain the logic in @src/utils/auth.js", puts the file's content into the conversation without a separate read step. A file that exceeds the Read tool's default limit of 25,000 tokens is not included in full, and text files larger than 256KB are left out ^[1].

To stop @ references from including content, set CLAUDE_CODE_DISABLE_FILE_MENTIONS to 1. The docs point out that PreToolUse hooks do not run for files referenced with @, because no tool call happens. To control what Claude can read, add a Read deny rule ^[1]. Images can be dragged into the window, pasted with Ctrl+V, or referenced by path in the prompt ^[1].

Parallel sessions and plan mode

To work on two things at once without edits colliding, use a worktree: claude --worktree feature-auth starts an isolated session on its own git worktree. The repository needs at least one commit before this works ^[1].

To review a plan before anything changes, start with claude --permission-mode plan. Claude reads files and proposes a plan, and makes no edits until you approve. Pressing Shift+Tab mid-session also switches to plan mode, and the status bar shows ⏸ plan mode on ^[1].

Send research to a subagent

Exploring a large codebase fills the context quickly. You can ask Claude to use a subagent for the investigation, for example "use a subagent to investigate how our auth system handles token refresh." The subagent reads files in its own context window and returns a summary ^[1].

Run Claude from scripts

For CI, pre-commit hooks or batch jobs, run Claude non-interactively. A command such as git log --oneline -20 | claude -p "summarize these recent commits" feeds standard input to the prompt and writes the result to standard output ^[1].

Scheduled runs

The docs list four ways to run work on a schedule. Cloud scheduled tasks (routines) run on Anthropic-managed infrastructure. Desktop scheduled tasks run on your own machine. GitHub Actions runs in CI. /loop runs in the current CLI session. A scheduled task runs without you and cannot ask questions, so its prompt should state what success looks like and what to do with the results ^[1].

Next steps

Start with reading code and fixing one small bug, then add worktrees, plan mode and subagents as the work grows. The official common workflows page has the full recipes ^[1].