How do you start using Claude Code on a real codebase?

Start small and supervised: give Claude Code one scoped change in a repository you know, ask for a plan before any edit, read every diff before you accept it, and only widen what it may do once a week of small changes has gone well. The tool is already on job ads: of 416 software engineering postings we collected on 29 September 2026, 27 (6%) named Claude Code.

This guide is for one developer. For a team's choice of tool, read Claude Code versus Codex for engineering teams instead. Claude Code changes often, so check its current documentation; the habits below outlast any release.

What should your first task with Claude Code be?

Something you could do yourself in under an hour, in code you know well, with a test that tells you whether it worked. Good first tasks:

• Fix a small bug you have already reproduced.
• Add a missing test for a function you understand.
• Rename something across a handful of files.
• Add input validation to one endpoint.

Avoid "tidy up the codebase", anything touching authentication or payments, or a feature whose shape you have not decided. The first task is for calibration: how the agent reads your code, where it guesses, and how long a review takes you.

Work in a clean branch so you can throw everything away, and name the files you expect it to touch if you know them.

Why should you ask for a plan before any code?

Because a wrong plan is cheap to fix and a wrong diff across eight files is not. Ask Claude Code to explain what it intends to change and why before it edits anything, then read the plan the way you would read a colleague's proposal:

• Does it touch files you did not expect? Ask why.
• Does it invent a helper that already exists somewhere? Point it at the existing one.
• Does it plan to change a test to make it pass? Stop it there.
• Is the plan bigger than the task? Cut it down.

Redirecting at the plan stage is the habit that most separates a useful session from a frustrating one.

What goes in CLAUDE.md?

CLAUDE.md is a file of project instructions in your repository that Claude Code reads at the start of a session. Write it after your first few tasks, when you know what the agent got wrong. Keep it short and specific:

# Project notes for Claude
- Run tests: make test  (single file: make test FILE=path)
- Lint and format: make lint
- Conventions: services in src/services, one class per file, no default exports
- Never edit: migrations/, vendor/, .env files
- Before finishing: run the tests and report the result

The test command matters most: an agent that can run your tests can check its own work. Keep it to a dozen clear lines, commit it, and edit it whenever you correct the same mistake twice.

How much permission should you give it?

Less than you think, at first. Claude Code asks before actions such as editing files or running commands, and you can allow some actions permanently. In the first week, approve each command yourself and notice which ones you approve every time without thinking: running the tests, the linter, a read-only git command. Those are the ones to allow. Keep asking for anything that deletes, installs, pushes, deploys or touches the network.

Whatever the settings, keep production credentials and customer data out of its reach, and never let it push to a shared branch unread.

Why are tests the contract?

Because they turn "looks right" into "is right". The workflow that works: you write or approve the failing test, the agent makes it pass, and the assertion is yours to change, not the agent's. When it writes tests for you, read them as carefully as the code: agent-written tests often check that the code does what it does rather than what it should.

Employers ask for this discipline alongside the tool. Among the 67 of those 416 postings that named an AI coding tool, 20 (30%) also mentioned testing. Do software engineering jobs expect AI coding tools? covers what else those ads ask for.

How should you review what Claude Code writes?

As if a new colleague wrote it, because in effect one did. For every diff:

1. Read the whole diff, not the summary. Summaries describe intent; diffs show what happened.
2. Check that you could explain each change in your own words. If you cannot, ask the agent to explain, then decide.
3. Look for the usual agent mistakes: a duplicated helper, a swallowed error, a changed assertion, an unrequested "improvement", a new dependency.
4. Run the tests yourself before you commit.

Nothing merges that you could not defend without the agent in the room.

When should you stop and write it yourself?

When the session is costing more than the code. Signs to stop:

• You have corrected the same misunderstanding three times.
• The diff keeps growing and you no longer follow it.
• The task needs a design decision you have not made.
• It is security-sensitive code you cannot fully verify.

Write the tricky part by hand, then hand the agent the routine work around it: tests, call sites, documentation.

What comes after the first two weeks?

Once small tasks are routine, add the extension points one at a time, each for a problem you have actually hit:

Adding all of them in week one is the common mistake.

Where should you start this week?

• Day one: install Claude Code and do one reproduced bug fix on a clean branch, plan first.
• Days two to four: one small task a day. Keep a note of every correction you make.
• Day five: turn those notes into a first CLAUDE.md with the test command, conventions and no-go folders.
• Week two: allow the commands you approved every time, try one refactor with tests added first, and review each diff line by line.
• End of week two: decide which task type you now hand over by default, and which you still write yourself.

Square 1's Claude Code from Zero is an on-demand course, recorded by an instructor and graded by Nova, the AI tutor: eight modules and about 10.5 hours, from a first reviewed change through CLAUDE.md, plans, tests, hooks, skills, subagents, MCP and worktrees to a feature taken from issue to merge. Its three projects are a reviewed feature, a hook-and-skill workflow on your own repository, and a refactor of code you did not write, with tests. It asks only that you write software in any language. AI Coding Workflows builds one feature in Cursor, Claude Code and Codex and teaches when to reach for which, and the twelve-week Claude Code for Engineering Bootcamp is live on Zoom with one instructor, about 15 hours a week. All are on a waitlist today.