# Scope a change before you start

Ask Claude Code which files a change would touch and how big it is, so you can size the work before it goes on a roadmap or into a sprint.

Paste into: **Claude Code**, started in your project folder

## Prompt template

How the builder on the page fills in this template, so you can do the same:

- `{{key}}` becomes the text entered for that field, exactly as typed. Empty text, or text that is only whitespace (spaces, tabs or line breaks), counts as empty: a required field then becomes `[fill in: <label>]` with its label, and an optional field becomes nothing.
- For a choice field, `{{key}}` becomes the text of the chosen option, or of the default when none is chosen.
- Text between `{{#key}}` and `{{/key}}` stays only when that field is not empty; a choice field always counts as filled. The markers themselves are removed, and a marker that stands alone on its line takes its line break with it.
- Each value is inserted once, as it is: `{{…}}` inside a value stays as typed.

```text
Which files would I need to touch to {{change}}?
{{#known}}

What I already know:
{{known}}
{{/known}}

Explore the code to answer; do not rely on file names alone. Only read. Do not change, create or delete any files, and do not start implementing.

Write the answer for {{audience}}.

Give me:
1. The files involved, grouped by area (for example interface, logic, data, tests, config), with one line on what would change in each.
2. The size: one self-contained component, or a change that cuts across several parts of the system. Explain why.
3. What could make it bigger than it looks: shared components, data migrations, settings that must be stored somewhere, or other teams' code.
4. Decisions someone has to make before work starts.

Do not estimate hours or days. If the request is unclear or could be built in very different ways, describe the options and list your questions instead of picking one silently.
```

## Fields

- `{{change}}` (required): The change you are considering. Describe the outcome as a user would see it. You do not need to know how it would be built.
- `{{audience}}`: Who the answer is for. Choose one:
  - someone who does not read code, in plain language with file paths listed at the end (default)
  - an engineer, with file paths and function names throughout
- `{{known}}`: What you already know or have decided. Optional. Limits on the scope, or decisions already made.

This site doesn't run Claude or show model output. Results depend on your input and the model you use.

## When to use this template

- You are deciding whether a feature fits in the next sprint or on the roadmap, and you need to know if it touches one component or half the system.
- You are a product manager or designer and want an answer grounded in the actual code before you talk to engineering about the work.
- You suspect a request that sounds small has hidden dependencies, such as shared components or stored settings, and want them found early.

## When not to use it

- The change has already been agreed and someone is about to build it. Use the plan template, which goes further into steps, order and checks.
- You need a time estimate for a commitment. This prompt deliberately sizes the change by its reach in the code, not in hours; turn the answer into an estimate with the people who will do the work.
- You are not in Claude Code or another tool that can read the repository. A file list written without the code would be a guess.

## Why this structure

- The opening question is about the outcome, not the implementation, so you can ask it without knowing how the code is organized.
- The audience setting decides how the answer is written. Plain language with paths at the end serves a product conversation; paths throughout serve an engineer.
- Grouping files by area in point 1 shows at a glance whether the change stays in one layer or reaches into data, config and tests as well.
- Point 3 asks for what could make the change bigger, because hidden work such as migrations or shared components is the usual reason a small request grows.
- The read-only rule and the ban on estimating hours keep this a sizing exercise. Claude reports reach and open decisions; people who own the work turn that into a schedule.

## Example input (fictional)

The change you are considering:

```
add a dark mode toggle to settings
```

Who the answer is for:

```
someone who does not read code, in plain language with file paths listed at the end
```

What you already know or have decided:

```
Only the web app for now. The mobile app will follow later.
```

## Follow-ups to send Claude

- Turn this into a plan an engineer could review: the steps in order, with a point after each where the tests should pass.
- Which of the open decisions blocks the most files? Explain the options for that one in plain language.
- Compare this with a smaller version of the feature that leaves out the parts in point 3, and list the files that version would touch.

## Common mistakes

- Describing a solution instead of the outcome, such as "add a CSS variable". That narrows the answer to your guess about how it should be built.
- Treating the file count as the size. One shared file can matter more than ten small ones; read point 3 before you judge.
- Skipping the questions at the end. Open decisions are usually where scope grows after work starts, so settle them before the change is scheduled.

## Related templates

- [Plan a code change before editing](https://awesomeclaudeprompts.com/prompts/plan-code-change/): Have Claude Code read the relevant code and propose a file-by-file plan for a multi-file change, without editing anything until you approve it.
- [Get oriented in a new codebase](https://awesomeclaudeprompts.com/prompts/codebase-overview/): Ask Claude Code to map an unfamiliar repository: its architecture, key directories, how the parts connect, and where to start for your task.
- [Ask the codebase a product question](https://awesomeclaudeprompts.com/prompts/ask-codebase-product-question/): Say your role and a user action, and Claude Code walks you through what the product does from the interface down to the result, from the source.

## Sources

- [Claude Code docs: Prompt library](https://code.claude.com/docs/en/prompt-library) (Anthropic documentation)
- [How Anthropic teams use Claude Code](https://claude.com/blog/how-anthropic-teams-use-claude-code) (Anthropic documentation)
- [Claude Code best practices: Explore first, then plan, then code](https://code.claude.com/docs/en/best-practices#explore-first-then-plan-then-code) (Anthropic documentation)

---

Awesome Claude Prompts is an independent project. It is not affiliated with, endorsed by, or sponsored by Anthropic. Claude is a trademark of Anthropic, PBC.