Claude Code Guide — Part 1: Install Claude Code and write your first CLAUDE.md

Why a configured workspace at all

You can use Claude Code as a chat tab in a terminal. Type claude, ask a question, read the answer, close the window. That works. It also wastes the thing that makes Claude Code different from the chat surfaces you already have — the on-disk-ness. Every other AI assistant configuration lives behind a UI somebody else owns. Claude Code's configuration lives in your repo, in plain files, under your version control, edited with your editor. The shape it loads on every turn is the shape you authored.

This series teaches the on-disk core across seven parts. A CLAUDE.md Claude Code reads at session start. A .claude/settings.json that holds your permission decisions. A .claude/skills/ directory of reusable procedures. A .claude/agents/ directory of forked-context workers. Hooks that fire deterministically on lifecycle events. The built-in tools the model already has on hand. And a four-phase method for tying all of it together. Seven parts, seven primitives, one hand-off-able workspace.

Part 1 lands the keystone. By the end of this article the CLI is installed, you have run a first session in a real project, and there is a CLAUDE.md at the project root with five named anchors that later parts hook into by exact name. Nothing fancy, nothing speculative — the file is short, it is yours, and it is real.

Install Claude Code

Installation is a moving target — installer URLs, package manager names, supported platforms all evolve. There is exactly one source of truth for which install path applies to your machine, and it is the official setup page. Read it once before you type anything.

The high-level shape, so you know what you are signing up for. Claude Code ships as a self-contained claude binary the installer drops on your PATH. There is a native installer that auto-updates itself in place, and there are package-manager paths (Homebrew, winget) that put the upgrade cadence in your hands. The native installer is the lower-friction choice for most readers; the package manager route is the right call if your team already standardises on one for tool installs. Either way, the file that lands is the same claude binary, and the rest of this series treats them as interchangeable.

When the install finishes, open a fresh shell and run claude --version. If it prints a version string, you are done with installation. Everything else lives in files you author.

Your first session

cd into a real project. Not ~, not /, not a tmp directory you will delete tomorrow. Pick a repo you actually work in — the project where you want Claude Code's context to live. The reason matters and we will get to it.

cd ~/code/your-project
claude

The first time you run claude it walks you through login. You can sign in with a Pro, Max, Team, or Enterprise account; with a Console API key; or with credentials for Bedrock, Vertex, or Azure Foundry if you route through a cloud provider. Pick whichever you have. The series does not depend on the choice — every primitive on disk works the same regardless of how you authenticate.

After login you land at the welcome screen — a prompt waiting for input, a hint about /help, and a status line showing the model and the working directory. Claude Code ships a small inventory of built-in slash commands (help, clear, init, memory, compact, model, permissions, login, status, resume, and a few more) plus a few bundled skills (/simplify, /loop, /claude-api, /schedule). You will reach for /help, /clear, and /status regularly; the others come up as the workspace fills in. Rather than enumerate them all here — the inventory shifts release to release — type /help once now, read the list that prints, and use the official reference when you want details: docs.claude.com/en/docs/claude-code/slash-commands.

Day-one invocations beyond the bare claude:

• claude "task description" — start a session with a first user message already queued.
• claude -p "task description" — print mode, no interactive REPL; useful for one-shot work or scripting.
• claude -c — continue your most recent session in this directory.
• /clear — reset the conversation in the current session without exiting.
• exit — leave the session.

That last point is the load-bearing one. The cwd you launch from decides what configuration loads. Claude Code looks for CLAUDE.md in the current directory, then walks up parent directories adding any CLAUDE.md it finds along the way. Same walk for .claude/. Launch from your project root and you get the project's instructions; launch from a subdirectory and you get the project's instructions plus anything the subdirectory adds; launch from ~ and you get whatever happens to live in your home tree.

Exit with exit or Ctrl-D. The session record is preserved — claude -c resumes it, /resume from inside any session lets you pick from a list.

What CLAUDE.md is

CLAUDE.md is a markdown file Claude Code reads at the start of every session and prepends to the model's context. It is not magic — it is just text. What makes it powerful is the loading rule. Every turn that runs from a directory containing CLAUDE.md, or any subdirectory of one, starts with that file in context. The lines you write ride along on every prompt without you retyping them.

That has two consequences. First, every line in CLAUDE.md costs every turn — both in tokens and in attention. Keep the file lean. The docs recommend a soft cap around 200 lines before adherence drops. Second, every line you write applies project-wide. A line that says "use pnpm, not npm" is binding for every session in the repo, every contributor running claude from the project root, every subagent that spawns under it.

The file is yours. It lives in your repo. You commit it, review it in pull requests, edit it with your editor, version it the same way you version code. There is no Claude Code UI for managing it — you open it, you change it, you save.

Author your first CLAUDE.md

The file uses five H2 anchors that the rest of this series hooks into by exact name. The anchors are load-bearing — Parts 2 through 5 will refer to them verbatim and fill in the pointer sections. Use these headers, in this order:

1. ## Goals & outcomes — what this project is, the kinds of work you do here, who reads or inherits the code, and what "good" looks like for a turn.
2. ## Stack & commands — the languages, frameworks, package manager, and the day-to-day invocations Claude Code should reach for (test, build, lint, run).
3. ## Working style & defaults — gotchas, drift Claude Code tends toward by default, conventions that differ from defaults.
4. ## Permissions (pointer) — a stub in Part 1; Part 2 fills this with a one-line pointer to .claude/settings.json.
5. ## Skills, subagents, hooks (pointers) — a stub in Part 1; Parts 3, 4, and 5 fill these in.

Two ways to author it. Claude Code ships an interactive /init command that walks you through a generic onboarding and writes a starter file. It is fine — but generic. The companion prompt in this article's sidebar is the alternative: a guided interview that scans your project for existing .claude/ assets first, asks you the right questions to fill the five anchors, and saves the file on your approval. Either route lands you at a working CLAUDE.md. The sidebar prompt is the one this series was designed around because it produces the exact anchor names later parts rely on.

Here is the shape the file lands in:

# CLAUDE.md

This file tells Claude Code who I am, what this project is, and how to behave on every turn.

## Goals & outcomes

This is a Next.js 16 / TypeScript / pnpm site that renders Obsidian-style markdown into a published blog and KB. The kinds of work I do here are: writing new articles in markdown, light component changes in `/website/components/`, and occasional build-script edits. The audience for the published output is technical readers; the audience for the code is me and one collaborator.

A turn went well when: the diff is small, no new dependencies were added, and `pnpm build` still passes. The repo's voice is declarative and warm — match it when generating prose.

## Stack & commands

- Languages: TypeScript, MDX-flavored markdown.
- Framework: Next.js 16 (App Router), Material UI 7.
- Package manager: pnpm. Never use npm or yarn here.
- Common commands:
  - `pnpm dev` — dev server on port 7091.
  - `pnpm build` — full production build (also syncs images).
  - `pnpm lint` — Next.js linter.
  - `pnpm sync-images` — copies images from content dirs to `public/attachments/`.

## Working style & defaults

- Prefer editing existing files over creating new ones.
- Do not introduce new dependencies without naming the tradeoff first.
- Markdown content lives at the repo root, not under `/website/`. Build reads `../` relative to the website folder.
- When in doubt about voice, read an existing article in the same series before drafting.

## Permissions (pointer)

Part 2 fills this with a pointer to `.claude/settings.json`.

## Skills, subagents, hooks (pointers)

Parts 3, 4, and 5 fill these in.

That is roughly thirty lines. Yours might be shorter or a touch longer. The discipline is the same: every line earns its place by passing the test "would removing this line cause Claude Code to make a mistake?" If the answer is no, leave it out. The file rides along on every turn — every line you keep costs every turn.

Save the file as CLAUDE.md at the project root. That is it. The next session you start from this directory will load it.

Run a sample turn and verify the file works

Authoring a file you cannot see working is unsatisfying. Run a sample turn now to confirm the lines you wrote are actually shaping behavior.

# 1. From the project root:
claude

# 2. Ask for a small task that draws on something in your CLAUDE.md.
#    Example, against the file above:
#
#      "Sketch a one-line shell command to run the test suite for this repo."
#
#    The model should reach for `pnpm`, not `npm`, because § Stack & commands
#    names pnpm explicitly. If it suggests npm, the line was not loaded —
#    check that you are running `claude` from the directory containing
#    CLAUDE.md, and that the file is named exactly `CLAUDE.md` (not
#    `Claude.md` or `claude.md`).

# 3. Ask for something the file doesn't cover and see the model say so.
#    Example:
#
#      "What's the deployment target for this project?"
#
#    A well-shaped response will note that CLAUDE.md doesn't say, rather
#    than inventing an answer. If the model invents one, that's a signal
#    to add the deployment target line under § Goals & outcomes.

# 4. Exit with `exit` or Ctrl-D. Edit CLAUDE.md to close any gaps the
#    sample surfaced. Save. Move on.

The verification is small on purpose. You are not testing whether Claude Code is smart — you are testing whether the file you wrote is being loaded. Two signals: the model honors a specific line you can point at, and the model says "this is not in CLAUDE.md" when you ask for something the file does not cover. Both signals together mean the file is in context and shaping behavior.

If something feels off, the first three things to check are: are you launching claude from the right directory, is the filename exactly CLAUDE.md, and is the file under the 200-line soft cap. Adherence drops on long files faster than most people expect.

Where everything lives

You have one file in one place. Here is the rest of the inventory so you know what is around it and what later parts will fill in.

Project-root scope.

• ./CLAUDE.md — the file you just authored. Loaded on every session run from this directory or any subdirectory.
• ./.claude/CLAUDE.md — alternate location for the same file. Some projects prefer keeping all Claude Code configuration under .claude/. Either path works; pick one. Most readers keep the file at the project root because it shows up next to README.md in ls.
• ./.claude/settings.json — Part 2 reads what Claude Code builds here. Permissions, model overrides, environment variables, and hook definitions all live in this file. Most of it is built incrementally as you click through permission prompts; the hooks stanza is the one section you hand-author (Part 5).
• ./.claude/skills/<name>/SKILL.md — Part 3 authors these. Reusable procedures Claude Code can apply inline or invoke as /<name>.
• ./.claude/agents/<name>.md — Part 4 authors these. Forked-context workers you delegate bounded tasks to via the Task tool.
• ./.claude/rules/*.md — Part 3 mentions these as part of the disposition framework for where content belongs. Modular rule files with paths: glob frontmatter that scope them to specific files.
• ./CLAUDE.local.md — gitignored personal variant. If you want lines that apply to your sessions but should not ship to teammates, this is where they go. Loaded after CLAUDE.md so its lines take precedence on conflict.

User scope.

• ~/.claude/CLAUDE.md — your personal instructions, loaded for every project on your machine. Useful for things that are about you, not the project ("I prefer concise commit messages", "always include type hints in Python"). Keep it short — it loads everywhere.
• ~/.claude/settings.json — user-scope settings. Same shape as the project file, applied across all projects.
• ~/.claude/skills/<name>/SKILL.md — user-scope skills. Available in every project.

Managed-policy paths. If you are running Claude Code under an organization's deployment, there are managed-policy locations (/Library/Application Support/ClaudeCode/ on macOS, C:\ProgramData\ClaudeCode\ on Windows, /etc/claude-code/ on Linux) that take precedence over user and project scope. Most readers will not encounter these; if you do, they exist and they win. Out of scope for this series.

Auto-memory. Claude Code maintains its own notepad at ~/.claude/projects/<repo-hash>/memory/MEMORY.md. It is Claude-written, not user-authored — the model jots down things it has learned about you across sessions. You can read it; you do not edit it. Mentioning it here so the file does not surprise you when you find it.

@path imports. Inside any CLAUDE.md you can include another file with @path/to/file.md. The import resolves relative to the file doing the importing, supports up to five hops of nesting, and lets you split a long brief into composable pieces. The example above does not use imports — the five anchors are short enough to live in one file. If your project already has an AGENTS.md (some repos use this for tool-agnostic agent instructions), @AGENTS.md on its own line at the top of CLAUDE.md lets both Claude Code and other tools read the same content.

Cross-surface portability. The on-disk-ness travels. The same CLAUDE.md, the same .claude/settings.json, the same skills and subagents work when Claude Code runs in your IDE plugin, in the desktop app, in the web product, in Slack, in GitHub Actions, in GitLab CI. You author once, on disk; every surface that loads your repo loads your configuration. This series teaches the CLI flavor — the files are identical wherever you run them.

What just changed

You started this part with a binary you may have run once and a vague sense that CLAUDE.md was a thing other people had. You finish with:

• The Claude Code CLI installed, with a verified claude --version.
• A first session run from a real project directory, with the welcome screen, /help, and the day-one slash commands familiar.
• A CLAUDE.md at the project root, structured around five named anchors the rest of this series hooks into by exact name.
• A sample turn that confirmed the file is loading and shaping behavior, with any gaps it surfaced now closed.
• An understanding of where every other on-disk surface lives, even though only one of them is populated yet.

If you want the same shape on the web product (Cowork) — a configured workspace shared with a team via the Instructions field rather than a file on disk — see cowork-guide Part 1. The two series are siblings. Neither is a prerequisite; they teach the same primitives on different surfaces.

What is next

Part 2 reads what Claude Code builds for you. Every "Always allow" click you make in a session appends a line to .claude/settings.json; the ## Permissions (pointer) stub you left in CLAUDE.md gets filled in there once you have a file worth pointing at. Continue at Part 2 — Read your settings.json.