title: "Your First Hour — Claude Code" tested_with: claude-code: "1.0.x" last_updated: 2026-03-21 status: proven difficulty: beginner prerequisites: [00-what-is-agentic-dev]

Your First Hour with Claude Code

A step-by-step walkthrough from installation to your first completed task. Every command below is copy-paste ready. Notes labeled Adapt this tell you what to change for your specific situation.

Step 1: Installation (~2 minutes)

Claude Code is distributed as an npm package. You need Node.js 18 or later.

npm install -g @anthropic-ai/claude-code

Verify the installation:

claude --version

You should see a version number starting with 1.0. If you get a "command not found" error, make sure your npm global bin directory is in your PATH.

Adapt this: If you use a Node version manager like nvm or fnm, make sure you are on Node 18+ before installing. Run node --version to check.

Step 2: API Key Setup (~2 minutes)

Claude Code needs an Anthropic API key. If you do not have one yet, create one at console.anthropic.com.

Set the key as an environment variable:

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

To make this permanent, add the line to your shell profile:

echo 'export ANTHROPIC_API_KEY="sk-ant-your-key-here"' >> ~/.bashrc
source ~/.bashrc

Adapt this: Replace ~/.bashrc with ~/.zshrc if you use zsh, or ~/.config/fish/config.fish for fish shell (using set -gx syntax instead of export).

Step 3: Navigate to Your Project and Launch (~1 minute)

Go to a project you actively work on. Not a toy project — a real codebase you understand well.

cd ~/projects/your-project
claude

Claude Code starts an interactive session in your terminal. You will see a prompt where you can type natural language instructions.

Adapt this: Replace ~/projects/your-project with the actual path to your project. Choose something you know well enough to evaluate the agent's output.

Step 4: The Guided Tour — Orient the Agent (~10 minutes)

Your first command should ask Claude to explore, not to build.

Read this project and summarize the architecture. What are the key directories,
the primary language, and how the code is organized?

Watch what happens. Claude will read files — package.json, README.md, directory listings, key source files. It will produce a summary of what it finds.

Now evaluate that summary against your own knowledge. Is it accurate? Did it miss anything important? Did it identify the right entry points and core modules?

Follow up with a more targeted question:

What are the 3 most important files in this project and why?

Compare its answer to what you would say. Disagreements here are informative — they tell you what context the agent is missing, which will inform your configuration file in the next step.

Adapt this: If your project is very large (100k+ lines), narrow the scope: "Read the src/api directory and summarize how the API layer is organized."

Step 5: Create a Minimal CLAUDE.md (~5 minutes)

Create a CLAUDE.md file in the root of your project. This gives Claude persistent context across sessions. Start small — you will expand it later as you learn what the agent needs.

Create a CLAUDE.md file in the project root with the following content, but adapt
the details to match what you just learned about this project.

Here is a starter template. Write this yourself or ask Claude to draft it after the orient phase:

# CLAUDE.md

This is a [brief description, e.g., "Python REST API for managing inventory"].
Built with [language/framework, e.g., "Python 3.12 and FastAPI"].

## Key commands
- Run tests: [your test command, e.g., `pytest`]
- Start dev server: [your dev command, e.g., `uvicorn main:app --reload`]

## Conventions
- [One critical convention, e.g., "All functions must have type hints and docstrings"]

That is five lines of actual content. It is enough. Do not spend twenty minutes writing an exhaustive document. You will learn what else to add through experience.

Adapt this: Fill in your project's actual language, framework, test command, and one convention you care about most. If you are unsure, ask Claude: "Based on what you read, draft a 5-line CLAUDE.md for this project."

Step 6: Your First Real Task (~15 minutes)

Pick a small, real task. Here are two safe starting points:

Option A — Add a test:

Write a unit test for the [function_name] function in [file_path].
Cover the happy path and one edge case. Follow the testing patterns
already used in this project.

Option B — Fix a small bug:

There's a bug in [file_path]: [brief description of the bug].
Fix it and explain what was wrong.

Watch the agent work. It will read relevant files, reason about the problem, propose changes, and ask for your permission before writing to disk.

When Claude proposes changes, read them before approving. This is not a speed exercise — it is a calibration exercise. You are learning what "good agent output" looks like for your specific codebase.

Adapt this: Replace the bracketed placeholders with a real function, file, or bug from your project. If nothing comes to mind, try: "Find a function in this project that has no tests and write one."

Step 7: Understanding Permissions (~2 minutes)

Claude Code asks for permission before performing actions that modify your system. You will see prompts like:

• File write permission: Claude wants to create or modify a file. You see the proposed changes and can approve or reject.
• Command execution permission: Claude wants to run a shell command (e.g., npm test). You see the command and can approve or reject.

You can also configure permission behavior:

/permissions

This shows your current permission settings. For your first session, keep the defaults — approve everything manually. This forces you to read every change, which is exactly what you want during calibration.

As you gain confidence, you can allow certain operations automatically. But not yet.

Step 8: Useful Built-in Commands (~3 minutes)

Claude Code has several built-in commands you should know about. Type any of these at the prompt:

/help

Shows all available commands and keyboard shortcuts.

/status

Shows the current session state: how many tokens have been used, the current model, and other session metadata.

/cost

Shows token usage and estimated cost for the current session. Check this periodically to build cost awareness.

/compact

Compresses the conversation history to free up context window space. Useful during long sessions when you notice the agent starting to "forget" earlier context.

/clear

Clears the conversation history entirely. Use this when you want to start a fresh task within the same session.

Take a minute to run /help and scan the available commands. You do not need to memorize them now, but knowing they exist will save you time later.

Step 9: Ending and Starting Sessions (~2 minutes)

To end your session:

• Press Ctrl+C to cancel the current operation (if one is running)
• Press Ctrl+D or type /exit to leave the session entirely

Your CLAUDE.md file persists on disk, so the next session will pick it up automatically. Conversation history is also preserved between sessions by default.

To start a new session later:

cd ~/projects/your-project
claude

To start a session with a specific task (non-interactive mode):

claude "Run the test suite and report any failures"

This runs the task and exits automatically when done. Useful for quick checks.

Adapt this: Non-interactive mode is especially useful for tasks you find yourself repeating. Think about what those might be for your project.

Step 10: Reviewing What Changed (~10 minutes)

This is the most important step. Before you close your terminal, review everything the agent changed.

git diff

If Claude created new files that are not yet tracked:

git status
git diff --cached

Read every line of the diff. Ask yourself:

• Is this code correct?
• Does it match the project's style?
• Did Claude change only what I asked it to change, or did it modify other things too?
• Would I approve this in a code review?

If you are satisfied with the changes, commit them:

git add -p
git commit -m "Add test for [function_name] via Claude Code"

Using git add -p lets you stage changes interactively, hunk by hunk. This is a good habit: it forces you to review every change one more time before committing.

If you are not satisfied, you can discard the changes:

git checkout -- .

Or keep what you like and discard what you don't — this is why version control exists.

Adapt this: If you use a different version control system, adjust the commands accordingly. The principle is the same: review every change before accepting it.

Quick Reference

Total estimated cost: $1-5 in API tokens for the full hour.