Claude Code Tutorial: One Verified Change

This Claude Code tutorial takes one small bug from inspection to a verified diff. You will open a disposable repository, let Claude map the code, approve a plan, allow a narrow edit, run the real test, and inspect the final change yourself. The goal is not to memorize every command. It is to learn the control loop you can reuse on an unfamiliar project.

Use a scratch directory and keep credentials, deployment access, and valuable uncommitted work out of it. The exercise is intentionally boring. That makes it possible to tell whether the agent followed the contract instead of being distracted by an impressive demo.

What You Will Produce

By the end, you should have five pieces of evidence:

The last row belongs to you. Anthropic gives Claude Code tools to read, edit, and run commands, but tool access is not product judgment.

Check The Current Setup Instructions

Anthropic's current Claude Code setup page recommends a native installer for macOS, Linux, and WSL, and documents separate Windows options. It also supports package-manager installations. Those details can change, so use that page rather than copying an old command from a screenshot.

After installation, the official checks are:

claude --version
claude doctor

The first confirms that the command resolves. The second prints read-only installation and settings diagnostics. Start Claude Code from inside the project you want it to inspect:

cd path/to/your-project
claude

Authentication depends on your account or configured provider. Follow the prompts and the current official documentation. Do not paste a secret into the chat because a tutorial told you to.

Create A Tiny Failure You Can Understand

You can use an existing practice repository. If you want a controlled fixture, create a new folder with this shape:

claude-code-practice/
  package.json
  src/normalize-tag.js
  test/normalize-tag.test.js
  CLAUDE.md

The package file uses Node's built-in test runner, so no dependency install is required:

{
  "name": "claude-code-practice",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --test"
  }
}

Put this deliberately incomplete function in src/normalize-tag.js:

export function normalizeTag(value) {
  return value.trim().toLowerCase().replaceAll(' ', '-');
}

Then add test/normalize-tag.test.js:

import test from 'node:test';
import assert from 'node:assert/strict';
import { normalizeTag } from '../src/normalize-tag.js';

test('collapses whitespace between tag words', () => {
  assert.equal(normalizeTag('  Ship   Small  '), 'ship-small');
});

The current function trims the ends and replaces each ordinary space separately. The test asks it to collapse the entire internal whitespace run into one separator. Read both files until you can explain that difference without Claude. This is your answer key.

Finally, give the repository a small CLAUDE.md:

# Repository Rules

- Run `npm test` after changing JavaScript.
- Do not add dependencies.
- Do not weaken or delete test assertions.
- Edit only `src/normalize-tag.js` for this exercise.
- Stop before commits, pushes, network calls, or destructive commands.

Initialize version control and make a baseline commit if this is a disposable repository. A clean baseline makes the later diff unambiguous. If you cannot safely make a commit, at least save a copy outside the working directory and inspect git status --short before the agent starts.

Checkpoint One: Inspect Without Editing

Claude Code has a documented plan permission mode for reading and analysis before source edits. Start there:

claude --permission-mode plan

Use a prompt that requests a repository map, not a fix:

Inspect this repository without editing anything.

Explain:
1. Which repository instruction file applies.
2. Why the current test fails.
3. Which source file should change.
4. Which command will verify the fix.
5. What you still need to assume.

Do not propose unrelated cleanup.

Read the response against the files. It should identify the whitespace run as the defect, keep the test assertion intact, name only the source file, and select npm test from the repository instructions.

If it gets the cause wrong, stop. Correct the missing context or make the task contract clearer before granting write access. Editing faster does not rescue a false diagnosis.

Checkpoint Two: Approve A Narrow Plan

Ask for the smallest implementation plan:

Plan the smallest change that makes the existing test pass.

Constraints:
- edit only src/normalize-tag.js
- add no dependencies
- preserve the test and its assertion
- keep behavior for already-normalized tags
- run npm test after the edit
- do not commit or push

The useful plan should replace the one-space assumption with handling for a whitespace run. It may choose a regular expression or another small standard-library expression. More than one implementation is reasonable.

Reject a plan that rewrites the module, modifies the test, adds a slug package, or expands the behavior into punctuation transliteration. Those may be separate features. They are outside this contract.

This is where a beginner often feels awkward because the agent sounds certain. Ignore the tone. Compare the plan with the written constraints.

Checkpoint Three: Let It Make The Edit

Leave plan mode using the interface option that gives you the level of approval you want. Anthropic's permission documentation describes the available modes and their tradeoffs. For a first exercise, keep edits visible and approve only the narrow action you just reviewed.

Tell Claude to execute the approved plan:

Apply the approved plan now. Keep the scope unchanged.
After editing, show the diff before doing anything else.

Inspect the diff yourself:

git diff -- src/normalize-tag.js
git status --short

A minimal implementation might use replace(/\s+/g, '-'). Do not judge it because it matches this sentence. Judge whether it satisfies the test and the stated boundary without damaging supported behavior.

The status output should show only the intended source change in a clean practice repository. If a settings file, test, lockfile, or unrelated source file changed, ask why before continuing.

Checkpoint Four: Run The Proof

Now ask Claude to run the repository's required check and preserve the result:

Run npm test.
Report the exact command, exit status, and test summary.
If it fails, diagnose the output before editing again.

The Claude Code CLI supports interactive tool use and command execution under its permission controls. You may be asked to approve the test command, depending on your mode and rules.

Watch the command output. Do not accept a prose-only "all good." Also inspect the test file after the run. The assertion must still express the original requirement.

If the test fails, keep the raw output in the conversation and ask for a diagnosis. Do not say only "fix it." The error text is evidence. A good recovery explains the mismatch, makes another bounded change if needed, and reruns the same proof.

One passing test proves this stated example, not every possible tag rule. Tabs, newlines, punctuation, non-Latin letters, and empty input are separate contract decisions. Add tests for them only when your real application defines the expected behavior.

Checkpoint Five: Review The Final State

Run your own final checks outside the agent's summary:

npm test
git diff --check
git diff
git status --short

Read the function and assertion together. The final answer should be easy to explain:

• repeated whitespace collapses to one hyphen;
• leading and trailing whitespace is removed;
• case is normalized;
• the original test was not weakened;
• no dependency or unrelated file was added.

All five bullets are part of this fixture's behavior and constraints. The single test directly proves only the specific whitespace example. Your code review determines whether the implementation reasonably generalizes to the whitespace run named in the test, while the diff confirms that no dependency or unrelated file was added.

If you decide to commit, write the commit yourself or give a separate explicit instruction after review. A tutorial run does not need push or deployment access.

What To Do When Claude Wants More Scope

Agents often find neighboring improvements while inspecting a small change. Some are useful. They still belong in a separate decision.

When Claude proposes extra work, ask it to record the idea without implementing it. Finish the verified task first. Then decide whether the follow-up has its own contract, test, and risk boundary.

I use this rule because mixed diffs are expensive to review. A whitespace fix, API redesign, and naming cleanup may each be defensible, while the combined change makes it harder to see which edit caused a regression.

If the agent claims it needs a new dependency, ask it to show why the language or existing repository pattern cannot solve the task. In this fixture, a dependency would be difficult to justify.

Move From The Fixture To A Real Repository

I would not jump from this exercise to a production migration. The next useful practice task has one additional boundary, not ten. Add a configuration file, a mocked service, or a package boundary while keeping the expected answer knowable.

Before I let an agent edit a real project, I want these questions answered in the task contract:

I would also inspect the starting worktree before the session. Existing modifications belong to somebody, even when the agent can technically overwrite them. If the tree is dirty, I note the files that are already changed and tell Claude to leave them alone unless they are part of the contract. A final diff is much less useful when nobody can tell which lines predated the task.

The verification command needs the same care. I prefer a focused test during iteration because feedback is fast, followed by the broader package check required by the repository. I do not ask for every test in a giant organization when the environment cannot run them. I ask for the strongest relevant proof available, then record the remaining gap instead of turning it into a fictional pass.

Keep A Session Evidence Log

For practice, save a tiny record after each run. I would use a table like this:

This takes a little longer than accepting the final summary. I think it pays for itself when a later failure raises the annoying question of what the agent actually saw. The record also lets you compare sessions without relying on which response sounded more confident.

If Claude cannot run a required service, I want that stated as an unresolved check. If a test passes only after the agent changes the fixture, I treat the result as a new test design that needs review. If the diff touches a protected path, I stop before debating whether the extra change is clever. Those are different failures and should not be collapsed into one vague quality score.

Is Claude Code Easy To Learn?

The basic interaction is approachable if you can navigate a terminal and read a diff. The harder skill is not prompt syntax. It is deciding what evidence makes a change acceptable.

You do not need to learn every command first. Learn this loop:

inspect -> plan -> edit -> diff -> test -> review

Repeat it on small tasks until you notice scope drift, altered tests, hidden assumptions, and unverifiable claims quickly. The official Claude Code quickstart covers the product interface. This exercise concentrates on the engineering judgment around it.

Is Claude Code Worth It For Coding?

It can be worth using when repository exploration, routine edits, and test iteration save more time than review and correction consume. That answer depends on your codebase, current access terms, task type, and ability to verify the output.

Run a few controlled fixtures before assigning sensitive work. Record accepted changes, rejected diffs, manual corrections, and the proof each run left behind. A polished response is not the metric.

For a direct product-selection method, use the Codex vs Claude Code workflow test. If your agent keeps producing broad or invented changes, tighten the task with the AI coding prompt guide before changing tools.

Keep The Loop Small Enough To Understand

The main lesson in this Claude Code tutorial is not the whitespace expression. It is the order of operations.

Inspect before granting edits. Approve a plan against written constraints. Read the diff before trusting the test. Preserve the raw command evidence. Then make the merge or commit decision yourself.

Once that loop feels ordinary, larger tasks become easier to divide. Skip it, and a fast agent can create a large pile of code whose correctness you cannot actually explain.