# New to Claude Code? Start here

A crash course for people who have never driven a coding agent. Half an hour of reading here saves days of
trial and error later, and a good share of your plan's usage.

You don't need to know git, GitHub or how agents work to follow it. Each idea comes with the one thing you need to
do about it.

## The words you'll keep hearing

Think of hiring a very fast contractor who forgets everything each morning.

| Word | What it means | The contractor version |
|---|---|---|
| Repository (repo) | A project folder that git keeps a history of | The building site |
| Commit | One saved snapshot of the project, with a message | A dated photo of the site, with a note |
| Branch | A separate line of commits you can merge back later | A second plot where a risky extension is tried first |
| Session | One run of `claude` in a folder, from start to exit | One working day |
| Context window | Everything the model can hold in mind at once: your messages, its replies, the files it read | The contractor's short-term memory |
| Token | The unit usage is counted in, roughly three quarters of a word | The contractor's hourly rate |
| `CLAUDE.md` | A file in your project that Claude Code reads at the start of every session | The note pinned to the site door |
| Compaction | Squeezing a long conversation into a summary to free room | Notes from yesterday, written in a hurry |
| Subagent | A helper with its own fresh context, sent off on one job | A subcontractor |
| Hook | A small script that runs at a fixed moment, such as after every edit | A site rule enforced by the gatekeeper, not by memory |
| Worktree | A second working copy of the same repository, on its own branch | A second workbench, so two jobs never share tools |
| `.md` (Markdown) | Plain text with light formatting (`#` headings, `-` lists); how agents' notes, docs and instructions are written | The site diary |
| Local | Running on your own computer, with your files | Working on your own site |
| Cloud | Running on someone else's computer, such as a session on claude.ai that clones your repository | A contractor working from their own yard |
| Headless | Running Claude Code with no chat window (`claude -p "…"`), from a script or CI; `--output-format stream-json` gives a line of JSON per step | Leaving written instructions and coming back for the report |
| Symlink | A file or folder that points at another one, so one copy shows up in two places | A signpost, not a second building |
| Artifact | Something an agent produces for you to look at or use: a page, a document, a chart | The drawings handed over at the end |
| MCP | Model Context Protocol: a standard plug for connecting outside tools (GitHub, a database, your calendar) | Giving the contractor a phone and an account at the merchant's |
| Skill | A packaged set of instructions for one kind of job, loaded when it's relevant (`.claude/skills/<name>/SKILL.md`) | A laminated method card for one task |
| Plugin | A bundle of skills, commands, agents, hooks and MCP servers you install in one go | A complete toolkit in one case |
| Mod | A change to the tool's own interface or behaviour: a status line, a side panel, a new slash command | Customising the van |

The last column is the whole problem in miniature: the contractor is brilliant, but anything that lives only in their
head is gone tomorrow. Everything below is about writing things down in the right place.

## Get set up

1. **A terminal.** macOS: Terminal. Windows: Windows Terminal (PowerShell). Linux: whatever came with it.
2. **git.** Check with `git --version`. If it's missing, install it from [git-scm.com](https://git-scm.com/downloads).
   Git is the undo button for everything an agent does, so don't skip it.
3. **Claude Code.** Install it from [the official setup page](https://code.claude.com/docs/en/setup), then run
   `claude` once and sign in with your plan.
4. **A project folder.** Make one, turn it into a repository and start a session in it:

   ```sh
   mkdir my-project && cd my-project
   git init
   claude
   ```

5. **Ask for the door note.** In the session, type `/init`. Claude Code reads the project and writes a starter
   `CLAUDE.md`. Keep it short: the commands that build and test the project, and the rules it must never break.

## Your first session

- **Just ask.** Describe what you want in plain words. Name the outcome, not the steps: "add a page that lists
  saved recipes, with a test" beats "open app.py and…".
- **Point at files** with `@`, as in `@src/app.py`, instead of pasting them.
- **Plan before building.** Press **Shift+Tab** to cycle permission modes. In plan mode Claude Code reads and proposes
  but changes nothing. Read the plan, correct it, then let it build. A wrong plan caught here costs a few hundred
  tokens; caught after the build it costs the build.
- **Permission modes.** The default asks before anything touches your machine. Accept-edits lets it change files
  without asking but still asks before commands. Start with the default until you trust what it does.
- **Stop it.** **Esc** interrupts. **Esc, Esc** opens the rewind menu, which can roll back the conversation, the code,
  or both.
- **Save your progress.** When something works, ask it to commit, or run `git add -A && git commit -m "what changed"`
  yourself. Small commits are cheap undo points.

## The commands you'll actually use

| Command | When |
|---|---|
| `/init` | Once per project, to write the starter `CLAUDE.md` |
| `/memory` | To read or edit the `CLAUDE.md` files in play |
| `/plan` | To start a task in plan mode |
| `/clear` | Between unrelated jobs: fresh context, `CLAUDE.md` kept |
| `/compact` | Mid-job, when the session gets long. Add a focus: `/compact keep the failing test names` |
| `/context` | To see what is filling the context window |
| `/usage` | To see where you stand against your plan's limits |
| `/cost` | To see what this session has spent |
| `/rewind` | To go back to an earlier point |
| `/resume` | To reopen an earlier session |
| `/diff` | To see what changed |
| `/permissions` | To choose what may run without asking |
| `/doctor` | When something about the install looks wrong |
| `/help` | For everything else |

The full list, with keyboard shortcuts, is on Anthropic's
[Claude Code cheatsheet](https://support.claude.com/en/articles/14553413-claude-code-cheatsheet).

## Why it goes wrong after the first hour

The first session usually feels like magic. The trouble starts on day two, and it is nearly always one of these.

- **The session got long.** Every turn re-sends the whole conversation, so a long session costs more per message and
  the model pays less attention to its middle. Clear between jobs; see
  [when to fork, compact or clear](https://atlas-ade.dev/docs/fork-compact-clear/index.md).
- **Compaction forgot something.** Anything you only said in chat can be summarised away. If it must survive, it goes
  in a file. See [long-horizon context management](https://atlas-ade.dev/docs/long-horizon-context-management/index.md).
- **The new session started cold.** It doesn't know what yesterday's session decided. You end up re-explaining, and
  re-explaining is usage spent on standing still. See [handovers](https://atlas-ade.dev/docs/handover-recency-bias/index.md).
- **`CLAUDE.md` grew into an essay.** It is read every session, so every line costs every time. Keep it to what is
  true for the whole project; see [CLAUDE.md and AGENTS.md](https://atlas-ade.dev/docs/claude-md-and-agents-md/index.md).
- **"Done" wasn't done.** An agent will say a task is finished when it believes it is. Give every task a line that can
  be checked, and have it show you the check: the page loads, the figure comes out right, the log line appears, a
  test passes.
- **The tests became the problem.** "Write a test for everything" sounds safe, and it is how projects drown. A test
  that pins today's exact output breaks on every harmless change, and the agent spends your usage fixing tests
  instead of the project. Keep a test only for something that must stay true for good: dates are always
  dd/mm/yyyy, not "the date is 30/10/2026". Prove everything else once, when it's done, and move on.
- **The same thing got built twice.** An agent that doesn't know a helper exists writes a new one, slightly
  different. A month later there are three ways to format a price, and a fix to one misses the other two.

## Habits that save usage

1. One job per session, `/clear` between jobs.
2. Plan mode first for anything bigger than a small fix.
3. Write the finish line before you start: "done when …", and say how it will be shown.
4. Look before you build: ask the agent to search for an existing function before writing a new one, and, when it
   writes something new, whether it should be a shared helper.
5. Tests only for what must stay true; a test that pins today's output is a tripwire.
6. Commit after every working step.
7. Decisions go in files, not chat.
8. Check `/usage` before a big job, not after.

## Or have it set up for you

Everything on this page can be done by hand, and it is worth understanding either way. Atlas ADE is these habits,
already wired together, so you can spend your usage on the project instead of on the setup:

| The habit | What ADE does instead |
|---|---|
| One job per session, a finish line for each | Every change is a card with its own done line |
| Plan, build, check | Each card flies the same short loop: its own workspace, a build, a review, the tests the change reaches, a merge |
| Decisions in files, not chat | Decisions and outcomes are recorded by ADE's commands and travel with the repo |
| No cold starts | Every session opens with a short generated briefing of where things stand |
| A lean instruction file | `ade init` generates the instructions, settings and agents for both engines |
| Know what a change touches | A chart generated from your code picks the tests to run, and notes a missing test instead of blocking on it |

One command sets it up in a new or existing project. Try the loop without installing anything on the
[demo](https://atlas-ade.dev/demo/), or start with the [quickstart](https://atlas-ade.dev/docs/quickstart/index.md).