Claude Code Tutorial: Make and Verify One Small Change

Use Claude Code on a repository you can build and restore. The first task should touch one small behavior with an existing or easy-to-write test. Start in Plan Mode, inspect the proposed files, approve only the needed commands, then review the diff yourself.

Prepare a real repository task

Suppose a TypeScript project has this function:

export function formatOwner(owner?: string) {
  return owner || 'Unknown';
}

The product rule says blank or whitespace-only owners must also return Unknown, while valid names keep their original spelling. Before Claude Code edits anything, record the expected cases:

This fixture is small, but it is a genuine behavior change with a regression risk: trimming the returned name would violate the last case.

Write the regression test before requesting a patch. This example assumes the project already runs TypeScript tests with tsx; use the repository’s own runner if it differs. The test’s import path may need to match your project layout.

import assert from 'node:assert/strict';
import test from 'node:test';
import { formatOwner } from '../src/formatOwner.ts';

test('uses Unknown only for missing or blank owners', () => {
  assert.equal(formatOwner(undefined), 'Unknown');
  assert.equal(formatOwner(''), 'Unknown');
  assert.equal(formatOwner('   '), 'Unknown');
  assert.equal(formatOwner(' Maya '), ' Maya ');
});

With the original implementation, the third assertion fails: a string of spaces is truthy. That failure establishes the baseline; it is not a reason to delete the test. Keep existing user changes separate from this exercise.

Inspect and plan before editing

Install and authenticate using Anthropic’s current setup guide. Open the repository, check that the working tree is understood, and start with claude --permission-mode plan when that flag is available in your installed version.

Inspect the repository and find formatOwner and its tests.
Plan the smallest change that treats undefined, empty and whitespace-only
owners as Unknown while preserving nonblank strings exactly.
Do not edit files yet. List the files, tests and commands you propose.

Reject a plan that rewrites unrelated helpers, changes formatting across the project or deletes a failing test. Scope is part of correctness.

Implement and verify

After approving the plan, ask Claude Code to add the four cases, make the smallest implementation change and run the repository’s existing test and typecheck commands. A minimal candidate is:

export function formatOwner(owner?: string) {
  return owner?.trim() ? owner : 'Unknown';
}

Run the test again. All four assertions should pass for this authored fixture. Also run the surrounding project’s tests and typecheck; the four assertions do not cover other callers. Record command names and exit codes, including any check you could not run.

Review:

1. the exact diff;
2. test output and exit status;
3. changed files against the approved plan;
4. behavior outside the new cases;
5. secrets, generated files and dependency changes.

The acceptance packet should identify the helper and test file, the failing baseline, the passing result, any remaining risk and the reviewer who accepted it. This is an authored teaching example, not a captured Claude Code session. Command names depend on the repository; use its documented scripts rather than inventing a generic build command.

Fix an overbroad change

If the patch returns owner.trim(), the tests should reveal that ' Maya ' changed. Tell Claude Code: “Preserve the original nonblank string. Use trimming only to decide whether it is empty.” Rerun the full fixed set, not only the failed case.

If a command requests network access, writes outside the agreed files or changes dependencies, pause and ask why it is needed. A passing local test does not approve a deployment. If the change must be abandoned, restore only the exercise files using the repository’s normal reviewable workflow; never discard unrelated uncommitted work.

Questions about Claude Code

Continue with the Claude Code course for a four-lesson practice sequence.