Set up Claude Code and write your first CLAUDE.md

The steps

One step at a time. When a step’s check matches, tick it and the next one opens.

1. 01

   Step 1 of 7: Check you have what you need

   Make sure your plan includes Claude Code, your system is supported and you can open a terminal.

   • A plan that includes Claude Code: Pro, Max, Team or Enterprise, or a Claude Console account with API credits. The free Claude.ai plan doesn’t include it.
   • A supported system: macOS 13 or later, Windows 10 version 1809 or later, or Linux such as Ubuntu 20.04+ or Debian 10+, with 4 GB of RAM or more.
   • An internet connection, in one of the countries where Anthropic offers Claude.
   • A terminal. You’ll paste a few commands. No coding needed.

   Claude Code’s installer brings everything it needs, so you don’t need Node.js for Claude Code itself.

   For macOS

   Open Terminal: press Cmd + Space, type Terminal and press Enter.

   For Linux

   Open your terminal app. On most distributions, Ctrl + Alt + T opens it, or search for Terminal in your app menu.

   For Windows

   Open PowerShell: press Win + X and choose Windows PowerShell or Terminal. Check which shell you’re in: PowerShell lines start with PS C:\Users\YourName>. Without the PS, you’re in Command Prompt.

   For WSL

   Open your WSL distribution, such as Ubuntu, from the Start menu. You’ll install and run Claude Code inside it, not in PowerShell or Command Prompt.

   For “The practice project”

   The practice project runs its tests on Node.js 22 or newer. Check your version:

   Terminal or PowerShellCopy

   node --version

   Check it worked

   • A terminal window is open with a blinking cursor. In PowerShell, the line starts with PS.
   • You know which account you’ll log in with, and it has one of the plans above.
   • For the practice project, node --version prints v22 or higher.

   If it didn’t work

   You’re on the free Claude.ai plan

   Claude Code isn’t included in it. Upgrade to Pro or Max at claude.com/pricing, or use a Claude Console account with API credits. On a Team or Enterprise plan, ask your admin for access.

   Node.js isn’t found, or it’s older than v22

   Install the LTS version from nodejs.org, then open a new terminal and check again. On WSL, install Node.js inside your Linux distribution: a Windows install doesn’t count there. You only need Node.js for the practice project.

   It worked — next step Not yet
2. 02

   Step 2 of 7: Install Claude Code

   Run the official installer for your system, then check that the claude command works in a new terminal.

   For macOS

   TerminalCopy

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

   No sudo needed: it installs into your home folder. When it finishes, you see Claude Code successfully installed!. Installs made this way update themselves in the background.

   Prefer Homebrew? brew install --cask claude-code works too, but Homebrew installs don’t update themselves. Run brew upgrade claude-code now and then.

   For Linux and WSL

   TerminalCopy

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

   No sudo needed: it installs into your home folder. When it finishes, you see Claude Code successfully installed!. Installs made this way update themselves in the background.

   On WSL, run this inside your WSL terminal, and start claude from WSL later too. Prefer a package manager on Linux? Anthropic publishes apt, dnf and apk repositories.

   For Windows

   PowerShellCopy

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

   Run it in PowerShell. You don’t need to run it as Administrator. When it finishes, you see Claude Code successfully installed!. Installs made this way update themselves in the background.

   In Command Prompt instead of PowerShell? Use this line there:

   Command PromptCopy

   curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

   Prefer WinGet? winget install Anthropic.ClaudeCode works too, but WinGet installs don’t update themselves. Run winget upgrade Anthropic.ClaudeCode now and then.

   Git for Windows is optional. With it, Claude can run Bash commands. Without it, Claude runs its commands in PowerShell.

   Then close the terminal and open a new one. Windows that were already open don’t know about the new claude command yet.

   Check it worked

   New terminal or PowerShell windowCopy

   claude --version

   It prints a version number followed by (Claude Code). The number changes often, so any version is fine.

   If it didn’t work

   The terminal says command not found: claude, or 'claude' is not recognized

   First, make sure you opened a new terminal after installing. If it still fails, the install folder isn’t on your PATH. Add it:

   For macOS

   Terminal (Zsh, the macOS default)Copy

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

   For Linux and WSL

   Terminal (Bash)Copy

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

   For Windows

   PowerShellCopy

   $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
   [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

   This adds %USERPROFILE%\.local\bin to your user PATH. Close PowerShell and open a new window.

   Then run claude --version again.

   Windows rejects the install line: an error about 'irm', '&&', 'install.cmd', 'fsSL' or 'bash'

   • irm not recognized: you’re in Command Prompt. Open PowerShell and run the PowerShell line, or use the Command Prompt line above.
   • && not a valid statement separator, or install.cmd not recognized: you’re in PowerShell with the Command Prompt line. Use the PowerShell line.
   • fsSL parameter not found, bash not recognized, or an error from WSL: you pasted the macOS and Linux line into PowerShell. Use the PowerShell line.

   PowerShellCopy

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

   macOS or Linux shows a syntax error about '<', or a page of HTML

   The install address sent back a web page instead of the script. If it mentions App unavailable in region, Claude Code isn’t offered in your country. Otherwise, run the command again. On macOS you can also install with Homebrew:

   TerminalCopy

   brew install --cask claude-code

   An older guide told you to install with npm or sudo

   Use the installer above instead. It doesn’t need Node.js, and Anthropic’s docs warn against sudo npm install -g because it causes permission and security problems. If you installed an npm copy before, check which claude runs:

   For macOS, Linux and WSL

   TerminalCopy

   which -a claude

   For Windows

   PowerShellCopy

   where.exe claude

   Keep one install, ideally the native one. To remove an npm copy, run npm uninstall -g @anthropic-ai/claude-code.

   Something else is wrong and you’re not sure what

   Terminal or PowerShellCopy

   claude doctor

   It checks your install and settings without starting a session, and lists any problems with suggested fixes. Anthropic’s installation troubleshooting guide matches error messages to fixes.

   It worked — next step Not yet Back
3. 03

   Step 3 of 7: Open your project in the terminal

   Move your terminal into the project folder and run its tests once, so you know where you start.

   Claude Code works on the folder you start it in. So first, move your terminal into the project.

   For “The practice project”

   Acme Quotes prices a job from a rate card: hours per role, a discount, then VAT. Download it and unzip it, or run these lines. They make a projects folder in your home folder, download the project there and open it.

   For macOS, Linux and WSL

   TerminalCopy

   mkdir -p ~/projects && cd ~/projects
   curl -fsSLO https://horizonlux.com/resources/claude-code-challenge/kits/horizonlux-claude-code-starter.zip
   unzip horizonlux-claude-code-starter.zip
   cd horizonlux-claude-code-starter

   For Windows

   PowerShellCopy

   New-Item -ItemType Directory -Force "$HOME\projects" | Out-Null
   cd "$HOME\projects"
   Invoke-WebRequest https://horizonlux.com/resources/claude-code-challenge/kits/horizonlux-claude-code-starter.zip -OutFile horizonlux-claude-code-starter.zip -UseBasicParsing
   Expand-Archive horizonlux-claude-code-starter.zip -DestinationPath . -Force
   cd horizonlux-claude-code-starter

   Run the tests once:

   Terminal or PowerShellCopy

   npm test

   Then try the app. This prices 10 hours of design and 24 hours of development, with a 10% discount:

   Terminal or PowerShellCopy

   node src/cli.js design:10 dev:24 --discount 10

   You should see

   Acme Quotes
   
   Design, 10 h at EUR 80.00          EUR 800.00
   Development, 24 h at EUR 95.00   EUR 2,280.00
   
   Subtotal                         EUR 3,080.00
   Discount (10%)                    -EUR 308.00
   After discount                   EUR 2,772.00
   VAT (20%)                          EUR 554.40
   Total                            EUR 3,326.40

   Remember that total, EUR 3,326.40. Your CLAUDE.md will tell Claude to check it.

   For “My own project”

   Go to your project’s root folder: the one with its package or build file and its README. In a git repository, that’s the folder that holds .git.

   Terminal or PowerShellCopy

   cd path/to/your/project

   Run your usual tests or build once, so you know the project works before Claude changes anything. If something already fails, note it now so you don’t blame Claude later.

   Warning: Pick a project that’s in git or backed up, so you can undo any change Claude makes.

   Check it worked

   • Practice project: the npm test summary shows pass 8 and fail 0, and the quote ends with Total and EUR 3,326.40, as above.
   • Your own project: your terminal is in the project root, and you know whether its tests pass today.

   If it didn’t work

   npm or node isn’t found

   Install Node.js 22 or newer, as in step 1, then open a new terminal and go back into the project folder.

   PowerShell says running scripts is disabled on this system

   PowerShell’s execution policy is blocking the npm.ps1 launcher. Run npm.cmd test instead, which does the same job. Or allow local scripts for your user, then run npm test again:

   PowerShellCopy

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

   Linux or WSL says unzip: command not found

   Install it, then run the unzip and cd lines again. On Ubuntu and Debian:

   TerminalCopy

   sudo apt install unzip

   The download line fails

   Download the practice project in your browser instead and unzip it into a folder you keep projects in. Avoid your home folder itself. Then cd into the horizonlux-claude-code-starter folder.

   It worked — next step Not yet Back
4. 04

   Step 4 of 7: Start Claude Code and log in

   Run claude in the project folder, trust the folder and log in with the account that has your plan.

   In the project folderCopy

   claude

   The first time you start Claude Code in a folder, it asks whether you trust that folder. Accept for the practice project and for your own code. Only trust folders whose contents you know, because a project’s settings can pre-approve commands and add hooks that run on your computer.

   Note: New sessions usually start in auto mode: Claude edits files and runs most commands without asking you. Reading and editing files in your project go ahead on their own, and a separate safety check reviews the rest, such as shell commands and network requests, before they run. Your very first session after installing can start in a different mode. The status bar under the prompt shows the mode, and Shift+Tab switches it. On Windows, if Shift+Tab does nothing, press Alt+M. To approve edits and commands yourself, press that key until the status bar shows ⏸ manual mode on.

   For “Claude Code isn’t installed yet”

   On first launch, Claude Code opens your browser to log in. Use the account with your Pro, Max, Team or Enterprise plan, or your Console account, and follow the prompts on screen. When it’s done, the terminal shows Login successful. Press Enter to continue. You stay logged in after that.

   Check it worked

   Above the prompt, you see the Claude Code version, the model and your project folder. Then type:

   In Claude CodeCopy

   /status

   The Status tab shows your version, model and account. Check that the account is the one with your plan, then close the dialog.

   If it didn’t work

   The browser doesn’t open, or it shows a code instead of going back to the terminal

   Press c in the terminal to copy the login URL, then paste it into your browser. If the browser shows a code after you sign in, which is common in WSL, paste it into the terminal where it says Paste code here if prompted.

   Claude Code asks you to approve an API key instead of opening the browser

   Your terminal has an ANTHROPIC_API_KEY variable set, perhaps from older work. If you approve it, Claude Code uses that key instead of your plan. To use your plan, remove the variable and start again:

   For macOS, Linux and WSL

   TerminalCopy

   unset ANTHROPIC_API_KEY
   claude

   For Windows

   PowerShellCopy

   Remove-Item Env:ANTHROPIC_API_KEY
   claude

   To make it stick, delete the export ANTHROPIC_API_KEY=... line from ~/.zshrc, ~/.bashrc or ~/.profile. On Windows, check your PowerShell profile ($PROFILE) and your user environment variables. Then /status shows which login is in use.

   You see API Error: 403 Request not allowed after logging in

   • On Pro or Max, check that your subscription is active at claude.ai/settings.
   • On a Console account, ask your admin for the Claude Code or Developer role.
   • Behind a company proxy, the proxy may be blocking requests. Ask your IT team.

   The trust question comes back every time you start Claude Code

   You’re starting it in your home folder, where Claude Code keeps your answer for one session only. Start it from the project folder instead. It remembers trust there.

   You logged in with the wrong account

   Type /login to sign in with another account, or /logout to sign out. After /logout, the next claude takes you through login again.

   It worked — next step Not yet Back
5. 05

   Step 5 of 7: Write your CLAUDE.md

   Create a short CLAUDE.md in the project root with the commands, rules and checks Claude can’t work out on its own.

   CLAUDE.md is a plain Markdown file in your project root. Claude Code reads it at the start of every session, so it’s where you write what you’d otherwise explain again each time. The best lines are the ones Claude can’t work out by reading the code:

   • Commands it can’t guess: how to install, test, run and lint.
   • Rules that differ from the defaults: for example, how money is rounded.
   • How to check work: the command that must pass before a task counts as done, and the proof to show.
   • Files not to edit by hand, and why: generated files, secrets, data someone else owns.

   Leave out what Claude can see for itself in the code, standard conventions, long explanations and anything that changes often. Write rules you could check: “Run npm test before saying you’re done”, not “Test your changes”. Anthropic suggests keeping each CLAUDE.md under 200 lines. Shorter files are followed more reliably.

   For “The practice project”

   Let Claude draft the file first. In Claude Code, type:

   In Claude CodeCopy

   /init

   Claude reads the project and writes a CLAUDE.md with the commands and conventions it finds. Read what it wrote, and cut anything Claude can work out from the code, such as a list of what each file does. It can’t know the owner’s rules, such as that prices in data/rates.json are the owner’s call, or how you want work checked before it’s called done. Those lines are what make the file worth having.

   Here’s the finished file for Acme Quotes. Copy it, open CLAUDE.md in any text editor, replace everything in it with the copy and save.

   CLAUDE.md · MarkdownCopy

   # Acme Quotes
   
   A command-line quote calculator for a small services business. It prices hours
   per role from a rate card, takes off an optional discount, adds VAT and prints
   the total. Plain Node.js with no dependencies.
   
   ## Commands
   
   - `npm test`: run every test in `test/` with Node's built-in test runner.
   - `npm run quote -- design:10 dev:24 --discount 10`: print a sample quote.
   - Needs Node 22 or newer. Ask before adding any npm package.
   
   ## Code rules
   
   - `src/quote.js` stays pure: no file, network or console access. Input and output belong in `src/cli.js`.
   - ES modules with `import`/`export`. Relative imports keep the `.js` extension.
   - Money is whole cents (integers) inside `src/quote.js`. Only `formatMoney` turns cents into text.
   - Round to the cent with `Math.round` at each step: each line, the discount, the VAT.
   - The discount comes off before VAT is added.
   - Throw an `Error` with a message the user can act on. `src/cli.js` prints it and exits with code 1.
   - 2-space indentation, single quotes, semicolons.
   
   ## Before you say a task is done
   
   1. Run `npm test`. Show the pass and fail counts from the output.
   2. If you touched pricing, run `npm run quote -- design:10 dev:24 --discount 10`.
      The total is EUR 3,326.40 unless the task was meant to change it.
   3. New behaviour in `src/quote.js` needs a test in `test/quote.test.js`.
   
   ## Don't edit by hand
   
   - `data/rates.json`: prices are the owner's call. Change them only when asked, and list what changed.
   - `.env`: holds secrets. Don't open, print or commit it. `.env.example` is safe to edit.
   

   Every rule here is one you could check. The same file is in the finished kit.

   For “My own project”

   Option 1: let Claude draft it. In Claude Code, type:

   In Claude CodeCopy

   /init

   Claude reads your project and writes a starting CLAUDE.md. Then tighten it with this prompt. Claude will ask you for the rules only you know:

   Paste into Claude CodeCopy

   Read CLAUDE.md and check it against this project. Rewrite it so it has these sections, and nothing you could work out by reading the code:
   
   - Commands: the exact commands to install, test, run and lint, including how to run a single test file.
   - Code rules: only the rules that differ from the usual defaults for this language.
   - Before you say a task is done: the commands that must pass and the proof to show me.
   - Don't edit by hand: generated files, secrets and files someone else owns, each with the reason.
   
   Use only facts you can confirm from the repository. Ask me about anything you can't confirm, especially which files must not be edited and why. Keep it short, well under 200 lines. Show me the new file before you save it.

   Option 2: start from our template. Save this as CLAUDE.md in your project root:

   CLAUDE.md · MarkdownCopy

   <!--
   Template for your own project. Save it as CLAUDE.md in your project root,
   replace every <placeholder> and delete the lines that don't apply.
   
   Write rules Claude can check: "Run npm test before saying you're done", not
   "Test your changes". Leave out what Claude can see in the code, such as what
   each folder holds. Keep it short; add a line when Claude makes the same
   mistake twice. Claude Code strips block-level HTML comments like this one
   before the file reaches Claude's context, so these notes cost nothing if you
   leave them in.
   -->
   
   # <Project name>
   
   <One or two sentences: what the project does and who uses it.>
   
   ## Commands
   
   - `<install command>`: <installs dependencies>
   - `<test command>`: <runs the tests; add how to run a single test file>
   - `<run or build command>`: <starts the app or builds it>
   - `<lint or format command>`: <checks style; say whether it also fixes files>
   
   ## Code rules
   
   - <A rule you could check in a review, such as "Use 2-space indentation">
   - <A convention a new teammate gets wrong, such as where new API routes go>
   - <A library or pattern to use, and one to avoid>
   
   ## Before you say a task is done
   
   1. <A command that must pass, such as `npm test`>
   2. <A second check, such as the type checker or the linter>
   3. <The proof to show, such as the test summary line>
   
   ## Don't edit by hand
   
   - `<generated or owned file>`: <why, and what to change instead>
   - `.env`: holds secrets. Don't open, print or commit it.
   

   The comment at the top is a note for you. Claude Code strips HTML comments like it before the file reaches Claude, so it costs nothing if you leave it.

   Then have Claude fill it in from your code:

   Paste into Claude CodeCopy

   CLAUDE.md is a template. Fill it in for this project: replace every <placeholder> with facts you can confirm from the code, the package or build files and the README, and delete the lines that don't apply. You can delete the comment at the top.
   
   Ask me about anything you can't confirm, especially which files must not be edited by hand and why. Keep it short, well under 200 lines. Show me the result before you save it.

   Note: Does your project already have an AGENTS.md for other coding tools? Claude Code reads it only while there’s no CLAUDE.md. Once you add one, put @AGENTS.md on the first line of your CLAUDE.md, so Claude keeps reading both.

   For “I already have a CLAUDE.md”

   You already have a CLAUDE.md, so run /init anyway: when the file exists, it suggests improvements instead of overwriting it. Check your file against the list above. Make sure it says which files not to edit by hand and how to check work, because step 7 tests both.

   Check it worked

   Your project root has a file named exactly CLAUDE.md, in capitals, next to your README. Open it. It’s well under 200 lines and has short sections for commands, rules, how to check work and files not to edit by hand. For the practice project, it matches the finished file above.

   If it didn’t work

   /init didn’t replace your existing CLAUDE.md

   That’s by design. When a CLAUDE.md exists, /init suggests improvements instead of overwriting it. Keep the ones you agree with, or replace the file by hand.

   Claude wrote a long file

   Cut it down. For each line, ask: would removing this make Claude make mistakes? If not, delete it. Steps that only matter for some tasks belong in a skill, which Day 2 covers.

   Claude seems to have forgotten your AGENTS.md

   Adding a CLAUDE.md stops Claude Code from reading AGENTS.md on its own. Put @AGENTS.md on the first line of CLAUDE.md to pull it back in, then start a new session.

   It worked — next step Not yet Back
6. 06

   Step 6 of 7: Check that Claude loaded it

   Start a fresh session and confirm that /context all lists your CLAUDE.md under Memory files.

   Claude Code reads CLAUDE.md when a session starts. If you wrote or changed yours during this session, start a new one. Leave Claude Code:

   In Claude CodeCopy

   /exit

   Start it again in the same folder:

   Terminal or PowerShellCopy

   claude

   Then ask what’s in Claude’s context. Add all: in fullscreen view, where new users usually start, plain /context folds away the list of what’s loaded and shows only the grid.

   In Claude CodeCopy

   /context all

   Check it worked

   /context all shows how full the context window is, then what’s in it. In the list under Memory files, you see your project’s CLAUDE.md.

   If it didn’t work

   Your CLAUDE.md isn’t under Memory files

   • Check you typed /context all. Plain /context can show only the grid, without the list.
   • Check the name. It must be exactly CLAUDE.md. Windows can hide a .txt ending: in File Explorer, turn on File name extensions in the View menu, then rename the file if it shows CLAUDE.md.txt.
   • Check the folder. Claude Code loads the CLAUDE.md in the folder you started it in, and in the folders above it. A CLAUDE.md in a subfolder only loads when Claude works on files there.
   • Check where you started. If you ran claude somewhere else, type /exit, cd into the project and run claude again.

   Claude Code warns that an instruction file is too long

   You see that warning at startup and in /status when a file goes over the recommended length. Trim CLAUDE.md to well under 200 lines, using the test from step 5: would removing this line make Claude make mistakes?

   It worked — next step Not yet Back
7. 07

   Step 7 of 7: Test that Claude follows it

   Ask a question that only your CLAUDE.md can answer, and check the reply.

   Loading the file isn’t the same as using it. These two questions have answers that live in your CLAUDE.md, not in the code:

   Paste into Claude CodeCopy

   Answer from your project instructions, without opening any files:
   
   1. Which files in this project must not be edited by hand, and why?
   2. What do you do before you tell me a task is done?

   Check it worked

   • Practice project: Claude names data/rates.json, because prices are the owner’s call, and .env, because it holds secrets. Before calling a task done, it runs npm test and shows you the pass and fail counts. If pricing changed, it also runs the sample quote and checks the total is EUR 3,326.40.
   • Your own project: the answer matches the “Don’t edit by hand” and “Before you say a task is done” parts of your CLAUDE.md, in Claude’s own words.

   If it didn’t work

   Claude misses a rule or gives a vague answer

   Make the rule more specific. “Don’t edit data/rates.json: prices are the owner’s call” works better than “Be careful with data”. Check that no two lines say different things, because Claude may pick either. Save, start a new session and ask again.

   You told Claude a rule in chat and it said it would remember it

   When you ask Claude to remember something, it saves it to auto memory: notes Claude keeps for itself on your computer, not in CLAUDE.md. For a rule your whole team should get, say “add this to CLAUDE.md” instead.

   Claude still breaks a rule now and then

   CLAUDE.md is guidance, not a lock. Claude reads it and tries to follow it, but nothing forces it. For anything that must never happen, use a hook, which runs every time whatever Claude decides. Day 3 shows how.

   It worked — finish Not yet Back