Claude Code for beginners: let the agent read the project first

It is easy to open a code folder, see ten unfamiliar files, and think: "Can Claude just fix this?" Sometimes, yes. But the best first question is not "fix everything." It is: "Read the project and explain what is here before changing anything."

Claude Code is Anthropic's coding agent. Unlike normal Claude chat, it can work inside a project folder, read files, propose edits, run commands, and show what changed. That makes it more powerful than a chat answer, but it also needs clearer boundaries: a small task, explicit approvals, diff review, and a simple check before you keep anything.

Source: Claude Code overview and Claude Code best practices.

Who this guide is for

This guide is for you if you have already tried Claude, ChatGPT, or OpenAI Codex and want to understand what a coding agent feels like in practice. You do not need to be a full-time developer. You do need a small first project: a copy of a landing page, a course project, a demo repo, or a simple script without customer data or production secrets.

This continues from two earlier Hammer guides. Claude as coworker was about reusable work context in Claude Projects. OpenAI Codex for beginners was about letting a coding agent explain code before changing it. Here we use the same calm pattern with Claude Code.

What you will learn in 10–20 minutes

By the end, you can:

• choose a small project that works as a first test,
• start Claude Code in the right project folder,
• ask the agent to explain files and structure before editing,
• request one small reversible improvement,
• approve only what you understand,
• review the diff and command output,
• verify with a test, lint, local preview, or manual checklist.

Install Claude Code

For this guide, we use Claude Code in the terminal. You need a terminal, a small project, and an account with Claude Code access, such as Claude Pro/Max/Team/Enterprise or Anthropic Console.

On macOS, Linux, or WSL, run:

curl -fsSL https://claude.ai/install.sh | bash

On Windows PowerShell, run:

irm https://claude.ai/install.ps1 | iex

On Windows CMD, use this instead:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

If you use macOS and prefer Homebrew, you can also run:

brew install --cask claude-code

After installation, open the terminal in your project folder and start Claude Code:

cd /path/to/your/project
claude

On first launch, Claude Code asks you to log in. On Windows, Anthropic recommends Git for Windows if you want Claude Code to use the Bash tool. VS Code, Desktop, Web, and JetBrains are also available, but this guide sticks to the terminal flow.

Source: Claude Code quickstart, advanced setup, terminal guide, and VS Code integration.

Before you start: choose a small project and a checkpoint

Do not choose production code for the first run. Use a copy, a sample project, or a course folder where experimenting is fine. If the project uses Git, make a checkpoint or commit before you start. If Git still feels unfamiliar, duplicate the folder so you can throw away the experiment without drama.

Keep the boundaries clean. Do not include .env files, API keys, customer data, private recordings, or code you do not have the right to use. The first test should show how the workflow behaves, not how bravely you can grant an agent access. In a real team, the same idea becomes more professional: secrets in environment variables or a secret manager, scoped permissions, approval steps, logs, and diff review.

Claude Code is built around permission prompts. Anthropic says it asks for explicit approval before editing files, running commands, or doing actions that may modify the system. Write access is also tied to the folder where you start Claude Code and its subfolders unless you allow more.

Source: Claude Code security and Claude Code permissions.

Step 1: open a small project

Open the terminal in a copy or small project folder and run claude. The first goal is not to build something. The goal is to see whether Claude Code can orient itself in the project.

Good first examples: a simple website where you want to change a heading, a course project where you want to understand the files, a reporting script you want explained, or a copy of a demo repo where nothing important is at stake.

Step 2: ask Claude Code to explain before editing

Paste this prompt first:

Explain this project before changing anything.

Please:
1. Describe what the project does in plain language.
2. List the 5–8 most important files or folders.
3. Tell me how I would run, preview, or test it if the project includes that information.
4. Point out anything that looks risky, unclear, or missing.
5. Do not edit files or run modifying commands yet.

Read the answer as if a colleague were walking you through the project. Still lost? Ask Claude Code to simplify, point to the first file you should read, or describe how data moves through the project. For beginners, this is often the most valuable part. You get a map before you start changing things.

Source: Claude Code common workflows.

Step 3: ask for one safe first change

Once the explanation makes sense, ask for a proposal. Keep it small. A text change, a tiny validation improvement, a clearer error message, or one documentation line is better than a larger refactor.

Suggest one small, reversible improvement for this project.

Context:
- I am using this as my first Claude Code exercise.
- Keep the change limited to [one file / one component / one text update / one small bug fix].
- Do not touch secrets, .env files, deployment settings, package manager configuration, or unrelated files.

Before editing, give me:
1. the exact change you propose,
2. why it is safe and useful,
3. which files it would touch,
4. what command or manual check will verify it.

Wait for my approval before editing.

If the proposal gets too large, stop there: "Make the task smaller. Choose one file and one change."

Step 4: approve only the bounded work

When the plan is understandable, approve that change only. If Claude Code asks for network access, parent-folder access, new dependencies, destructive Git commands, or production-like access, ask why. For a first session, it is almost always better to stay local and small.

The rule is simple: the agent gets only the access the task needs. Secrets stay outside the chat, risky steps need approval, and the result must leave evidence in a diff, log, or test output.

Step 5: review the diff and command output

A diff is the before/after view of changed files. Look for things that do not belong:

• files you did not ask for,
• changed settings,
• new dependencies,
• edits to .env, deployment, or package manager configuration,
• broad rewrites when you asked for one small thing,
• commands that failed but are followed by a confident answer.

If something feels wrong, steer it back:

Keep the scope smaller. Address only the change we agreed on. Do not modify unrelated files or settings.

In VS Code, a visual diff can make review easier. In the terminal, ask Claude Code to summarize exactly which files changed and show the relevant diff.

Step 6: verify before you keep the change

Ask Claude Code for the smallest useful check. It might be a test command, lint, a build, a local preview, or a manual checklist. If you cannot run the project yourself, ask the agent to explain how a human should inspect the result.

Suggest the smallest check to verify this change.
If the project has test, lint, build, or preview commands, show them.
If I cannot run them, give me a manual checklist.

Keep only what you actually want. Commit, save, or document the change if it passes the check. Revert whatever surprises you.

Reusable first Claude Code task card

Save this prompt for the next small task:

You are helping me with my first small Claude Code task.

Rules:
- Explain before editing.
- Keep the task small and reversible.
- Do not touch secrets, .env files, deployment settings, package manager settings, or unrelated files.
- Ask before using network access, parent folders, destructive Git commands, or new dependencies.
- Mark anything uncertain as "needs human check".

Task:
1. Explain the project in plain language.
2. Suggest one safe first improvement.
3. Show which files would change.
4. Wait for approval before editing.
5. After editing, summarize the diff and tell me how to verify it.

Common mistakes

The most common mistake is starting too large: a production repo, a vague prompt, full auto-approval, or "fix everything." Another is skipping the explanation because the agent's first answer sounds confident. Code still needs review.

Do not bring the whole Claude Code universe into day one either. CLAUDE.md, hooks, MCP, subagents, GitHub Actions, SDK, worktrees, and background agents can be useful later. The first session should teach the rhythm: read, explain, propose, approve, review, verify.

Next step

If the first exercise works, create a small project note, or later a CLAUDE.md, with how the project runs, how it is tested, and how changes should be reviewed. Then Claude Code has to guess less next time.

Want to test coding agents in a team without giving them too much freedom too soon? Hammer can help choose the first small project, set simple permission rules, and build a routine for plan, diff, tests, and human review.

The next natural guide in the series could be CLAUDE.md for beginners, Claude Code permissions/plan mode, or a calm Claude Code vs Codex comparison, depending on interest.