Skip to content

commandWorkflow

Explain Code

Explains a file or function to a newcomer: purpose, a step-by-step walk-through with a worked example, and the gotchas.

npx workspacetemplates add explain-code --tool claude-code

Writes 1 file to .claude/commands/

.claude/commands/explain-code.md14 lines · 1.0 KBFile
---
description: "Explains a file or function to a newcomer: purpose, a step-by-step walk-through with a worked example, and the gotchas."
argument-hint: "<file path or function name>"
---

Explain this code to a developer who is new to the project: $ARGUMENTS

1. Locate the target. For a function name, search for its definition. Read the whole function, then its callers and the types it uses. If the name matches several places, list them and ask which one.
2. Start with one sentence: what problem this code solves and who calls it.
3. Walk through it in execution order. Pick a small concrete input and show how values change at each step, quoting the lines with `file:line`.
4. Call out the non-obvious: hidden state, side effects, error paths, performance cost, and assumptions the callers must keep.
5. Finish with "Where to look next": two or three related files or functions.

Rules: explain what the code does, not what you wish it did. Mark guesses with "I infer". Do not edit anything and do not suggest refactors unless asked. Keep it under 400 words.

What it does

Reading unfamiliar code is slow because the purpose is hidden behind the details. This command starts with what the code is for, then walks through it in execution order using a small concrete input.

It points out the surprising parts, such as hidden state, side effects and implicit assumptions, and it says where it is not sure rather than bluffing.

Example

you › /explain-code src/billing/prorate.ts

agent › prorate() turns a plan change into a credit or charge for the rest of the billing period.

Walk-through with a $30 plan upgraded to $60 on day 10 of 30: line 18 computes 20 unused days, line 22 credits $20, line 27 charges $40, net charge $20.

Gotcha: line 31 rounds half up per line item, so totals can differ by a cent from the invoice.

Questions

Will it change the code?
No. It only reads. Suggestions for changes come only if you ask.
What if it misreads something?
It marks inferred parts, so you know which claims to verify against the source.
  • Debug Error

    CommandWorkflow

    Free
  • Estimate Task

    CommandWorkflow

    Free
  • Plan Feature

    CommandWorkflow

    Free
  • Reproduce Bug

    CommandWorkflow

    Free