Common workflows

These are the patterns I reach for most days. Each one is a short sequence of prompts you can adapt to your own project, plus the habits that make them work. They apply on any surface: terminal, IDE, desktop or web.

For broader advice on prompting and managing context, read best practices. For a library of ready-made prompts, see the prompt library.

Learning an unfamiliar codebase

Get the lay of the land

New client repo, first morning. Open a session at the project root and work from broad to narrow:

cd ~/clients/fleet-tracker
claude

give me a tour of this project: what it does, how it's structured, and how it runs locally

what are the main domain entities and where are they defined?

how do requests get authenticated and authorised?

write me a glossary of the project-specific terms you've come across

Ask about conventions too ("how are errors reported to the client?"). That answer often ends up in CLAUDE.md. For monorepos and very large repositories, large codebases explains how to set things up.

Find the code behind a feature

which files implement the geofence alerts?

how do those pieces talk to each other?

trace an alert from the GPS ping arriving to the push notification being sent

Use the project's own vocabulary, and be specific. If you work in a typed language, install a code intelligence plugin so Claude can jump to definitions and find references instead of grepping.

Fixing bugs

Give Claude the failure and the way to reproduce it:

`pnpm test src/billing` fails with "expected 1999 received 2000". reproduce it and find the cause

give me two or three options for fixing it, with trade-offs

go with the second option and add a test that would have caught this

What makes this work:

• Include the exact command that reproduces the problem so Claude can get a stack trace itself.
• Mention the steps that trigger it in the app.
• Say whether it is consistent or intermittent. Flaky failures need a very different investigation.

Refactoring

Work in small, verifiable steps:

find everywhere we still use the old `request` library

propose how to migrate src/clients/weather.js to native fetch with async/await

do the migration without changing any public function signatures

run the tests for the clients package and show me the results

Ask Claude to explain why the new approach is better, state any compatibility constraints up front, and keep each refactor small enough that a failing test points clearly at the cause.

Writing tests

which functions in InvoiceCalculator.kt have no test coverage?

add tests for those, following the style of the existing tests in that module

now add cases for edge conditions: zero quantities, negative discounts, currency rounding

run the new tests and fix anything that fails

Claude looks at your existing test files and copies their framework, structure and assertion style. Be clear about which behaviour you want to pin down, and ask it to suggest edge cases you might have missed: error paths, boundaries and odd inputs are where it adds the most value.

Tip: If a test fails, tell Claude whether the test or the code is wrong. Otherwise it may "fix" a correct test to match buggy code.

Pull requests

The quick version is just "open a PR for this". For more control:

summarise what I've changed on this branch

create a pull request with that summary, a testing section and a note about the migration

add a short risk section to the description: what could break and how we'd notice

Always read the generated description before you submit it.

Claude Code links a session to a pull request when Claude creates it with gh pr create or glab mr create, or works on an existing one. To get back to that session later, run claude --from-pr 482 with your PR number, or paste the PR URL into the search box in the /resume picker. See sessions.

Documentation

find exported functions in packages/sdk that have no docstrings

add TSDoc comments to them, with a short example for anything non-obvious

check the new comments against the conventions in docs/CONTRIBUTING.md

Name the documentation style you want (JSDoc, TSDoc, Python docstrings, rustdoc), ask for examples, and prioritise public APIs and complicated logic.

Notes and other non-code folders

Claude Code is not limited to code. Point it at a notes vault, a docs site or any folder of Markdown and it will search, edit and reorganise just as it would a repository. .claude/ and CLAUDE.md happily coexist with other tools' config folders, and because Claude reads files fresh on each tool call, it sees edits you made in another app the next time it opens the file.

I use this to tidy meeting notes into client folders and to keep a project's decision log consistent.

Working with images

Get an image into the conversation in any of three ways:

1. Drag and drop it into the Claude Code window.
2. Copy it and paste with Ctrl+V (or Alt+V on Windows and WSL).
3. Give a path: "look at ~/Desktop/checkout-bug.png".

Then use it as context:

this is what the checkout page looks like on a 375px screen. what's causing the overflow?

here's the whiteboard sketch of the new data model. turn it into Prisma schema changes

build this card component to match the mockup, using our existing Tailwind tokens

Screenshots of errors, UI designs and diagrams all work, and you can use several images in one conversation. When Claude refers to an image as [Image #1], Cmd+Click (macOS) or Ctrl+Click (Windows and Linux) opens it in your default viewer.

Referencing files with @

Typing @ followed by a path puts a file straight into context so Claude does not have to go and find it:

explain the retry logic in @src/queue/worker.ts

what's in @infra/modules?

compare @api/v1/orders.py with @api/v2/orders.py and list the behavioural differences

• A file is included if it fits within the Read tool's limit (25,000 tokens by default); text files over 256 KB are not included.
• A directory reference gives a listing, not contents.
• Relative and absolute paths both work.
• Referencing a file also loads any CLAUDE.md in that file's folder and its parents.
• Type @ to get a path suggestion menu; Enter or Tab accepts the suggestion and Enter again sends.
• MCP resources use @server:resource, for example @github:repos/acme/api/issues. See MCP.

Running Claude on a schedule

For recurring jobs like a morning PR review, a weekly dependency audit or an overnight look at CI failures, choose by where the job needs to run:

Scheduled prompts run unattended and cannot ask questions, so spell out success and what to do with the result. For example: "Check open PRs labelled ready-for-review, leave inline comments on real problems only, then post a three-line summary to #web-team."

Asking Claude about Claude Code

Claude Code can answer questions about its own features, and it always has access to current documentation regardless of your installed version:

how do I stop you from ever editing files in the migrations folder?

what's the difference between a skill and a subagent?

how do I point you at Amazon Bedrock?

For hands-on lessons with animated demos, run /powerup.

Picking up where you left off

claude --continue

This reopens the most recent session in the current directory. If there is none, it prints No conversation found to continue and exits. claude --resume lets you choose from a list, and /resume switches from inside a session. Sessions covers naming, branching and the picker.

Parallel sessions with worktrees

To have Claude fix a bug in one terminal while you build a feature in another, give each its own git worktree: a separate checkout on its own branch.

claude --worktree fix-timezone-bug

Run the same command with a different name in a second terminal for another isolated session. Worktrees are created from an existing commit, so a brand-new repository with no commits fails with Failed to resolve base branch "HEAD": git rev-parse failed. Worktrees covers clean-up and copying gitignored files like .env. To keep an eye on several sessions from one screen, see agent view.

Planning before editing

For changes you want to approve before anything touches disk, use plan mode. Claude reads and investigates, then proposes a plan, and makes no edits until you accept.

claude --permission-mode plan

Or press Shift+Tab mid-session until the status bar shows ⏸ plan mode on. Permission modes explains the approval flow and how to edit the plan in your own editor.

I use plan mode for anything touching billing, auth or data migrations, and for any change I am going to hand to someone else to review.

Delegating research to subagents

Exploring a big codebase fills your context with file contents you will never look at again. Hand it off:

use a subagent to find every place we write to the audit_log table and report the call sites

The subagent does the reading in its own context window and returns a summary. Subagents shows how to define your own with specific tools and instructions.

Scripting and pipelines

Run Claude non-interactively for CI, git hooks or batch jobs. It reads stdin and writes stdout like any other Unix tool:

git log --since="1 week ago" --pretty=format:'%h %s' | claude -p "write a short weekly update for the client from these commits"

Headless mode covers output formats, permission flags and running many jobs in parallel.

Related

• Best practices
• Prompt library
• Sessions
• Worktrees
• Features overview