Explain a file

Claude Code slash command (.claude/commands/explain-file.md). Explains a source file's purpose, public surface, control flow, dependencies, and gotchas, grounded in the file and its callers.

License: CC0-1.0 · By waxmark · v1 · 2026-11-02

Share on X

Add a trust badge to your README

[![Waxmark](https://waxmark.app/api/badge/explain-file)](https://waxmark.app/items/explain-file/scan)
Report
---
description: Explain what a source file does, its public API, how it is used, and what to watch out for
argument-hint: <path/to/file>
allowed-tools: Read, Grep, Glob, Bash(git log *)
---

Explain the file at `$0` to an engineer who is new to this codebase.

File contents:
@$0

Recent history:
!`git log --oneline -8 -- "$0"`

Procedure:
1. Find how it is used: Grep for its exported names and for imports of its path. Read one or two representative callers.
2. Find what it depends on: imports and the key external calls (DB, HTTP, FS).
3. Write the explanation below. Use the file's own names; link claims to line numbers.

Output:

## `$0`
**Purpose:** one or two sentences, in terms of the domain, not the syntax.
**Used by:** the main callers (file paths) and in what situation.

### Public surface
| Export | Signature (short) | What it does | Line |
|---|---|---|---|

### How it works
Walk through the main path in 4-8 bullets, in execution order. Name the branches that matter and skip boilerplate.

### Dependencies and side effects
- Reads/writes: ...
- Network/DB/FS: ...
- Globals or module state: ...

### Gotchas
- Non-obvious behaviors, implicit contracts, ordering requirements, error handling quirks, TODOs, and anything the recent history suggests is fragile.

### If you need to change it
- Where the tests are (path) and what they cover.
- The one place a change here is most likely to break something else.

Keep it under 60 lines. If the file is generated or trivially small, say so in a paragraph and stop.
Explain a file · Waxmark