Claude Code Setup: Build Your First Real Coding Workflow

If you are a developer who has watched Claude Code demos and wondered how to get the same results in your own repo, this guide is for you. A proper Claude Code setup takes about fifteen minutes but pays back in hours of focused work per week. Most first-time users stop at “install and run,” which leaves the best features — project context, permission rules, slash commands, MCP tools — completely untouched.

This tutorial walks through a full Claude Code setup you can apply today. By the end, you will have Claude Code installed, authenticated, aware of your project conventions, and running a real workflow on an existing codebase. Furthermore, you will know when to trust it, when to rein it in, and what most beginners get wrong on day one.

What Is Claude Code?

Claude Code is Anthropic’s official command-line coding agent. It runs in your terminal, reads and edits files in your project, runs shell commands with your approval, and uses Claude as its reasoning engine. Unlike chat-only assistants, Claude Code executes multi-step work directly in your repository — reading tests, running builds, opening pull requests — all within a single session.

The tool ships as a Node.js package and installs globally through npm. Consequently, it works on macOS, Linux, and Windows (through WSL or native Windows). It also integrates with VS Code, JetBrains IDEs, and other editors through extensions, but the CLI is the primary surface area and the one this guide focuses on.

For a broader comparison of agent-style coding tools, see our guide on AI code assistants compared.

Claude Code Setup Prerequisites

Before starting your Claude Code setup, make sure you have the following in place:

• Node.js 18 or later (node --version to check)
• A terminal you are comfortable working in (bash, zsh, PowerShell, or similar)
• An Anthropic account with Claude Pro, Claude Max, or API billing enabled
• A test project — ideally a small repository you know well, not a critical production service on day one

Notably, Claude Code needs write access to the directory where you run it. Therefore, start in a throwaway branch or a side project until you trust the permission model. Running it against main on a production repo is the fastest way to regret inviting an agent into your editor.

Step 1: Install Claude Code

Installation uses npm globally. Open your terminal and run:

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

Next, verify the install:

claude --version
# Expected output: 1.x.y (or newer)

If the command is not found, your npm global bin directory may not be on your PATH. On macOS and Linux, add this to your shell config:

# ~/.zshrc or ~/.bashrc
export PATH="$(npm prefix -g)/bin:$PATH"

On Windows, the Node.js installer usually configures PATH automatically. If it did not, open your user environment variables and add %APPDATA%\npm to PATH, then restart your terminal.

In practice, the most common install failure is a mismatched Node version. Claude Code depends on modern Node features. As a result, installs on Node 16 or earlier will either fail outright or produce unpredictable behavior. Upgrade Node before filing any bug report.

Step 2: Authenticate Claude Code

Authentication runs on first launch. From any directory, run:

claude

You will see a prompt asking how you want to authenticate. There are two main options:

1. Subscription login — opens a browser and signs you in through your Claude account (Pro, Max, or Team)
2. API key — uses a key from the Anthropic Console and bills against your API credits

For personal work, the subscription login is usually the better choice. Furthermore, Claude Pro and Max subscriptions include generous Claude Code usage without per-token billing to track. For team automation, CI pipelines, or shared tooling, generate an API key in the Anthropic Console and paste it when prompted.

Your credentials are stored in ~/.claude/ on macOS and Linux, or %USERPROFILE%\.claude\ on Windows. This directory also holds your settings, memory files, and project histories. Back it up if you customize heavily, but never commit it to any repository — it contains secrets.

Step 3: Run Your First Prompt

With authentication complete, navigate to a real project and launch Claude Code:

cd ~/projects/my-app
claude

You are now in an interactive session. First, try a simple, safe prompt:

Summarize the project structure and tell me what this repo does.

Claude will read your files, form a mental model, and respond. It does not edit anything on read-only prompts, so this is a risk-free way to confirm it can see your code. Next, try an action-oriented prompt:

Find the function that handles user registration and add input validation for the email field.

At this point Claude Code will propose an edit and ask for your approval before writing to disk. This approval step is the core safety mechanism — you see every change before it lands on your filesystem.

In a typical early session, treat Claude like a capable new teammate with strong technical skills but zero context about your conventions. It will sometimes format things oddly or pick libraries you would not. Meanwhile, those are exactly the problems the next steps fix. For more on working alongside an AI assistant, see AI-powered pair programming best practices.

Step 4: Add a CLAUDE.md File

The single biggest upgrade to your Claude Code setup is a CLAUDE.md file at the root of your repository. This file is loaded into every session automatically. Consequently, it lets you teach Claude your stack, conventions, and non-obvious constraints once — rather than repeating them in every prompt.

A minimal CLAUDE.md for a TypeScript Next.js project looks like:

# My App

## Stack
- Next.js 15 (App Router)
- TypeScript strict mode
- Prisma + PostgreSQL
- Tailwind CSS + shadcn/ui

## Conventions
- Server components by default; only add "use client" when needed
- Database access goes through `lib/db/` — never import Prisma in components
- All API routes use zod for input validation
- Tests live alongside source files as `*.test.ts`

## Commands
- `pnpm dev` — start dev server
- `pnpm test` — run Vitest
- `pnpm typecheck` — run tsc --noEmit

## Never do
- Install new dependencies without asking first
- Run `prisma migrate` — that is a manual step
- Edit files in `generated/`

Importantly, keep it under 200 lines. Claude reads the whole file every turn, so long CLAUDE.md files waste context and degrade response quality. Focus on what a new engineer would need to ship their first PR correctly — not an exhaustive style guide.

Furthermore, you can place CLAUDE.md files in subdirectories. A frontend/CLAUDE.md is only loaded when work happens in frontend/, which keeps context scoped to the task at hand. This pattern scales well in monorepos where backend and frontend have wildly different conventions.

Step 5: Configure Permissions and Settings

Claude Code reads settings from ~/.claude/settings.json (user-level) and .claude/settings.json (project-level). The project-level file is the important one — commit it to git so the whole team shares the same permissions.

A sensible starter .claude/settings.json for a Node.js project:

{
  "permissions": {
    "allow": [
      "Bash(pnpm run test:*)",
      "Bash(pnpm run typecheck)",
      "Bash(pnpm run lint)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)",
      "Bash(pnpm publish:*)"
    ]
  }
}

The allow list specifies tool calls Claude can make without prompting you every time. For example, running pnpm test should not require a click, but deleting files should. Meanwhile, the deny list blocks dangerous commands outright — Claude will refuse them even if you try to approve manually.

Start with a tight allowlist and expand it as you notice yourself approving the same command repeatedly. A common mistake is allowing Bash(*) to skip prompts entirely, which defeats the whole point of the permission system. In contrast, a well-scoped allowlist removes most friction without opening risky doors.

You can also set environment variables, default models, and status line customization in settings.json. The official Claude Code documentation lists every supported field. For team use, keep secrets out of the committed file and put them in .claude/settings.local.json, which is gitignored by default.

Step 6: Add a Useful Slash Command

Slash commands are reusable prompts stored as markdown files in .claude/commands/. Instead of retyping “review the diff and suggest three improvements,” save it as a command and invoke it with /review.

Create .claude/commands/review.md:

---
description: Review the current diff and suggest three improvements
---

Look at the current git diff (staged and unstaged changes in this repo).

For each change, answer:
1. Does it do what the commit message implies?
2. Are there edge cases the code misses?
3. Is there a simpler way to express the same idea?

Return a prioritized list of three improvements. Skip nitpicks — focus on things that matter in production.

Next, in a Claude Code session, type /review and watch it run. The command is version-controlled with your repo, so every teammate gets the same review heuristic on every branch.

Slash commands also accept arguments. For instance, /migration add-user-roles could generate a Prisma migration for a named feature. Moreover, commands are the fastest way to turn ad-hoc prompts into durable team workflows — every prompt you find yourself retyping is a candidate for its own command file.

Step 7: Try an MCP Server

Model Context Protocol (MCP) servers let Claude Code call external tools — databases, APIs, issue trackers — as first-class capabilities. To try one without any custom work, add a Postgres MCP server to your setup:

claude mcp add postgres -s project \
  -e DATABASE_URL=$DATABASE_URL \
  -- npx -y @modelcontextprotocol/server-postgres

This registers the server at the project level, so the config ships with your repo. Restart Claude Code and ask:

Show me the five most recent users in the database.

Claude now has a query tool that runs read-only SQL against your database. It will propose the query, show you the plan, and execute on approval. This pattern — plug in a tool, ask natural-language questions — is where Claude Code starts feeling less like a code editor and more like an engineering assistant you can delegate work to.

Other useful MCP servers include GitHub (issues and PRs), Linear (tickets), Slack, and Playwright (browser automation). For a deeper look at how Claude’s tool use model works under the hood, see our getting started with the Claude API guide.

Real-World Scenario: First Week With a Fresh Claude Code Setup

A solo developer starting on an existing Next.js and Postgres project often spends the first two days just getting oriented — scanning files, reading Prisma schemas, tracing request flow. With a ten-minute Claude Code setup (CLAUDE.md plus a scoped allowlist plus a Postgres MCP server), the same onboarding can collapse into a single focused session. The developer asks “walk me through how a signup request flows from the client to the database,” and Claude reads the relevant files and traces the path step by step, answering follow-up questions in real time.

However, early wins hide a trap. Without a tight permission allowlist, developers approve commands reflexively and lose the safety net that makes the approval prompt valuable. Meanwhile, without a CLAUDE.md file, Claude produces code that technically works but does not match repo conventions — which takes longer to review than writing from scratch. The ten minutes spent on setup prevents hours of cleanup later.

When to Use Claude Code

• You work primarily in a terminal and want an agent that operates where you already are
• You need Claude to read and edit actual project files, not just paste snippets into a chat window
• You are willing to write a CLAUDE.md file and maintain a permission allowlist
• You want version-controlled slash commands and hooks shared across the team
• You want MCP tool integrations (databases, issue trackers, browsers) as first-class capabilities
• You prefer long-running, multi-step agent work over line-by-line autocomplete

When NOT to Use Claude Code

• You prefer a GUI-first workflow with inline diffs and autocomplete (Cursor or Windsurf fit better)
• You need strong IDE features like refactoring actions, symbol navigation, and integrated debugging as the primary interface
• You cannot install global npm packages or lack Node 18+ on your machine
• Your repository is subject to strict audit requirements that forbid autonomous file edits
• You only need occasional chat-style help — a browser conversation is lighter weight

Common Mistakes with Claude Code

• Skipping CLAUDE.md. Without project context, Claude defaults to generic patterns. As a result, output quality drops and reviewing its PRs takes longer than writing from scratch. Always start with at least a minimal CLAUDE.md, even if it is only twenty lines.
• Over-broad permission allowlists. Setting Bash(*) to bypass prompts removes the safety net entirely. Consequently, one hallucinated rm command can destroy uncommitted work. Keep the allowlist scoped and grow it deliberately as patterns emerge.
• Running Claude Code on uncommitted work. If Claude’s edits go sideways, you lose your changes along with its. Therefore, always commit or stash before letting the agent loose on meaningful work, and work on a feature branch.
• Treating output as final. Claude produces good drafts but misses project-specific edge cases, especially early in a new project before CLAUDE.md catches up. Review the diff like any other PR — the agent is a fast junior engineer, not a senior one.
• Ignoring subagents. For large refactors, spawning parallel subagents for independent files is much faster than a single linear session. Read the subagents docs after your first few sessions land cleanly, not before.
• Forgetting to share project settings. If .claude/settings.json and .claude/commands/ live only on your machine, your teammates lose the workflow benefits. Commit them to the repo so the whole team gets the same experience.

Conclusion

A good Claude Code setup is not about the install — it is about the context, permissions, and commands that make the agent actually useful in your repo. Install and authenticate in five minutes, then spend another ten on CLAUDE.md, a scoped permission allowlist, and one slash command. That is the setup that turns Claude Code from “fun demo” into a daily driver you reach for without thinking.

Start by writing your CLAUDE.md this week, even if it is fifty lines. Next, tighten your allowlist based on the commands you approve most often. For the next step, read our guide on AI tools for coding productivity to see where Claude Code fits alongside the broader AI toolchain.