Explain an Unfamiliar Script With Claude Code Before Running It

Someone hands you a small script and says, “It only renames a few files.” That is not a review. Before running unfamiliar code, use Claude Code to map what it reads, writes, depends on, and could do unexpectedly. Keep the first pass read-only and make the human approval step explicit.

Evidence label: documentation-based builder lesson with illustrative output. The workflow was not executed here and does not claim a reproduced Claude Code demo.

Prerequisites and safe setup

• Claude Code installed on a terminal, IDE, desktop or web surface. The official overview lists these surfaces and notes that access requirements vary.
• A disposable copy of the project or script. Do not start in a production folder.
• A clean working tree or a backup you can restore.

Claude Code’s documentation describes it as able to read a codebase, run commands, edit files and connect to tools. That capability is useful for inspection, but it is also why you should set a boundary before the first prompt.

Create this fictional folder:

review-me/
  rename_reports.py
  reports/
    April report.csv
    May report.csv

The sample script is fictional. If you create it for practice, keep it limited to the reports/ folder and do not put secrets or real customer files inside.

1. Start in plan mode

From the project folder, start Claude Code with its documented plan mode:

cd /path/to/review-me
claude --permission-mode plan

Plan mode is designed to let Claude read and propose a plan without editing until you approve it. The mode is a safety aid, not a guarantee: still inspect the commands and file paths yourself.

2. Request a read-only map

Paste this prompt:

I need to understand rename_reports.py before anyone runs it.

Read the script and any local files it imports. Do not edit files, run the
script, install packages, access the network, or use MCP/tools. Stay in this
project folder.

Return:
1. A plain-English summary of the control flow.
2. Every file and directory it reads, writes, renames, deletes, or creates.
3. Every command, subprocess, network request, environment variable, and
   external package it can use.
4. Whether it can escape the reports/ folder, overwrite an existing file, or
   behave differently when a filename contains spaces.
5. A five-step dry-run plan that prints proposed changes without applying them.
6. Questions or uncertainties that require a human review.

Do not claim that the script is safe. Quote the relevant lines for each risk.

Claude Code’s common workflow guidance recommends starting with exploration, narrowing to relevant files, and planning before edits. The prompt above turns that general pattern into an acceptance checklist for a small utility.

3. Review the result before leaving plan mode

The explanation passes the first review only if it identifies the script’s actual paths and side effects. Check the source yourself:

1. Search for file-writing calls such as open(..., "w"), rename, replace, or delete operations.
2. Search for subprocess, shell, network, and package-import calls.
3. Confirm the proposed dry run does not create or rename anything.
4. Check that filenames with spaces are handled as paths, not split into shell words.
5. Confirm the script never receives a production path or secret-bearing environment.

This is a review procedure, not a claim that Claude found every risk. If the response and source disagree, stop and escalate to a qualified reviewer.

4. Ask for a bounded dry-run change only after approval

After you understand the script, leave plan mode only if you choose to. Then ask for a minimal change:

Add a --dry-run option to rename_reports.py.

Before editing, show the files you will change. The dry run must only print the
source and destination for each proposed rename; it must not write, rename,
delete, install, or access the network. Add a test using a temporary directory,
including a filename with spaces. Do not touch files outside this project.
After editing, show the diff and the exact test command. Wait for my approval
before running the command.

Inspect the diff. A passing test is useful evidence about the test case, not a blanket safety certification for every input.

No-code alternative

If terminal work is not appropriate, open the script in a text editor and make a small table with: input, output, write/delete operation, dependency, and risk. Ask a technical owner to run it in a disposable folder. The control is the same: understand first, dry-run second, execute last.

Troubleshooting and limits

• Claude proposes an edit during inspection: cancel it and restart in plan mode with “read-only; do not edit or run.”
• The script imports an unknown package: do not install it automatically. Check its official documentation and have an owner review the dependency.
• The script calls an external tool or MCP server: stop, inspect scopes and data flow, and treat read access and write access as separate approvals.

TRY this for a small, non-sensitive script you can isolate. SKIP autonomous execution for destructive changes, regulated data, production folders, or code you cannot review.

For one no-code review workflow, see Use ChatGPT to Review a Draft Against a Written Brief. If you want one practical AI-for-work workflow each week, join The Weekly Verdict.