First Hour with Claude Code: From Install to Your First Useful Output

What You'll Build in 60 Minutes

By the end of this tutorial, you will have:

1. Claude Code installed and authenticated on your machine.
2. A CLAUDE.md file that makes Claude Code understand your project's architecture and conventions.
3. Three completed tasks on your actual codebase — not a toy project, your real code.

This is not a feature tour. You will open your terminal, install the tool, and do real work. Every section has a time estimate so you can track your pace.

Prerequisites:

• macOS, Windows, or Linux
• A Claude Pro subscription ($20/month) or an Anthropic API key
• A real project with at least a few source files (any language)
• A terminal you are comfortable with

No prior AI coding tool experience required.

Minute 0-5: Install Claude Code

Claude Code installs via a native installer. No Node.js dependency, no npm. One command.

macOS and Linux:

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

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

Homebrew (macOS alternative):

brew install --cask claude-code

After installation, run:

claude

On first launch, Claude Code opens your browser for authentication. Log in with your Claude.ai account (the same account as your Pro subscription). If the browser does not open automatically, press c to copy the login URL to your clipboard and paste it into your browser manually.

Once authenticated, you see the Claude Code prompt in your terminal. Your credentials are stored in ~/.claude/ — you will not need to log in again unless you explicitly log out.

What you should see: A clean prompt with Claude Code's version number and a cursor waiting for input. If you see an error about authentication, verify your Pro subscription is active at claude.ai/settings.

Time check: You should be done in under 5 minutes. If authentication took longer because of browser issues, do not worry — this is a one-time cost.

Minute 5-10: Your First Prompt

Navigate to a real project directory. Not a fresh one — pick something you have been working on. A project with at least 5-10 files gives Claude Code enough to demonstrate its value.

cd ~/projects/your-actual-project
claude

Type your first prompt:

Explain the architecture of this project. What are the main modules,
how do they connect, and what patterns does the codebase follow?

Claude Code reads your project files — it scans the directory structure, opens key files (package.json, config files, entry points), and builds a mental map of your codebase. This takes a few seconds.

What good output looks like: A structured summary that identifies the framework, the directory layout, the data flow between modules, and any patterns it detects (MVC, repository pattern, feature-based folders). It should mention specific file paths from your project.

What bad output looks like: Vague generalities that could apply to any project. If Claude Code says "this appears to be a web application" without identifying your specific framework, router, or state management — the codebase is too small or Claude Code did not read enough files. Try a more specific prompt: "Read the main entry point and trace the request flow from the API endpoint to the database."

This first prompt is read-only. Claude Code reads files but does not modify anything. No risk.

Time check: 5 minutes in, you have a working Claude Code installation and your first useful output — an architecture overview you can share with teammates or use for documentation.

Minute 10-20: Create a CLAUDE.md File

The architecture explanation you just got was decent. Now you will make it dramatically better by giving Claude Code persistent context about your project.

Why CLAUDE.md Matters

Every time Claude Code starts a session in your project, it reads CLAUDE.md from the project root. This file tells Claude Code things it cannot infer from code alone: your team's conventions, your preferred patterns, constraints that are not encoded in linters, and the "why" behind architectural decisions.

Think of it as onboarding documentation — but for an AI agent, not a new hire.

Research from ETH Zurich found that overly detailed context files actually degrade agent performance. The sweet spot is 200-500 words of high-signal information. Each line should pass this test: "Would removing this cause Claude Code to make a mistake?"

A Working Template

Create a file called CLAUDE.md in your project root:

## Project Overview
[One paragraph: what this project does, who it serves, what problem it solves]

## Architecture
- Framework: [e.g., Next.js 15 App Router]
- Database: [e.g., PostgreSQL via Prisma]
- Auth: [e.g., NextAuth.js v5]
- Styling: [e.g., Tailwind CSS]
- Testing: [e.g., Vitest for unit, Playwright for e2e]

## Code Conventions
- [e.g., TypeScript strict mode everywhere]
- [e.g., Prefer server components; 'use client' only when necessary]
- [e.g., Error handling uses Result types, not try/catch]
- [e.g., No default exports except for pages/layouts]

## Directory Structure
- src/app/ — routes and pages
- src/components/ — shared UI components
- src/lib/ — business logic and utilities
- src/db/ — database schema and migrations

## Hard Constraints
- [e.g., Never modify migration files directly]
- [e.g., All API routes must validate input with Zod]
- [e.g., No external HTTP calls in server components]

Fill this in with your project's actual details. Spend 5 minutes on it — do not overthink. You can refine it over time.

Key principles:

• Keep it under 100 lines. Claude Code's own system prompt uses about 50 of its ~200 instruction slots. Your CLAUDE.md should be lean.
• Prefer pointers over copies. Instead of pasting code snippets, write See src/lib/errors.ts for the error handling pattern. Snippets in CLAUDE.md go stale; file references stay accurate.
• Do not duplicate linter rules. If ESLint already enforces something, do not restate it in CLAUDE.md. Claude Code runs your linters as hooks — let deterministic tools handle deterministic rules.

See the Difference

Now run the same architecture prompt again:

Explain the architecture of this project. What are the main modules,
how do they connect, and what patterns does the codebase follow?

The difference is immediate. With CLAUDE.md, Claude Code uses your terminology, references your specific conventions, and structures its answer around the architecture you described. It stops guessing and starts speaking your project's language.

Time check: 20 minutes in. You have Claude Code installed, authenticated, and configured with project context. Everything from here is actual productivity.

Minute 20-35: Your First Real Task

Time to make Claude Code do real work. Pick a concrete, well-scoped task from your actual backlog. If you do not have one handy, use this universal example:

Add input validation to the signup API endpoint.
Validate email format, password minimum 8 characters,
and username between 3-30 alphanumeric characters.
Use Zod for the schema. Return specific error messages
for each validation failure.

The Interaction Flow

Step 1: Claude Code reads. After you submit the prompt, Claude Code identifies the relevant files — the signup route, existing validation patterns, your schema definitions. It reads these files automatically. You see each file access logged in your terminal.

Step 2: Claude Code plans. Before writing any code, Claude Code shows you what it intends to do: "I'll create a Zod schema in src/lib/validations/auth.ts, import it in the signup route at src/app/api/auth/signup/route.ts, and add error formatting that returns field-specific messages."

Step 3: You review and approve. Claude Code shows the proposed changes as diffs. This is the permission model at work:

• File reads happen automatically — no approval needed.
• File writes require your explicit approval. Claude Code shows you exactly what it wants to write before writing it.
• Shell commands (like npm install zod) also require approval.

Review the diff carefully on your first few tasks. Over time, you will develop a feel for when to approve immediately and when to push back.

Step 4: Claude Code executes. After your approval, Claude Code writes the files. It often runs follow-up actions — creating the file, adding imports, and sometimes running your test suite to verify the change works.

Step 5: Verify. Ask Claude Code to verify its own work:

Run the tests related to the signup endpoint.
If there are no tests, write them first.

This is a critical habit. Never accept a code change without verification. Claude Code can run your test suite, check for TypeScript errors, and confirm the implementation is correct — but only if you ask.

What to Watch For

• Does Claude Code respect your CLAUDE.md conventions? If you specified Zod for validation and it uses a different library, your CLAUDE.md needs a stronger constraint.
• Are the changes minimal? A good change touches only the files that need touching. If Claude Code modified 8 files for a simple validation task, something went wrong.
• Can you understand the code? If the generated code is clever but unreadable, tell Claude Code: "Simplify this. I should be able to read each function in 10 seconds."

Time check: 35 minutes in. You have completed a real task with code review and verification. This is the core Claude Code workflow — everything else builds on this loop.

Minute 35-50: Multi-File Task

Single-file changes are nice, but Claude Code's real advantage over simple autocomplete is multi-file reasoning. It can trace dependencies, update imports, and maintain consistency across a codebase. Let's use that.

Pick a task that spans multiple files. If you do not have one:

Refactor the error handling in this project to use a centralized
error class. Create a base AppError class with status code, error code,
and user-friendly message. Replace all ad-hoc error throws with
specific subclasses (ValidationError, NotFoundError, AuthError).
Update the error handling middleware to use the new classes.

What Happens Differently

This task is where Claude Code separates itself from simpler tools. Watch the process:

1. Broad file scanning. Claude Code reads not just the error handling code but the entire middleware chain, the route handlers that throw errors, and the tests that assert on error behavior. It needs to understand the full error surface before proposing changes.

2. Cross-file planning. Claude Code proposes a multi-step plan: create the error class hierarchy, update each route handler, modify the error middleware, and update tests. The plan shows file-by-file what changes.

3. Ordered execution. Claude Code creates the base class first, then updates consumers. The order matters — if it updated route handlers before creating the error class, the code would break between steps.

4. Import management. Every file that references the new error classes gets its imports updated. This is tedious work that Claude Code handles automatically.

5. Test updates. If your tests assert on specific error messages or status codes, Claude Code updates them to match the new error class structure.

Review the full changeset before approving. This is a larger change — take 2-3 minutes to read through the diffs. Check that the error class hierarchy makes sense, that no error cases were missed, and that the middleware correctly catches the new error types.

Show me a summary of all files changed and what changed in each one.

After approval and execution, verify:

Run the full test suite. Show me any failures.

Time check: 50 minutes in. You have completed a non-trivial refactoring task that touched multiple files — the kind of task that typically takes 30-60 minutes of manual work.

Minute 50-60: Set Up Your Workflow

You have proven Claude Code works on your codebase. Now set it up for daily use.

Configure Permissions

Claude Code's permission system lives in .claude/settings.json in your project root. This controls which operations run automatically and which require approval.

A practical starting configuration:

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run lint *)",
      "Bash(npx tsc --noEmit)"
    ]
  }
}

This allows test and lint commands to run without approval, while file writes and other shell commands still require confirmation. Start conservative — you can expand the allowlist as you build trust.

Learn the Key Commands

Inside a Claude Code session, these commands are essential:

• /help — Shows all available commands
• /compact — Compresses conversation context when sessions get long
• /clear — Resets the session, useful when context becomes cluttered
• /effort — Controls reasoning depth (higher effort for complex tasks, lower for simple ones)

Understand Subagents

For large tasks, Claude Code can spawn subagents — isolated child sessions that handle a specific subtask without polluting your main conversation context. You do not need to configure this manually; Claude Code uses subagents automatically when a task benefits from parallel or isolated work.

You can also use subagents explicitly by telling Claude Code to delegate:

Use a subagent to research all the places in this codebase
where we handle authentication tokens. Report back with
file paths and a summary.

The subagent gets its own context window, does its work, and reports back to the main session. Your main session stays clean.

Set Up Your Terminal for Multi-Task Work

Running Claude Code alongside your regular development workflow — tests in one pane, Claude Code in another, your editor in a third — is the natural daily setup. You will want a terminal environment that handles multiple panes without friction.

A proper multi-pane setup lets you watch Claude Code work in one terminal while running tests or checking git status in another. Drag files directly into the Claude Code terminal. Keep a dedicated pane for verification commands. This side-by-side workflow is where the productivity multiplier actually shows up.

Install Useful Skills

Claude Code supports skills — reusable instruction sets that you or the community create. Skills can define workflows, enforce patterns, or add specialized knowledge. Check out the growing ecosystem of community skills for common tasks like PR review, test generation, and documentation writing.

What's Next

You have spent 60 minutes and you now have a working Claude Code setup with project context, experience on real tasks, and a configured workflow. Here is where to go from here:

Go deeper on the tool landscape. The 2026 AI CLI Tools Complete Guide covers every major AI CLI tool — Claude Code, Gemini CLI, Copilot CLI, Codex CLI, and six others — with full pricing, capability comparisons, and multi-agent workflow patterns.

Optimize your costs. Claude Code's Pro plan at $20/month is the entry point, but you can stretch it further. The dual-tool strategy shows how to pair Claude Code with Gemini CLI's free tier — use Gemini CLI for exploration and simple tasks, save Claude Code capacity for the complex work that actually needs it. Many developers cut their effective costs by 60-70% this way.

Build your CLAUDE.md over time. The template you created today is a starting point. After a week of daily use, you will know which instructions Claude Code follows reliably and which it ignores. Refine your CLAUDE.md based on the mistakes Claude Code actually makes, not the mistakes you imagine it might make.

Set up hooks for enforcement. CLAUDE.md instructions get followed about 70% of the time. For rules that must be enforced 100% — like running the linter before every commit, or blocking writes to certain directories — use hooks. Hooks are shell scripts that fire at specific points in Claude Code's workflow and enforce rules deterministically.