How to Set Up Claude Code Properly

Introduction: Claude Code Is a Framework

Most developers install Claude Code, run a prompt, and assume they are done. They are not. Claude Code is not just an AI coding assistant, it is a framework for structured, agent-driven development. Used casually, it acts like a better autocomplete. Configured properly, it becomes a persistent, context-aware partner that works within your codebase, applies your standards, and hands off focused tasks to specialist agents.

1. Installation & First-Time Setup

Prerequisites

Before installing Claude Code, you need:

An active Anthropic account with Claude Pro, Max, Team, or Enterprise subscription (the free plan does not include Claude Code access)
VS Code (Optional). Screenshots in this article use the VS Code integrated terminal, but all commands and Claude Code prompts work identically in a standalone terminal window.

There are a few ways to install Claude Code. Here is what you need to know about each.

Method 1: Native Installer (Recommended)

This is the method Anthropic now recommends. No Node.js required, auto-updates silently in the background, and is the fastest option. For all platforms and install variants, see the official docs at code.claude.com/docs/en/overview.

macOS and Linux

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

Windows (PowerShell)

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

After installing

When installation completes successfully, you will see output like the screenshot below.

Successful Claude Code install via PowerShell on Windows, showing version, install location, and the PATH setup note.

Windows PATH fix

After installation you may see a setup note warning that C:\Users\<you>\.local\bin is not in your PATH. This means Windows does not know where to find the claude command, so typing claude in any terminal will return a not found error.
The fastest fix is to run this command in the same PowerShell window:

[Environment]::SetEnvironmentVariable("PATH", ":PATH;:USERPROFILE\.local\bin", [EnvironmentVariableTarget]::User)

Method 2: VS Code Extension

If you spend most of your day inside VS Code, this is the most frictionless option. The extension brings Claude Code directly into your editor sidebar with no terminal switching required.

Steps

Open VS Code and go to Extensions (Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on Mac).
Search for Claude Code and install the extension published by Anthropic. Check for the verified publisher badge.
Click the Spark icon in your sidebar to open the Claude Code panel.
Sign in with your Anthropic account via OAuth, or paste your API key into the extension settings.

The extension also works in Cursor, Windsurf, and VSCodium.

VS Code opens the Claude Code welcome screen when the extension is first installed.

2. Opening a Project in VS Code

Claude Code is most powerful when run inside an actual project directory. It reads your file structure, can reference your code, and will write the CLAUDE.md and other configuration files into the right places.

Create a new project folder and open it:

mkdir my-projectcd my-projectcode .

Creating and navigating into a new project folder in PowerShell, then opening it in VS Code with code .

If you already have an existing project, simply navigate to it and open it in VS Code instead. The key point is that Claude Code should be running from within your project's root directory.

3. CLAUDE.md - The Agent's Constitution

What Is CLAUDE.md?

CLAUDE.md is the single most important configuration file in your Claude Code setup. Think of it as a standing brief that Claude reads at the start of every session. It tells the agent who you are, how your project is structured, what conventions to follow, and what tools are available.

Without it, Claude starts each session cold, no memory of your stack, no awareness of your coding standards, no understanding of your project's quirks. With a good CLAUDE.md, Claude feels like a senior developer who already knows the codebase.

The Hierarchy

CLAUDE.md files work in layers, from the broadest to the most specific:

~/.claude/CLAUDE.md, your global file, loaded for every project on your machine. Put things here that apply everywhere: your name, your preferred language, global tool preferences.
.claude/CLAUDE.md (project root), the project-level file. This is where most of your configuration lives: tech stack, architecture decisions, file conventions, environment setup.
Any subfolder CLAUDE.md, for monorepos or projects with distinct sections (e.g., /backend, /frontend), you can add CLAUDE.md files inside subdirectories. They add context without overriding the root file.

Generating It with /init

The fastest way to create your first CLAUDE.md is to run the /init command inside your project:

claude /init

On your very first run, Claude Code walks you through a short one-time setup before doing anything else. First, it asks you to pick a terminal theme.

First run of claude /init: theme selection prompt. Choose whichever looks best in your terminal, you can change it later with /theme.

After picking a theme, Claude Code asks you to confirm workspace access, a quick safety check before it reads, edits, or executes anything in your project folder.

Workspace trust prompt: Claude Code confirms you own or trust the project before it is allowed to read, edit, and execute files. Select Yes, I trust this folder to continue.

Once setup is complete, Claude scans your project and runs /init. On an empty project it offers two options, as shown below.

/init on an empty project folder. Claude finds no files to analyse and offers two options: create a minimal starter now, or wait until you have added files for a more tailored result.

Option 1 creates a minimal starter CLAUDE.md immediately, a blank template with placeholder sections you fill in as the project grows. This is the right choice if you are starting from scratch and want something in place from day one.

Option 2 tells Claude to wait. Once you have added your actual code files, run /init again and Claude will analyse the real structure of your project and generate a much more accurate and useful CLAUDE.md. For an existing codebase, always choose this option.

Selecting option 1 on this empty project produces exactly what Claude promises, a minimal starter file written immediately, with placeholder sections ready to fill in.

Claude writes 11 lines to CLAUDE.md instantly, a Commands section and an Architecture section with placeholder text. The final message confirms it: run /init again once files exist and it will fill in the real content.

Here is what the same CLAUDE.md looks like after being edited with real project content, in this case a browser-based Tetris demo used for this article.

The edited CLAUDE.md open in VS Code. The placeholder sections have been replaced with a real Project Overview, a Commands table with actual run commands, and Architecture notes describing the stack and file structure.

What to Put in CLAUDE.md

A well-structured CLAUDE.md typically includes the following sections. Here's a minimal example:

# Project: My App## Stack- Frontend: React 18 + TypeScript- Backend: Node.js + Express- Database: PostgreSQL- Styling: Tailwind CSS## Conventions- Use functional components only, no class components- Use kebab-case for file names- Always write unit tests for new utilities- Use named exports, not default exports## Environment- Run `npm run dev` to start the dev server on port 3000- Run `npm test` to run the test suite- `.env.local` stores local environment variables## Architecture- `/src/components` - Shared UI components- `/src/features` - Feature-specific modules- `/src/utils` - Pure utility functions

Global vs. Project CLAUDE.md

Your global CLAUDE.md (at ~/.claude/CLAUDE.md) is where you store things that apply to every project: your preferred response style, your name, global coding conventions, and any reminders you always want Claude to follow. Your project CLAUDE.md is where everything specific to that codebase lives.

On Windows, navigate to the .claude folder in your user directory and open or create CLAUDE.md:

cd .claudecode CLAUDE.md

Navigating to the ~/.claude directory in PowerShell and opening the global CLAUDE.md directly in VS Code.

Here is what a well-structured global CLAUDE.md looks like, coding rules and conventions that should apply to every project you work on:

A global CLAUDE.md with General Coding Rules, File & Project Conventions, and a What to Avoid section. These apply to every project on this machine without repeating them in each repo.

Not sure what to put in your global file? The fastest approach is to ask Claude.ai to generate one for you. It will ask a few questions about your stack, coding style, and communication preferences, then produce a tailored file you can paste straight in.

Asking Claude.ai to generate a global CLAUDE.md. It asks about your focus area, code style, and communication preferences, then produces a ready-to-use file on the right.

Putting CLAUDE.md to Work

With the project CLAUDE.md in place, open Claude Code in your project terminal and tell it to build:

Typing "Build this project based on the CLAUDE.md file" into Claude Code. Claude reads the spec and immediately starts generating files.

Claude reads the entire CLAUDE.md, project overview, architecture, conventions, and scaffolds the project. A minute later, the files are there:

Claude Code has generated game.js, index.html, and style.css, a complete project scaffolded from the CLAUDE.md spec in under two minutes.

Open index.html in a browser and the game runs immediately, score, level, piece preview, controls, and all:

The finished Tetris game running in the browser, built entirely from the CLAUDE.md spec with a single prompt.

4. Commands - Reusable Workflows

What Are Commands?

Commands are slash commands you can invoke inside Claude Code to trigger a pre-written set of instructions. They work like keyboard shortcuts for complex tasks: instead of typing a long prompt every time you want to, say, run a code review or generate a changelog, you type /review or /changelog and Claude knows exactly what to do.
Every command is simply a markdown file stored in .claude/commands/ inside your project. The filename becomes the command name.

Creating Your First Command

Commands live at .claude/commands/<command-name>.md. On Windows, create the folder and open the file like this:

mkdir commandscd .\commands\code review.md

Creating the commands folder inside ~/.claude and opening review.md in VS Code.

Open review.md and write the instructions you want Claude to follow when you type /review:

The review.md command file open in VS Code. This prompt runs every time you type /review in Claude Code.

To run it, open Claude Code in your project and type /review:

Typing /review into Claude Code. Claude reads the review.md file and runs the full prompt against the current project.

Claude returns a structured report, a plain-English summary followed by issues ranked by severity:

The /review output: a Summary, then Critical issues with file and line references, Warnings, and Suggestions. One prompt, zero configuration at runtime.

Using Arguments in Commands

Commands support positional arguments using $1, $2, etc. This lets you make commands more flexible:

# .claude/commands/fix.md  Fix the following issue in the codebase: $1     Provide a clear explanation of the root cause and apply the fix directly.

Then call it like: /fix "button doesn't work on mobile"

Global vs. Project Commands

Just like CLAUDE.md, commands can live at two levels:

~/.claude/commands/ - global commands, available in every project
.claude/commands/ - project-specific commands, only available in that project

5. Skills - Automatic Context Injection

Skills vs. Commands

While commands are explicitly triggered by you, skills are triggered automatically by Claude based on context. When you ask Claude to do something that matches a skill's description, Claude reads the skill's instructions and uses them without you having to think about it.
Skills are folders, each containing a SKILL.md file (with a description and instructions) plus any supporting files, templates, scripts, reference docs.

Anatomy of a Skill

A skill lives at ~/.claude/skills/<skill-name>/SKILL.md (or in your project at .claude/skills/). The SKILL.md file has two parts: a frontmatter block that describes when to trigger the skill, and a body that contains the instructions.

To create your first global skill, navigate to ~/.claude, create the skills folder, create a subfolder for the skill, and open SKILL.md:

Creating the skills folder, then the react-component subfolder inside ~/.claude/skills/, and opening SKILL.md in VS Code.

The SKILL.md file has two parts: a frontmatter block (name and description) that tells Claude when to apply it, and a body with the actual instructions. Here is the react-component skill:

The SKILL.md file for the react-component skill. The frontmatter description tells Claude when to activate it; the body contains the standards Claude follows every time it creates or modifies a React component.

Making Skills Trigger Reliably

Skills activate when their description matches the task. The description in the frontmatter is the key, write it the way a developer would describe the task, and include synonyms and trigger phrases.

One practical tip: list your available skills in your CLAUDE.md with a note like "When working with React components, check the react-component skill in .claude/skills/." This acts as a reliable fallback trigger.

Sharing Skills Across Projects

Skills placed in ~/.claude/skills/ are available in every project. This is ideal for general-purpose skills like writing commit messages, generating changelogs, or following a code review process that applies everywhere.

6. Subagents - Isolated Workers for Complex Tasks

The Problem Subagents Solve

Every Claude Code session has a context window, a limit on how much information can be held at once. Long research tasks, large file reads, and multi-step planning all eat into that context. If you're mid-way through a coding task and Claude has to research a complex topic, that research can crowd out the context you need for your actual work.
Subagents solve this by creating isolated Claude instances. A subagent works in its own context, completes a task, and returns only the result, keeping your main session's context clean and focused.

Creating a Subagent

Subagents are defined as markdown files in ~/.claude/agents/<agent-name>.md. Navigate to ~/.claude, create the agents folder, and open your first agent file:

Creating the agents folder inside ~/.claude and opening planner.md in VS Code.

Like skills, agent files have a frontmatter block (name, description, model, and an optional color label) followed by the agent's system prompt. Here is the planner agent:

The planner.md agent file. The frontmatter sets the model (claude-opus-4-5) and a blue color label; the body defines what the agent does and how it formats its output.

To invoke it, tell Claude Code to use the planner agent with a specific task:

Invoking the planner agent: "use the planner agent to plan: add a high score leaderboard to the Tetris game". Claude Code spins up the agent in its own isolated context.

The planner agent returns a structured implementation plan, numbered steps, key risks, and a summary, without writing a single line of code:

The planner agent output: 8 ordered implementation steps, key risks (localStorage failures, XSS via name input, z-index conflicts), and a prompt asking whether to proceed. Planning only, no code written.

When to Use Subagents

Subagents are most valuable when:

You need research or planning that would consume a lot of context
You have a clearly defined, bounded task that produces a single output
You want a specialist agent that only does one thing (e.g., only writes tests, only reviews security, only writes documentation)
You're working on a long session and want to protect your main context

The Built-in Task() Alternative

Claude Code also has a built-in ability to spawn task instances dynamically, without you pre-defining an agent file. This is useful for ad-hoc parallelism. The difference: a defined subagent has a specific persona and instructions baked in, while Task() clones are more general-purpose. For recurring specialist tasks, defined subagents win. For one-off parallel work, Task() is more flexible.

7. How Everything Works Together

A Complete Workflow Example

Here is how all four layers work together in a real scenario, the leaderboard feature built in this guide.

CLAUDE.md provided the standing context: vanilla HTML/CSS/JS, no frameworks, kebab-case filenames, no placeholder content.
The planner subagent received the task in isolation, produced a structured plan, and returned it without consuming the main session context.
Responding "yes" handed control back to the main session, which implemented the full feature using the plan as a blueprint.
The /review command could then be run immediately to check the new code against the same standards as the rest of the project.

Here is the moment the plan was approved and implementation began:

Replying "yes" to the planner agent. Claude Code immediately starts reading the existing files and implementing the feature from the plan.
Claude implemented all eight steps from the plan, localStorage helpers, leaderboard panel, name-entry modal, and styles, in under five minutes:

The generated index.html showing the name-entry modal and leaderboard panel added exactly as planned. Claude followed the existing code structure and matched the project conventions throughout.
Open the browser and the High Scores panel is live, no configuration, no explanation, no repeated instructions:

The Tetris game with the High Scores panel added to the right sidebar. The feature was planned by a subagent and implemented by the main session, neither required any manual setup instructions.
That is the compounding value of proper setup. Every layer contributed something Claude already knew, it did not have to be told twice.

8. File Structure Quick Reference

Here's how a fully set-up project looks on disk:

Global scope: ~/.claude/~/.claude/├── CLAUDE.md                   # global constitution├── commands/│   └── review.md               # global command└── skills/    └── commit-message/        └── SKILL.md            # global skillProject scope: my-project/my-project/├── CLAUDE.md                   # project constitution└── .claude/    ├── commands/    │   ├── review.md           # project command    │   ├── fix.md    │   └── test.md    ├── skills/    │   ├── react-component/    │   │   └── SKILL.md    │   └── api-endpoint/    │       └── SKILL.md    └── agents/        ├── planner.md          # subagent        └── security-reviewer.md

9. Tips, Pitfalls & Best Practices

Keep CLAUDE.md Lean

It's tempting to put everything you can think of in CLAUDE.md. Resist this. A bloated CLAUDE.md is hard to maintain and Claude has to process all of it every session. Keep it to the essential context, and use reference files for detailed docs ("See /docs/api-design.md for the full API conventions").

Mine Old Sessions for Improvements

After a long Claude Code session, use claude --resume to revisit it. Look for moments where you had to re-explain something or correct Claude. Those are exactly the things that should go in your CLAUDE.md or skills.

Write Command Descriptions Like Docs, Not Code

Commands are plain English instructions. Write them the way you'd write a spec for a junior developer: clear, specific, with examples of the expected output format. The more concrete your command instructions, the more consistent the output.

Distribute Setups as Plugins

If you work in a team, you can bundle your .claude/ folder (commands, skills, agents) and commit it to your repo. Every developer who clones the project gets the full setup automatically. For larger teams, consider creating a shared global skills folder that everyone installs.

Common Pitfalls

Forgetting to run /init: Claude won't have a CLAUDE.md to reference and will start cold every session.
Putting project-specific things in the global CLAUDE.md: keep them separate or they'll interfere across projects.
Writing skills with vague descriptions: Claude may not trigger them. Be specific about when the skill should activate.
Making subagent files too long: concise, focused instructions work better than comprehensive briefs.
Not committing .claude/ to git: your team won't benefit from the setup you've built.

Model Context Protocol