Module 2: Getting Started With Your First Agent

Setup: Installing And Launching Claude Code

Before you build anything, you must install Claude Code, log in to it, and run it on a real project.

This lesson gets you there in three steps: install, log in, start your first session.

Install Claude Code

On macOS, Linux, or WSL, open a terminal and run:

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

On Windows, install Git for Windows, so that Claude Code can use its Bash tool. Without it, Claude Code uses PowerShell as the shell tool instead.

A WSL setup does not need it.

A native install updates itself in the background, so you do not repeat this step later. When the install finishes, confirm that it worked:

claude --version

You see a version number, and then (Claude Code) after it.

Log In

Claude Code needs an account. Start it for the first time, and it prompts you to log in:

claude

You can log in with a Claude subscription: Pro, Max, Team, or Enterprise. This is the best route for most people.

You can also log in with a Claude Console account, or through a supported enterprise cloud provider.

Claude Code stores your credentials after you log in, so it does not ask you again. To switch accounts, type /login inside an active session.

Start Your First Session

Open your terminal in the project you want to work on. Then start Claude Code there:

cd /path/to/your/project
claude

You see the Claude Code prompt. Above it, Claude Code shows the current version, the model, and the working directory.

Claude Code reads your project files when it needs them. You do not add context by hand before you start.

The permission mode decides whether Claude asks you before it changes a file. In the default mode, Claude asks for approval before every change.

Press Shift+Tab to cycle through the modes. The acceptEdits mode approves file edits automatically, and the plan mode lets Claude propose changes without a change to any file.

You will use these modes again later in this module, in the lesson on how to review and iterate on an agent's work.

A few commands cover most of your day-to-day work:

claude              start an interactive session
claude "task"       run a one-time task and exit
claude -p "query"   run a one-off question and exit
/clear              clear the current conversation history
/help               show available commands
/exit               exit Claude Code

This setup covers what most readers need.

You may hit a platform-specific issue, or want more control over the install and the updates. The Claude Code Docs' Advanced setup page covers:

• System requirements by OS, hardware, and network.
• Windows-specific setup: native install vs. WSL.
• How to install on Alpine and other musl-based Linux distributions.
• The claude doctor diagnostic command.
• Update management: release channels, version pins, and how to turn off auto-updates.

Your First Real Experience With An Agent

You installed Claude Code and you started it. Now you can put it to work on a real project.

This lesson walks through the Common Workflows by Anthropic.

Get a Quick Codebase Overview

Suppose you join a new project and must understand its structure quickly. Start Claude Code in the project root, then ask for a high-level overview:

cd /path/to/project
claude

give me an overview of this codebase

From there, drill into the parts you need. Specific questions work better once you have the broad picture:

explain the main architecture patterns used here
what are the key data models?
how is authentication handled?

Start broad, then narrow.

Ask about the coding conventions and patterns that the project already uses. If the codebase has its own vocabulary, ask Claude for a glossary of project-specific terms.

None of this changes a single file. You build a mental model, and Claude reads for you.

Fix Bugs Efficiently

Suppose you hit an error message and must find and fix its source. Share the error with Claude first:

I'm seeing an error when I run npm test

Ask for a few ways to fix it before you commit to one:

suggest a few ways to fix the @ts-ignore in user.ts

When you pick an approach, apply it:

update user.ts to add the null check you suggested

Tell Claude the exact command that you ran to reproduce the issue. The command lets Claude pull a real stack trace instead of a guess.

Mention the steps that reproduce the error. Also say whether the error happens every time, or only sometimes.

This context separates a fast, targeted fix from a few rounds of trial and error.

How To Write The Best CLAUDE.md File

In the last lesson, you had to explain your project to Claude at the start of the session.

Do that every session, and you repeat yourself about your architecture, your testing setup, and your code style, over and over.

A CLAUDE.md file fixes this. It gives Claude persistent context about your project, and every conversation loads that context automatically.

Remember how Claude Code carries knowledge across sessions?

What Is a CLAUDE.md File?

CLAUDE.md is a special configuration file that lives in your repository and provides Claude with project-specific context.

Place it in your repository root to share it with your team. For a monorepo, place it in a parent directory.

Place it in your home folder to apply it across all your projects.

A CLAUDE.md file typically documents things like:

# Project Context
When working with this codebase, prioritize readability over cleverness.

## Key Directories
- app/models/  - database models
- app/api/     - route handlers
- app/core/    - configuration and utilities

## Standards
- Type hints required on all functions
- pytest for testing (fixtures in tests/conftest.py)

## Common Commands
uvicorn app.main:app --reload   # dev server
pytest tests/ -v                # run tests

Your CLAUDE.md file becomes part of Claude's system prompt, so every conversation starts with this context already in place.

You no longer explain the same basics at the start of every session.

Get Started with /init

It can feel daunting to write a CLAUDE.md file from scratch, especially in an unfamiliar codebase.

The /init command automates this step. It analyzes your project and generates a starter file for you.

cd your-project
claude
/init

Claude reads your package files, existing documentation, configuration files, and code structure.

It then generates a CLAUDE.md file that fits what it finds: build commands, test instructions, key directories, and the coding conventions that it detected.

Think of /init as a start, not a finished product. From there:

• Review the generated content for accuracy.
• Add workflow instructions that Claude could not infer on its own: branch name conventions, deployment processes, and code review requirements.
• Remove generic guidance that does not apply to your project.
• Commit the file to version control, so your team benefits too.

Give Claude a Map

It becomes tedious to explain your project's architecture, key libraries, and coding style for every new task.

Add a project summary and high-level directory structure to your CLAUDE.md instead, so Claude has immediate orientation whenever it navigates your codebase.

This is how compact it can be:

├── logs
│   ├── application.log
├── modules
│   ├── cli.py
│   ├── logging_utils.py
│   ├── media_handler.py
│   ├── player.py

Include your main dependencies, architectural patterns, and any non-standard organizational choices. If you use domain-driven design, microservices, or a specific framework, document that too.

Claude uses this map to make better decisions about where to find code and where to make changes.

Define Standard Workflows

When Claude jumps straight into code changes without a plan, you get rework.

Claude might implement a solution that misses requirements. It might choose the wrong architectural approach, or make changes that break existing functionality.

Define standard workflows in your CLAUDE.md for the types of tasks you do repeatedly. A solid default workflow answers four questions before it makes changes:

1. Is this a question about current state that requires investigation first?
2. Does this need a detailed plan before implementation?
3. What additional information is missing?
4. What commit message format and approval steps must Claude follow?

When Claude knows your workflow upfront, it structures the work to match your team's actual process. It does not guess.

Prompting For Codebases

You need a different skill to prompt Claude Code than to prompt a chatbot for prose.

According to Anthropic, you can follow best practices when you talk with agents that work in your codebase.

1. Be Clear and Direct

Claude responds well to clear, explicit instructions.

When you are specific about the output you want, you get better results.

If you want above and beyond behavior, request it explicitly. Do not rely on Claude to infer it from a vague prompt.

Less effective:
create an analytics dashboard

More effective:
Create an analytics dashboard. Include as many relevant features and
interactions as possible. Go beyond the basics to create a fully-featured
implementation.

Think of Claude as a brilliant but new employee who lacks context on your norms and workflows. The more precisely you explain what you want, the better the result.

The guide's golden rule: show your prompt to a colleague who has little context on the task, and ask them to follow it. If they are confused, Claude is confused too.

Two things follow from this:

• Be specific about the desired output format and constraints.
• Provide instructions as sequential steps in a numbered list or a bulleted list. Do this when the order or completeness of the steps matters.

2. Add Context to Improve Performance

When you explain why an instruction matters, and not just what it is, Claude generalizes correctly.

Say you tell Claude to avoid a certain pattern, because it broke production last time.

Claude can then apply that reasoning to similar situations that it never saw before. It does not avoid only that one exact pattern.

3. Use Examples Effectively

Examples are one of the most effective tools to steer Claude toward what you want. Good examples share two traits:

• Diverse: they cover edge cases, so Claude does not pick up unintended patterns.
• Structured: you wrap them in tags, so Claude can tell them apart from your instructions.

Three to five examples is generally enough to see the benefit.

4. Structure Prompts with XML Tags

A prompt that mixes several kinds of content together is easy for Claude to misread. Those kinds are instructions, context, and examples.

When you wrap each type in its own tag, you remove the ambiguity. Use consistent, descriptive tag names, and nest tags when your content has a natural hierarchy.

A short one-line request to fix a typo does not need this. A prompt that hands Claude several pieces of context at once does.

The guide's own multidocument example wraps each piece of content in <document> tags with <source> and <document_content> subtags. The same pattern for a coding task looks like this:

<documents>
  <document index="1">
    <source>error_log.txt</source>
    <document_content>
      {{ERROR_LOG}}
    </document_content>
  </document>
  <document index="2">
    <source>user.ts</source>
    <document_content>
      {{FILE_CONTENTS}}
    </document_content>
  </document>
</documents>

Find the cause of this error and suggest a fix.

What To Do In Long Sessions

Claude's later models handle long-horizon tasks in one way: they track state and make steady progress on a few things at a time. They do not attempt everything at once.

You see this most across multiple context windows. Claude can work on a complex task, save its state, and continue in a fresh context window.

Claude Code compacts a long session as the context window fills up. Tell Claude that upfront, so it does not wrap up too early when it senses the limit.

How To Review And Iterate The Code Written By An Agent

You installed Claude Code, ran your first task, gave it project context, and learned to prompt it well.

The last skill is how to review its work, and how to correct course when necessary.

Why the Context Window Is Important

Claude's context window holds your entire conversation. It holds every message, every file that Claude reads, and every command output.

A single debugging session or codebase exploration can consume tens of thousands of tokens.

LLM performance degrades as context fills. When the context window becomes full, Claude may start to 'forget' earlier instructions, or make more mistakes.

If Claude loses the thread partway through a long session, the full context window is often the cause.

Here are some ways you can improve and iterate:

1. Give Claude a Way to Verify Its Work

Claude stops when the work looks done. Without a check that it can run, “looks done” is the only signal available.

You then become the verification loop, and every mistake waits for you to notice it.

Give Claude something that produces a pass or a fail instead. It can then close the loop itself: it does the work, runs the check, reads the result, and iterates until the check passes.

The check can be anything that returns a signal Claude can read: a test suite, a build, or a linter. It can also be a screenshot that you compare against a design.

Have Claude show evidence, not an assertion of success. The evidence can be the test output, the command that it ran and what that command returned, or a screenshot.

It is faster to review evidence than to run the verification yourself. It also works for a session that you did not watch.

2. Explore, Then Plan, Then Code

"Separate research and planning from implementation to avoid solving the wrong problem." The recommended workflow has four phases:

1. Explore. Enter plan mode. Let Claude read files and answer questions without a change to any file.
2. Plan. Ask Claude to create a detailed implementation plan. You can open the plan in your text editor to edit it directly before Claude proceeds.
3. Implement. Switch out of plan mode and let Claude code. It verifies its work against the plan as it goes.
4. Commit. Ask Claude to commit with a descriptive message and open a pull request.

A plan adds overhead, and small changes do not need one. For a typo fix or a variable rename, just ask Claude to do it directly.

A plan earns its cost when you are uncertain about the approach. It also earns its cost when the change touches multiple files.

It earns its cost when you do not know the code that the change modifies.

3. Provide Specific Context to Reduce Corrections

The more precise your instructions, the fewer corrections you'll need.

Claude can infer intent, but it cannot read your mind.

A vague prompt still has a place. A prompt like what would you improve in this file? can surface things that you never thought to ask about.

It works when you explore, and when you can afford to course-correct.

4. Review a Diff Yourself

Claude Code Docs' Code Review page describes an automated PR-review feature that posts inline findings on your GitHub pull requests. It is currently a research preview for Team and Enterprise subscriptions.

On other plans, you can still get a review inside your terminal. Run the /code-review command in any Claude Code session to review a diff locally.

You can also extend Claude Code with hooks, skills, subagents, plugins, and MCP servers. These tools give it deterministic guardrails, reusable domain knowledge, and connections to outside systems.

They are powerful, but they belong to a different lesson. A later part of this guide covers how to design tools and instructions for agents, and how to coordinate multiple agents on one task.

Together, those steps are the full shape of agentic engineering in practice.

You decide what the agent must do, and whether the result is good enough.

Claude handles the how. It does this better as you give it more context and verification to work with.

So far, this guide covered how to use Claude Code well, as it comes out of the box.