# Explain unfamiliar code and its data flow

Ask Claude Code to explain what one file or module does and how data moves through it, written up in the format you learn from best.

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
Explain what {{path}} does and how data flows through it. Write it up as {{format}}.
{{#purpose}}

Why I need it: {{purpose}}
{{/purpose}}

Read the code itself, and follow calls into other files where that is needed to explain the flow. Do not change any existing files. If the format needs a new file, create only that one and tell me its path.

Cover these points:
1. What the code is for, in two or three sentences.
2. Its inputs and outputs: what calls it, what it receives, and what it returns or produces.
3. The data flow, step by step, naming the function or file at each step.
4. Side effects: writes to files or databases, network calls, shared state, timers.
5. Anything surprising or easy to get wrong, such as hidden ordering rules or silent error handling.

Mark anything you inferred rather than read in the code. If part of the flow leaves the code you can see, for example through config or an external service, say where it goes and that you could not follow it. List open questions instead of guessing.
```

## Fields

- `{{path}}` (required): File, folder or module to explain. In Claude Code you can type @ to pick the file from a list.
- `{{format}}`: Format of the write-up. Choose one:
  - a written explanation here in the chat, with a plain-text diagram of the data flow (default)
  - short bullet points, one per step of the data flow
  - an HTML page with a diagram, saved as one new file, then opened in my browser
- `{{purpose}}`: Why you need to understand it. Optional. Claude spends more detail on the parts that matter for this.

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 have to change or review a file you did not write, and you want to know what it does and where its data comes from before you touch it.
- The code passes data through several functions or files, and reading it line by line keeps losing the thread.
- You learn better from a diagram or a short list than from a long reply, and you want to choose the format of the answer up front.

## When not to use it

- You want a map of the whole repository rather than one part of it. Use the codebase overview template first, then come back to the file that matters.
- You do not know which file to ask about yet. Ask Claude Code where the behavior happens first, then explain the file it points to.
- You are in a plain chat without access to the project. Claude cannot open a file by its path there; paste the code into a regular explanation prompt instead.

## Why this structure

- The prompt names the file and the format of the answer in its first line. Choosing the format up front saves a second round of asking for the same content in a shape you can use.
- The optional purpose line tells Claude which parts of the code deserve the most detail, so the explanation leans toward the change you are about to make.
- Following calls into other files is allowed explicitly, because data flow rarely stops at one file, while the rule against changing existing files keeps the session read-only apart from the one write-up file the HTML option creates.
- The five numbered points move from purpose to inputs, flow, side effects and pitfalls. Side effects get their own point because they are the part most likely to break when you edit the code.
- Asking Claude to mark inferences and to say where the flow leaves the visible code separates what it read from what it guessed, and shows you where the explanation ends.

## Example input (fictional)

File, folder or module to explain:

```
src/scheduler/queue.ts
```

Format of the write-up:

```
an HTML page with a diagram, saved as one new file, then opened in my browser
```

Why you need to understand it:

```
I need to add a priority level to queued jobs without breaking retries.
```

## Follow-ups to send Claude

- Now trace one concrete input through the same code, with example values at each step.
- Which parts of this code have no tests? List them with the behavior that would go unnoticed if it broke.
- Add a short comment block at the top of the file that summarizes the data flow, matching the comment style already used there.

## Common mistakes

- Asking about a whole folder when you need one flow. The explanation gets longer and shallower; name the file or the entry point you care about.
- Leaving out the purpose. Without it, Claude gives equal weight to code you will never touch and to the part you are about to change.
- Taking the explanation as fact without checking it. Open two of the files it names and confirm the flow matches before you plan a change around it.

## Related templates

- [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.
- [Trace how code evolved through its history](https://awesomeclaudeprompts.com/prompts/trace-code-history/): Have Claude Code read the commit history of a file and explain how it reached its current shape and why, with commits cited as evidence.
- [Find where something happens in the code](https://awesomeclaudeprompts.com/prompts/find-where-code-happens/): Describe a behavior and let Claude Code find the code that does it, with file paths, the path that leads there and any duplicate implementations.

## Sources

- [Claude Code docs: Prompt library](https://code.claude.com/docs/en/prompt-library) (Anthropic documentation)
- [Claude Code docs: Common workflows, reference files and directories](https://code.claude.com/docs/en/common-workflows#reference-files-and-directories) (Anthropic documentation)
- [Claude Code best practices: Ask codebase questions](https://code.claude.com/docs/en/best-practices#ask-codebase-questions) (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.